En esta página

Portar « Qt 3D » a « Qt Quick 3D»: una guía de migración

Esta guía está dirigida a los desarrolladores que actualmente utilizan Qt 3D y que deseen migrar a Qt Quick 3D.

Diferencias de ámbito

Aunque Qt 3DQt Quick y 3D puedan parecer similares, ya que ambos proporcionan API 3D, están diseñados con enfoques fundamentalmente diferentes.

Qt 3D es una API flexible para implementar renderizadores 3D personalizados, que ofrece abstracciones de bajo nivel para los distintos aspectos del proceso de renderizado. Como resultado, Qt 3D proporciona API tanto para C++ como para QML.

Por el contrario, « Qt Quick 3D» es una API de alto nivel centrada en el renderizado de contenido 3D y diseñada como una extensión de « Qt Quick ». En consecuencia, la mayoría de sus API están basadas en QML. Por lo tanto, si tu aplicación actual de « Qt 3D » depende en gran medida de C++, la migración a « Qt Quick 3D» requerirá pasar a QML.

Diferencias arquitectónicas

Qt 3D y Qt Quick 3D difieren significativamente en su arquitectura. Qt Quick 3D sigue los mismos patrones de diseño que Qt Quick, ampliando sus capacidades para admitir el renderizado 3D.

La primera diferencia importante radica en el uso de los patrones de diseño. Qt 3D utiliza un patrón de sistema de entidades y componentes (ECS). En este sistema, se emplea una clase de entidad genérica, que puede especializarse añadiendo diversos componentes a la entidad, siguiendo un patrón de composición. Por el contrario, Qt Quick 3D utiliza una API basada en la herencia que se alinea con el marco más amplio de Qt, donde los nodos especializados son subclases de una clase base común. Debido a estas diferencias fundamentales, no existe una correspondencia directa 1:1 entre las dos API.

Otra diferencia significativa radica en los modelos de subprocesos. Qt 3D introduce el concepto de «aspectos», que proporcionan diferentes puntos de entrada para diversos tipos de componentes asociados a las entidades. Cada aspecto puede crear tareas que son procesadas por un grupo de subprocesos, siguiendo un árbol de proveedores y dependencias para completar todo el trabajo necesario para renderizar un fotograma. Por otro lado, Qt Quick 3D utiliza el mismo modelo de subprocesos que Qt Quick. Cuenta con una API de interfaz, accesible desde el subproceso principal de la interfaz gráfica de usuario (GUI) para gestionar el estado de la escena, y una API de fondo en el subproceso de renderizado. Aunque el subproceso de renderizado puede utilizar subprocesos adicionales para determinadas tareas, el modelo conceptual desde la perspectiva del usuario implica únicamente dos subprocesos. No existe un concepto diferenciado de «aspectos» en Qt Quick 3D, aunque gran parte de la funcionalidad que ofrecen los aspectos de Qt 3D sigue estando disponible.

Desde el punto de vista del renderizado, Qt 3D ofrece un enfoque altamente personalizable, lo que permite la creación de flujos de renderizado a medida. Sin embargo, esta flexibilidad conlleva cierta complejidad; por defecto, Qt 3D no proporciona un flujo de renderizado preconfigurado. Por el contrario, Qt Quick 3D está diseñado para ser más intuitivo, con un proceso de renderizado listo para usar que se adapta automáticamente a las necesidades de la escena. Por ejemplo, si una luz direccional en Qt Quick 3D se configura para proyectar sombras, el proceso de renderizado incluirá automáticamente una pasada de generación de mapas de sombras, que luego utilizarán los materiales de la escena. En Qt 3D, dicha funcionalidad requeriría una configuración manual del gráfico de fotogramas y una ampliación de los materiales para que admitan la pasada de mapeo de sombras. Además, para diferentes tipos de luz, como las luces puntuales o los focos, serían necesarias modificaciones adicionales en el gráfico de fotogramas y en las definiciones de los materiales. Aunque Qt 3D ofrece potentes opciones de personalización para las técnicas de mapeo de sombras, esto puede suponer una sobrecarga significativa en comparación con Qt Quick 3D, donde habilitar las sombras es tan sencillo como configurar una única propiedad en una luz.

