En esta página

Qt Quick 3D - XR: ejemplo sencillo de entrada

Muestra cómo utilizar el mando de control en Qt Quick 3D XR.

Tetera con el controlador XR apuntando hacia el panel de la interfaz de usuario con botones de colores

Este ejemplo muestra cómo utilizar las API de entrada de bajo nivel de Qt Quick 3D XR para interactuar con objetos 2D y 3D de la escena. Sigue la estructura básica del ejemplo xr_simple.

Entrada del mando

En este ejemplo, realizamos un « ray picking » desde la posición de XrController:

XrController {
    id: rightController
    controller: XrController.RightController
    poseSpace: XrController.AimPose

    property QtObject hitObject

    onRotationChanged: {
        const pickResult = xrView.rayPick(scenePosition, forward)
        if (pickResult.hitType !== PickResult.Null) {
            pickRay.hit = true
            pickRay.length = pickResult.distance
            hitObject = pickResult.objectHit
            cursorSphere.position = pickResult.scenePosition
            cursorSphere.visible = true
        } else {
            pickRay.hit = false
            pickRay.length = 50
            hitObject = null
            cursorSphere.visible = false
        }
    }

    Node {
        id: pickRay
        property real length: 50
        property bool hit: false

        Model {
            eulerRotation.x: -90
            scale: Qt.vector3d(0.005, pickRay.length/100, 0.005)
            source: "#Cone"
            materials: PrincipledMaterial {
                baseColor: rightTrigger.pressed ? "#99aaff" : "#cccccc"
                lighting: PrincipledMaterial.NoLighting
            }
            opacity: 0.8
        }
    }

    Node {
        z: 5
        Model {
            eulerRotation.x: 90
            scale: Qt.vector3d(0.05, 0.10, 0.05)
            source: "#Cylinder"
            materials: PrincipledMaterial {
                baseColor: "black"
                roughness: 0.2
            }
        }
    }
}

Esto realiza las siguientes funciones:

  • Si chocamos con algo, cambiamos la longitud del « pickRay » para que toque el objeto con el que hemos chocado. El « pickRay » es un cono semitransparente (un cilindro cónico) que muestra hacia dónde apunta el usuario. También movemos « cursorSphere » hasta el punto donde impacta el rayo. («cursorSphere » es una esfera semitransparente que es un elemento secundario de « XrView »).
  • Establecemos la propiedad hitObject en el objeto que hemos alcanzado.

También utilizamos un cilindro negro como representación genérica del mando.

Para este ejemplo, hemos creado un sencillo botón 3D en el archivo ExampleButton.qml. (Aquí no se explican los detalles del funcionamiento del botón.) Creamos un « XrInputAction » para que reaccione a las pulsaciones del disparador:

XrInputAction {
    id: rightTrigger
    controller: XrInputAction.RightController
    actionId: [XrInputAction.TriggerPressed, XrInputAction.TriggerValue, XrInputAction.IndexFingerPinch]
    onTriggered: {
        const button = rightController.hitObject as ExampleButton
        if (button && button !== panel.activeButton) {
            panel.activeButton = button
        }
    }
}

La acción rightTrigger reacciona a varios ID diferentes para admitir tanto el seguimiento de manos como distintos tipos de mandos. Cuando se activa la acción, comprueba si el hitObject que hemos configurado anteriormente es del tipo ExampleButton. En ese caso, se activa el botón.

Para permitir que un mando 3D interactúe con contenido 2D, necesitamos añadir una acción « XrVirtualMouse » que establezca la correspondencia entre ambos:

XrInputAction {
    id: rightThumbstickX
    controller: XrInputAction.RightController
    actionId: [XrInputAction.ThumbstickX]
}
XrInputAction {
    id: rightThumbstickY
    controller: XrInputAction.RightController
    actionId: [XrInputAction.ThumbstickY]
}

XrVirtualMouse {
    view: xrView
    source: rightController
    leftMouseButton: rightTrigger.pressed
    scrollWheelX: rightThumbstickX.value
    scrollWheelY: rightThumbstickY.value
}

En primer lugar, añadimos dos acciones más para detectar la posición horizontal y vertical del joystick. A continuación, creamos un « XrVirtualMouse », utilizando el « XrController » como fuente de posición. Utilizamos la acción « rightTrigger » que hemos creado anteriormente para generar pulsaciones y sueltas del ratón, y utilizamos las acciones del joystick para generar eventos de la rueda del ratón.

Por último, añadimos una respuesta háptica cuando el « pickRay » choca contra un objeto:

XrHapticFeedback {
    controller: XrHapticFeedback.RightController
    condition: XrHapticFeedback.RisingEdge
    trigger: pickRay.hit
    hapticEffect: XrSimpleHapticEffect {
        amplitude: 0.5
        duration: 10
        frequency: 200
    }
}

El efecto háptico se activará cada vez que la propiedad « pickRay.hit » pase de « false » a « true ».

XrItem

La forma habitual de integrar interfaces de usuario 2D en escenas 3D también funciona en XR, pero dado que la unidad de medida es un centímetro, esas interfaces de usuario tendrán que escalarse para que resulten útiles. El tipo ` XrItem ` ofrece una forma cómoda de realizar el escalado automáticamente estableciendo el tamaño físico del elemento 3D y el tamaño lógico de la superficie 2D.

XrItem {
    width: 75
    height: 100
    x: -100
    y: height + table.height + 5
    z: 40
    eulerRotation.y: 45
    color: "transparent"
    contentItem: Rectangle {
        color: Qt.rgba(1, 1, 1, 0.5)
        border.width: 5
        border.color: "lightblue"
        height: 400
        width: 300
        radius: 25
    ...
        }
    }

Situamos el XrItem en tres dimensiones y lo configuramos con 75 cm de ancho y 100 cm de alto. A continuación, añadimos un rectángulo como elemento de contenido y lo configuramos con unas dimensiones de 300 x 400 unidades. El resto de los elementos de la interfaz de usuario Qt Quick se añaden como elementos secundarios del rectángulo de la forma habitual y no se muestran aquí. El contenido 2D se escala automáticamente para que ocupe todo el espacio de XrItem.

Proyecto de ejemplo en @code.qt.io

© 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.