En esta página

Pasos de renderizado definidos por el usuario en Qt Quick 3D

Qt Quick 3D ofrece una API de alto nivel para el renderizado 3D que gestiona automáticamente la mayoría de los detalles del renderizado. Sin embargo, para casos de uso avanzados, es posible que las aplicaciones necesiten un control total sobre el proceso de renderizado. Las pasadas de renderizado definidas por el usuario lo hacen posible, ya que permiten a las aplicaciones desactivar el proceso de renderizado interno y definir sus propias pasadas personalizadas.

Las pasadas de renderizado definidas por el usuario permiten técnicas de renderizado avanzadas, tales como:

  • Sombreado e iluminación diferidos
  • Efectos de renderizado de múltiples pasadas
  • Flujos de trabajo de posprocesamiento personalizados
  • Renderizado selectivo con filtrado basado en capas
  • Efectos en el espacio de pantalla (oclusión ambiental, reflejos, etc.)
  • Técnicas personalizadas de mapeado de sombras
  • Pasos de visualización de depuración

Niveles de personalización

Qt Quick 3D ofrece tres niveles complementarios de personalización del renderizado, cada uno de ellos adecuado para diferentes casos de uso:

NivelÁmbitoCasos de uso
EffectPosprocesadoAplica efectos una vez renderizada la escena (desenfoque, corrección de color, etc.)
CustomMaterialShaders por materialShaders de vértices y fragmentos personalizados para materiales individuales
RenderPass (Pasos de renderizado del usuario)Control total del proceso de renderizadoRenderizado diferido, múltiples pasadas, objetivos de renderizado personalizados

Los pases de renderizado de usuario (RenderPass) ofrecen el máximo control, lo que te permite complementar o sustituir por completo el proceso de renderizado predeterminado. Esto complementa CustomMaterial y Effect: CustomMaterial personaliza la forma en que se renderizan los objetos individuales, mientras que los pases de renderizado de usuario controlan la estrategia y la arquitectura generales del renderizado.

Uso de las pasadas de renderizado de usuario

Las pasadas de renderizado de usuario se pueden utilizar de dos maneras:

Como complemento de las pasadas internas

Puedes añadir objetos « RenderPass » personalizados junto con el proceso de renderizado predeterminado sin desactivar las pasadas internas. Esto resulta útil para renderizar en texturas que luego se utilizan en « Effect » o « CustomMaterial », o para crear objetivos de renderizado auxiliares.

View3D {
    // Internal passes still run normally

    RenderPassTexture { id: customTexture; format: RenderPassTexture.RGBA16F }

    RenderPass {
        // Custom pass renders to texture
        commands: [
            ColorAttachment { target: customTexture },
            DepthStencilAttachment { }
        ]
    }

    // Use customTexture in an Effect or material
}

Sustitución de pases internos

Para tener un control total sobre el proceso de renderizado, desactiva el renderizado interno de « Qt Quick 3D» configurando la propiedad « renderOverrides »:

View3D {
    renderOverrides: View3D.DisableInternalPasses

    // Your custom render passes go here
}

Cuando las pasadas internas están desactivadas, Qt Quick 3D no realizará ningún renderizado predeterminado. Esto significa que debe:

  • Definir al menos un « RenderPass » para renderizar la escena
  • Proporcionar la textura de salida final que se mostrará mediante « SimpleQuadRenderer » o un mecanismo similar
  • Gestionar todos los aspectos del renderizado, incluidos los búferes de profundidad, la transparencia, etc.

Nota: Desactivar los pases internos le ofrece un control total, pero también una responsabilidad total. Funciones como el renderizado automático de sombras, la clasificación de transparencias y los reflejos del entorno deben implementarse en sus pases personalizados si es necesario.

Conceptos básicos

Los pases de renderizado definidos por el usuario se construyen a partir de varios componentes clave:

RenderPass

El tipo « RenderPass » es el componente principal. Define una única operación de renderizado con un conjunto de comandos que controlan qué se renderiza y cómo. Cada pasada puede:

  • Renderizar en una o más texturas de color (hasta 4 objetivos de renderizado simultáneos)
  • Escribir información de profundidad y estarcido
  • Filtrar qué objetos se deben renderizar en función de las capas
  • Anular el estado del canal de procesamiento gráfico (mezcla, culling, etc.)
  • Utilizar materiales originales, mejorarlos con sombreadores personalizados o sustituirlos por completo

RenderPassTexture

El tipo « RenderPassTexture » define texturas que sirven como destinos de renderizado. Pueden ser texturas de color en diversos formatos (RGBA8, RGBA16F, RGBA32F, etc.) o texturas de profundidad/plantilla. Las texturas de paso de renderizado se utilizan como salidas de un paso y pueden emplearse como entradas de textura para pasos posteriores.

RenderOutputProvider

El tipo ` RenderOutputProvider ` conecta las pasadas de renderizado al exponer las texturas de salida de una pasada como entradas de textura que pueden ser utilizadas por materiales u otras pasadas. Esto es esencial para el renderizado de múltiples pasadas, en el que las pasadas posteriores necesitan leer los resultados de las pasadas anteriores.

ContentLayer

El singleton ` ContentLayer ` proporciona constantes de capa (de `Layer0` a `Layer23`) que se utilizan para filtrar qué objetos se renderizan en cada paso. Al asignar objetos a capas específicas y utilizar ` RenderablesFilter ` en tus pasos, puedes controlar con precisión qué se renderiza en cada paso.

Comandos de renderizado

Cada RenderPass contiene una lista de comandos que configuran su comportamiento:

Modos de material

Cada objeto « RenderPass » tiene una propiedad « materialMode » que controla cómo se gestionan los materiales durante el renderizado. Los tres modos ofrecen distintos niveles de control sobre los materiales:

Modo «OriginalMaterial»

Este modo renderiza los objetos con los materiales que tienen asignados sin modificarlos. Resulta útil cuando se desea controlar la estructura del proceso de renderizado (múltiples pasadas, destinos de renderizado personalizados) pero mantener el comportamiento estándar del material.

RenderPass {
    materialMode: RenderPass.OriginalMaterial
    commands: [
        ColorAttachment { target: myColorTexture },
        DepthStencilAttachment { }
    ]
}

Modo «AugmentMaterial»

Este modo inyecta código de shader personalizado en el proceso de renderizado de materiales existente. Resulta especialmente útil para el renderizado diferido, en el que es necesario enviar datos adicionales (como normales, posiciones, etc.) a múltiples destinos de renderizado, al tiempo que se conserva el comportamiento básico del material.

RenderPass {
    materialMode: RenderPass.AugmentMaterial
    augmentShader: "my_augment.glsl"
    commands: [
        ColorAttachment { target: gbuffer0; name: "GBUFFER0" },
        ColorAttachment { target: gbuffer1; name: "GBUFFER1" },
        DepthStencilAttachment { }
    ]
}

El archivo de sombreador de ampliación contiene una función ` MAIN_FRAGMENT_AUGMENT() `:

void MAIN_FRAGMENT_AUGMENT()
{
    // Access material properties
    vec3 color = BASE_COLOR.rgb;
    float metal = METALNESS;
    float rough = ROUGHNESS;
    vec3 normal = normalize(WORLD_NORMAL);

    // Write to multiple render targets
    GBUFFER0 = vec4(color, metal);
    GBUFFER1 = vec4(normal * 0.5 + 0.5, rough);
}

Consulta «Sombreadores de ampliación para múltiples destinos de renderizado » para obtener más detalles.

Modo «OverrideMaterial»

Este modo sustituye todos los materiales de los objetos por un único material. Resulta útil para pasadas especializadas como el mapeado de sombras, la pasada previa de profundidad o la visualización de depuración.