Detalles por módulo

Qt 3D Núcleo

El módulo «Core» de Qt 3D proporciona las primitivas fundamentales sobre las que se construyen otros módulos de Qt 3D. La mayoría de las clases del módulo «Core» de Qt 3D tienen componentes equivalentes en Qt Quick 3D, salvo aquellas clases que admiten específicamente la arquitectura Entity-Component-System (ECS). Qt Quick 3D ofrece componentes preconfigurados que se corresponden con combinaciones comunes de entidad-componente utilizadas en Qt 3D, lo que simplifica el proceso de desarrollo.

A modo de ejemplo, esta es la configuración de una entidad renderizable en Qt3D:

PhongMaterial {
    id: material
}

TorusMesh {
    id: torusMesh
    radius: 5
    minorRadius: 1
    rings: 100
    slices: 20
}

Transform {
    id: torusTransform
    scale3D: Qt.vector3d(1.5, 1, 0.5)
    rotation: fromAxisAndAngle(Qt.vector3d(1, 0, 0), 45)
}

Entity {
    id: torusEntity
    components: [ torusMesh, material, torusTransform ]
}

En el código anterior se puede ver que la entidad se compone de una malla, un material y una transformación. En Qt Quick 3D, el código equivalente tendría este aspecto:

Model {
    id: torusModel
    scale: Qt.vector3d(1.5, 1, 0.5)
    eulerRotation.x: 45
    geometry: TorusGeometry {
        radius: 5
        tubeRadius: 1
        rings: 100
        segments: 20
    }
    materials: [
        PrincipledMaterial {
            id: material
    ]
}

En este ejemplo, la entidad se sustituye por un « Model », que es una subclase del componente « Node », el cual hereda el equivalente al componente « Transform » de Qt 3D. Además, cualquier subclase de «Node» formará parte de un grafo de escena, con relaciones padre-hijo. El componente «Model» es una entidad renderizable que puede tener una geometría y uno o varios materiales. En este caso utilizamos la propiedad « geometry » para que coincida con la API procedural utilizada por el código de « Qt 3D », pero también es posible especificar la geometría a partir de un archivo estático utilizando la propiedad « source ». La propiedad « materials » del componente «Model» es una lista de materiales que se utilizarán para sombrear la geometría. Se trata de una lista porque es posible que las geometrías contengan varios subconjuntos, cada uno de los cuales puede utilizar un material distinto. El componente « PrincipledMaterial » es un material PBR (renderizado basado en la física) que utiliza el flujo de trabajo «Metallic-Roughness» y, en el caso de este ejemplo, sustituye al « PhongMaterial » utilizado por el fragmento de código « Qt 3D ».

Qt 3D Input

Qt 3D ofrece una variedad de clases de entrada a través de su propio sistema de entrada personalizado. Por el contrario, Qt Quick 3D reutiliza principalmente clases de entrada de Qt Quick. Para interactuar con una escena 3D, Qt Quick 3D proporciona API adicionales para realizar el lanzamiento de rayos y la selección de objetos.

View3D es la clase principal para gestionar operaciones de selección en Qt Quick 3D, y ofrece métodos de selección tanto explícitos como implícitos. La API de selección explícita permite seleccionar directamente desde el espacio 2D especificando las coordenadas x e y en View3D. Esta operación devuelve un valor de pickResult que contiene detalles sobre el objeto alcanzado y la ubicación del impacto. La API es síncrona, lo que significa que el resultado está disponible inmediatamente después de lanzar el rayo. Además, es posible lanzar rayos desde cualquier punto de la escena. Tanto el método de selección explícito como el implícito pueden devolver una lista de todas las colisiones, no solo la primera.

import QtQuick
import QtQuick.Controls
import QtQuick3D

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    View3D {
        id: view
        anchors.fill: parent

        PerspectiveCamera {
            z: 200
        }

        DirectionalLight {

        }

        PrincipledMaterial {
            id: material
            baseColor: "red"
        }
        PrincipledMaterial {
            id: selectedMaterial
            baseColor: "blue"
        }

        Model {
            id: sphereModel
            source: "#Sphere"
            pickable: true
            materials: [
                material
            ]
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: (mouse) => {
            let result = view.pick(mouse.x, mouse.y)
            if (result.hitType == PickResult.Model) {
                if (result.objectHit == sphereModel) {
                    // toggle selection
                    if (sphereModel.materials[0] == material)
                        sphereModel.materials[0] = selectedMaterial
                    else
                        sphereModel.materials[0] = material
                }
            } else {
                // deselect
                sphereModel.materials[0] = material
            }
        }
    }
}

En este fragmento de código de ejemplo, se crea una escena sencilla con un modelo de esfera. El modelo de esfera se configura como « pickable », lo que significa que, cuando se proyecte un rayo en la escena, este modelo se tendrá en cuenta para la selección. Sobre el « View3D » hay un « MouseArea » que detecta los clics. Cuando se detecta un clic, se invoca el método pick con las coordenadas x e y del clic. A continuación, el resultado de la operación de selección se utiliza para determinar si se ha seleccionado el modelo de esfera. Si es así, el material del modelo de esfera cambia entre el rojo y el azul.

import QtQuick
import QtQuick.Controls
import QtQuick3D

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    View3D {
        id: view
        anchors.fill: parent

        Node {
            eulerRotation.y: 45
            PerspectiveCamera {
                z: 200

            }
        }

        DirectionalLight {

        }

        Node {
            id: anchorItem
            Item {
                anchors.centerIn: parent
                width: 250
                height: 250
                Button {
                    anchors.centerIn: parent
                    text: "Click Me"
                }

            }
        }
    }
}

