Qt Quick Escenas 3D con contenido 2D
Elementos 2D en un mundo 3D
Qt Quick El 3D permite crear y renderizar de forma eficiente escenas que combinan elementos 3D y 2D.
¿Qué entendemos por una escena combinada 3D-2D?
Por naturaleza, un objeto « View3D », que representa una ventana de visualización 3D en la escena 2D, puede combinarse fácilmente con elementos « Qt Quick », como «Rectangle», «Image» o «Text», situados alrededor, debajo o encima del objeto « View3D », que a su vez es un « Qt Quick » Item.
Consideremos el siguiente ejemplo:
import QtQuick
import QtQuick3D
Rectangle {
gradient: Gradient {
GradientStop { position: 0; color: "steelblue" }
GradientStop { position: 1; color: "black" }
}
Text {
text: "Hello 2D World"
font.pointSize: 32
color: "red"
anchors.top: parent.top
anchors.horizontalCenter: parent.horizontalCenter
}
Item {
width: 400; height: 400
anchors.centerIn: parent
View3D {
anchors.fill: parent
environment: SceneEnvironment { backgroundMode: SceneEnvironment.Color; clearColor: "lightGray" }
PerspectiveCamera { z: 600 }
DirectionalLight { }
Model {
source: "#Cube"
materials: PrincipledMaterial { baseColor: "green"; metalness: 0.0; roughness: 0.0 }
eulerRotation: Qt.vector3d(30, 45, 0)
}
}
}
}
Aquí, la escena 3D es el área con fondo gris. El resto de la ventana está formado por elementos 2D Qt Quick. Estos pueden solaparse con el View3D, pero no forman parte del mundo 3D, no utilizan el sistema de coordenadas 3D y no participan en las transformaciones de la escena 3D.
¿Qué ocurre si queremos tener elementos 2D dentro del mundo 3D, de tal forma que participen realmente en todas las transformaciones 3D? Por ejemplo, ¿podemos colocar elementos Rectangle y Text dentro del mundo 3D, de manera que sigan la rotación del cubo y estén siempre situados por encima de él?

