Qt Quick 3D - XR-Beispiel für „Simple Touch“

Demonstriert die Eingabe per Hand-Tracking in „ Qt Quick 3D Xr“.

Virtueller Bildschirm mit der Bezeichnung „XR Touch Example“ und drei Schaltflächen

Dieses Beispiel zeigt, wie man die Hand-Tracking-API in „ Qt Quick 3D XR“ nutzt, um mit 2D- und 3D-Objekten in der Szene zu interagieren. Es folgt der Grundstruktur des Beispiels „xr_simple “.

Zunächst erstellen wir eine wiederverwendbare Komponente „ TouchHand “, die die gesamte Logik für jede Hand kapselt.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
import QtQuick
import QtQuick3D
import QtQuick3D.Xr

Node {
    id: root
    property color color: "#ddaa88"
    required property int touchId
    required property int hand
    required property XrView view

    property alias touchPosition: handController.scenePos
    property bool touchActive: false

    XrController {
        id: handController
        controller: root.hand

        property vector3d scenePos: view.xrOrigin.mapPositionToScene(pokePosition)

        onScenePosChanged: {
            const touchOffset = view.processTouch(scenePos, root.touchId)
            handModel.position = touchOffset

            const touchState = view.touchpointState(root.touchId)
            const gadget = touchState.model as XrGadget
            if (gadget) {
                gadget.handleTouch(touchState.uvPosition, root.touchId, touchState.pressed)
            }
        }
    }

    XrHandModel {
        id: handModel
        hand: root.hand
        materials: PrincipledMaterial {
            baseColor: root.color
            roughness: 0.5
        }
    }
}

Die Komponente enthält ein ` XrController`, das uns die 3D-Position des Zeigefingers liefert, sowie ein ` XrHandModel `, um anzuzeigen, wo sich die Hand befindet. Im ` onTouchPositionChanged `-Handler geschieht das Wesentliche. Wir rufen ` XrView.processTouch()` auf, das die Hauptarbeit übernimmt: Es versucht, die 3D-Berührungsposition auf eine 2D-Position auf einem ` XrItem ` abzubilden und sendet ein Berührungsereignis, wenn es ein Element findet. Anschließend gibt er den Versatz von der 3D-Position zum Berührungspunkt auf der 2D-Oberfläche zurück. Diesen Versatz nutzen wir dann, um die Position von ` XrHandModel` zu verschieben und so den Eindruck zu erwecken, dass die Hand von der Oberfläche gestoppt wird.

Hinweis: Dieser Effekt funktioniert nicht auf dem Apple Vision Pro, da das System die echten Hände des Benutzers anzeigt und die „ XrHandModel “ nicht dargestellt wird.

Wir erstellen zwei Instanzen der „TouchHand“-Komponente innerhalb des „ XrOrigin “, eine für jede Hand:

XrOrigin {
    id: theOrigin
    z: 50
    TouchHand {
        id: rightHandModel
        hand: XrHandModel.RightHand
        view: xrView
        touchId: 0
        onTouchPositionChanged: buttons.handleTouch(touchPosition)
    }
    TouchHand {
        id: leftHandModel
        hand: XrHandModel.LeftHand
        view: xrView
        touchId: 1
        onTouchPositionChanged: buttons.handleTouch(touchPosition)
    }
}
xrOrigin: theOrigin

Hierbei handelt es sich bei „ buttons “ um eine Gruppe von 3D-Schaltflächen, die über eine „ handleTouch “-Funktion verfügt. (Die Implementierung ist nicht XR-spezifisch, daher werden die Details hier nicht dokumentiert.)

Wir positionieren die „ XrOrigin “ 50 Zentimeter vom Ursprung der Szene entfernt, was eine angenehme Berührungsdistanz darstellen sollte.

Der Rest der Szene enthält einige 3D-Modelle und eine „ XrItem “, die auf Berührungsereignisse reagiert.

Beispielprojekt @ 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.