En este fragmento de código de ejemplo, se crea una escena sencilla con un « Button » en el centro de la pantalla. El botón es un elemento 2D, pero como su elemento padre es un ` Node`, se proyectará en el espacio 3D. Se puede interactuar con estos componentes de la misma forma que en el espacio 2D. ` View3D ` se encargará automáticamente de lanzar rayos hacia la escena y de reenviar los eventos de entrada a cualquier elemento 2D que forme parte de la escena.

import QtQuick
import QtQuick.Controls
import QtQuick3D

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    View3D {
        id: view
        anchors.fill: parent

        Node {
            eulerRotation.y: 25
            PerspectiveCamera {
                z: 200

            }
            DirectionalLight {

            }
        }

        Model {
            source: "#Cube"
            pickable: true
            materials: [
                PrincipledMaterial {
                    baseColorMap: Texture {
                        sourceItem: Pane {
                            width: 250
                            height: 250
                            Button {
                                anchors.centerIn: parent
                                text: "Click Me"
                            }
                        }
                    }
                }
            ]
        }
    }
}

De forma similar, en el fragmento de código anterior, se crea un cubo Model con una textura que es un Pane que contiene un Button. En este caso, se crea un Texture de 250x250 píxeles renderizando un componente Pane que contiene un Button. Normalmente, esta textura no sería interactiva, pero al establecer pickable en «true» en el Model, se utilizará el mismo mecanismo de selección implícito que reenviaba los eventos de entrada al Button en el ejemplo anterior para reenviar los eventos de entrada al Button en este ejemplo. En el caso del cubo Model, cada cara del cubo será ahora interactiva con el Button.

La mayoría de las clases de entrada de Qt 3D no son directamente trasladables a Qt Quick 3D, por lo que se requiere cierto esfuerzo de adaptación; sin embargo, el mecanismo de selección implícito de Qt Quick 3D facilita la interacción con elementos 2D en una escena 3D.

Qt 3D Lógica

El módulo «Logic» de Qt 3D contiene un único componente que proporciona una llamada de retorno para cada fotograma renderizado. En Qt Quick 3D, el enfoque equivalente consiste en utilizar el componente « FrameAnimation », un componente general de Qt Quick que proporciona información de sincronización y un mecanismo de llamada de retorno para cada fotograma renderizado.

