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_shared/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.
+ */