Migración de Qt 3D a Qt Quick 3D: Guía de migración

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

Diferencias de alcance

Mientras que Qt 3D y Qt Quick 3D pueden parecer similares, ya que ambas proporcionan API 3D, están diseñadas 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 contenidos 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 su aplicación actual Qt 3D depende en gran medida de C++, la migración a Qt Quick 3D requerirá la transición 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 soportar el renderizado 3D.

La primera gran diferencia radica en el uso de patrones de diseño. Qt 3D utiliza un patrón Entity-Component System (ECS). En este sistema, se utiliza una clase de entidad genérica, que puede especializarse añadiendo diversos componentes a la entidad, siguiendo un patrón de composición. En cambio, Qt Quick 3D utiliza una API basada en la herencia que se ajusta al 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 ambas API.

Otra diferencia significativa está en los modelos de hilos. Qt 3D introduce el concepto de Aspectos, que proporcionan diferentes puntos de entrada para varios tipos de componentes adjuntos a entidades. Cada aspecto puede crear tareas que son procesadas por un grupo de hilos, 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 hilos que Qt Quick. Tiene una API frontend, accesible desde el hilo principal de la GUI para gestionar el estado de la escena, y una API backend en el hilo de renderizado. Aunque el hilo de renderizado puede utilizar hilos adicionales para ciertas tareas, el modelo conceptual desde la perspectiva del usuario implica sólo dos hilos. En Qt Quick 3D no existe un concepto diferenciado de aspecto, aunque gran parte de la funcionalidad proporcionada por los aspectos de Qt 3D sigue estando disponible.

Desde el punto de vista del renderizado, Qt 3D ofrece un enfoque altamente personalizable, que permite la creación de pipelines de renderizado a medida. Sin embargo, esta flexibilidad conlleva complejidad; por defecto, Qt 3D no proporciona un canal de renderizado preconfigurado. Por el contrario, Qt Quick 3D está diseñado para ser más fácil de usar, con un canal de renderizado preconfigurado que se adapta automáticamente a las necesidades de la escena. Por ejemplo, si una luz direccional de Qt Quick 3D está configurada 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, esta funcionalidad requeriría la configuración manual del gráfico de tramas y la ampliación de los materiales para que admitan el pase de generación de mapas de sombras. Además, para distintos tipos de luz, como las puntuales o los focos, sería necesario modificar el gráfico de tramas y las definiciones de los materiales. Mientras que Qt 3D ofrece potentes opciones de personalización para las técnicas de mapeado de sombras, esto puede resultar en una sobrecarga significativa en comparación con Qt Quick 3D, donde habilitar las sombras es tan simple como establecer una sola propiedad en una luz.

Detalles por módulo

Qt 3D Núcleo

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

Como ejemplo esta es la configuración para 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 se vería así:

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 que hereda el equivalente del componente Transform de Qt 3D. Además cualquier subclase de Nodo formará parte de un grafo de escena, con relaciones padre-hijo. El componente Modelo es una entidad renderizable que puede tener una geometría y material(es). En este caso utilizamos la propiedad geometry para que coincida con la API de procedimiento utilizada por el código Qt 3D, pero también es posible especificar la geometría desde un archivo estático utilizando la propiedad source. La propiedad materials del componente Modelo 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 múltiples subconjuntos, cada uno de los cuales puede utilizar un material distinto. El componente PrincipledMaterial es un material PBR (Physically Based Rendering) que utiliza el flujo de trabajo Metallic-Roughness, y en el caso de este ejemplo sustituye al PhongMaterial utilizado por el fragmento Qt 3D.

Qt 3D Entrada

Qt 3D proporciona una serie de clases de entrada a través de su propio sistema de entrada personalizado. En cambio, Qt Quick 3D reutiliza principalmente las clases de entrada de Qt Quick. Para interactuar con una escena 3D, Qt Quick 3D proporciona APIs adicionales para realizar ray casting y picking de objetos.