FrameAnimation {
    running: true
    onTriggered: {
        console.log(`currentFrame: ${currentFrame}, frameTime: ${frameTime}`)
    }
}

Este componente se puede utilizar en cualquier parte de la escena, incluso como elemento secundario de un objeto en el que se desee realizar alguna acción en cada fotograma.

No obstante, cabe señalar que este patrón solo es necesario cuando se desea realizar alguna acción en cada fotograma. Aunque « FrameAnimation » permite recrear el comportamiento de sondeo de algunos motores de juego, también es posible utilizar en « Qt Quick 3D» los mismos patrones basados en eventos que en « Qt Quick ».

Qt 3D Render

El módulo Render de Qt 3D contiene la mayoría de las clases esenciales necesarias para el renderizado. En Qt Quick 3D, la mayor parte de la funcionalidad equivalente se proporciona como detalles de implementación interna que no se exponen directamente al usuario. Sin embargo, hay algunas clases que se exponen al usuario como API y que pueden utilizarse para ampliar y personalizar la funcionalidad de Qt Quick 3D.

Geometría

Los datos de geometría o malla en Qt 3D se representan mediante la clase ` QGeometryRenderer ` o el componente ` GeometryRenderer `. En Qt Quick 3D, los equivalentes son la clase ` QQuick3DGeometry ` y el componente ` ProceduralMesh `. En Qt 3D, la clase ` QGeometryRenderer ` es de nivel inferior y espera que el usuario proporcione las disposiciones de los atributos de vértice como parte de los datos de geometría. En Qt Quick 3D, puedes controlar qué atributos de vértice integrados se van a utilizar, pero la disposición de los búferes se gestiona internamente como detalles de implementación.

Para obtener más detalles sobre cómo se hace esto, consulta el ejemplo de geometría personalizada deQt Quick 3D.

Texturas

Las texturas en Qt 3D están representadas por las subclases de QAbstractTexture. En Qt Quick 3D, el equivalente es el componente Texture, que es la representación de interfaz de usuario de una textura y un muestreador. No obstante, los datos utilizados por el componente de textura pueden proceder de diversas fuentes. La forma más sencilla es simplemente establecer la propiedad ` source ` en un archivo de imagen, que se cargará en la GPU como datos de textura. También es posible generar datos de textura de forma procedural en tiempo de ejecución, ya sea utilizando contenido QML 2D como fuente, creando una subclase de ` QQuick3DTextureData ` o utilizando el componente ` ProceduralTextureData `. Estos tipos permiten especificar los datos de textura indicando el tamaño, el formato y los datos de imagen sin procesar. También existe la posibilidad de crear texturas en la GPU mediante el uso de ` render extensions`.

Para obtener más detalles sobre cómo se hace esto, consulta el ejemplo de textura procedimental 3D deQt Quick .

Materiales

Aunque en Qt 3D era posible utilizar algunos materiales integrados, al hacerlo te veías limitado a los framegraphs integrados con los que podían funcionar. Qt Quick 3D presenta una situación similar, ya que ofrece una selección de materiales integrados que funcionan con la estrategia de renderizado interna. Sin embargo, tanto en Qt 3D como en Qt Quick 3D es posible crear materiales personalizados.

En Qt 3D, este era un proceso bastante complejo que implicaba un árbol de QMaterial, QEffect, QTechnique, QRenderPass y QShaderProgram. En Qt Quick 3D, para los materiales este proceso se simplifica a un único componente CustomMaterial. Este componente te permite especificar código de sombreador personalizado para el material, y el resto de la configuración la realiza el renderizador. Hay dos modos para CustomMaterial: con sombreado y sin sombreado. En el modo con sombreado, la API de código de sombreador personalizado te permite personalizar el sombreador integrado de PrincipledMaterial, mientras que en el modo sin sombreado puedes escribir tu propio código de sombreador desde cero. En ambos casos, el lenguaje de sombreador es GLSL, con algunas extensiones de palabras clave específicas de Qt para facilitar la integración con el resto de la API Qt Quick 3D.

