Qt Quick Introducción al 3D con recursos glTF
El ejemplo «Qt Quick 3D - Introducción» ofrece una introducción rápida a la creación de aplicaciones basadas en QML con « Qt Quick 3D», pero lo hace utilizando únicamente primitivas integradas, como esferas y cilindros. Esta página ofrece una introducción utilizando recursos glTF 2.0, con algunos de los modelos del repositorio de modelos de ejemplo glTF de Khronos.
Nuestra aplicación «Skeleton»
Empecemos con la siguiente aplicación. Este fragmento de código se puede ejecutar tal cual con la herramienta de línea de comandos qml. El resultado es una vista 3D completamente verde en la que no hay nada más.
import QtQuick
import QtQuick3D
import QtQuick3D.Helpers
Item {
width: 1280
height: 720
View3D {
anchors.fill: parent
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.Color
clearColor: "green"
}
PerspectiveCamera {
id: camera
}
WasdController {
controlledObject: camera
}
}
}
Importación de un recurso
Vamos a utilizar dos modelos glTF 2.0 del repositorio «Sample Models»: Sponza y Suzanne.
Estos modelos suelen incluir varios mapas de textura y los datos de la malla (geometría) almacenados en un archivo binario independiente, además del archivo .gltf:

¿Cómo incorporamos todo esto a nuestra escena 3D de « Qt Quick »?
Hay varias opciones:
- Generar componentes QML que se puedan instanciar en la escena. La herramienta de línea de comandos para realizar esta conversión es la herramienta Balsam. Además de generar un archivo .qml, que es en realidad una subescena, también vuelve a empaquetar los datos de la malla (geometría) en un formato optimizado y de carga rápida, y copia asimismo los archivos de imagen de los mapas de textura.
- Realizar lo mismo utilizando
balsamui, una interfaz gráfica de usuario para Balsam. - Si se utiliza Qt Design Studio, el proceso de importación de recursos está integrado en las herramientas de diseño visual. La importación se puede iniciar, por ejemplo, arrastrando y soltando el archivo .gltf en el panel correspondiente.
- En el caso concreto de los recursos glTF 2.0, también existe una opción en tiempo de ejecución: el tipo « RuntimeLoader ». Esto permite cargar un archivo .gltf (y los archivos binarios y de datos de textura asociados) en tiempo de ejecución, sin necesidad de realizar ningún preprocesamiento mediante herramientas como Balsam. Esto resulta muy útil en aplicaciones que desean abrir y cargar recursos proporcionados por el usuario. Por otro lado, este enfoque es significativamente menos eficiente en cuanto al rendimiento. Por lo tanto, no nos centraremos en él en esta introducción. Consulta el ejemplo «Qt Quick 3D - RuntimeLoader» para ver un ejemplo de este enfoque.
Tanto la aplicación « balsam » como « balsamui » se incluyen con Qt y deberían encontrarse en el directorio junto con otras herramientas ejecutables similares, siempre que se haya instalado o compilado « Qt Quick 3D». En muchos casos, basta con ejecutar «balsam» desde la línea de comandos sobre el archivo .gltf, sin necesidad de especificar ningún argumento adicional. No obstante, conviene conocer las numerosas opciones de la línea de comandos —o interactivas, si se utiliza balsamui o Qt Design Studio —. Por ejemplo, al trabajar con mapas de luz preprocesados para proporcionar iluminación global estática, es probable que se desee pasar --generateLightmapUV para obtener el canal UV adicional del mapa de luz generado en el momento de la importación del recurso, en lugar de realizar este proceso, que puede resultar muy lento, en tiempo de ejecución. Del mismo modo, la opción « --generateMeshLevelsOfDetail » es esencial cuando se desea generar versiones simplificadas de las mallas para habilitar el LOD automático en la escena. Otras opciones permiten generar datos que faltan (p. ej., « --generateNormals ») y realizar diversas optimizaciones.
En balsamui, las opciones de la línea de comandos se corresponden con elementos interactivos:

Importación mediante balsam
¡Empecemos! Suponiendo que el repositorio https://github.com/KhronosGroup/glTF-Sample-Models git está descargado en algún lugar, podemos simplemente ejecutar balsam desde el directorio de nuestra aplicación de ejemplo, especificando una ruta absoluta a los archivos .gltf:
balsam c:\work\glTF-Sample-Models\2.0\Sponza\glTF\Sponza.gltf
Esto nos proporciona un archivo Sponza.qml, un archivo .mesh en el subdirectorio meshes y los mapas de texturas copiados en maps.
Nota: Este archivo QML no se puede ejecutar por sí solo. Se trata de un componente que debe instanciarse dentro de una escena 3D asociada a un archivo View3D.
La estructura de nuestro proyecto es muy sencilla en este caso, ya que los archivos QML de los recursos se encuentran justo al lado de nuestra escena principal .qml. Esto nos permite instanciar fácilmente el tipo Sponza utilizando el sistema estándar de componentes de QML. (En tiempo de ejecución, se buscará Sponza.qml en el sistema de archivos).
Sin embargo, limitarse a añadir el modelo (subescena) no sirve de nada, ya que, por defecto, los materiales incluyen los cálculos completos de iluminación PBR, por lo que no se muestra nada de nuestra escena sin una luz como DirectionalLight, PointLight o SpotLight, o sin tener habilitada la iluminación basada en imágenes a través de the environment.
Por ahora, optamos por añadir una « DirectionalLight » con la configuración predeterminada (lo que significa que el color es white y que la luz se emite en la dirección del eje Z).
import QtQuick
import QtQuick3D
import QtQuick3D.Helpers
Item {
width: 1280
height: 720
View3D {
anchors.fill: parent
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.Color
clearColor: "green"
}
PerspectiveCamera {
id: camera
}
DirectionalLight {
}
Sponza {
}
WasdController {
controlledObject: camera
}
}
}Al ejecutar esto con la herramienta « qml », el programa se cargará y se ejecutará, pero la escena estará completamente vacía por defecto, ya que el modelo de Sponza se encuentra detrás de la cámara. La escala tampoco es la ideal; por ejemplo, moverse con las teclas WASD y el ratón (activado mediante « WasdController ») no resulta natural.
Para solucionarlo, escalamos el modelo de Sponza (subescena) mediante 100 a lo largo de los ejes X, Y y Z. Además, la posición Y inicial de la cámara se aumenta a 100.
import QtQuick
import QtQuick3D
import QtQuick3D.Helpers
Item {
width: 1280
height: 720
View3D {
anchors.fill: parent
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.Color
clearColor: "green"
}
PerspectiveCamera {
id: camera
y: 100
}
DirectionalLight {
}
Sponza {
scale: Qt.vector3d(100, 100, 100)
}
WasdController {
controlledObject: camera
}
}
}Al ejecutar esto, obtenemos:

Con el ratón y las teclas WASDRF podemos desplazarnos:


Nota: Hemos mencionado « subscene » varias veces anteriormente como alternativa a «model». ¿A qué se debe esto? Aunque no resulte obvio con el activo Sponza —que, en su formato glTF, es un único modelo con 103 submallas, asignadas a un único objeto « Model » con 103 elementos en su « materials list »—, un activo puede contener cualquier número de « models », cada uno con múltiples submallas y materiales asociados. Estos modelos pueden establecer relaciones padre-hijo y combinarse con nodes adicionales para realizar transformaciones como traslación, rotación o escalado. Por lo tanto, resulta más adecuado considerar el recurso importado como una subescena completa, un árbol arbitrario de nodes, aunque el resultado renderizado se perciba visualmente como un único modelo. Abre el archivo Sponza.qml generado, o cualquier otro archivo QML generado a partir de dichos activos, en un editor de texto sin formato para hacerte una idea de la estructura (que, naturalmente, siempre depende de cómo se haya diseñado el activo de origen, en este caso el archivo glTF).
Importación mediante balsamui
Para nuestro segundo modelo, utilicemos en su lugar la interfaz gráfica de usuario de balsam.
Al ejecutar balsamui se abre la herramienta:

Importemos el modelo de Suzanne. Se trata de un modelo más sencillo con dos mapas de textura.

Como no es necesario aplicar ninguna opción de configuración adicional, basta con hacer clic en «Convertir». El resultado es el mismo que al ejecutar balsam: un archivo Suzanne.qml y algunos archivos adicionales generados en el directorio de salida específico.

A partir de este momento, trabajar con los recursos generados es igual que en la sección anterior.
import QtQuick
import QtQuick3D
import QtQuick3D.Helpers
Item {
width: 1280
height: 720
View3D {
anchors.fill: parent
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.Color
clearColor: "green"
}
PerspectiveCamera {
id: camera
y: 100
}
DirectionalLight {
}
Sponza {
scale: Qt.vector3d(100, 100, 100)
}
Suzanne {
y: 100
scale: Qt.vector3d(50, 50, 50)
eulerRotation.y: -90
}
WasdController {
controlledObject: camera
}
}
}De nuevo, se aplica una escala al nodo Suzanne instanciado y se modifica ligeramente la posición Y para que el modelo no acabe en el suelo del edificio Sponza.

Todas las propiedades se pueden modificar, vincular y animar, igual que con Qt Quick. Por ejemplo, apliquemos una rotación continua a nuestro modelo de Suzanne:
Suzanne {
y: 100
scale: Qt.vector3d(50, 50, 50)
NumberAnimation on eulerRotation.y {
from: 0
to: 360
duration: 3000
loops: Animation.Infinite
}
}Mejorar el aspecto
Más luz
Ahora, nuestra escena está un poco oscura. Añadamos otra luz. Esta vez, un « PointLight », y uno que proyecte una sombra.
import QtQuick
import QtQuick3D
import QtQuick3D.Helpers
Item {
width: 1280
height: 720
View3D {
anchors.fill: parent
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.Color
clearColor: "green"
}
PerspectiveCamera {
id: camera
y: 100
}
DirectionalLight {
}
Sponza {
scale: Qt.vector3d(100, 100, 100)
}
PointLight {
y: 200
color: "#d9c62b"
brightness: 5
castsShadow: true
shadowFactor: 75
}
Suzanne {
y: 100
scale: Qt.vector3d(50, 50, 50)
NumberAnimation on eulerRotation.y {
from: 0
to: 360
duration: 3000
loops: Animation.Infinite
}
}
WasdController {
controlledObject: camera
}
}
}Al ejecutar esta escena y mover un poco la cámara, se aprecia que, efectivamente, empieza a verse mejor que antes:

Depuración de la iluminación
La luz « PointLight » está situada ligeramente por encima del modelo de Suzanne. Al diseñar la escena con herramientas visuales, como Qt Design Studio, esto resulta obvio, pero al desarrollar sin herramientas de diseño puede resultar útil poder visualizar rápidamente la ubicación de las luces « lights » y otros elementos de iluminación « nodes ».
Esto lo podemos hacer añadiendo un nodo hijo, un « Model », al « PointLight ». La posición del nodo hijo es relativa al padre, por lo que el « (0, 0, 0) » por defecto es, en la práctica, la posición del « PointLight » en este caso. Encerrar la luz dentro de alguna geometría (el cubo integrado en este caso) no supone ningún problema para los cálculos estándar de iluminación en tiempo real, ya que este sistema no tiene en cuenta la oclusión, lo que significa que la luz no tiene problemas para atravesar «paredes». Si utilizáramos mapas de luz precalculados, en los que la iluminación se calcula mediante trazado de rayos, la cosa sería diferente. En ese caso, tendríamos que asegurarnos de que el cubo no bloquee la luz, quizá desplazando nuestro cubo de depuración un poco por encima de la luz.
PointLight {
y: 200
color: "#d9c62b"
brightness: 5
castsShadow: true
shadowFactor: 75
Model {
source: "#Cube"
scale: Qt.vector3d(0.01, 0.01, 0.01)
materials: PrincipledMaterial {
lighting: PrincipledMaterial.NoLighting
}
}
}Otro truco que utilizamos aquí es desactivar la iluminación del material utilizado en el cubo. Así aparecerá simplemente con el color base predeterminado (blanco), sin verse afectado por la iluminación. Esto resulta muy útil para objetos utilizados con fines de depuración y visualización.
El resultado: fíjate en el pequeño cubo blanco que aparece, que muestra la posición del « PointLight »:

Skybox e iluminación basada en imágenes
Otra mejora obvia es hacer algo con el fondo. Ese color verde claro no es precisamente ideal. ¿Qué tal un entorno que también contribuya a la iluminación?
Como no disponemos necesariamente de una imagen panorámica HDRI adecuada, utilicemos una imagen de cielo de alto rango dinámico generada proceduralmente. Esto es fácil de hacer gracias a la compatibilidad de ProceduralSkyTextureData y Texture con datos de imagen generados dinámicamente y no basados en archivos. En lugar de especificar source, utilizaremos la propiedad textureData.
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.SkyBox
lightProbe: Texture {
textureData: ProceduralSkyTextureData {
}
}
}Nota: El código de ejemplo prefiere definir los objetos en línea. Esto no es obligatorio; los objetos SceneEnvironment o ProceduralSkyTextureData también podrían haberse definido en otra parte del árbol de objetos y, a continuación, referenciarse mediante id.
Como resultado, disponemos tanto de un skybox como de una iluminación mejorada. (Lo primero se debe a que backgroundMode está establecido en SkyBox y light probe en un Texture válido; lo segundo, a que light probe está establecido en un Texture válido).


Análisis básicos del rendimiento
Para obtener una visión básica de los aspectos relacionados con los recursos y el rendimiento de la escena, es recomendable añadir desde el principio del proceso de desarrollo una forma de mostrar un elemento interactivo de tipo « DebugView ». En este caso, optamos por añadir un « Button » que alterna el « DebugView », ambos anclados en la esquina superior derecha.
import QtQuick
import QtQuick.Controls
import QtQuick3D
import QtQuick3D.Helpers
Item {
width: 1280
height: 720
View3D {
id: view3D
anchors.fill: parent
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.SkyBox
lightProbe: Texture {
textureData: ProceduralSkyTextureData {
}
}
}
PerspectiveCamera {
id: camera
y: 100
}
DirectionalLight {
}
Sponza {
scale: Qt.vector3d(100, 100, 100)
}
PointLight {
y: 200
color: "#d9c62b"
brightness: 5
castsShadow: true
shadowFactor: 75
Model {
source: "#Cube"
scale: Qt.vector3d(0.01, 0.01, 0.01)
materials: PrincipledMaterial {
lighting: PrincipledMaterial.NoLighting
}
}
}
Suzanne {
y: 100
scale: Qt.vector3d(50, 50, 50)
NumberAnimation on eulerRotation.y {
from: 0
to: 360
duration: 3000
loops: Animation.Infinite
}
}
WasdController {
controlledObject: camera
}
}
Button {
anchors.right: parent.right
text: "Toggle DebugView"
onClicked: debugView.visible = !debugView.visible
DebugView {
id: debugView
source: view3D
visible: false
anchors.top: parent.bottom
anchors.right: parent.right
}
}
}
Este panel muestra los tiempos en tiempo real, permite examinar la lista en tiempo real de mapas de texturas y mallas, y ofrece información sobre las pasadas de renderizado que deben realizarse antes de que se pueda renderizar el búfer de color final.
Debido a que el « PointLight » es una luz que proyecta sombras, hay varias pasadas de renderizado implicadas:

En la sección « Textures » vemos los mapas de textura de los activos «Suzanne» y «Sponza» (este último tiene muchos), así como la textura del cielo generada proceduralmente.

La página « Models » no presenta sorpresas:

En la página « Tools » hay algunos controles interactivos para activar o desactivar « wireframe mode » y varios « material overrides ».
Aquí, con el modo de estructura de alambre activado y forzando el renderizado para que utilice únicamente el componente « base color » de los materiales:

Con esto concluye nuestro recorrido por los conceptos básicos de la creación de una escena 3D de «Qt Quick » con recursos importados.
© 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.