Qt Quick 3D - XR 简单输入示例
演示了在Qt Quick 3D XR中的控制器输入。
本示例展示了如何使用Qt Quick 3D XR中的低级输入API与场景中的2D和3D对象进行交互。它遵循xr_simple示例的基本结构。
控制器输入
在此示例中，我们从XrController 的位置进行ray picking 操作：
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
}
}
}
}这将执行以下功能：
- 如果击中任何物体，我们会调整
pickRay的长度，使其触碰到被击中的物体。pickRay是一个半透明的锥体（锥形圆柱体），用于显示用户的瞄准位置。我们还会将cursorSphere移动到光线击中的点。（cursorSphere是一个半透明的球体，它是XrView 的子对象。） - 我们将属性
hitObject设置为被击中的对象。
我们还使用一个黑色圆柱体作为控制器的通用表示。
在此示例中，我们在文件ExampleButton.qml 中制作了一个简单的 3D 按钮。（按钮的工作原理在此不作详细说明。）我们创建了一个XrInputAction 来响应按钮按压：
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
}
}
}rightTrigger 动作会响应多个不同的 ID，以同时支持手部追踪和不同类型的控制器。当该动作被触发时，它会检查我们上面设置的hitObject 是否属于ExampleButton 类型。如果是，则按钮被激活。
为了让 3D 控制器能够与 2D 内容交互，我们需要添加一个 `XrVirtualMouse ` 来实现二者的映射：
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
}首先，我们再添加两个动作来检测摇杆的水平和垂直位置。然后，我们创建一个XrVirtualMouse ，并使用XrController 作为位置来源。我们利用之前创建的rightTrigger 动作来生成鼠标点击/释放事件，并利用摇杆动作来生成鼠标滚轮事件。
最后，当pickRay 撞击物体时，我们会添加一些触觉反馈：
XrHapticFeedback {
controller: XrHapticFeedback.RightController
condition: XrHapticFeedback.RisingEdge
trigger: pickRay.hit
hapticEffect: XrSimpleHapticEffect {
amplitude: 0.5
duration: 10
frequency: 200
}
}每当pickRay.hit 属性从false 变为true 时，触觉效果就会触发。
XrItem
在 3D 场景中嵌入 2D 用户界面的常规方法在 XR 中同样适用，但由于单位尺寸为 1 厘米，这些用户界面必须进行缩放才能发挥作用。XrItem 类型提供了一种便捷的方式，通过设置 3D 项的物理尺寸和 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
...
}
}我们将XrItem 在三维空间中定位，并将其宽度设为75厘米，高度设为100厘米。然后添加一个矩形作为内容项，并将其尺寸设为300×400单位。其余的Qt Quick 用户界面元素以常规方式作为该矩形的子元素添加，此处不再赘述。 2D 内容会自动缩放，以填满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.
