En esta página

Qt 3D: Ejemplo de QML de estructura alámbrica

Una aplicación QML de « Qt 3D » que implementa un método de renderizado de wireframe de una sola pasada.

Representación en 3D con estructura alámbrica de un nudo toroidal rojo con malla triangular

Qt 3D La representación de alambre ilustra cómo dibujar una única entidad (un nudo trifoliado) utilizando un conjunto personalizado de sombreadores para implementar un método de representación de alambre de una sola pasada.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Creación de entidades

El renderizador busca entidades que tengan geometría, un material y, opcionalmente, una transformación. Todo ello se especifica mediante subclases de `QComponent` que se han exportado al motor QML en forma de ` Mesh`, ` Material` y ` Transform`. Utilizamos estos componentes para crear un elemento QML personalizado en `TrefoilKnot.qml`.

Comenzamos importando el módulo Qt3D 2.0, que proporciona el tipo Entity y ayudantes de tipos de valor, como Qt.vector3d(). También importamos el módulo Qt3D.Renderer, que proporciona los componentes y otros tipos que utiliza el aspecto del renderizador:

import Qt3D.Core 2.0
import Qt3D.Render 2.0

Para utilizar componentes de otros aspectos, también tendríamos que importar el módulo QML correspondiente.

A continuación, utilizamos un tipo « Entity » como elemento raíz del tipo QML personalizado, exponiendo algunas propiedades personalizadas tal y como se haría con cualquier otro tipo en QML:

Entity {
    id: root

    property real x: 0.0
    property real y: 0.0
    property real z: 0.0
    property real scale: 1.0
    property real theta: 0.0
    property real phi: 0.0
    property Material material

Además de agregar componentes, el tipo ` Entity ` se puede utilizar para agrupar objetos hijos. Esto es análogo a cómo se utiliza el tipo ` Item ` en ` Qt Quick 2`.

Especificación de transformaciones

Instanciamos un componente ` Transform ` y un componente ` Mesh `. El componente ` Transform ` especifica cómo debe transformar el renderizador la geometría al dibujarla con el pipeline de OpenGL. Combinamos un conjunto ordenado de transformaciones en un único componente ` Transform `. Esta información estará automáticamente disponible para nuestros shaders a través de variables uniformes estándar con nombre:

    Transform {
        id: transform
        translation: Qt.vector3d(root.x, root.y, root.z)
        rotation: fromEulerAngles(theta, phi, 0)
        scale: root.scale
    }

Carga de datos dinámicos por vértice

El componente « Mesh » es muy sencillo. Utilizamos su propiedad «source» para cargar un conjunto estático de geometría (como posiciones de vértices, vectores normales y coordenadas de textura) desde un archivo en formato Wavefront Obj. Estos datos se exportaron desde la aplicación Blender.

    Mesh {
        id: mesh
        source: "qrc:/assets/obj/trefoil.obj"
    }

Además del elemento « Mesh », « Qt 3D » también permite la generación dinámica de datos de atributos por vértice a través de «hooks» de C++ que son invocados por el motor basado en tareas.

Agregación de componentes

Sin embargo, no basta con instanciar los componentes. Para que estos doten a una entidad de un comportamiento especial, la entidad debe agregar los componentes mediante su propiedad «components»:

    components: [ transform, mesh, root.material ]

Esto permite compartir componentes entre varias entidades con gran facilidad. En este ejemplo, contamos con componentes para la transformación y la malla que se encuentran dentro del tipo personalizado `TrefoilKnot`. El componente final, de tipo ` Material`, lo proporciona una propiedad del tipo personalizado `TrefoilKnot`. Más adelante personalizaremos el aspecto de la entidad.

Representación desde cámaras

Utilizamos el tipo personalizado `TrefoilKnot` en ` main.qml ` para dibujar el nudo trefoil en la pantalla.

Utilizamos las mismas declaraciones de importación que en TrefoilKnot.qml, con la adición de una importación con espacio de nombres para el módulo Qt Quick que necesitaremos para las animaciones:

import QtQuick 2.1 as QQ2
import Qt3D.Core 2.0
import Qt3D.Render 2.0

Utilizamos un tipo « Entity » como tipo raíz simplemente para que actúe como padre de sus hijos. En este sentido, el tipo « Entity » se parece mucho al tipo « Item »:

import Qt3D.Input 2.0
import Qt3D.Extras 2.0

Entity {
    id: root

El componente `RendererSettings` utiliza el tipo `ForwardRenderer` para configurar completamente el renderizador sin tocar ningún código C++:

    // Render from the mainCamera
    components: [
        RenderSettings {
            activeFrameGraph: ForwardRenderer {
                id: renderer
                camera: mainCamera
            }
        },
        // Event Source will be set by the Qt3DQuickWindow
        InputSettings { }
    ]

El tipo BasicCamera es un envoltorio trivial en torno al tipo integrado Camera, que representa una cámara virtual. Cuenta con propiedades para aspectos como los planos cercano y lejano, el campo de visión, la relación de aspecto, el tipo de proyección, la posición y la orientación:

    BasicCamera {
        id: mainCamera
        position: Qt.vector3d( 0.0, 0.0, 15.0 )
    }

El tipo «Configuration» ofrece una solución provisional para controlar la cámara con el ratón mientras se completa la implementación adecuada que utiliza aspectos y componentes:

    FirstPersonCameraController { camera: mainCamera }

Es muy sencillo utilizar varias cámaras y elegir entre ellas mediante el framegraph para el renderizado de toda la escena o de parte de ella.

Asignación de materiales

Qt 3D cuenta con un sistema de materiales robusto y muy flexible que permite múltiples niveles de personalización. Utilizamos el tipo personalizado `WireframeMaterial` para envolver el tipo ` Material `:

    WireframeMaterial {
        id: wireframeMaterial
        effect: WireframeEffect {}
        ambient: Qt.rgba( 0.2, 0.0, 0.0, 1.0 )
        diffuse: Qt.rgba( 0.8, 0.0, 0.0, 1.0 )

A continuación, instanciamos el tipo «TrefoilKnot» y le asignamos el material:

    TrefoilKnot {
        id: trefoilKnot
        material: wireframeMaterial
    }

El motor « Qt 3D », junto con el aspecto del renderizador, dispone ahora de información suficiente para renderizar finalmente nuestra malla utilizando el material que hemos especificado.

Uso de elementos de animación

Utilizamos los elementos de animación que proporciona Qt Quick 2 para animar las propiedades de los tipos `TrefoilKnot` y `WireframeMaterial`. Las propiedades de los componentes de un tipo se actualizan mediante el mecanismo de enlace de propiedades de QML:

        QQ2.SequentialAnimation {
            loops: QQ2.Animation.Infinite
            running: true

            QQ2.NumberAnimation {
                target: wireframeMaterial;
                property: "lineWidth";
                duration: 1000;
                from: 0.8
                to: 1.8
            }

            QQ2.NumberAnimation {
                target: wireframeMaterial;
                property: "lineWidth";
                duration: 1000;
                from: 1.8
                to: 0.8
            }

            QQ2.PauseAnimation { duration: 1500 }
        }

La clase base ` QNode ` detecta las actualizaciones de propiedades y las envía automáticamente a los objetos correspondientes en el aspecto del renderizador. A continuación, el renderizador se encarga de traducir las actualizaciones de propiedades a nuevos valores para las variables uniformes en los programas de sombreado GLSL.

Ejecuta el ejemplo para ver el nudo de trébol con el ancho de las líneas de la estructura alámbrica parpadeando. Todo el trabajo pesado lo realiza la GPU. La CPU solo tiene que ejecutar las animaciones de propiedades y traducir el grafo de escena y el grafo de fotogramas en llamadas OpenGL sin procesar.

También es posible animar en la GPU mediante un programa de sombreado y un material personalizados.

Proyecto de ejemplo en code.qt.io

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