En esta página

Qt Quick 3D: ejemplo de pasadas de usuario

Muestra cómo crear pases de renderizado personalizados en Qt Quick 3D.

Una escena en 3D renderizada mediante pasadas personalizadas del usuario

}

El ejemplo «Pases de usuario» muestra cómo crear pases de renderizado personalizados en Qt Quick 3D. Implementa un proceso de renderizado con iluminación diferida utilizando varios pases de renderizado definidos por el usuario y muestra cómo gestionar la secuencia completa de renderizado: geometría opaca, skybox, elementos 2D integrados en la escena y geometría transparente.

Desactivación de los pases de renderizado internos

De forma predeterminada, Qt Quick 3D utiliza un conjunto de pases de renderizado internos para renderizar la escena 3D. En ocasiones, es posible que desee desactivar estos pases internos e implementar su propio proceso de renderizado utilizando pases de renderizado definidos por el usuario.

Para desactivar los pases de renderizado internos, establece la propiedad ` renderOverrides ` del ` View3D ` en ` View3D.DisableInternalPasses`.

View3D {
    id: view3D
    anchors.fill: parent
    renderOverrides: View3D.DisableInternalPasses
    environment: ExtendedSceneEnvironment {
        lightProbe: Texture {
            textureData: ProceduralSkyTextureData {
            }
        }
        backgroundMode: SceneEnvironment.SkyBox
    }

Si desactivas los pases de renderizado internos, tendrás que proporcionar el resultado del pase de color principal para que el ` View3D ` pueda mostrar algo en la pantalla.

Pase de búfer de geometría

En este ejemplo, la primera pasada de renderizado personalizada es una pasada de búfer de geometría (G-buffer) que renderiza la geometría de la escena en múltiples objetivos de renderizado, almacenando diferentes propiedades de material en cada objetivo. El ejemplo proporcionado es un subconjunto de todas las propiedades de material que ofrecen los materiales 3D de Qt Quick, centrándose en las propiedades necesarias para una implementación básica de iluminación diferida.

Nuestro ` RenderPass ` se define en GBufferPass.qml:

RenderPass {
    id: gbufferPass
    clearColor: Qt.rgba(0.0, 0.0, 0.0, 0.0)

    property alias layerMask: filter.layerMask
    required property RenderPassTexture depthTexture

    RenderPassTexture {
        id: gbuffer0
        format: RenderPassTexture.RGBA16F
        // rgb: baseColor (linear), a: metalness
    }

    RenderPassTexture {
        id: gbuffer1
        format: RenderPassTexture.RGBA16F
        // rgb: normal, a: roughness
    }

    RenderPassTexture {
        id: gbuffer2
        format: RenderPassTexture.RGBA16F
        // rgb: emissive, a: ao/spare
    }

    commands: [
        ColorAttachment { target: gbuffer0; name: "GBUFFER0" },
        ColorAttachment { target: gbuffer1; name: "GBUFFER1" },
        ColorAttachment { target: gbuffer2; name: "GBUFFER2" },
        DepthTextureAttachment { target: gbufferPass.depthTexture },
        RenderablesFilter {
            id: filter
            renderableTypes: RenderablesFilter.Opaque
        }
    ]

    materialMode: RenderPass.AugmentMaterial
    augmentShader: "gbuffer_augment.glsl"
}

Define tres adjuntos de color y un adjunto de profundidad. El paso requiere tres texturas que se definen como objetos « RenderPassTexture » dentro de « RenderPass ». Estas tres «RenderPassTextures» se utilizan como destinos para los adjuntos de color del paso, y el adjunto de profundidad utiliza una textura de profundidad proporcionada desde fuera del paso.

El propio « RenderPass » está configurado en modo « AugmentMaterial », lo que significa que ampliará los materiales de los objetos renderizados con código de shader adicional. El shader de ampliación se proporciona en el archivo « gbuffer_augment.glsl », que envía las propiedades de material requeridas a los múltiples destinos de renderizado.

void MAIN_FRAGMENT_AUGMENT()
{
    vec3 baseColor   = BASE_COLOR.rgb;
    float metalness  = METALNESS;
    float roughness  = ROUGHNESS;
    vec3 worldNormal = normalize(WORLD_NORMAL);

    // GBuffer 0: albedo + metalness
    GBUFFER0 = vec4(baseColor, metalness);

    // GBuffer 1: normal (encoded to 0..1) + roughness
    GBUFFER1 = vec4(worldNormal * 0.5 + 0.5, roughness);

    // GBuffer 2: world position
    GBUFFER2 = vec4(qt_varWorldPos, 1.0);
}

Aquí se puede ver cómo el color base, la metalicidad, la normal global, la rugosidad y la posición global se almacenan en los tres adjuntos de color del G-buffer.

Para utilizar realmente el paso del G-buffer en el proceso de renderizado, debemos crear una instancia del mismo en ` Main.qml` y proporcionar la textura de profundidad necesaria:

RenderPassTexture {
    id: mainDepthStencilTexture
    format: RenderPassTexture.Depth24Stencil8
}
GBufferPass {
    id: gbufferPass
    layerMask: ContentLayer.Layer0 | ContentLayer.Layer1
    depthTexture: mainDepthStencilTexture
}

RenderOutputProvider {
    id: gbuffer0Provider
    textureSource: RenderOutputProvider.UserPassTexture
    renderPass: gbufferPass
    attachmentSelector: RenderOutputProvider.Attachment0
}

RenderOutputProvider {
    id: gbuffer1Provider
    textureSource: RenderOutputProvider.UserPassTexture
    renderPass: gbufferPass
    attachmentSelector: RenderOutputProvider.Attachment1
}

RenderOutputProvider {
    id: gbuffer2Provider
    textureSource: RenderOutputProvider.UserPassTexture
    renderPass: gbufferPass
    attachmentSelector: RenderOutputProvider.Attachment2
}

Se crean tres instancias de « RenderOutputProvider » para proporcionar referencias a las texturas del G-buffer renderizadas, que se utilizarán en la pasada de iluminación posterior.

La propiedad « layerMask » del paso del G-buffer se configura para renderizar únicamente los objetos que se encuentran en ContentLayer.Layer0 y ContentLayer.Layer1. Esto nos permite controlar qué objetos se renderizan en el paso del G-buffer configurando su propiedad « layers » en consecuencia.

Pasa de color principal y SubRenderPasses

En lugar de un único paso de renderizado plano, este ejemplo utiliza un « mainColorPass » compuesto que contiene las texturas principales de color y profundidad y coordina todo el renderizado a través de una secuencia de elementos secundarios de tipo « SubRenderPass ».

Cada « SubRenderPass » comparte los mismos objetivos de renderizado que el paso exterior y se ejecuta en orden. Esto facilita la creación de un proceso de renderizado por capas en el que cada etapa se suma al resultado de la anterior.

RenderPass {
    id: mainColorPass
    clearColor: "black"
    // Preserve depth across SubRenderPasses so geometry depth is available
    // when rendering the skybox, transparent objects, and 2D items.
    renderTargetFlags: RenderPass.RenderTargetFlags.PreserveDepthStencilContents

    commands: [
        ColorAttachment {
            target: mainColorTexture
        },
        DepthTextureAttachment {
            target: mainDepthStencilTexture
        },
        RenderablesFilter {
            // Nothing renders directly in the outer pass; all rendering
            // is delegated to the SubRenderPasses below.
            renderableTypes: RenderablesFilter.None
        },

        // 1. Deferred lighting: shade opaque geometry stored in the G-buffer.
        SubRenderPass {
            renderPass: RenderPass {
                id: deferredLightingPass
                materialMode: RenderPass.OriginalMaterial
                commands: [
                    PipelineStateOverride {
                        // The full-screen quad must not write or test depth;
                        // geometry depth was already written by the G-buffer pass.
                        depthWriteEnabled: false
                        depthTestEnabled: false
                    },
                    RenderablesFilter { layerMask: ContentLayer.Layer13 }
                ]
            }
        },

        // 2. Skybox: render the environment behind all scene geometry.
        SubRenderPass {
            renderPass: RenderPass {
                id: skyboxPass
                passMode: RenderPass.SkyboxPass
                commands: [
                    PipelineStateOverride {
                        // The skybox is rendered "at infinity" so it must
                        // depth-test (to be hidden by geometry) but must not
                        // write depth.
                        depthTestEnabled: true
                        depthWriteEnabled: false
                    }
                ]
            }
        },

        // 3. 2D items: render any Qt Quick Items embedded in the 3D scene.
        SubRenderPass {
            renderPass: RenderPass {
                id: item2DPass
                passMode: RenderPass.Item2DPass
            }
        },

        // 4. Transparent objects: render blended geometry on top of everything else.
        SubRenderPass {
            renderPass: RenderPass {
                id: transparentItemPass
                materialMode: RenderPass.OriginalMaterial
                commands: [
                    RenderablesFilter {
                        renderableTypes: RenderablesFilter.Transparent
                        layerMask: ContentLayer.Layer0 | ContentLayer.Layer1
                    },
                    PipelineStateOverride {
                        // Enable alpha blending and depth testing so transparent
                        // objects sort correctly against opaque geometry.
                        blendEnabled: true
                        depthTestEnabled: true
                        targetBlend0.enable: true
                        targetBlend0.srcColor: RenderTargetBlend.SrcAlpha
                        targetBlend0.dstColor: RenderTargetBlend.OneMinusSrcAlpha
                        targetBlend0.srcAlpha: RenderTargetBlend.One
                        targetBlend0.dstAlpha: RenderTargetBlend.OneMinusSrcAlpha
                    }
                ]
            }
        }
    ]
}

El paso exterior establece ` renderableTypes: RenderablesFilter.None` para que nada se renderice directamente en el paso padre; todo el renderizado se delega a los subpasos. El indicador ` PreserveDepthStencilContents ` garantiza que los valores de profundidad escritos por el paso del G-buffer estén disponibles para todos los subpasos.

Subpaso de iluminación diferida

El primer subpaso ejecuta el cálculo de la iluminación diferida. Renderiza el modelo de « deferredLightingQuad » a pantalla completa, que muestrea las texturas del G-buffer y evalúa la iluminación de cada píxel.

Model {
    id: deferredLightingQuad
    layers: ContentLayer.Layer13
    castsShadows: false
    receivesShadows: false
    geometry: PlaneGeometry {
        // geometry doesn't matter, just need 4 verts
        plane: PlaneGeometry.XY
    }
    materials: [
        CustomMaterial {
            id: lightingPassMaterial
            property TextureInput gbuffer0: TextureInput {
                enabled: true
                texture: Texture {
                    textureProvider: gbuffer0Provider
                }
            }
            property TextureInput gbuffer1: TextureInput {
                enabled: true
                texture: Texture {
                    textureProvider: gbuffer1Provider
                }
            }
            property TextureInput gbuffer2: TextureInput {
                enabled: true
                texture: Texture {
                    textureProvider: gbuffer2Provider
                }
            }
            shadingMode: CustomMaterial.Unshaded
            fragmentShader: "lighting.frag"
            vertexShader: "lighting.vert"
        }
    ]
}

El « deferredLightingQuad » se coloca en « ContentLayer.Layer13 » para que sea invisible para el paso del G-buffer y solo lo renderice este subpaso.

Un « PipelineStateOverride » desactiva tanto las escrituras de profundidad como las comprobaciones de profundidad para el cuadrilátero. El paso del G-buffer ya ha escrito la profundidad correcta para la geometría de la escena, por lo que el cuadrilátero a pantalla completa no debe alterar ni comprobar la profundidad.

Subpaso de skybox

El segundo subpaso renderiza el skybox del entorno de la escena utilizando el modo de paso especial « RenderPass.SkyboxPass ». « Qt Quick 3D» se encarga de dibujar la geometría del skybox utilizando los ajustes « lightProbe » y « backgroundMode » de « SceneEnvironment ».

Un « PipelineStateOverride » habilita la comprobación de profundidad para que el skybox quede correctamente oculto tras la geometría de la escena, mientras que las escrituras de profundidad están deshabilitadas porque el skybox se sitúa «en el infinito» y nunca debe ocluir la geometría.

Subpaso de objetos transparentes

Los objetos transparentes no pueden almacenarse en el G-buffer porque requieren una mezcla ordenada de atrás hacia delante. En su lugar, se renderizan en último lugar utilizando sus materiales originales a través de un subpaso específico.

El cono transparente de la escena se declara de la siguiente manera:

Model {
    id: cone
    layers: ContentLayer.Layer1
    source: "#Cone"
    y: 100
    materials: [
        PrincipledMaterial {
            baseColor: Qt.rgba(0.0, 1.0, 0.0, 0.5)
            alphaMode: PrincipledMaterial.Blend
            metalness: 0.0
            roughness: 0.5
        }
    ]
}

El subpaso transparente utiliza un « RenderablesFilter » para seleccionar únicamente los elementos renderizables transparentes en las capas coincidentes, y un « PipelineStateOverride » habilita la mezcla alfa al tiempo que mantiene activa la comprobación de profundidad, de modo que los objetos transparentes se ordenen correctamente frente a la geometría opaca.

Los objetos transparentes deben renderizarse después de todas las pasadas opacas, de modo que el búfer de profundidad esté completamente rellenado antes de que se produzca la mezcla.

Elementos 2D en un subpaso 3D

Qt Quick El 3D puede incrustar elementos 2D estándar de Qt Quick dentro de la escena 3D utilizando Node como contenedor. Para incluir estos elementos en un proceso de renderizado personalizado, añade un subpaso con passMode: RenderPass.Item2DPass.

Node {
    x: -200
    y: 100

    Item {
        anchors.centerIn: parent
        ColumnLayout {
            Button {
                text: "Click Me!"
            }
            Rectangle {
                color: "blue"
                implicitWidth: 50
                implicitHeight: 50

                NumberAnimation on rotation {
                    from: 0
                    to: 360
                    duration: 4000
                    loops: Animation.Infinite
                    running: true
                }
            }
        }
    }

    NumberAnimation on eulerRotation.y {
        from: 0
        to: 360
        duration: 6000
        loops: Animation.Infinite
        running: true
    }
}

El modo « Item2DPass » indica a « Qt Quick 3D» que renderice todos los elementos de « Qt Quick » que sean hijos de nodos 3D en el destino de renderizado actual, combinados con el contenido 3D ya presente.

Renderizado en pantalla

Por último, para mostrar en pantalla el resultado de nuestras pasadas de renderizado personalizadas, debemos asegurarnos de que la textura de color principal de « View3D » se actualice con el resultado de la pasada de color principal.

SimpleQuadRenderer {
    texture: Texture {
        textureProvider: mainColorPassProvider
    }
}

RenderPassTexture {
    id: mainColorTexture
    format: RenderPassTexture.RGBA16F
}

RenderOutputProvider {
    id: mainColorPassProvider
    textureSource: RenderOutputProvider.UserPassTexture
    renderPass: mainColorPass
    attachmentSelector: RenderOutputProvider.Attachment0
}

El ` SimpleQuadRenderer ` se utiliza para copiar la textura de color principal generada por el ` mainColorPass ` al búfer de fotogramas del ` View3D`. El ` RenderOutputProvider ` expone el primer anexo de color de ` mainColorPass ` como una textura que el ` SimpleQuadRenderer ` puede muestrear.

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.