RenderPass {
    materialMode: RenderPass.OverrideMaterial
    overrideMaterial: CustomMaterial {
        fragmentShader: "depth_only.frag"
        // All objects will use this material
    }
    commands: [
        DepthTextureAttachment { target: depthTexture }
    ]
}

Comandos de pasada de renderizado

Los comandos se especifican en la propiedad « commands » y se ejecutan en el orden en que están definidos.

Adjunto de color

El comando « ColorAttachment » especifica un destino de renderizado de color. La propiedad « name » define cómo se accede al anexo en los shaders de aumento.

ColorAttachment {
    target: myTexture      // RenderPassTexture to render to
    name: "GBUFFER0"      // Name for shader access (optional)
}

Se pueden tener hasta 4 adjuntos de color por pasada (para múltiples destinos de renderizado).

Adjuntos de profundidad

Hay dos formas de gestionar la profundidad:

DepthStencilAttachment utiliza un búfer de profundidad/plantilla implícito:

DepthStencilAttachment { }  // Creates depth/stencil buffer automatically

DepthTextureAttachment utiliza una textura explícita para la salida de profundidad:

RenderPassTexture {
    id: depthTex
    format: RenderPassTexture.Depth24Stencil8
}

DepthTextureAttachment {
    target: depthTex  // Explicit depth texture
}

Utiliza « DepthTextureAttachment » cuando necesites compartir el búfer de profundidad entre varias pasadas o utilizarlo como entrada de textura en los shaders.

Filtro de renderizables

El comando « RenderablesFilter » controla qué objetos se renderizan en función de su asignación de capa y su tipo de renderizable.

RenderablesFilter {
    layerMask: ContentLayer.Layer0 | ContentLayer.Layer1
    renderableTypes: RenderablesFilter.Opaque
}

La propiedad « layerMask » utiliza el operador OR bit a bit para combinar capas. La propiedad « renderableTypes » puede tener los siguientes valores:

  • RenderablesFilter.Opaque: Renderizar solo objetos opacos
  • RenderablesFilter.Transparent: Renderizar solo objetos transparentes
  • RenderablesFilter.Opaque | RenderablesFilter.Transparent: renderizar ambos

Anulación del estado del canal de procesamiento

El comando « PipelineStateOverride » ofrece un control muy preciso sobre el estado del canal de procesamiento gráfico. Permite anular la comprobación de profundidad, la mezcla, el culling, el modo de polígono y mucho más.

PipelineStateOverride {
    depthTestEnabled: true
    depthWriteEnabled: false
    blendEnabled: true
    cullMode: PipelineStateOverride.Back
    polygonMode: PipelineStateOverride.Fill
}

Consulta «Control del estado del pipeline » para ver más ejemplos.

Subpaso de renderizado

El comando « SubRenderPass » permite la composición jerárquica de pasadas de renderizado mediante la ejecución de otra pasada de renderizado dentro de la pasada actual.

RenderPass {
    id: parentPass
    commands: [
        ColorAttachment { target: colorTex },
        SubRenderPass { renderPass: childPass },
        // More commands after child pass
    ]
}

RenderPass {
    id: childPass
    // This pass executes within parentPass
}

Añadir «define»

El comando « AddDefine » añade definiciones del preprocesador de sombreadores que afectan a la compilación de los mismos.

AddDefine {
    name: "USE_SPECIAL_MODE"
    value: 1
}

Ejemplo sencillo: renderizado de un solo paso

A continuación se muestra un ejemplo mínimo que ilustra los pases de renderizado definidos por el usuario:

import QtQuick
import QtQuick3D
import QtQuick3D.Helpers

View3D {
    anchors.fill: parent
    renderOverrides: View3D.DisableInternalPasses

    // Camera and lights
    PerspectiveCamera { z: 300 }
    DirectionalLight { }

    // Define render target texture
    RenderPassTexture {
        id: colorTarget
        format: RenderPassTexture.RGBA16F
    }

    // Define the render pass
    RenderPass {
        id: mainPass
        materialMode: RenderPass.OriginalMaterial
        clearColor: "skyblue"

        commands: [
            ColorAttachment { target: colorTarget },
            DepthStencilAttachment { }
        ]
    }

    // Display the result
    SimpleQuadRenderer {
        texture: Texture {
            textureProvider: RenderOutputProvider {
                textureSource: RenderOutputProvider.UserPassTexture
                renderPass: mainPass
                attachmentSelector: RenderOutputProvider.Attachment0
            }
        }
    }

    // Scene content
    Model {
        source: "#Sphere"
        materials: PrincipledMaterial {
            baseColor: "red"
            metalness: 0.0
            roughness: 0.3
        }
    }
}

Este ejemplo:

  1. Desactiva las pasadas internas
  2. Crea una textura de destino de renderizado (colorTarget)
  3. Define una pasada de renderizado que se aplica a esa textura
  4. Utiliz RenderOutputProvider para mostrar la textura
  5. Muestra el resultado con SimpleQuadRenderer
  6. Renderiza una esfera con un material estándar

Trabajar con capas

El singleton ` ContentLayer ` proporciona constantes para organizar los objetos en capas, lo que permite un control minucioso sobre lo que se renderiza en cada pasada.

Constantes de capas

Qt Quick 3D ofrece 24 capas asignables por el usuario:

  • ContentLayer.Layer0 a través de ` ContentLayer.Layer23`: Capas individuales
  • ContentLayer.LayerAll: Todas las capas de usuario combinadas
  • ContentLayer.LayerNone: Sin capas

Nota: Las capas 24-31 están reservadas para uso interno.

Asignación de objetos a capas

Asigna objetos a capas utilizando la propiedad « layers »:

Model {
    source: "#Cube"
    layers: ContentLayer.Layer0
    materials: PrincipledMaterial { baseColor: "red" }
}

Model {
    source: "#Sphere"
    layers: ContentLayer.Layer1 | ContentLayer.Layer2
    materials: PrincipledMaterial { baseColor: "blue" }
}

Los objetos pueden pertenecer a varias capas mediante el operador OR bit a bit.

Filtrado por capa

Utiliza ` RenderablesFilter ` en tus pasadas de renderizado para seleccionar qué capas se van a renderizar:

RenderPass {
    id: pass1
    commands: [
        ColorAttachment { target: texture1 },
        RenderablesFilter {
            layerMask: ContentLayer.Layer0
        }
    ]
    // Only renders objects on Layer0 (red cube)
}

RenderPass {
    id: pass2
    commands: [
        ColorAttachment { target: texture2 },
        RenderablesFilter {
            layerMask: ContentLayer.Layer1 | ContentLayer.Layer2
        }
    ]
    // Only renders objects on Layer1 or Layer2 (blue sphere)
}

Caso de uso: renderizado selectivo

Un ejemplo práctico es renderizar determinados objetos como superposiciones de estructura alámbrica:

View3D {
    renderOverrides: View3D.DisableInternalPasses

    RenderPassTexture { id: colorTex; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: depthTex; format: RenderPassTexture.Depth24Stencil8 }

    // Pass 1: Render solid objects
    RenderPass {
        id: solidPass
        commands: [
            ColorAttachment { target: colorTex },
            DepthTextureAttachment { target: depthTex },
            RenderablesFilter { layerMask: ContentLayer.Layer0 }
        ]
    }

    // Pass 2: Render wireframe overlay
    RenderPass {
        id: wireframePass
        commands: [
            ColorAttachment { target: colorTex },
            DepthTextureAttachment { target: depthTex },
            PipelineStateOverride {
                polygonMode: PipelineStateOverride.Line
                depthTestEnabled: true
                depthWriteEnabled: false
            },
            RenderablesFilter { layerMask: ContentLayer.Layer1 }
        ]
    }

    SimpleQuadRenderer {
        texture: Texture {
            textureProvider: RenderOutputProvider {
                textureSource: RenderOutputProvider.UserPassTexture
                renderPass: wireframePass
                attachmentSelector: RenderOutputProvider.Attachment0
            }
        }
    }

    Model {
        source: "#Sphere"
        layers: ContentLayer.Layer0  // Rendered solid
        materials: PrincipledMaterial { baseColor: "blue" }
    }

    Model {
        source: "#Sphere"
        layers: ContentLayer.Layer1  // Rendered as wireframe
        materials: PrincipledMaterial { baseColor: "yellow" }
    }
}

