Revision control
++ // Copyright (C) 2026 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example xr_advanced_touch
++ \ingroup quick3d-examples
++ \ingroup qt3dxr-examples
++ \title Qt Quick 3D - XR Advanced Touch
++ \examplecategory {3D}
++ \brief Demonstrates touch on curved displays and 3D model touch handling.
++ \image {xr_touch_advanced.webp} {Example showing curved UI panel and paintable 3D objects}
++
++ This example builds on the \l{Qt Quick 3D - XR Simple Touch Example}{XR Simple Touch Example}
++ to demonstrate more advanced touch interaction techniques in \qxr:
++
++ \list
++ \li Touch interaction with 2D UI elements rendered on a curved 3D surface.
++ \li Direct touch handling on 3D models using UV coordinates.
++ \li Grabbing and manipulating 3D objects using pinch gestures.
++ \li Creating procedural curved meshes for immersive displays.
++ \li Building custom paintable textures with C++.
++ \endlist
++
++ \section1 Curved Display with Source Item
++
++ One of the key features of this example is displaying a 2D user interface on a curved surface.
++ We create a custom procedural mesh component, \c CurvedMesh, that generates a curved plane:
++
++ \quotefile xr_advanced_touch/CurvedMesh.qml
++
++ The \c CurvedMesh inherits from \l ProceduralMesh and generates vertices, normals, and UV coordinates
++ for a curved surface. The curvature is controlled by the \c radius property, which determines how much
++ the surface bends. The mesh is divided into \c partitions segments to create a smooth curve.
++
++ We then apply this curved geometry to a \l Model with a \l PrincipledMaterial that uses a \c sourceItem
++ to render 2D content:
++
++ \snippet xr_advanced_touch/Scene.qml curved screen
++
++ The \c sourceItem property contains a standard Qt Quick \l Rectangle with a complex UI including color swatches,
++ sliders, and a drawing canvas. This 2D content is automatically projected onto the curved 3D surface.
++ Touch events on the curved surface are mapped back to 2D coordinates and delivered to the appropriate
++ Qt Quick elements.
++
++ \note The \c emissiveMap and \c emissiveFactor are used to make the screen appear self-lit, improving visibility
++ in different lighting conditions. The slight transparency (opacity: 0.99) enables alpha blending.
++
++ \section1 Custom Paintable Texture
++
++ The drawing canvas in the UI uses a custom C++ class, \c TextureItem, which extends \l QQuickPaintedItem
++ to provide a paintable texture that can be used in 3D materials:
++
++ \quotefromfile xr_advanced_touch/textureitem.h
++ \skipto class TextureItem
++ \printuntil };
++
++ The \c TextureItem maintains an internal \l QImage that can be drawn on using \l QPainter. The image data
++ is then exposed as a \l QQuick3DTextureData that can be used in material textures. This allows us to create
++ dynamic, user-modified textures that update in real-time.
++
++ The key method is \c setUv(), which handles touch input in UV coordinate space:
++
++ \quotefromfile xr_advanced_touch/textureitem.cpp
++ \skipto void TextureItem::setUv
++ \printuntil }
++
++ This method implements several sophisticated features:
++ \list
++ \li Temporal smoothing with adaptive filtering to reduce jitter.
++ \li Detection and handling of UV coordinate wrapping (when drawing crosses texture boundaries).
++ \li Per-touch-point state tracking for multi-touch support.
++ \endlist
++
++ \section1 Touch Handling on 3D Models
++
++ The example demonstrates direct touch interaction with 3D models through the enhanced \c XrGadget component.
++ When a hand touches a 3D model, the touch position is converted to UV coordinates and forwarded to the model:
++
++ \snippet xr_advanced_touch/TouchHand.qml touch handling
++
++ The \c XrGadget component receives these touch events through its \c handleTouch function:
++
++ \snippet xr_advanced_touch/Scene.qml gadget touch
++
++ When the user is not grabbing the model, touch events are forwarded to the \c TextureItem, which draws on the
++ model's texture. This allows users to paint directly on the 3D object's surface.
++
++ \section1 Grabbing and Manipulating 3D Objects
++
++ The example also implements grab-and-move functionality using the pinch gesture:
++
++ \snippet xr_advanced_touch/Scene.qml grab action
++
++ When the user performs a pinch gesture with their right hand, the system captures the offset and rotation
++ between the hand and the selected object:
++
++ \snippet xr_advanced_touch/Scene.qml grab controller
++
++ As the hand moves, the object follows while maintaining the original offset and relative rotation. This creates
++ a natural and intuitive way to position 3D objects in space.
++
++ \section1 Color Selection and Multi Touch
++
++ The color palette on the curved display demonstrates multi-touch interaction. Each hand can independently
++ select a color by tapping a color swatch:
++
++ \snippet xr_advanced_touch/Scene.qml color swatch
++
++ The \c TapHandler responds to taps from different touch points (identified by \c pt.id), allowing each hand
++ to have its own color. When a color is selected, it updates both the hand color and the drawing color for
++ that touch ID through the \c colorChange signal:
++
++ \snippet xr_advanced_touch/Main.qml color change
++
++ This demonstrates how to build multi-user or multi-hand interfaces where different touch points can have
++ independent state and behavior.
++
++ \section1 UI Controls and Model Customization
++
++ The example includes a complete control panel that allows users to:
++ \list
++ \li Select different geometric primitives (torus, cube, sphere, cylinder, and cone).
++ \li Adjust the scale of the 3D model.
++ \li Change the pen width for drawing.
++ \li Clear the drawing canvas by long-pressing a color swatch.
++ \endlist
++
++ These controls demonstrate how to build full-featured spatial interfaces that combine 2D UI paradigms
++ with 3D interaction in an XR environment.
++ */