Para obtener más detalles sobre cómo se hace esto, consulta los ejemplos de «Modo sombreado » y «Modo sin sombreado », así como esta descripción general sobre el uso del lenguaje de sombreadores GLSL personalizado de « Qt Quick 3D».

Efectos

Desde la perspectiva de Qt3D, no hay diferencia entre renderizar una escena 3D y renderizar efectos de posprocesamiento, y desde una perspectiva de bajo nivel esto es correcto. Sin embargo, Qt Quick 3D establece una distinción. Models parte de una escena 3D contendrá una lista de materials, y estos se renderizan durante las pasadas principales. El resultado de estas pasadas principales es el contenido 3D renderizado, ya sea directamente en la superficie de una ventana o en una textura. Effects se diferencian en que, en Qt Quick 3D, se refieren a efectos de posprocesamiento en los que cada pass acaba siendo un único cuadrilátero que cubre todo el objetivo de renderizado. La textura resultante de la pasada de color principal se pasa entonces a la primera pasada de efectos como textura, y el resultado de esa pasada se pasa a su vez a la siguiente pasada Effect como textura, y así sucesivamente. A continuación, el paso final se renderiza en el destino de renderizado de salida, que suele ser la superficie de la ventana. Algunos Effects requieren un « buffers » creado durante los pasos principales, como la textura de profundidad, y otros requerirán pasos intermedios, todos los cuales pueden definirse mediante las API de efectos de Qt Quick 3D.

Qt Quick 3D optimiza esta cadena de efectos de posprocesamiento con API que te permiten definir tantos pases de renderizado como necesites para conseguir el efecto deseado.

Para obtener más detalles sobre cómo se hace esto, consulta el ejemplo de posprocesamiento de 3D «Qt Quick ».

Búferes de instancias

En Qt 3D, el uso de la instanciación y los búferes de instancia es bastante básico, por lo que su aplicación dependerá del caso de uso específico. En « Qt Quick » 3D, los materiales integrados tienen algunas propiedades de instanciación fijas que se pueden configurar, pero para ello es necesario proporcionar los datos de instancia como un búfer. Hay varias formas de proporcionar estos datos y, una vez proporcionados, solo hay que configurar la propiedad « instancing » en el componente « Model » para asociar los datos del búfer de instancia con lo que se desea instanciar.

Para obtener más detalles, consulta este artículo específico sobre la instanciación en Qt Quick 3D.

Extensiones del renderizador

El objetivo de Qt 3D es ofrecer una forma eficaz de definir una solución de renderizado personalizada para tu aplicación. Qt Quick 3D no ofrece este nivel de personalización, ya que su objetivo es ser fácil de usar en lugar de fácil de personalizar, pero sí proporciona algunas formas de ampliar el proceso de renderizado, además de todas las mencionadas anteriormente. Esto se consigue implementando render extensions, que te permiten añadir pasadas de renderizado personalizadas al renderizador utilizando los mismos datos que este. Se trata de una API de bajo nivel que requiere un buen conocimiento del proceso de renderizado de Qt Quick 3D, así como de la API de Qt Rendering Hardware Interface (RHI).

Para ver un ejemplo de cómo se hace esto, consulta el ejemplo de la extensión «Stencil Outline».

Qt 3D Extras

El módulo « Qt 3D » Extras proporciona diversas utilidades para facilitar una experiencia «lista para usar», como materiales, generadores de geometría y controladores de cámara. También incluye un grafo de fotogramas del renderizador directo. En Qt Quick 3D, no es necesario definir explícitamente un grafo de fotogramas; en su lugar, este se genera automáticamente en función de los requisitos de la escena.

Materiales integrados