Gestión de texturas

Las pasadas de renderizado del usuario dependen en gran medida de las texturas, tanto como destinos de renderizado como entradas para pasadas o materiales posteriores.

Formatos de textura de las pasadas de renderizado

RenderPassTexture Admite varios formatos para distintos casos de uso:

Formatos de color:

FormatoDescripciónCaso de uso
RGBA88 bits por canalSalida de color estándar, menor consumo de memoria
RGBA16F16 bits en coma flotanteRenderizado HDR, búferes intermedios
RGBA32F32 bits en coma flotanteCálculos de alta precisión
R8, R16, R16F, R32FVariantes de un solo canalDatos en escala de grises, búferes especializados

Formatos de profundidad:

FormatoDescripción
Profundidad 16Profundidad de 16 bits
Profundidad 24Profundidad de 24 bits
Profundidad 32Profundidad de 32 bits
Profundidad 24 + Plantilla 8Profundidad de 24 bits + estarcido de 8 bits

Ejemplos de definiciones de texturas:

RenderPassTexture {
    id: hdrColorBuffer
    format: RenderPassTexture.RGBA16F  // HDR color
}

RenderPassTexture {
    id: depthBuffer
    format: RenderPassTexture.Depth24Stencil8  // Depth + stencil
}

RenderPassTexture {
    id: normalBuffer
    format: RenderPassTexture.RGBA16F  // Store normals
}

Compartir texturas entre pasadas

Varias pasadas pueden compartir la misma textura de profundidad, lo que permite realizar pruebas de profundidad entre pasadas:

RenderPassTexture {
    id: sharedDepth
    format: RenderPassTexture.Depth24Stencil8
}

RenderPass {
    id: geometryPass
    commands: [
        ColorAttachment { target: colorTex1 },
        DepthTextureAttachment { target: sharedDepth }
    ]
}

RenderPass {
    id: transparentPass
    renderTargetFlags: RenderPass.PreserveDepthStencilContents
    commands: [
        ColorAttachment { target: colorTex2 },
        DepthTextureAttachment { target: sharedDepth }
        // Uses depth from geometryPass for depth testing
    ]
}

Proveedor de salida de renderizado

El « RenderOutputProvider » expone las salidas de las pasadas de renderizado como entradas de « Texture »:

// Define a render pass with color output
RenderPass {
    id: firstPass
    commands: [
        ColorAttachment { target: intermediateTexture }
    ]
}

// Expose its output
RenderOutputProvider {
    id: intermediateProvider
    textureSource: RenderOutputProvider.UserPassTexture
    renderPass: firstPass
    attachmentSelector: RenderOutputProvider.Attachment0
}

// Use in a material
CustomMaterial {
    property TextureInput inputTex: TextureInput {
        texture: Texture { textureProvider: intermediateProvider }
    }
    fragmentShader: "process.frag"
}

La propiedad « attachmentSelector » especifica qué adjunto de color se debe utilizar cuando un paso tiene varios objetivos de renderizado:

  • RenderOutputProvider.Attachment0: Primer adjunto de color
  • RenderOutputProvider.Attachment1: Segundo adjunto de color
  • RenderOutputProvider.Attachment2: Tercera asignación de color
  • RenderOutputProvider.Attachment3: Cuarto adjunto de color

Ejemplo de encadenamiento de pasadas

Se pueden encadenar varias pasadas, de modo que cada una procese la salida de la anterior:

View3D {
    renderOverrides: View3D.DisableInternalPasses

    // Intermediate textures
    RenderPassTexture { id: tex0; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: tex1; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: tex2; format: RenderPassTexture.RGBA16F }

    // Pass 1: Render scene
    RenderPass {
        id: scenePass
        commands: [
            ColorAttachment { target: tex0 },
            DepthStencilAttachment { }
        ]
    }

    // Pass 2: Process tex0 -> tex1
    RenderPass {
        id: process1
        materialMode: RenderPass.OriginalMaterial
        commands: [
            ColorAttachment { target: tex1 }
        ]
    }

    Model {
        layers: ContentLayer.Layer10
        geometry: PlaneGeometry { }
        materials: CustomMaterial {
            property TextureInput input: TextureInput {
                texture: Texture {
                    textureProvider: RenderOutputProvider {
                        textureSource: RenderOutputProvider.UserPassTexture
                        renderPass: scenePass
                    }
                }
            }
            fragmentShader: "effect1.frag"
        }
    }

    // Pass 3: Process tex1 -> tex2
    RenderPass {
        id: process2
        commands: [
            ColorAttachment { target: tex2 },
            RenderablesFilter { layerMask: ContentLayer.Layer11 }
        ]
    }

    Model {
        layers: ContentLayer.Layer11
        geometry: PlaneGeometry { }
        materials: CustomMaterial {
            property TextureInput input: TextureInput {
                texture: Texture {
                    textureProvider: RenderOutputProvider {
                        textureSource: RenderOutputProvider.UserPassTexture
                        renderPass: process1
                    }
                }
            }
            fragmentShader: "effect2.frag"
        }
    }

    // Display final result
    SimpleQuadRenderer {
        texture: Texture {
            textureProvider: RenderOutputProvider {
                textureSource: RenderOutputProvider.UserPassTexture
                renderPass: process2
            }
        }
    }
}

Control del estado del canal de procesamiento

El comando « PipelineStateOverride » proporciona un control detallado sobre el estado de la canalización gráfica, lo que permite personalizar la comprobación de profundidad, la mezcla, el culling y mucho más.

Comprobación y escritura de profundidad

Controla cómo se comprueban y se escriben los valores de profundidad:

PipelineStateOverride {
    depthTestEnabled: true
    depthWriteEnabled: true
    depthFunction: PipelineStateOverride.LessOrEqual
}

La propiedad ` depthFunction ` puede tomar los siguientes valores:

  • Never, Less, Equal, LessOrEqual
  • Greater, NotEqual, GreaterOrEqual, Always

Mezcla

Activa y configura la mezcla para la transparencia:

PipelineStateOverride {
    blendEnabled: true
    // Uses default blend mode (source alpha blending)
}

Para múltiples objetivos de renderizado, utiliza estados de mezcla por objetivo. PipelineStateOverride expone las propiedades de tipo valor por adjunto, desde targetBlend0 hasta targetBlend7 (de tipo renderTargetBlend), y las enumeraciones de factor de mezcla y operación se encuentran en el espacio de nombres RenderTargetBlend:

PipelineStateOverride {
    targetBlend0.enable: true
    targetBlend0.srcColor: RenderTargetBlend.SrcAlpha
    targetBlend0.dstColor: RenderTargetBlend.OneMinusSrcAlpha
    targetBlend0.opColor:  RenderTargetBlend.Add

    targetBlend1.enable: false  // No blending for attachment 1
}

Culling

Control del culling de caras:

PipelineStateOverride {
    cullMode: PipelineStateOverride.Back   // Override material's cull mode to Back
}

Al establecer aquí « cullMode » se anula el valor que, de otro modo, especificaría el material para esta pasada. Opciones: None (sin culling), Front (culling de caras frontales), Back (culling de caras traseras).