En las siguientes secciones veremos cómo se puede lograr esto. Aunque el ejemplo utiliza Rectangle y Text, cualquier contenido de Qt Quick, incluidos los controles de Qt Quick, Shape, ShaderEffect y ParticleSystem, se puede utilizar de esta manera.
Nota: Tambiénexisten otros métodos para integrar contenido 2D con los objetos 3D. Añadir elementos 2D a nodos 3D permite combinar libremente los objetos 2D y 3D en el mundo 3D, pero no permite renderizar el contenido 2D en la superficie de un objeto 3D. Si el objetivo es texturizar una malla 3D con contenido generado por Qt Quick, utiliza en su lugar the sourceItem property o Texture.
| Qt Quick contenido utilizado como mapa de textura | Qt Quick elementos de la escena 3D |
|---|---|
|
|
Añadir elementos 2D a nodos 3D
El factor clave es la capacidad de Object3D para aceptar objetos hijos de tipo Item y tratarlos de forma especial. Object3D es la clase base para el tipo Node. Esto significa que cualquier Node, así como tipos como Model, aceptan hijos de tipo Item.
A partir de Qt 6.0, añadir un elemento 2D a un nodo 3D ya no provoca que el contenido 2D se renderice en una textura OpenGL, una imagen Vulkan o similar. En su lugar, el modo predeterminado es renderizar los elementos 2D en línea con el resto de la escena 3D, en la misma pasada de renderizado. A los elementos 2D se les aplican todas las transformaciones 3D. Las transformaciones se heredan del nodo envolvente « Node ».
import QtQuick
import QtQuick3D
Rectangle {
gradient: Gradient {
GradientStop { position: 0; color: "steelblue" }
GradientStop { position: 1; color: "black" }
}
Text {
text: "Hello 2D World"
font.pointSize: 32
color: "red"
anchors.top: parent.top
anchors.horizontalCenter: parent.horizontalCenter
}
Item {
width: 400; height: 400
anchors.centerIn: parent
View3D {
anchors.fill: parent
environment: SceneEnvironment { backgroundMode: SceneEnvironment.Color; clearColor: "lightGray" }
PerspectiveCamera { z: 600 }
DirectionalLight { }
Model {
Node {
y: 150
Rectangle {
anchors.horizontalCenter: parent.horizontalCenter
color: "white"
width: text3d.width
height: text3d.height
Text {
id: text3d
text: "Hello 3D World"
font.pointSize: 32
}
}
}
source: "#Cube"
materials: PrincipledMaterial { baseColor: "green"; metalness: 0.0; roughness: 0.0 }
eulerRotation: Qt.vector3d(30, 45, 0)
}
}
}
}
En comparación con el primer fragmento de código, el nodo « Model » tiene ahora un nodo hijo, con una transformación que lo sitúa ligeramente por encima de la posición del cubo. « 150 » es relativo al centro del cubo, en el espacio de coordenadas 3D.
Model {
Node {
y: 150Luego está el elemento « Rectangle ». Al añadirlo bajo un « Node », los límites entre el mundo 3D y el 2D se cruzan internamente, pero esto pasa desapercibido para el diseñador de la aplicación. Se genera automáticamente un « content item » invisible, lo que permite que el «Rectangle» haga referencia a un « parent » y realice el anclaje. La transformación 3D del «Node» se aplica a todo el subárbol 2D. En el ejemplo, esto significa que la rotación coincidirá con la del cubo.
Node {
y: 150
Rectangle {
anchors.horizontalCenter: parent.horizontalCenterEspacios de coordenadas en 2D y 3D
Los elementos 2D siguen utilizando el sistema de coordenadas de Qt Quick: el eje Y va de arriba abajo y las unidades corresponden a píxeles. Por su parte, los nodos 3D utilizan el sistema de coordenadas 3D: el eje Y apunta hacia arriba y las unidades corresponden a centímetros, lo cual se ve afectado por la proyección en perspectiva de Camera.
La esquina superior izquierda del elemento superior se sitúa, por defecto, en el origen del nodo. Esto significa que, a menudo, será conveniente especificar un punto de anclaje para el elemento de nivel superior de un subárbol 2D, por ejemplo, anchors.centerIn: parent, o, como en el ejemplo, anclar el centro horizontal al centro horizontal del nodo padre, centrando así el contenido 2D horizontalmente sobre el nodo 3D.
Consideraciones adicionales
- Aunque los elementos 2D se representan en línea con los objetos 3D, no participan en la iluminación y no proyectarán sombras.
- Clipping puede que no funcione como se espera y debe evitarse. Si el recorte es esencial para el diseño de los elementos 2D, la aplicación debe recurrir explícitamente a la representación en una textura. Esto puede lograrse añadiendo
layer.enabled: trueal elemento de nivel superiorItembajo el nodo 3D. - A partir de Qt 6.2, la entrada se pasa a los elementos 2D según sea necesario. La entrada procedente de dispositivos de puntero debe producirse dentro de la « childrenRect » de los elementos declarados.
- Aunque añadir un árbol de elementos 2D a la escena 3D no supone un gran esfuerzo, debe evitarse un número excesivo (cientos o más) de subárboles 2D dentro de la escena 3D, ya que en grandes cantidades esto puede provocar un mayor consumo de memoria y de recursos gráficos. Ten en cuenta que esto se refiere al número de subárboles Item independientes bajo los nodos 3D, no al número total de elementos 2D en dichos subárboles. Por ejemplo, el fragmento de código QML anterior contiene solo un subárbol 2D.
Véase también Qt Quick 3D - Ejemplo de elementos rápidos y QQuickItem::mapFromGlobal().
© 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.

