En esta página

XrView QML Type

Configura la vista de una aplicación Xr. Más información...

Import Statement: import QtQuick3D.Xr
Since: Qt 6.8
Inherits:

Node

Status: Technology preview

Este tipo se encuentra en fase de vista previa tecnológica y está sujeto a cambios.

Propiedades

Señales

Métodos

  • pickResult closestPointPick(vector3d origin, float radius, Model model) (since 6.11)
  • vector3d processTouch(vector3d position, int pointId)
  • pickResult rayPick(vector3d origin, vector3d direction)
  • pickResult rayPick(vector3d origin, vector3d direction, Model model) (since 6.11)
  • List<pickResult> rayPickAll(vector3d origin, vector3d direction)
  • void setTouchpoint(Item target, point position, int pointId, bool pressed)
  • object touchpointState(int pointId)

Descripción detallada

Un XrView configura la vista de una aplicación XR. El siguiente fragmento de código procede del ejemplo sencillo «Qt Quick » de 3D Xr y muestra cómo utilizar este tipo.

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

import QtQuick
import QtQuick.Layouts
//! [XrView]
import QtQuick3D
import QtQuick3D.Xr

XrView {
    id: xrView
    XrErrorDialog { id: err }
    onInitializeFailed: (errorString) => err.run("XRView", errorString)
    referenceSpace: XrView.ReferenceSpaceLocalFloor
//! [XrView]

    environment: SceneEnvironment {
        clearColor: "black"
        backgroundMode: SceneEnvironment.Color
    }

Notas sobre la plataforma

Dispositivos Meta Quest

Para « enable passthrough », debes añadir el siguiente permiso al archivo ` AndroidManifest.xml ` de tu aplicación:

<uses-feature android:name="com.oculus.feature.PASSTHROUGH" android:required="false"/>

Documentación de propiedades

depthSubmissionEnabled : bool [default: false]

Determina si está habilitado el envío del búfer de profundidad al compositor XR.

Por defecto, el búfer de profundidad utilizado por la escena 3D en el motor de renderizado « XrView » no se expone al compositor XR. Sin embargo, en algunas plataformas, el envío de la profundidad es implícito y la aplicación no puede desactivarlo ni controlarlo. Un ejemplo de ello es VisionOS. Cambiar esta propiedad no tiene ningún efecto en esas plataformas. En el resto de casos, y en particular con OpenXR, la compatibilidad depende de la implementación de OpenXR utilizada en tiempo de ejecución.

Siempre es seguro establecer depthSubmissionEnabled en true. Simplemente no tendrá ningún efecto cuando no sea compatible con la pila subyacente. Para asegurarte, puedes inspeccionar la salida de depuración para comprobar si se está utilizando el envío de profundidad. El envío del búfer de profundidad puede mejorar las reproyecciones que realice el compositor XR. La reproyección podría producirse, por ejemplo, cuando el sistema no puede mantener la frecuencia de fotogramas objetivo y, por lo tanto, tiene que recurrir a predecir el contenido de los fotogramas para mejorar y estabilizar la percepción que tiene el usuario de la escena y reducir el posible mareo por movimiento. Sin embargo, ni la aplicación ni Qt tienen control sobre el uso de los datos. También podría ocurrir que el envío de datos de profundidad no tenga efectos prácticos y sea ignorado por el tiempo de ejecución XR subyacente y el compositor.

En la práctica, el envío del búfer de profundidad implica renderizar en una textura de profundidad proporcionada por el tiempo de ejecución de XR, en lugar de en la textura intermedia o el búfer de renderizado creado y gestionado por Qt. El renderizado en una textura de profundidad tiene ciertas consecuencias a bajo nivel que pueden afectar al rendimiento:

Al utilizar el « multisample antialiasing » (MSAA), habilitar el envío de profundidad implica renderizar en una textura de profundidad multimuestra y resolver las muestras en la textura de profundidad no multimuestra proporcionada por el tiempo de ejecución de XR. Sin el envío de profundidad, el paso de resolución no sería necesario. Además, algunas API 3D no admiten la resolución de datos de profundidad-estencil multimuestra (véase el indicador « QRhi::ResolveDepthStencil » para más detalles). Sin esta compatibilidad, los intentos de habilitar el envío de profundidad en combinación con MSAA se ignoran de forma controlada.

Incluso cuando no se utiliza MSAA, la activación del envío de profundidad provoca la escritura de datos de profundidad con las API 3D que tienen control sobre ello. La operación de almacenamiento de datos de profundidad/estencil suele indicarse en Qt como innecesaria, lo que puede tener efectos positivos en el rendimiento en arquitecturas de GPU en mosaico. Esto no ocurre con el envío de profundidad, ya que, desde la perspectiva de Qt, los datos de profundidad siempre deben escribirse.

Nota: Recomendamos a los desarrolladores que prueben sus aplicaciones con el envío de profundidad activado, evalúen las ventajas y desventajas, y tomen una decisión informada basada en sus pruebas a la hora de decidir si desean activarlo o no.

environment : SceneEnvironment

Contiene

Contiene el objeto « SceneEnvironment » para la vista XR.

fixedFoveation : enumeration [default: XrView.HighFoveation]

Controla el nivel de renderizado foveado fijo para XrView.

El renderizado foveado reduce la carga de la GPU al disminuir la calidad de la imagen (resolución) en aquellas zonas donde la diferencia es menos perceptible para el ojo. Con el renderizado foveado fijo, las zonas con fidelidad visual reducida son fijas y no cambian. En algunas plataformas, no existe el concepto de renderizado foveado fijo ni la posibilidad de controlarlo. Por ejemplo, los dispositivos basados en VisionOS realizan una renderización foveada dinámica, basada en el seguimiento ocular; por lo tanto, el valor de esta propiedad se ignora en la práctica. Otros dispositivos, como el Meta Quest 3, solo admiten la renderización foveada fija, lo que hace que esta propiedad sea relevante.

El valor puede ser uno de los siguientes:

ConstanteDescripción
XrView.NoFoveation0, sin foveación.
XrView.LowFoveation1, foveación baja.
XrView.MediumFoveation2, foveación media.
XrView.HighFoveation3, foveación alta.

Cuando esté disponible, el valor por defecto es « HighFoveation ». Por lo tanto, en la práctica rara vez será necesario modificar este valor en las aplicaciones.

isQuitOnSessionEndEnabled : bool

Indica si la aplicación debe cerrarse cuando finalice la sesión de XR.

multiViewRenderingEnabled : bool [default: true]

Esta es una propiedad de solo lectura que indica si la representación multivista está habilitada para la vista XR.

Esta propiedad indica si el renderizado multivista se está utilizando realmente en tiempo de ejecución. Cuando no es compatible, el valor volverá a ser « false ».

Se recomienda habilitar el renderizado multivista. Puede mejorar el rendimiento y reducir el consumo de CPU y GPU. De forma predeterminada, está deshabilitado para garantizar la máxima compatibilidad. Se recomienda a los desarrolladores que comprueben que su aplicación se renderiza según lo esperado con «multiViewRenderingEnabled» establecido en « true » y que, posteriormente, lo dejen así.

Nota: Es posible queciertas funciones de « Qt Quick » y «Quick 3D» que implican código de shader proporcionado por la aplicación requieran que dicho código se modifique para que sea compatible con la representación multivista. Algunos ejemplos son los materiales 2D y 3D personalizados y los efectos de posprocesamiento. La documentación sobre la representación multivista ofrece más información al respecto y sobre cómo desactivar la representación multivista.

Véase también « multiViewRenderingSupported » y «Renderizado multivista».

multiViewRenderingSupported : bool

Esta propiedad de solo lectura indica la disponibilidad de la función «Multiview Rendering».

Véase también multiViewRenderingEnabled.

passthroughEnabled : bool

Valor

Indica si la función de paso directo está activada para la vista XR.

passthroughSupported : bool

Indica

Indica si se admite el paso directo para la vista XR.

referenceSpace : enumeration [default: XrView.ReferenceSpaceLocal]

Obtiene o establece el espacio de referencia de la vista XR.

Puede ser una de las siguientes:

ConstanteDescripción
XrView.ReferenceSpaceUnknown 
XrView.ReferenceSpaceLocalEl origen se encuentra en la posición predeterminada de la vista (normalmente definida por una operación de «restablecer vista»).
XrView.ReferenceSpaceStageEl origen se encuentra a la altura del suelo, en el centro del área definida por el usuario.
XrView.ReferenceSpaceLocalFloorEl origen se encuentra a la altura del suelo, por debajo de la posición de vista predeterminada.

ReferenceSpaceLocal Resulta especialmente útil para aplicaciones en las que el usuario está sentado y el contenido no se sitúa en relación con el suelo, como, por ejemplo, los menús flotantes. El contenido se moverá cuando el usuario restablezca la vista.

ReferenceSpaceStage Resulta especialmente útil para aplicaciones a escala de sala, en las que el usuario se mueve libremente dentro del área de juego. El contenido no se moverá cuando el usuario restablezca la vista.

ReferenceSpaceLocalFloor Es útil principalmente para aplicaciones estáticas (sentado o de pie) en las que el contenido se sitúa en relación con el suelo. El contenido se moverá cuando el usuario restablezca la vista.

Nota: En visionOS, el espacio de referencia es siempre ReferenceSpaceLocalFloor y no se puede modificar. Esto significa que las aplicaciones diseñadas con ReferenceSpaceLocal tendrán su origen a nivel del suelo en visionOS, lo que puede provocar que el contenido aparezca en una posición inesperada. Para solucionar esto, las aplicaciones pueden comprobar la propiedad referenceSpace en tiempo de ejecución y ajustar la posición vertical de su contenido en consecuencia. Por ejemplo:

y: xrView.referenceSpace === XrView.ReferenceSpaceLocalFloor ? 130 : 0

renderStats : RenderStats

Contiene

Contiene estadísticas de renderizado para la vista XR.

runtimeInfo : QQuick3DXrRuntimeInfo

Ofrece

Proporciona información sobre el entorno de ejecución de XR para la vista XR.

xrOrigin : XrOrigin

Almacena el origen XR activo.

El origen XR es el punto de la escena que se considera el origen del sistema de coordenadas XR. El origen XR se utiliza para posicionar en la escena los objetos rastreados, como la cámara y los mandos. Una aplicación puede tener varios XrOrigins, pero solo uno puede estar activo a la vez.

Nota: Esta propiedad debe estar configurada para que la escena se renderice en XR.

Véase también XrOrigin.

Documentación de Signal

initializeFailed(const QString &errorString)

Se emite cuando falla la inicialización y existe un nuevo errorString que describe el fallo.

Nota: El controlador correspondiente es onInitializeFailed.

sessionEnded()

Se emite cuando finaliza la sesión.

Nota: El controlador correspondiente es onSessionEnded.

Documentación del método

[since 6.11] pickResult closestPointPick(vector3d origin, float radius, Model model)

Este método buscará el punto de la superficie de model que se encuentre más cerca de origin, dentro de una distancia de radius. Si model es null, se buscará el objeto más cercano dentro de radius.

Si no existe ningún objeto de este tipo, se devuelve null.

Este método se introdujo en Qt 6.11.

vector3d processTouch(vector3d position, int pointId)

Este método buscará un « XrItem » o un «Model» con un « sourceItem texture » cerca de « position » y enviará un evento táctil virtual con el ID del punto táctil « pointId » si « position » se corresponde con un punto de la superficie.

El valor devuelto es el desplazamiento entre position y el punto tocado en la superficie. Esto se puede utilizar para evitar que un modelo de mano atraviese un XrItem.

Véase también XrHandModel.

pickResult rayPick(vector3d origin, vector3d direction)

Este método lanzará un rayo hacia la escena partiendo de origin y en direction, y devolverá información sobre la intersección más cercana con un objeto de la escena.

Por ejemplo, pasa la posición y el vector de avance de cualquier objeto de una escena para ver qué objeto se encuentra delante de un elemento. Esto permite realizar la selección desde cualquier punto de la escena.

[since 6.11] pickResult rayPick(vector3d origin, vector3d direction, Model model)

Este método «lanzará» un rayo hacia la escena partiendo de origin y en direction, y devolverá información sobre la intersección entre el rayo y el model especificado.

Este método se introdujo en Qt 6.11.

List<pickResult> rayPickAll(vector3d origin, vector3d direction)

Este método lanzará un rayo hacia la escena partiendo de origin y en direction, y devolverá una lista con información sobre las intersecciones más cercanas con los objetos de la escena. La lista está ordenada previamente por distancia desde el origen a lo largo del vector de dirección, de modo que las intersecciones más cercanas aparecen en primer lugar y las más lejanas, en último lugar.

Esto se puede invocar, por ejemplo, con la posición y el vector de avance de cualquier objeto de una escena para ver qué objetos se encuentran delante de un elemento. Esto permite realizar la selección desde cualquier punto de la escena.

void setTouchpoint(Item target, point position, int pointId, bool pressed)

Envía un evento táctil sintético a target, desplazando el punto táctil con el ID pointId a position, y utilizando pressed para determinar si el punto está pulsado. También envía el evento de liberación táctil correspondiente si pointId estaba activo previamente en otro elemento.

object touchpointState(int pointId)

Este método devuelve el estado del punto táctil con el ID « pointId ». El estado se representa mediante un mapa que relaciona los nombres de las propiedades con sus valores:

ClaveTipoDescripción
grabbedbool¿Está el punto capturado por un elemento? Si es « false », todos los demás valores son « undefined ».
targetXrItemEl elemento que está capturando el punto táctil, o null si no hay ninguno XrItem.
pressedbool¿Se ha pulsado el punto de contacto?
cursorPospointLa posición 2D del punto de contacto dentro de target
touchDistancerealLa distancia desde el plano hasta el punto de contacto. Será 0 si pressed es true.
surfacePointvector3dLa posición del punto de contacto en el espacio de la escena. [desde la versión 6.11]
normalvector3dEl vector normal en el punto de contacto en el espacio de la escena. [desde la versión 6.11]
uvPositionvector2dLa posición UV en el punto de contacto. [desde la versión 6.11]
modelModelEl modelo que está capturando el punto de contacto, o null si no hay ningún modelo. [desde la versión 6.11]

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.