Renderizado de estructura de alambre

Renderizar la geometría como mallas alámbricas:

PipelineStateOverride {
    polygonMode: PipelineStateOverride.Line
    cullMode: PipelineStateOverride.None  // Show both sides
}

La opción « polygonMode » puede ser « Fill » (por defecto) o « Line » (malla alámbrica).

Rectángulos de recorte

Limitar el renderizado a una región rectangular:

PipelineStateOverride {
    usesScissor: true
    scissor: Qt.rect(100, 100, 400, 300)  // x, y, width, height
}

Control de la ventana de visualización

Anular la configuración de la ventana gráfica:

PipelineStateOverride {
    viewport: Qt.rect(0, 0, 800, 600)
}

Ejemplo completo: Superposición de estructura alámbrica

Este ejemplo renderiza una escena de forma normal y, a continuación, superpone una versión de estructura alámbrica:

View3D {
    renderOverrides: View3D.DisableInternalPasses

    RenderPassTexture { id: color; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: depth; format: RenderPassTexture.Depth24Stencil8 }

    // Solid pass
    RenderPass {
        id: solidPass
        clearColor: "black"
        commands: [
            ColorAttachment { target: color },
            DepthTextureAttachment { target: depth },
            RenderablesFilter {
                layerMask: ContentLayer.Layer0
                renderableTypes: RenderablesFilter.Opaque
            }
        ]
    }

    // Wireframe overlay
    RenderPass {
        id: wirePass
        renderTargetFlags: RenderPass.PreserveColorContents |
                          RenderPass.PreserveDepthStencilContents
        commands: [
            ColorAttachment { target: color },
            DepthTextureAttachment { target: depth },
            PipelineStateOverride {
                polygonMode: PipelineStateOverride.Line
                depthTestEnabled: true
                depthWriteEnabled: false
                blendEnabled: true
            },
            RenderablesFilter { layerMask: ContentLayer.Layer0 }
        ]
    }

    SimpleQuadRenderer {
        texture: Texture {
            textureProvider: RenderOutputProvider {
                textureSource: RenderOutputProvider.UserPassTexture
                renderPass: wirePass
            }
        }
    }

    PerspectiveCamera { z: 300 }
    DirectionalLight { }

    Model {
        source: "#Sphere"
        layers: ContentLayer.Layer0
        materials: PrincipledMaterial {
            baseColor: "blue"
            metalness: 0.5
            roughness: 0.3
        }
    }
}

Shaders de aumento para múltiples objetivos de renderizado

Al utilizar el mod RenderPass.AugmentMaterial, se proporciona un sombreador de aumento que inyecta código personalizado en el sombreador de fragmentos del material. Esto resulta especialmente útil para el renderizado diferido, en el que es necesario enviar datos de material a múltiples destinos de renderizado (MRT).

La función MAIN_FRAGMENT_AUGMENT

El archivo del sombreador de ampliación debe definir una función « MAIN_FRAGMENT_AUGMENT() »:

void MAIN_FRAGMENT_AUGMENT()
{
    // Your custom shader code here
}

Esta función se invoca durante el shader de fragmentos, una vez finalizados los cálculos del material, lo que permite acceder a las propiedades del material y escribir en salidas personalizadas.

Variables integradas disponibles

Dentro de ` MAIN_FRAGMENT_AUGMENT()`, el motor sustituye un conjunto de macros que exponen datos del canal de materiales. Solo las macros que se enumeran a continuación forman parte de la API del sombreador de aumento:

MacroTipoDescripción
BASE_COLORvec4Color base del material (espacio de color lineal, tras el procesamiento del material).
METALNESSfloatMetalicidad del material en el rango de 0,0 a 1,0.
ROUGHNESSfloatRugosidad del material en el rango de 0,0 a 1,0.
WORLD_NORMALvec3Normal de la superficie en el espacio mundial (tras el mapeado normal).
WORLD_TANGENTvec3Vector tangente en el espacio mundial.
WORLD_BINORMALvec3Vector binormal en el espacio mundial.
DIFFUSE_LIGHTvec3Contribución acumulada de la luz difusa.
SPECULAR_LIGHTvec3Contribución acumulada de la luz especular.
EMISSIVE_LIGHTvec3Contribución emisiva del material.
F0vec3Reflectancia de Fresnel en incidencia normal.
F90vec3Reflectancia de Fresnel con incidencia rasante.

Nota: Algunos ejemplos (incluido el de renderizado diferido que aparece a continuación) leen la posición del fragmento en el espacio del mundo mediante ` qt_varWorldPos`. Se trata del nombre variable subyacente del motor, no de una macro de Augment-Shader, y entra en la misma categoría semipública que los archivos « .glsllib » descritos en «Funcionalidades de shaders integradas»: funciona en la práctica, pero no se garantiza que se mantenga estable en futuras versiones.

Escribir en salidas con nombre

Los adjuntos de color de tu pasada de renderizado pueden tener nombres que se correspondan con variables de salida de tu sombreador:

RenderPass {
    commands: [
        ColorAttachment { target: tex0; name: "GBUFFER0" },
        ColorAttachment { target: tex1; name: "GBUFFER1" },
        ColorAttachment { target: tex2; name: "GBUFFER2" }
    ]
}

En tu shader «augment»:

void MAIN_FRAGMENT_AUGMENT()
{
    GBUFFER0 = vec4(...);  // Writes to first attachment
    GBUFFER1 = vec4(...);  // Writes to second attachment
    GBUFFER2 = vec4(...);  // Writes to third attachment
}

Qt Quick 3D admite hasta 4 adjuntos de color simultáneos (de GBUFFER0 a GBUFFER3).

Ejemplo completo de shader de aumento

A continuación se muestra un ejemplo completo de un paso de G-buffer de renderizado diferido:

// gbuffer_augment.glsl
void MAIN_FRAGMENT_AUGMENT()
{
    // Get material properties
    vec3 baseColor = BASE_COLOR.rgb;
    float metalness = METALNESS;
    float roughness = ROUGHNESS;
    vec3 worldNormal = normalize(WORLD_NORMAL);
    vec3 worldPos = qt_varWorldPos;

    // GBuffer 0: Albedo (RGB) + Metalness (A)
    GBUFFER0 = vec4(baseColor, metalness);

    // GBuffer 1: World Normal (RGB) + Roughness (A)
    // Encode normal from [-1,1] to [0,1] for storage
    GBUFFER1 = vec4(worldNormal * 0.5 + 0.5, roughness);

    // GBuffer 2: World Position
    GBUFFER2 = vec4(worldPos, 1.0);
}

Cuando se utiliza con un paso de renderizado (RenderPassTexture, las instancias se declaran como hijos directos del View3D que las contiene y se hace referencia a ellas mediante su id):

View3D {
    RenderPassTexture { id: gbuffer0; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: gbuffer1; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: gbuffer2; format: RenderPassTexture.RGBA16F }

    RenderPass {
        id: gbufferPass
        materialMode: RenderPass.AugmentMaterial
        augmentShader: "gbuffer_augment.glsl"
        commands: [
            ColorAttachment { target: gbuffer0; name: "GBUFFER0" },
            ColorAttachment { target: gbuffer1; name: "GBUFFER1" },
            ColorAttachment { target: gbuffer2; name: "GBUFFER2" },
            DepthStencilAttachment { }
        ]
    }
}

Conservación del comportamiento del material

El shader de aumento se ejecuta además del proceso habitual de materiales, no en su lugar. Esto significa que:

  • Las texturas, propiedades y cálculos del material siguen aplicándose
  • Se añaden salidas adicionales, no se sustituye la salida de color principal
  • La salida RGBA del material original sigue escribiéndose en el primer anexo de color, a menos que se sobrescriba

