// 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

    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.
    This is located in the separate sub-project \c xr_shared, so you can easily re-use it in other projects.

    \quotefile xr_shared/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.

*/
