En esta página

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
        }
    }
}

Vista 3D vacía con fondo verde

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:

Lista de archivos que muestra los archivos de recursos de Sponza

¿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:

Panel de configuración de Balsam UI

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:

Interior del Palacio Sponza con iluminación direccional

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

El palacio Sponza visto desde otro ángulo

El palacio Sponza visto desde fuera

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:

Ventana de inicio de Balsam UI

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

Explorador de archivos que muestra los archivos de recursos de Suzanne

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.

Interfaz de usuario de Balsam que muestra la conversión en curso

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.

Modelo «Suzanne» con cabeza de mono en una escena oscura

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:

Suzanne con iluminación adicional

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 »:

Cabeza de mono de Suzanne en el suelo del Palacio Sponza

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).

El Palacio Sponza con iluminación basada en imágenes

El palacio Sponza con una orientación diferente respecto a la IBL

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
        }
    }
}

Escena de Sponza con el panel de vista de depuración, en el que se muestran las estadísticas de rendimiento

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:

Suzanne con el panel de depuración, en el que se muestran las pasadas de renderizado

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.

Escena con el panel de depuración en la que se muestran las estadísticas de texturas

La página « Models » no presenta sorpresas:

Escena con el panel de depuración en la que se muestran las estadísticas de la malla

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:

Escena de Sponza en modo de estructura alámbrica con panel de depuración

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.