Si solo necesitas generar datos personalizados y no necesitas los cálculos estándar del material, plantéate utilizar en su lugar « RenderPass.OverrideMaterial ».

Cuándo utilizar «Augment» frente a «Override»

Utiliza « AugmentMaterial » cuando:

  • Necesites propiedades del material (metalicidad, rugosidad, normales) para los G-buffers
  • Desees aprovechar las características existentes de los materiales, como el mapeado de texturas
  • Necesites múltiples objetivos de renderizado con datos de material

Utiliza « OverrideMaterial » cuando:

  • Necesites un comportamiento idéntico para todos los objetos (prepaso de profundidad, mapas de sombras)
  • No necesites propiedades específicas por material
  • Quieres obtener el máximo rendimiento evitando los cálculos de los materiales

Funcionalidades de shaders integradas

Los shaders de ampliación y los materiales personalizados utilizados en las pasadas de renderizado tienen acceso a la infraestructura de shaders integrada de « Qt Quick 3D» a través de un sistema de inclusión. Estos archivos de biblioteca de shaders (.glsllib) proporcionan funcionalidades para la iluminación, las sombras, el mapeo de tonos y mucho más.

Sintaxis de inclusión:

Utiliza las directivas « \#include » en tu código de sombreador para importar funcionalidades:

#include "tonemapping.glsllib"
#include "lightsData.glsllib"
#include "shadowMapping.glsllib"
#include "funcprocessPunctualLighting.glsllib"

void MAIN()
{
    // Use included functions
    vec3 color = qt_tonemap(hdrColor);
}

Bibliotecas de sombreadores disponibles:

Estas bibliotecas de sombreadores se encuentran en el motor en src/runtimerender/res/effectlib/ y se consideran semipúblicas: se pueden utilizar en sombreadores de usuario, pero no ofrecen las mismas garantías de compatibilidad binaria que el resto de la API pública de Qt.

BibliotecaDescripción
tonemapping.glsllibProporciona la función qt_tonemap() para la conversión de HDR a LDR utilizando el algoritmo de mapeo de tonos integrado
lightsData.glsllibContiene información sobre la iluminación de la escena (posiciones de las luces, colores, direcciones, etc.) a la que se puede acceder en cálculos de iluminación personalizados
shadowMapping.glsllibProporciona funciones para el muestreo a partir de los mapas de sombras predeterminados, lo que permite que los materiales personalizados reciban sombras
funcprocessPunctualLighting.glsllibContiene « qt_processPunctualLighting() » y otras funciones de iluminación integradas para cálculos estándar de iluminación PBR
sampleProbe.glsllibFunciones para el muestreo de sondas de iluminación basadas en imágenes (qt_sampleDiffuse(), qt_sampleGlossyPrincipled())

Ejemplo: Iluminación personalizada con funciones integradas

A continuación se muestra un ejemplo de sombreador de fragmentos que utiliza las funciones de iluminación integradas:

#include "lightsData.glsllib"
#include "funcprocessPunctualLighting.glsllib"
#include "tonemapping.glsllib"
#include "sampleProbe.glsllib"

void MAIN()
{
    vec3 worldPos = ...; // From G-buffer or varying
    vec3 normal = ...;
    vec3 viewDir = normalize(CAMERA_POSITION - worldPos);
    vec3 baseColor = ...;
    float roughness = ...;
    float metalness = ...;

    vec3 F0 = mix(vec3(0.04), baseColor, metalness);

    vec3 diffuseAccum = vec3(0.0);
    vec3 specAccum = vec3(0.0);

    // Use built-in punctual lighting (directional, point, spot lights)
    qt_processPunctualLighting(diffuseAccum,
                               specAccum,
                               baseColor,
                               worldPos,
                               normal,
                               viewDir,
                               vec3(1.0), // specularAmount
                               vec3(1.0), // specularTint
                               roughness,
                               metalness,
                               F0,
                               vec3(1.0)); // F90

    // Add image-based lighting
    vec4 probeDiffuse = vec4(baseColor, 1.0) * qt_sampleDiffuse(normal);
    vec4 probeSpecular = qt_sampleGlossyPrincipled(normal, viewDir, F0, roughness);
    diffuseAccum += probeDiffuse.rgb;
    specAccum += probeSpecular.rgb;

    vec3 color = diffuseAccum + specAccum;

    // Apply tonemapping
    FRAGCOLOR = vec4(qt_tonemap(color), 1.0);
}

Nota: Estas bibliotecas de sombreadores son una API semipública. Aunque son estables y están pensadas para su uso en sombreadores personalizados, Qt no garantiza que su implementación interna o las funciones disponibles permanezcan inalteradas entre versiones. Sin embargo, es poco probable que funciones de uso común como qt_tonemap() y qt_processPunctualLighting() cambien de forma significativa.

Ejemplo avanzado: renderizado diferido

El renderizado diferido es una técnica en la que la información geométrica se renderiza en múltiples texturas (denominadas «G-buffer» o «búfer de geometría») en una primera pasada, y los cálculos de iluminación se realizan en una segunda pasada utilizando los datos geométricos almacenados. Este enfoque resulta especialmente eficiente cuando hay muchas luces, ya que cada píxel se sombrea solo una vez, independientemente del número de luces.

Arquitectura del renderizado diferido

El proceso de renderizado diferido consta de dos pasadas principales:

  1. Pasa de geometría (pasa del G-buffer): renderiza la geometría de la escena en múltiples objetivos de renderizado, almacenando propiedades de los materiales como el albedo, las normales, la rugosidad, la metalicidad y la posición en el mundo.
  2. Pasa de iluminación: renderiza un cuadrilátero a pantalla completa que muestrea los G-buffers y realiza cálculos de iluminación para cada píxel basándose en los datos geométricos almacenados.

Implementación de la pasada de G-Buffer

En primer lugar, define una pasada de G-buffer que envíe los datos de los materiales a múltiples destinos de renderizado:

GBufferPass.qml: Los objetivos de renderizado del G-buffer se exponen como propiedades obligatorias, de modo que el « View3D » que los engloba los proporciona y puede leer sus resultados:

import QtQuick
import QtQuick3D

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

    property alias layerMask: filter.layerMask

    // Provided by the View3D that uses this pass
    required property RenderPassTexture gbuffer0   // rgb: baseColor, a: metalness
    required property RenderPassTexture gbuffer1   // rgb: normal,    a: roughness
    required property RenderPassTexture gbuffer2   // rgb: world pos, a: spare
    required property RenderPassTexture depthTexture

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

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

gbuffer_augment.glsl:

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

El shader de ampliación accede a las propiedades del material calculadas por el proceso de materiales y las escribe en los tres anexos del G-buffer. Las normales se codifican del rango [-1,1] al rango [0,1] para su almacenamiento.

Implementación de la pasada de iluminación

La pasada de iluminación renderiza un cuadrilátero a pantalla completa que muestrea los G-buffers y calcula la iluminación:

// Lighting pass model (full-screen quad)
Model {
    id: deferredLightingQuad
    layers: ContentLayer.Layer13  // Dedicated layer for lighting quad

    geometry: PlaneGeometry {
        plane: PlaneGeometry.XY  // Quad in screen space
    }

    materials: CustomMaterial {
        // Texture inputs for G-buffers
        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"
    }
}

// Lighting pass renders the quad to main output
RenderPass {
    id: deferredLightingPass
    materialMode: RenderPass.OriginalMaterial

    commands: [
        ColorAttachment { target: mainColorTexture },
        DepthStencilAttachment { },
        RenderablesFilter { layerMask: ContentLayer.Layer13 }
    ]
}