En « Qt Quick » 3D, los materiales se proporcionan bien mediante el uso de « PrincipledMaterial » o « SpecularGlossyMaterial », bien definiendo un « CustomMaterial » con código de sombreador personalizado. El « PrincipledMaterial » es un sombreador PBR (renderizado basado en la física) que utiliza el flujo de trabajo «Metallic-Roughness». La complejidad del sombreador generado aumenta en función de las propiedades establecidas por el usuario y del contenido de la escena. Por ejemplo, si una luz proyecta sombras, el shader generado incluirá código para la recepción de sombras; si hay una sonda de luz o una sonda de reflexión, el shader incorporará esa información de iluminación. Esta adaptación dinámica también se aplica a los « CustomMaterial » en modo sombreado. Sin embargo, los shaders « CustomMaterial » sin sombreado no tienen en cuenta automáticamente la información de la escena, como la iluminación.

Ayudas geométricas

Al igual que Qt 3D, Qt Quick 3D también ofrece numerosas primitivas geométricas integradas, así como muchos generadores de geometría procedural.

La siguiente tabla muestra una correspondencia entre las clases geométricas de Qt 3D y sus equivalentes en Qt Quick 3D:

Qt 3DQt Quick 3D
ConeMeshConeGeometry
CuboidMeshCuboidGeometry
CylinderMeshCylinderGeometry
ExtrudedTextMeshExtrudedTextGeometry
Malla de planoPlaneGeometry
Malla esféricaSphereGeometry
Malla de toroTorusGeometry

Controladores de cámara

Para el control de cámaras, Qt Quick 3D ofrece opciones comparables a las de OrbitCameraController y WasdController. El controlador « WasdController » es similar al « FirstPersonCameraController » de Qt3D, pero puede controlar cualquier elemento de la escena, no solo las cámaras.

Qt 3D Animación

El módulo de animación de Qt 3D define cómo se gestionan los diferentes tipos de animaciones en 3D. En Qt Quick 3D, la funcionalidad equivalente se distribuye entre varios módulos, a menudo aprovechando las clases existentes de Qt Quick siempre que es posible. Por ejemplo, puedes utilizar las diversas clases de animación de la importación QtQuick para animar propiedades de nodos 3D.

Al importar animaciones desde herramientas de creación de contenido 3D, estas suelen definirse mediante líneas de tiempo. El módulo «Qt Quick » Timeline proporciona las clases necesarias para definir dichas animaciones, y cualquier contenido importado que incluya animaciones requerirá este módulo para funcionar.

Además de las transformaciones básicas (como la traslación, la rotación y el escalado) de los elementos de una escena, Qt Quick 3D admite animaciones basadas en armaduras, en las que se animan los huesos de un esqueleto, lo que afecta a los vértices asociados a cada articulación u hueso. Esto se consigue mediante el componente Skin, que conecta los objetos Node que representan los huesos de la escena con los pesos de hueso correspondientes en una geometría de Model's. En este caso, la animación del esqueleto se realiza animando los huesos mediante transformaciones.

Qt Quick 3D también admite animaciones de objetivos de transformación, en las que se pueden animar directamente los cambios en la geometría de un modelo. Los objetivos de transformación son instantáneas predefinidas de la geometría de un modelo, y se puede animar entre ellas utilizando el componente MorphTarget.

Para combinar varias animaciones o fusionarlas, se utilizan los componentes del módulo « Qt Quick Timeline Blend Trees». Este módulo permite definir árboles complejos para gestionar la forma en que interactúan las diferentes animaciones. La mayoría de estas clases de animación genéricas no son específicas de Qt Quick 3D, sino que forman parte del marco más amplio de Qt Quick, aprovechando la funcionalidad existente en lugar de introducir nuevos métodos.

Qt 3D Scene2D

En Qt 3D, el componente Scene2D se utiliza para renderizar escenas 2D de Qt Quick en texturas que pueden utilizarse dentro de una escena 3D. En Qt Quick 3D, esto se consigue mediante la propiedad « sourceItem » del componente « Texture ». La propiedad «sourceItem» puede hacer referencia a un « Item » existente o definir un elemento en línea. El elemento de nivel superior determina el tamaño de la textura, y la escena Qt Quick se renderiza en una capa que se asigna al componente « Texture ».

Además, es posible utilizar componentes « Item-based » directamente dentro de una escena 3D, donde se proyectan en el espacio 3D sin necesidad de una textura.

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