View3D es la clase principal para manejar las operaciones de picking en Qt Quick 3D, ofreciendo métodos de picking explícitos e 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 pickResult que contiene detalles sobre el objeto golpeado y su ubicación. La API es sincrónica, 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 los métodos de selección explícitos como implícitos pueden devolver una lista de todos los impactos, no sólo del primero.

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 simple con un modelo de esfera. El modelo de esfera está configurado en pickable, lo que significa que cuando se lanza un rayo a la escena, este modelo será considerado para la selección. Encima de View3D hay un MouseArea que escucha los clics. Cuando se detecta un clic, se llama al método pick con las coordenadas x e y del clic. El resultado de la operación de recogida se utiliza para determinar si el modelo de la esfera fue golpeado. Si lo fue, el material del modelo de la esfera se alterna entre los materiales rojo y 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 simple con un Button en el centro de la pantalla. El botón es un elemento 2D, pero como su padre es un Node, se proyectará en el espacio 3D. Tales componentes pueden ser interactuados de la misma manera que en el espacio 2D. View3D manejará automáticamente el lanzamiento de rayos en la escena y el reenvío de 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"
                            }
                        }
                    }
                }
            ]
        }
    }
}

Del mismo modo, 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 mediante el renderizado de un componente Pane que contiene un Button. Normalmente, esta textura no sería interactiva, pero al establecer pickable como verdadero en Model, el mismo mecanismo de selección implícito que reenvió eventos de entrada a Button en el ejemplo anterior se utilizará para reenviar eventos de entrada a Button en este ejemplo. En el caso del cubo Model, cada cara del cubo será ahora interactiva con Button.

La mayoría de las clases de entrada en Qt 3D no son directamente traducibles a Qt Quick 3D, por lo que se requiere algún esfuerzo de portabilidad, pero el mecanismo de picking implícito en Qt Quick 3D hace que sea fácil interactuar con elementos 2D en una escena 3D.

Qt 3D Lógica

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

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

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

Vale la pena señalar, sin embargo, que este patrón sólo es necesario cuando se desea realizar alguna acción en cada fotograma. Mientras que FrameAnimation hace posible recrear el comportamiento de sondeo en algunos motores de juego también es posible utilizar los mismos patrones de conducción de eventos en Qt Quick 3D que en Qt Quick.

Qt 3D Renderizado

El módulo Qt 3D Render contiene la mayoría de las clases críticas 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 están expuestas al usuario como API que se pueden utilizar para ampliar y personalizar la funcionalidad de Qt Quick 3D.

Geometría

En Qt 3D, los datos geométricos o de malla 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, tienes el control sobre qué atributos de vértice incorporados utilizar, pero la disposición de los búferes se maneja internamente como detalles de implementación.

Para más detalles sobre cómo se hace esto, echa un vistazo a Qt Quick 3D Custom Geometry Example.

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 frontend de una textura y un muestreador. Sin embargo, los datos utilizados por el componente de textura pueden proceder de diversas fuentes. La forma más sencilla es 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 procedimental en tiempo de ejecución, bien utilizando contenido qml 2D como fuente, bien subclasificando QQuick3DTextureData o utilizando el componente ProceduralTextureData. Estos tipos permiten especificar los datos de textura proporcionando 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 más detalles sobre cómo se hace esto, echa un vistazo a Qt Quick 3D Procedural Texture Example.

Materiales

Si bien era posible utilizar algunos materiales incorporados en Qt 3D, al hacerlo estabas limitado a los incorporados en framegraphs con los que podían trabajar. Qt Quick 3D es una situación similar en el sentido de que proporciona una selección de materiales incorporados que funcionan con la estrategia de render interno. Sin embargo, tanto en Qt 3D como en Qt Quick 3D es posible crear materiales personalizados.

En Qt 3D, esto era un proceso bastante complicado 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 permite especificar un código de sombreado personalizado para el material, y el resto de la configuración la realiza el renderizador. Hay dos modos para CustomMaterial, sombreado y sin sombrear. En el modo sombreado, la API de código de sombreado personalizado te permite personalizar el sombreador incorporado en PrincipledMaterial, y en el modo sin sombreado puedes escribir tu propio código de sombreado desde cero. En ambos casos, el lenguaje de sombreado 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 más detalles sobre cómo se hace esto, echa un vistazo a los ejemplos de modo sombreado y modo sin sombrear, así como a esta visión general sobre el uso del lenguaje de sombreado GLSL personalizado de Qt Quick 3D.

Efectos