El shader de vértices de iluminación (lighting.vert) crea un cuadrilátero a pantalla completa en coordenadas normalizadas del dispositivo, y el shader de fragmentos (lighting.frag) muestrea los G-buffers y realiza los cálculos de iluminación.

Integración completa

A continuación se explica cómo integrar ambas pasadas en un View3D:

View3D {
    renderOverrides: View3D.DisableInternalPasses

    // Main output texture
    RenderPassTexture { id: mainColorTexture; format: RenderPassTexture.RGBA16F }

    // Shared depth texture
    RenderPassTexture { id: mainDepthStencilTexture; format: RenderPassTexture.Depth24Stencil8 }

    // G-buffer render targets
    RenderPassTexture { id: gbuffer0Tex; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: gbuffer1Tex; format: RenderPassTexture.RGBA16F }
    RenderPassTexture { id: gbuffer2Tex; format: RenderPassTexture.RGBA16F }

    // G-buffer pass
    GBufferPass {
        id: gbufferPass
        layerMask: ContentLayer.Layer0 | ContentLayer.Layer1
        gbuffer0: gbuffer0Tex
        gbuffer1: gbuffer1Tex
        gbuffer2: gbuffer2Tex
        depthTexture: mainDepthStencilTexture
    }

    // Expose G-buffer outputs
    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
    }

    // Lighting pass (defined above)

    // Display final result
    SimpleQuadRenderer {
        texture: Texture {
            textureProvider: RenderOutputProvider {
                textureSource: RenderOutputProvider.UserPassTexture
                renderPass: deferredLightingPass
                attachmentSelector: RenderOutputProvider.Attachment0
            }
        }
    }

    // Scene objects
    Model {
        layers: ContentLayer.Layer0
        source: "#Sphere"
        materials: PrincipledMaterial {
            baseColor: "red"
            metalness: 0.5
            roughness: 0.3
        }
    }

    // Camera and lights
    PerspectiveCamera { z: 300 }
    DirectionalLight { eulerRotation.x: -45 }
}

Flujo de renderizado

El renderizado se lleva a cabo de la siguiente manera:

  1. Pase de G-buffer: Se renderizan los objetos de la escena en las capas Layer0 y Layer1. Para cada objeto, el sombreador de aumento escribe el albedo, las normales, la rugosidad, la metalicidad y la posición en tres adjuntos de color. La profundidad se escribe en la textura de profundidad compartida.
  2. Pasa de iluminación: Se renderiza el cuadrado a pantalla completa de la Capa 13. Su material personalizado toma muestras de las tres texturas del G-buffer y de la textura de profundidad, reconstruye la información de la escena y realiza cálculos de iluminación (luces direccionales, iluminación basada en imágenes, etc.) para producir el color iluminado final.
  3. Visualización: El resultado de la pasada de iluminación se muestra mediante SimpleQuadRenderer.

Ventajas y limitaciones

Ventajas:

  • Eficaz con muchas luces (cada píxel se ilumina una vez)
  • La complejidad de la iluminación es independiente de la complejidad de la escena
  • Fácil implementación de efectos en el espacio de pantalla
  • Desacopla las pasadas de geometría y de iluminación

Limitaciones:

  • Mayor ancho de banda de memoria debido a las lecturas y escrituras en el G-buffer
  • No hay MSAA por hardware (requiere un antialiasing alternativo)
  • La transparencia requiere una pasada directa independiente
  • Proceso más complejo de configurar y mantener

Para ver un ejemplo completo y funcional, consulta «Qt Quick 3D - Ejemplo de pasadas de usuario».

Ejemplo completo de canalización de renderizado

Un proceso de renderizado personalizado y realista suele necesitar combinar varios tipos de pasadas: geometría opaca, fondo de skybox, superposiciones 2D y objetos transparentes. A continuación se muestra un ejemplo completo que ilustra cómo organizarlos utilizando « SubRenderPass » para la composición jerárquica:

View3D {
    renderOverrides: View3D.DisableInternalPasses

    environment: SceneEnvironment {
        backgroundMode: SceneEnvironment.SkyBox
        lightProbe: Texture {
            textureData: ProceduralSkyTextureData { }
        }
    }

    RenderPassTexture {
        id: mainColorTexture
        format: RenderPassTexture.RGBA16F
    }

    RenderPassTexture {
        id: mainDepthStencilTexture
        format: RenderPassTexture.Depth24Stencil8
    }

    // Main pass orchestrates the complete render path:
    // 1. Opaque geometry (deferred)
    // 2. Skybox background
    // 3. 2D UI overlays
    // 4. Transparent objects (forward)
    RenderPass {
        id: mainColorPass
        clearColor: "black"
        renderTargetFlags: RenderPass.PreserveDepthStencilContents

        commands: [
            ColorAttachment { target: mainColorTexture },
            DepthTextureAttachment { target: mainDepthStencilTexture },
            RenderablesFilter {
                renderableTypes: RenderablesFilter.None  // Parent doesn't render
            },

            // Sub-pass 1: Deferred lighting
            SubRenderPass {
                renderPass: RenderPass {
                    id: deferredLightingPass
                    materialMode: RenderPass.OriginalMaterial
                    commands: [
                        PipelineStateOverride {
                            depthWriteEnabled: false
                            depthTestEnabled: false
                        },
                        RenderablesFilter { layerMask: ContentLayer.Layer13 }
                    ]
                }
            },

            // Sub-pass 2: Skybox (behind everything)
            SubRenderPass {
                renderPass: RenderPass {
                    passMode: RenderPass.SkyboxPass
                    commands: [
                        PipelineStateOverride {
                            depthTestEnabled: true
                            depthWriteEnabled: false
                        }
                    ]
                }
            },

            // Sub-pass 3: 2D Qt Quick content
            SubRenderPass {
                renderPass: RenderPass {
                    passMode: RenderPass.Item2DPass
                }
            },

            // Sub-pass 4: Transparent objects (forward rendering)
            SubRenderPass {
                renderPass: RenderPass {
                    materialMode: RenderPass.OriginalMaterial
                    commands: [
                        RenderablesFilter {
                            renderableTypes: RenderablesFilter.Transparent
                            layerMask: ContentLayer.Layer0 | ContentLayer.Layer1
                        },
                        PipelineStateOverride {
                            blendEnabled: true
                            depthTestEnabled: true
                            depthWriteEnabled: false
                        }
                    ]
                }
            }
        ]
    }

    // G-buffer pass (referenced by deferred lighting)
    GBufferPass {
        id: gbufferPass
        layerMask: ContentLayer.Layer0 | ContentLayer.Layer1
        depthTexture: mainDepthStencilTexture
    }

    // Full-screen quad for deferred lighting
    Model {
        layers: ContentLayer.Layer13
        geometry: PlaneGeometry { plane: PlaneGeometry.XY }
        materials: CustomMaterial {
            property TextureInput gbuffer0: TextureInput {
                texture: Texture {
                    textureProvider: RenderOutputProvider {
                        textureSource: RenderOutputProvider.UserPassTexture
                        renderPass: gbufferPass
                        attachmentSelector: RenderOutputProvider.Attachment0
                    }
                }
            }
            // ... other G-buffer inputs
            shadingMode: CustomMaterial.Unshaded
            fragmentShader: "lighting.frag"
            vertexShader: "lighting.vert"
        }
    }

    // Display final result
    SimpleQuadRenderer {
        texture: Texture {
            textureProvider: RenderOutputProvider {
                textureSource: RenderOutputProvider.UserPassTexture
                renderPass: mainColorPass
            }
        }
    }

    // Opaque 3D content
    Model {
        layers: ContentLayer.Layer0
        source: "#Sphere"
        materials: PrincipledMaterial { baseColor: "red" }
    }

    // Transparent 3D content
    Model {
        layers: ContentLayer.Layer1
        source: "#Cone"
        materials: PrincipledMaterial {
            baseColor: Qt.rgba(0.0, 1.0, 0.0, 0.5)
            alphaMode: PrincipledMaterial.Blend
        }
    }

    // 2D content in 3D space
    Node {
        x: -200
        y: 100
        Item {
            Button { text: "Click Me!" }
            Rectangle {
                color: "blue"
                width: 50; height: 50
            }
        }
    }

    PerspectiveCamera { z: 300 }
    DirectionalLight { eulerRotation.x: -45 }
}

