Revision control
++ // Copyright (C) 2024 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example xr_touch
++ \ingroup quick3d-examples
++ \ingroup qt3dxr-examples
++ \title Qt Quick 3D - XR Simple Touch Example
++ \examplecategory {3D}
++ \brief Demonstrates hand-tracking input in \qxr.
++ \image xrtouch-example.jpg
++ {Virtual screen labeled XR Touch Example with three buttons}
++
++ This example shows how to use the hand-tracking API in \qxr to
++ interact with 2D and 3D objects in the scene. It follows the basic structure of
++ the \l{Qt Quick 3D - XR Simple Example}{xr_simple} example.
++
++ We start by creating a reusable component \c TouchHand that encapsulates all the logic that we need for each hand.
++
++ \quotefile xr_touch/TouchHand.qml
++
++ The component contains an XrController, giving us the 3D position of the index finger, and an
++ XrHandModel to show where the hand is. The \c onTouchPositionChanged handler is where the magic happens.
++ We call \l{XrView::processTouch}{XrView.processTouch()}, which does the heavy lifting: It tries to map the 3D touch position
++ to a 2D position on an \l XrItem and sends a touch event if it finds an item. It then returns the offset
++ from the 3D position to the touch point on the 2D surface. We then use that offset to shift the position
++ of the XrHandModel, to give the illusion that the hand is stopped by the surface.
++
++ \note This effect will not work on the Apple Vision Pro since the system shows the real hands of the user,
++ and the XrHandModel is not shown.
++
++ We create two instances of the TouchHand component inside the XrOrigin, one for each hand:
++
++ \snippet xr_touch/main.qml origin
++
++ Here, \c buttons is a group of 3D buttons that has a \c handleTouch function.
++ (The implementation is not XR specific, so the details are not documented here.)
++
++ We position the XrOrigin 50 centimeters from the origin of the scene, which should be a comfortable
++ touching distance.
++
++ The rest of the scene contains some 3D models and an XrItem that reacts to touch events.
++
++ */