Qt Quick 3D - XR Advanced Touch
Muestra la interacción táctil en pantallas curvas y el manejo táctil de modelos 3D.

Este ejemplo se basa en el ejemplo «XR Simple Touch » para mostrar técnicas de interacción táctil más avanzadas en Qt Quick 3D Xr:
- Interacción táctil con elementos de la interfaz de usuario 2D representados en una superficie 3D curvada.
- Manipulación táctil directa de modelos 3D mediante coordenadas UV.
- Selección y manipulación de objetos 3D mediante gestos de pellizco.
- Creación de mallas curvas procedimentales para pantallas inmersivas.
- Creación de texturas personalizadas pintables con C++.
Pantalla curva con elemento fuente
Una de las características clave de este ejemplo es la visualización de una interfaz de usuario 2D sobre una superficie curva. Creamos un componente de malla procedural personalizada, ` CurvedMesh`, que genera un plano curvo:
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
import QtQuick
import QtQuick3D
import QtQuick3D.Helpers
ProceduralMesh {
property real partitions: 50
property real segments: 1
property real radius: 50.0
property real height: 50.0
property real width: 80
property var meshArrays: generateMesh(partitions , width, height, radius)
positions: meshArrays.verts
normals: meshArrays.normals
uv0s: meshArrays.uvs
indexes: meshArrays.indices
function generateMesh(partitions : real, width: real, height: real, radius: real) : var {
let verts = []
let normals = []
let uvs = []
let indices = []
// width = angleSpan * radius
const angleSpan = width / radius
for (let i = 0; i <= partitions ; ++i) {
for (let j = 0; j <= 1; ++j) {
const u = i / partitions ;
const v = j;
const x = u - 0.5 // centered
const angle = x * angleSpan
const posZ = radius - radius * Math.cos(angle)
const posY = height * v
const posX = radius * Math.sin(angle)
verts.push(Qt.vector3d(posX, posY, posZ));
let normal = Qt.vector3d(0 - posX, 0, radius - posZ).normalized();
normals.push(normal);
uvs.push(Qt.vector2d(u, v));
}
}
for (let i = 0; i < partitions ; ++i) {
let a = (segments + 1) * i;
let b = (segments + 1) * (i + 1);
let c = (segments + 1) * (i + 1) + 1;
let d = (segments + 1) * i + 1;
// Generate two triangles for each quad in the mesh
// Adjust order to be counter-clockwise
indices.push(a, b, d);
indices.push(b, c, d);
}
return { verts: verts, normals: normals, uvs: uvs, indices: indices }
}
}El « CurvedMesh » hereda de « ProceduralMesh » y genera vértices, normales y coordenadas UV para una superficie curva. La curvatura se controla mediante la propiedad « radius », que determina el grado de curvatura de la superficie. La malla se divide en segmentos « partitions » para crear una curva suave.
A continuación, aplicamos esta geometría curva a un Model con un PrincipledMaterial que utiliza un sourceItem para renderizar contenido 2D:
Model {
objectName: "curved screen"
x: 0
y: -40
z: -50
// mesh origin is at bottom of screen; scene origin is at eye height
geometry: CurvedMesh {
width: height * 32 / 9
height: 40
radius: 80
}
visible: true
pickable: true
materials: PrincipledMaterial {
baseColorMap: Texture {
id: screenTexture
sourceItem: Rectangle {
id: uiItem
width: height * 32 / 9
height: 500
property real dim: Math.min(width, height)
color: "#dd000000"
ColumnLayout {
id: leftItem
anchors.top: parent.top
anchors.bottom: parent.bottom
anchors.left: parent.left
anchors.right: centralItem.left
anchors.margins: 15
spacing: 10
GridLayout {
rows: 3
columns: 3
columnSpacing: 5
rowSpacing: 5
Layout.alignment: Qt.AlignHCenter | Qt.AlignVCenter
ColorSwatch {
color: "red"
}
ColorSwatch {
color: "orange"
}
ColorSwatch {
color: "yellow"
}
ColorSwatch {
color: "green"
}
ColorSwatch {
color: "blue"
}
ColorSwatch {
color: "purple"
}
ColorSwatch {
color: "white"
}
ColorSwatch {
color: "gray"
}
ColorSwatch {
color: "black"
}
}
RowLayout {
Label {
text: "Stroke width: " + penWidthSlider.value.toFixed(1)
}
Slider {
id: penWidthSlider
Layout.fillWidth: true
from: 1
to: 30
value: 10
onValueChanged: painterItem.setPenWidth(value)
}
}
}
Rectangle {
id: centralItem
width: uiItem.dim - 10
height: uiItem.dim - 10
anchors.centerIn: parent
color: "gray"
TextureItem {
id: painterItem
anchors.fill: parent
anchors.margins: 2
MultiPointTouchArea {
anchors.fill: parent
onPressed: (list) => {
for (const pt of list) {
painterItem.setPoint(pt.x, pt.y, pt.pointId, pt.pressed)
}
}
onUpdated: (list) => {
for (const pt of list) {
painterItem.setPoint(pt.x, pt.y, pt.pointId, pt.pressed)
}
}
onReleased: (list) => {
for (const pt of list) {
painterItem.setPoint(pt.x, pt.y, pt.pointId, pt.pressed)
}
}
}
Component.onCompleted: {
// Let initial colors be the same as the hand colors
setColor("green", 1)
setColor("red", 2)
}
}
}
Item {
id: rightItem
anchors.left: centralItem.right
anchors.top: parent.top
anchors.bottom: parent.bottom
anchors.right: parent.right
GroupBox {
anchors.centerIn: parent
title: "3D Model"
ColumnLayout {
ColumnLayout {
id: radioButtons
RadioButton {
text: "Torus"
checked: true
}
RadioButton {
text: "Cube"
}
RadioButton {
text: "Sphere"
}
RadioButton {
text: "Cylinder"
}
RadioButton {
text: "Cone"
}
}
RowLayout {
Label {
text: "Scale: " + scaleSlider.value.toFixed(2)
}
Slider {
id: scaleSlider
Layout.fillWidth: true
from: 0.01
to: 2
value: 0.25
}
}
}
ButtonGroup {
buttons: radioButtons.children
onCheckedButtonChanged: {
selectableModel.meshName = checkedButton.text
}
}
}
}
}
}
emissiveMap: screenTexture
emissiveFactor: Qt.vector3d(0.8, 0.8, 0.8)
}
opacity: 0.99 // enable alpha blending
}La propiedad « sourceItem » contiene un « Qt Quick » estándar « Rectangle » con una interfaz de usuario compleja que incluye muestras de color, controles deslizantes y un lienzo de dibujo. Este contenido 2D se proyecta automáticamente sobre la superficie 3D curvada. Los eventos táctiles en la superficie curvada se asignan a coordenadas 2D y se envían a los elementos « Qt Quick » correspondientes.
Nota: Se utilizanlos métodos ` emissiveMap ` y ` emissiveFactor ` para que la pantalla parezca autoiluminada, lo que mejora la visibilidad en diferentes condiciones de iluminación. La ligera transparencia (opacidad: 0,99) permite la mezcla alfa.
Textura personalizable
El lienzo de dibujo de la interfaz de usuario utiliza una clase personalizada de C++, TextureItem, que hereda de QQuickPaintedItem para proporcionar una textura pintable que se puede utilizar en materiales 3D:
class TextureItem : public QQuickPaintedItem {
Q_OBJECT
Q_PROPERTY(const QQuick3DTextureData* textureData READ textureData NOTIFY textureDataChanged FINAL)
QML_ELEMENT
public:
TextureItem(QQuickItem *parent = nullptr);
void paint(QPainter *painter) override;
const QQuick3DTextureData *textureData() const;
Q_INVOKABLE void setPoint(float x, float y, int id, bool pressed);
Q_INVOKABLE void setUv(float u, float v, int id, bool pressed);
Q_INVOKABLE void clear(const QColor &color);
Q_INVOKABLE void setColor(const QColor &newColor, int id = 0);
Q_INVOKABLE void setPenWidth(qreal newPenWidth);
Q_INVOKABLE void resetPoint(int id);
public slots:
void updateImage();
signals:
void textureDataChanged();
void colorChanged();
void penWidthChanged();
private:
struct TouchPointState {
QColor color = "red";
qreal penWidth = 10; // unused
double alpha = 0.5; // smoothing factor (0..1)
bool initialized = false;
QPointF prevFiltered;
QPointF prevRaw;
qint64 prevTime = 0; // timestamp in milliseconds
void reset() {
initialized = false;
prevTime = 0;
}
QPointF filter(const QPointF &unfiltered, qint64 timestamp) {
prevRaw = unfiltered;
if (!initialized) {
prevFiltered = unfiltered;
prevTime = timestamp;
initialized = true;
} else {
// Adjust alpha based on time delta
qint64 dt = timestamp - prevTime;
double adaptiveAlpha = qMin(1.0, alpha * (dt / 16.0)); // 16ms = ~60fps baseline
prevFiltered.setX(adaptiveAlpha * unfiltered.x() + (1 - adaptiveAlpha) * prevFiltered.x());
prevFiltered.setY(adaptiveAlpha * unfiltered.y() + (1 - adaptiveAlpha) * prevFiltered.y());
prevTime = timestamp;
}
return prevFiltered;
}
};La clase ` TextureItem ` mantiene una ` QImage ` interna sobre la que se puede dibujar utilizando ` QPainter`. A continuación, los datos de la imagen se exponen como un ` QQuick3DTextureData ` que puede utilizarse en texturas de materiales. Esto nos permite crear texturas dinámicas, modificables por el usuario, que se actualizan en tiempo real.
El método clave es ` setUv()`, que gestiona la entrada táctil en el espacio de coordenadas UV:
void TextureItem::setUv(float u, float v, int id, bool pressed)
{
auto &s = state[id];
bool inRange = u >= 0 && u <= 1 && v >=0 && v <= 1;
if (!pressed || !inRange) {
s.reset();
return;
}Este método implementa varias funciones avanzadas:
- Suavizado temporal con filtrado adaptativo para reducir las fluctuaciones.
- Detección y gestión del envoltorio de coordenadas UV (cuando el dibujo traspasa los límites de la textura).
- Seguimiento del estado por punto táctil para la compatibilidad con multitáctil.
Manejo táctil en modelos 3D
El ejemplo muestra la interacción táctil directa con modelos 3D a través del componente mejorado « XrGadget ». Cuando una mano toca un modelo 3D, la posición táctil se convierte en coordenadas UV y se envía al modelo:
const touchState = view.touchpointState(root.touchId)
const gadget = touchState.model as XrGadget
if (gadget) {
gadget.handleTouch(touchState.uvPosition, root.touchId, touchState.pressed)
}El componente ` XrGadget ` recibe estos eventos táctiles a través de su función ` handleTouch `:
onTouched: (uvPosition, touchID, pressed) => {
if (!isGrabbing)
painterItem.setUv(uvPosition.x, uvPosition.y, touchID, pressed);
}Cuando el usuario no está agarrando el modelo, los eventos táctiles se envían a ` TextureItem`, que dibuja sobre la textura del modelo. Esto permite a los usuarios pintar directamente sobre la superficie del objeto 3D.
Selección y manipulación de objetos 3D
El ejemplo también implementa la funcionalidad de «agarrar y mover» mediante el gesto de pellizco:
XrInputAction {
id: grabAction
controller: XrInputAction.RightHand
actionId: [ XrInputAction.IndexFingerPinch ]
onPressedChanged: {
if (pressed)
grabController.startGrab()
}
}Cuando el usuario realiza un gesto de pellizco con la mano derecha, el sistema captura el desplazamiento y la rotación entre la mano y el objeto seleccionado:
XrController {
id: grabController
controller: XrController.RightHand
property vector3d grabOffset
property quaternion grabRotation
function startGrab() {
const scenePos = selectableModel.scenePosition
const sceneRot = selectableModel.sceneRotation
grabOffset = scenePos.minus(scenePosition)
grabRotation = rotation.inverted().times(sceneRot)
}
onRotationChanged: {
if (isGrabbing) {
let newPos = scenePosition.plus(grabOffset)
let newRot = sceneRotation.times(grabRotation)
selectableModel.setPosition(newPos)
selectableModel.setRotation(newRot)
}
}
}A medida que la mano se mueve, el objeto la sigue manteniendo el desplazamiento original y la rotación relativa. Esto crea una forma natural e intuitiva de colocar objetos 3D en el espacio.
Selección de colores y multitáctil
La paleta de colores de la pantalla curva muestra la interacción multitáctil. Cada mano puede seleccionar un color de forma independiente tocando una muestra de color:
component ColorSwatch: Rectangle {
implicitWidth: 100
implicitHeight: 100
function perceivedBrightness() {
return 0.2 * color.r + 0.7 * color.g + 0.1 * color.b
}
function contrastColor() {
if (perceivedBrightness() > 0.6)
return Qt.darker(color, 1.1)
const h = color.hslHue
const s = color.hslSaturation
const l = color.hslLightness + 0.2
return Qt.hsla(h, s, l, 1.0)
}
border.color: contrastColor()
border.width: csth.pressed ? 8 : 4
property real penWidth: 5
TapHandler {
id: csth
dragThreshold: 1000
onTapped: (pt) => {
painterItem.setColor(parent.color, pt.id)
colorChange(parent.color, pt.id)
}
onLongPressed: {
painterItem.clear(parent.color)
}
}
}El « TapHandler » responde a los toques procedentes de diferentes puntos táctiles (identificados por pt.id), lo que permite que cada mano tenga su propio color. Cuando se selecciona un color, se actualizan tanto el color de la mano como el color de dibujo para ese identificador táctil a través de la señal colorChange:
y: xrView.referenceSpace === XrView.ReferenceSpaceLocalFloor ? 130 : 0
onColorChange: (col, id) => {
if (id === 1)
rightHand.color = col
else
leftHand.color = col
}Esto muestra cómo crear interfaces multiusuario o multimanual en las que los distintos puntos táctiles pueden tener un estado y un comportamiento independientes.
Controles de la interfaz de usuario y personalización del modelo
El ejemplo incluye un panel de control completo que permite a los usuarios:
- Seleccionar diferentes primitivas geométricas (toro, cubo, esfera, cilindro y cono).
- Ajustar la escala del modelo 3D.
- Cambiar el grosor del lápiz para dibujar.
- Borrar el lienzo de dibujo manteniendo pulsada una muestra de color.
Estos controles muestran cómo crear interfaces espaciales con todas las funciones que combinan paradigmas de interfaz de usuario 2D con interacción 3D en un entorno XR.
© 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.