Conceptos clave

SubRenderPass para la organización jerárquica:

La pasada principal utiliza comandos « SubRenderPass » para ejecutar las pasadas secundarias de forma secuencial. La pasada principal en sí misma no renderiza nada (RenderablesFilter.None), sino que se limita a coordinar las pasadas secundarias. Esto proporciona una estructura clara y permite compartir el búfer de profundidad entre todas las subpasadas.

Modos de paso:

  • RenderPass.UserPass (por defecto): Renderizado personalizado con tu geometría y materiales
  • RenderPass.SkyboxPass: Renderiza el skybox del entorno a partir de SceneEnvironment
  • RenderPass.Item2DPass: Renderiza contenido 2D de « Qt Quick » integrado en la escena 3D

Orden de renderizado:

  1. Geometría opaca renderizada en el G-buffer
  2. Iluminación diferida aplicada al cuadrilátero a pantalla completa
  3. El skybox se renderiza detrás de la geometría (prueba de profundidad activada, escritura de profundidad desactivada)
  4. Las superposiciones de la interfaz de usuario 2D se renderizan encima
  5. Los objetos transparentes se renderizan en último lugar con mezcla

Compartición del búfer de profundidad:

El búfer de profundidad ( mainDepthStencilTexture ) se comparte entre pasadas mediante la función « PreserveDepthStencilContents ». Esto garantiza que el skybox se renderice detrás de la geometría y que los objetos transparentes se comparen correctamente con la geometría opaca.

Contenido de Item2D:

Qt Quick Los elementos 2D (botones, rectángulos, texto, etc.) colocados en objetos « Node » se renderizan mediante « RenderPass.Item2DPass ». Estos elementos se sitúan en el espacio 3D, pero se renderizan como superposiciones 2D que pueden recibir entradas del ratón o táctiles.

Consideraciones sobre el rendimiento

Las pasadas de renderizado definidas por el usuario ofrecen el máximo control, pero requieren un análisis minucioso de las implicaciones en el rendimiento.

Opciones de formato de textura

Elige los formatos de textura en función de tus necesidades:

FormatoTamaño por píxelCaso de uso
RGBA84 bytesSalida final, búferes de color sencillos
RGBA16F8 bytesContenido HDR, búferes intermedios, normales
RGBA32F16 bytesCálculos de alta precisión, posiciones
R16F2 bytesHDR monocanal (profundidad, AO, etc.)

Para un búfer de fotogramas de 1920x1080:

  • RGBA8: ~8 MB
  • RGBA16F: ~16 MB
  • RGBA32F: ~32 MB
  • Tres G-buffers RGBA16F: ~48 MB

Recomendación: utiliza RGBA16F para los búferes intermedios y RGBA8 o R8 cuando sea suficiente.

Renderizado diferido frente a renderizado directo

AspectoRenderizado diferidoRenderizado directo
Muchas lucesEficiente (O(luces + píxeles))Costoso (O(luces * objetos))
Ancho de banda de memoriaElevado (lecturas/escrituras en el G-buffer)Bajo
TransparenciaRequiere una pasada separadaCompatibilidad nativa
MSAANo es compatible directamenteFunciona el MSAA por hardware
Complejidad de la configuraciónMás complejaMás sencilla

Utiliza el renderizado diferido cuando:

  • Tengas muchas luces (más de 10)
  • Los efectos en el espacio de pantalla sean importantes
  • La escena es mayoritariamente opaca

Utiliza el renderizado directo cuando:

  • Haya pocas luces (<5)
  • Hay mucha transparencia
  • El ancho de banda de memoria sea limitado
  • Se prefiera un proceso más sencillo

Optimización del orden de las pasadas

Las pasadas de renderizado se ejecutan en el orden en que se encuentran. Optimiza mediante:

  • Renderizar la geometría opaca antes que la transparente
  • Utilizando un paso previo de profundidad cuando resulte beneficioso (reduce el sobredibujado en escenas complejas)
  • Minimizar los cambios de destino de renderizado
  • Reutilizando los búferes de profundidad entre pasadas siempre que sea posible

Indicadores del destino de renderizado

La propiedad « renderTargetFlags » controla el comportamiento de la memoria:

RenderPass {
    // First pass: write new content
    renderTargetFlags: 0  // Default: clear render targets
}

RenderPass {
    // Second pass: add to existing content
    renderTargetFlags: RenderPass.PreserveColorContents |
                      RenderPass.PreserveDepthStencilContents
}

RenderPass {
    // Depth not needed after this pass
    renderTargetFlags: RenderPass.DoNotStoreDepthStencilContents
}

PreserveColorContents/PreserveDepthStencilContents: conserva los datos existentes (por ejemplo, para el renderizado de múltiples pasadas en el mismo destino).

DoNotStoreDepthStencilContents: indica que la profundidad y la plantilla se pueden descartar (en algunos equipos, esto puede mejorar el rendimiento al evitar escrituras en memoria).

Cuándo utilizar pasadas de usuario

Considera la posibilidad de utilizar pasadas de renderizado de usuario cuando:

  • Se implemente el renderizado diferido
  • Se creen efectos complejos de múltiples pasadas
  • Se necesite un control explícito sobre el orden de renderizado
  • Al implementar técnicas de renderizado personalizadas
  • Al crear efectos en el espacio de pantalla que requieran datos geométricos

Evita las pasadas de usuario cuando:

  • El renderizado predeterminado satisfaga tus necesidades
  • Solo necesites posprocesamiento (utiliza Effect en su lugar)
  • Solo necesites sombreadores de materiales personalizados (utiliza en su lugar CustomMaterial )
  • El rendimiento sea fundamental y las pasadas adicionales supongan un desperdicio

Patrones comunes y casos de uso

Las pasadas de renderizado definidas por el usuario permiten muchas técnicas de renderizado avanzadas. Estos son algunos patrones comunes:

Sombreado/iluminación diferidos

Almacena los atributos geométricos en G-buffers y realiza la iluminación en el espacio de pantalla. Se trata en detalle en el ejemplo avanzado: Renderizado diferido.

Detección de bordes y delineado

Renderiza la escena normalmente y, a continuación, aplica la detección de bordes en una segunda pasada:

// Pass 1: Render scene with normals/depth
RenderPass {
    id: scenePass
    commands: [
        ColorAttachment { target: colorTex },
        DepthTextureAttachment { target: depthTex }
    ]
}

// Pass 2: Edge detection using depth discontinuities
RenderPass {
    id: edgePass
    commands: [
        ColorAttachment { target: outlineTex },
        RenderablesFilter { layerMask: ContentLayer.Layer10 }
    ]
}

Model {
    layers: ContentLayer.Layer10
    geometry: PlaneGeometry { }
    materials: CustomMaterial {
        property TextureInput depthInput: TextureInput {
            // depthProvider is the id of a RenderOutputProvider that exposes
            // depthTex as a sampleable texture (see "Render Output Provider"
            // earlier in this page).
            texture: Texture { textureProvider: depthProvider }
        }
        fragmentShader: "edge_detect.frag"
        // Shader samples depth, computes gradients, draws edges
    }
}