Desde la perspectiva de Qt3D, no hay diferencia entre renderizar una escena 3D y renderizar efectos de post-procesado, y desde una perspectiva de bajo nivel esto es correcto. Sin embargo hay una distinción hecha por Qt Quick 3D. Models parte de una escena 3D contendrá una lista de materials, y estos se renderizan durante los pases principales. El resultado de estos pases principales es el contenido 3D renderizado, ya sea directamente en una superficie de ventana o en una textura. Effects son diferentes en el sentido de que en Qt Quick 3D se refieren a efectos de postprocesado en los que cada pass acaba siendo un único quad que cubre todo el objetivo de renderizado. La textura resultante del pase de color principal se pasa al primer pase de efecto como textura, y el resultado de ese pase se pasa al siguiente pase de Effect como textura, y así sucesivamente. El pase final se renderiza en el destino de render de salida, que suele ser la superficie de la ventana. Algunos Effects requieren buffers creados durante los pases principales, como la textura de profundidad, y otros requerirán pasos intermedios, todos los cuales pueden ser definidos usando las APIs de Efectos en Qt Quick 3D.

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

Para más detalles sobre cómo se hace esto, echa un vistazo a Qt Quick 3D Post Processing Example.

Búferes de instancia

En Qt 3D, el uso de instancias y buffers de instancia es de bajo nivel, por lo que su uso dependerá del caso de uso específico. En Qt Quick 3D, los materiales incorporados tienen algunas propiedades fijas de instanciación que se pueden establecer, pero para ello es necesario proporcionar los datos de instancia como un búfer. Hay varias maneras de proporcionar estos datos y una vez que se proporciona, es sólo una cuestión de establecer la propiedad instancing en el componente Model para asociar los datos de búfer de instancia con lo que desea instancia.

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

Extensiones del renderizador

El propósito de Qt 3D es proporcionar una forma potente de definir una solución de renderizado personalizada para su aplicación. Qt Quick 3D no proporciona 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 extender la tubería de renderizado, además de todas las formas mencionadas anteriormente. Esto se hace mediante la implementación de render extensions, que le permite añadir pases de renderizado personalizados al renderizador utilizando los mismos datos que el renderizador. Se trata de una API de bajo nivel que requiere un buen conocimiento del proceso de renderizado 3D de Qt Quick, así como de la API Qt Rendering Hardware Interface (RHI).

Para ver un ejemplo de cómo se hace, consulte el Ejemplo de extensión del contorno del esténcil.

Qt 3D Extras

El módulo Qt 3D Extras proporciona varias utilidades para facilitar una experiencia "out-of-the-box", como materiales, generadores de geometría y controladores de cámara. También incluye un gráfico de fotogramas del renderizador. En Qt Quick 3D, no es necesario definir explícitamente un gráfico de tramas; en su lugar, se genera automáticamente un gráfico de tramas basado en los requisitos de la escena.

Materiales incorporados

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

Ayudantes de geometría

Al igual que Qt 3D, Qt Quick 3D también proporciona muchas primitivas geométricas incorporadas, así como muchos generadores de geometría procedimental.

La siguiente tabla proporciona una correspondencia entre las clases de geometría de Qt 3D y sus equivalentes en Qt Quick 3D:

Controladores de cámara

Para el control de la cámara, Qt Quick 3D proporciona opciones comparables con OrbitCameraController y WasdController. El WasdController es similar al FirstPersonCameraController en Qt3D pero puede controlar cualquier elemento de la escena, no sólo cámaras.

Qt 3D Animación

El módulo Qt 3D Animation define cómo se manejan los diferentes tipos de animaciones en 3D. En Qt Quick 3D, la funcionalidad equivalente está repartida en varios módulos, a menudo aprovechando clases existentes de Qt Quick cuando es posible. Por ejemplo, puede utilizar las distintas clases de animación de la importación de QtQuick para animar propiedades de nodos 3D.

Cuando se importan animaciones desde herramientas de creación de contenidos 3D, normalmente se definen utilizando líneas de tiempo. El módulo Qt Quick Timeline proporciona las clases necesarias para definir dichas animaciones, y cualquier contenido importado con animaciones requerirá este módulo para funcionar.

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

Qt Quick 3D también soporta animaciones morph target, donde puedes animar cambios en la geometría de un modelo directamente. Los objetivos morph son instantáneas predefinidas de la geometría de un modelo, y puedes animar entre ellas utilizando el componente MorphTarget.

Para combinar varias animaciones o mezclarlas, se utilizan los componentes del módulo Qt Quick Timeline Blend Trees. Este módulo permite definir árboles complejos para gestionar cómo interactúan las distintas animaciones. La mayoría de estas clases genéricas de animación 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 Escena2D

En Qt 3D, el componente Scene2D se utiliza para renderizar escenas 2D Qt Quick en texturas que pueden utilizarse dentro de una escena 3D. En Qt Quick 3D, esto se consigue utilizando 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 mapea en el 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.