Qt Quick 3D - XR: ejemplo sencillo de entrada
Muestra cómo utilizar el mando de control en Qt Quick 3D XR.

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