Cadenas de posprocesado personalizadas

Encadena varios efectos de posprocesamiento alimentando la salida de cada pasada a la siguiente mediante RenderOutputProvider. Consulta el «Ejemplo de encadenamiento de pasadas» para ver un ejemplo práctico de una cadena de varias etapas (scenePass → process1 → process2 → visualización).

Superposición selectiva de estructura alámbrica

Renderiza algunos objetos como sólidos y otros como superposiciones de estructura alámbrica. Consulta el ejemplo en «Trabajar con capas».

Visualización de depuración

Crea pasadas de depuración que visualicen normales, profundidad u otros datos:

// Normal visualization pass
RenderPass {
    materialMode: RenderPass.OverrideMaterial
    overrideMaterial: CustomMaterial {
        fragmentShader: "debug_normals.frag"
        // FRAGCOLOR = vec4(normalize(NORMAL) * 0.5 + 0.5, 1.0);
    }
    commands: [
        ColorAttachment { target: debugTex }
    ]
}

Mapeo de sombras personalizado

Implementa un mapeo de sombras personalizado con control explícito:

// Shadow map pass (render from light's perspective)
RenderPass {
    id: shadowPass
    materialMode: RenderPass.OverrideMaterial
    overrideMaterial: CustomMaterial {
        fragmentShader: "depth_only.frag"
    }
    commands: [
        DepthTextureAttachment { target: shadowMapTex }
    ]
}

// Main pass using shadow map
RenderPass {
    id: mainPass
    commands: [
        ColorAttachment { target: colorTex },
        DepthStencilAttachment { }
    ]
}

// Materials in main pass sample shadowMapTex for shadow testing

Consideraciones importantes

Al trabajar con pasadas de renderizado de usuario, ten en cuenta estos puntos importantes:

Manejo de las sombras

Las pasadas de renderizado de usuario no incluyen automáticamente el renderizado interno de sombras de Qt Quick 3D. Si desactivas las pasadas internas y necesitas sombras, debes:

  • Implementar tus propias pasadas de mapeado de sombras
  • Renderizar la escena desde la perspectiva de la luz en una textura de profundidad
  • Muestrear el mapa de sombras en tus cálculos de iluminación

Como alternativa, en casos más sencillos, es posible que no necesites sombras o que puedas utilizar mapas de sombras precalculados.

HDR y mapeo de tonos

Al utilizar objetivos de renderizado de punto flotante (RGBA16F, RGBA32F), el renderizado se realiza en el espacio HDR lineal. Debes aplicar el mapeo de tonos en tu pasada de visualización final para convertirlo a LDR visualizable:

CustomMaterial {
    fragmentShader: "tonemap.frag"
}
// In tonemap.frag
vec3 tonemap(vec3 hdr) {
    // Simple Reinhard tonemapping
    return hdr / (hdr + vec3(1.0));
}

void MAIN() {
    vec3 hdrColor = texture(hdrInput, UV0).rgb;
    FRAGCOLOR = vec4(tonemap(hdrColor), 1.0);
}

Qt Quick 3D proporciona una función ` qt_tonemap() ` en los shaders que se puede utilizar para este fin.

Generación de texturas de profundidad

Cuando necesites la profundidad como textura (para efectos como la profundidad de campo), utiliza ` DepthTextureAttachment ` en lugar de ` DepthStencilAttachment`:

RenderPassTexture {
    id: depthTex
    format: RenderPassTexture.Depth24Stencil8
}

RenderPass {
    commands: [
        ColorAttachment { target: colorTex },
        DepthTextureAttachment { target: depthTex }
        // depthTex can now be sampled in shaders
    ]
}

Valores de borrado y gestión de objetivos de renderizado

Cada pasada puede especificar valores de borrado:

RenderPass {
    clearColor: Qt.rgba(0.0, 0.0, 0.0, 0.0)
    depthClearValue: 1.0
    stencilClearValue: 0
}

Cuando un paso no conserva el contenido (por defecto), los objetivos de renderizado se borran con estos valores antes del renderizado. Cuando se establece « PreserveColorContents » o « PreserveDepthStencilContents », se conserva el contenido existente y se ignoran los valores de borrado.

Prácticas recomendadas para la organización de capas

Organiza tus capas de forma lógica:

  • Capa 0-2: Objetos principales de la escena
  • Capas 3-4: Objetos transparentes (paso independiente)
  • Capa 10+: Cuadrantes a pantalla completa para el posprocesamiento
  • Capa 15+: superposiciones de interfaz de usuario/depuración

Documenta el uso de las capas en los comentarios y mantén la coherencia en toda la aplicación.

Compatibilidad de shaders

Los shaders de Augment y los materiales personalizados utilizados en las pasadas de renderizado deben ser compatibles con la infraestructura de shaders de Qt Quick 3D:

  • Utiliza sintaxis compatible con GLSL
  • Incluye las directivas de « \#include » adecuadas para las funciones de « Qt Quick » 3D
  • Ten en cuenta las variables integradas disponibles
  • Realiza pruebas en todas las plataformas de destino (OpenGL, Vulkan, Metal, D3D)

Limitaciones de los objetivos de renderizado múltiples

Al utilizar múltiples objetivos de renderizado (MRT):

  • Máximo de 4 adjuntos de color
  • Todos los anexos deben tener las mismas dimensiones
  • El estado de mezcla se puede especificar por adjunto mediante PipelineStateOverride
  • No todo el hardware es compatible con MRT (comprueba las capacidades del dispositivo)

Transparencia

Los objetos transparentes plantean dificultades con el renderizado diferido. Enfoques habituales:

  • Pasa directa para los objetos transparentes: renderizar la geometría opaca de forma diferida y la geometría transparente en una pasa directa independiente
  • G-buffer transparente independiente: renderizar la geometría transparente en un conjunto independiente de G-buffers con la mezcla activada
  • Transparencia ponderada con mezcla independiente del orden: utilizar técnicas OIT especializadas

En la mayoría de los casos, lo más sencillo es realizar una pasada directa independiente para los objetos transparentes.

Referencia de la API

La siguiente tabla ofrece una referencia completa de todos los tipos relacionados con las pasadas de renderizado del usuario:

CaracterísticaTipo QMLDescripción
Definición de la pasada de renderizado principalRenderPassDefine una pasada de renderizado con comandos y modo de material
Texturas de destino de renderizadoRenderPassTextureTextura utilizada como destino de renderizado (color o profundidad/plantilla)
Proveedor de salida de texturasRenderOutputProviderExpone la salida del paso de renderizado como entrada de textura
Constantes de capaContentLayerSingleton que proporciona constantes de filtrado de capas
Salida de colorColorAttachmentEspecifica un destino de renderizado de color
Profundidad/plantilla (por defecto)DepthStencilAttachmentUtiliza un búfer implícito de profundidad/plantilla
Profundidad/plantilla (textura)DepthTextureAttachmentUtiliza una textura de profundidad explícita
Filtrado de objetosRenderablesFilterFiltra los objetos por capa y tipo
Estado del canal de procesamientoPipelineStateOverrideAnula el estado del canal de procesamiento gráfico
Ejecución de pasadas anidadasSubRenderPassEjecuta otra pasada de renderizado
Definiciones de shaderAddDefineAñade una definición del preprocesador del shader
Estado de mezcla por destinorenderTargetBlendConfiguración de mezcla para MRT
Ayudante de visualizaciónSimpleQuadRendererRenderiza la salida final en View3D
TipoDescripción
CustomMaterialMaterial personalizado con sombreadores de vértices/fragmentos
EffectEfectos de posprocesamiento
View3DVista 3D con la propiedad « renderOverrides »
ModelModelo 3D con la propiedad « layers »

Ejemplos

Véase también

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