qtquick3d-userpasses.qdoc

Go to the documentation of this file.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtquick3d-userpasses.html
\title User-Defined Render Passes in Qt Quick 3D
\brief Controlling the rendering pipeline with custom render passes
 
\since 6.11
 
Qt Quick 3D provides a high-level API for 3D rendering that handles most rendering
details automatically. However, for advanced use cases, applications may need complete
control over the rendering pipeline. User-defined render passes enable this by allowing
applications to disable the internal rendering pipeline and define their own custom passes.
 
User render passes enable advanced rendering techniques such as:
 
\list
\li Deferred shading and lighting
\li Multi-pass rendering effects
\li Custom post-processing pipelines
\li Selective rendering with layer-based filtering
\li Screen-space effects (ambient occlusion, reflections, etc.)
\li Custom shadow mapping techniques
\li Debug visualization passes
\endlist
 
\section1 Levels of Customization
 
Qt Quick 3D offers three complementary levels of rendering customization, each suited
to different use cases:
 
\table
\header
\li Level
\li Scope
\li Use Cases
\row
\li \l Effect
\li Post-processing
\li Applies effects after the scene is rendered (blur, color grading, etc.)
\row
\li \l CustomMaterial
\li Per-material shaders
\li Custom vertex and fragment shaders for individual materials
\row
\li \l RenderPass (User Render Passes)
\li Complete pipeline control
\li Deferred rendering, multiple passes, custom render targets
\endtable
 
User render passes (\l RenderPass) provide the most control, allowing you to either
supplement or completely replace the default rendering pipeline. This complements
\l CustomMaterial and \l Effect: \l CustomMaterial customizes how individual objects
are rendered, while user render passes control the overall rendering strategy and
architecture.
 
\section1 Using User Render Passes
 
User render passes can be used in two ways:
 
\section2 Supplementing Internal Passes
 
You can add custom \l RenderPass objects alongside the default rendering pipeline without
disabling internal passes. This is useful for rendering to textures that are then used by
\l Effect or \l CustomMaterial, or for creating auxiliary render targets.
 
\qml
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
}
\endqml
 
\section2 Replacing Internal Passes
 
For complete control over the rendering pipeline, disable Qt Quick 3D's internal rendering
by setting the \l{View3D::renderOverrides}{renderOverrides} property:
 
\qml
View3D {
    renderOverrides: View3D.DisableInternalPasses
 
    // Your custom render passes go here
}
\endqml
 
When internal passes are disabled, Qt Quick 3D will not perform any default rendering.
This means you must:
 
\list
\li Define at least one \l RenderPass to render your scene
\li Provide the final output texture to display via \l SimpleQuadRenderer or similar mechanism
\li Handle all rendering aspects including depth buffers, transparency, etc.
\endlist
 
\note Disabling internal passes gives you complete control, but also complete responsibility.
Features like automatic shadow rendering, transparency sorting, and environment reflections
must be implemented in your custom passes if needed.
 
\section1 Core Concepts
 
User-defined render passes are built from several key components:
 
\section2 RenderPass
 
The \l RenderPass type is the main building block. It defines a single rendering operation
with a set of commands that control what gets rendered and how. Each pass can:
 
\list
\li Render to one or more color textures (up to 4 simultaneous render targets)
\li Write depth and stencil information
\li Filter which objects to render based on layers
\li Override graphics pipeline state (blending, culling, etc.)
\li Use original materials, augment them with custom shaders, or override them entirely
\endlist
 
\section2 RenderPassTexture
 
The \l RenderPassTexture type defines textures that serve as render targets. These can be
color textures in various formats (RGBA8, RGBA16F, RGBA32F, etc.) or depth/stencil
textures. Render pass textures are used as outputs from one pass and can be used as
texture inputs to subsequent passes.
 
\section2 RenderOutputProvider
 
The \l RenderOutputProvider type connects render passes by exposing the output textures
from one pass as texture inputs that can be used by materials or other passes. This is
essential for multi-pass rendering where later passes need to read the results of
earlier passes.
 
\section2 ContentLayer
 
The \l ContentLayer singleton provides layer constants (Layer0 through Layer23) used for
filtering which objects render in which pass. By assigning objects to specific layers and
using \l RenderablesFilter in your passes, you can control precisely what gets rendered
in each pass.
 
\section2 Render Commands
 
Each \l RenderPass contains a list of commands that configure its behavior:
 
\list
\li \l ColorAttachment: Specifies a color render target
\li \l DepthStencilAttachment: Specifies depth/stencil handling
\li \l DepthTextureAttachment: Uses a texture for depth output
\li \l RenderablesFilter: Filters objects by layer and type (opaque/transparent)
\li \l PipelineStateOverride: Controls graphics pipeline state
\li \c SubRenderPass: Executes another render pass within this pass
\li \l AddDefine: Adds shader preprocessor defines
\endlist
 
\section1 Material Modes
 
Each \l RenderPass has a \l{RenderPass::materialMode}{materialMode} property that controls
how materials are handled during rendering. The three modes offer different levels of
material control:
 
\section2 OriginalMaterial Mode
 
This mode renders objects with their assigned materials unchanged. It's useful when you
want to control the rendering pipeline structure (multiple passes, custom render targets)
but keep the material behavior standard.
 
\qml
RenderPass {
    materialMode: RenderPass.OriginalMaterial
    commands: [
        ColorAttachment { target: myColorTexture },
        DepthStencilAttachment { }
    ]
}
\endqml
 
\section2 AugmentMaterial Mode
 
This mode injects custom shader code into the existing material pipeline. It's particularly
useful for deferred rendering where you need to output additional data (like normals,
positions, etc.) to multiple render targets while preserving the material's base behavior.
 
\qml
RenderPass {
    materialMode: RenderPass.AugmentMaterial
    augmentShader: "my_augment.glsl"
    commands: [
        ColorAttachment { target: gbuffer0; name: "GBUFFER0" },
        ColorAttachment { target: gbuffer1; name: "GBUFFER1" },
        DepthStencilAttachment { }
    ]
}
\endqml
 
The augment shader file contains a \c{MAIN_FRAGMENT_AUGMENT()} function:
 
\badcode
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);
}
\endcode
 
See \l{Augment Shaders for Multiple Render Targets} for more details.
 
\section2 OverrideMaterial Mode
 
This mode replaces all object materials with a single material. It's useful for specialized
passes like shadow mapping, depth prepass, or debug visualization.
 
\qml
RenderPass {
    materialMode: RenderPass.OverrideMaterial
    overrideMaterial: CustomMaterial {
        fragmentShader: "depth_only.frag"
        // All objects will use this material
    }
    commands: [
        DepthTextureAttachment { target: depthTexture }
    ]
}
\endqml
 
\section1 Render Pass Commands
 
Commands are specified in the \l{RenderPass::commands}{commands} property and execute
in the order they are defined.
 
\section2 Color Attachment
 
The \l ColorAttachment command specifies a color render target. The \c name property
defines how the attachment is accessed in augment shaders.
 
\qml
ColorAttachment {
    target: myTexture      // RenderPassTexture to render to
    name: "GBUFFER0"      // Name for shader access (optional)
}
\endqml
 
You can have up to 4 color attachments per pass (for multiple render targets).
 
\section2 Depth Attachments
 
There are two ways to handle depth:
 
\b{DepthStencilAttachment} uses an implicit depth/stencil buffer:
 
\qml
DepthStencilAttachment { }  // Creates depth/stencil buffer automatically
\endqml
 
\b{DepthTextureAttachment} uses an explicit texture for depth output:
 
\qml
RenderPassTexture {
    id: depthTex
    format: RenderPassTexture.Depth24Stencil8
}
 
DepthTextureAttachment {
    target: depthTex  // Explicit depth texture
}
\endqml
 
Use \l DepthTextureAttachment when you need to share the depth buffer between multiple
passes or use it as a texture input in shaders.
 
\section2 Renderables Filter
 
The \l RenderablesFilter command controls which objects are rendered based on their layer
assignment and renderable type.
 
\qml
RenderablesFilter {
    layerMask: ContentLayer.Layer0 | ContentLayer.Layer1
    renderableTypes: RenderablesFilter.Opaque
}
\endqml
 
The \c layerMask property uses bitwise OR to combine layers. The \c renderableTypes
property can be:
\list
\li \c RenderablesFilter.Opaque: Render only opaque objects
\li \c RenderablesFilter.Transparent: Render only transparent objects
\li \c RenderablesFilter.Opaque | RenderablesFilter.Transparent: Render both
\endlist
 
\section2 Pipeline State Override
 
The \l PipelineStateOverride command provides fine-grained control over graphics pipeline
state. It can override depth testing, blending, culling, polygon mode, and more.
 
\qml
PipelineStateOverride {
    depthTestEnabled: true
    depthWriteEnabled: false
    blendEnabled: true
    cullMode: PipelineStateOverride.Back
    polygonMode: PipelineStateOverride.Fill
}
\endqml
 
See \l{Pipeline State Control} for more examples.
 
\section2 Sub Render Pass
 
The \c SubRenderPass command allows hierarchical composition of render passes by executing
another render pass within the current pass.
 
\qml
RenderPass {
    id: parentPass
    commands: [
        ColorAttachment { target: colorTex },
        SubRenderPass { renderPass: childPass },
        // More commands after child pass
    ]
}
 
RenderPass {
    id: childPass
    // This pass executes within parentPass
}
\endqml
 
\section2 Add Define
 
The \l AddDefine command adds shader preprocessor defines that affect shader compilation.
 
\qml
AddDefine {
    name: "USE_SPECIAL_MODE"
    value: 1
}
\endqml
 
\section1 Simple Example: Single Pass Rendering
 
Here's a minimal example showing user-defined render passes:
 
\qml
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
        }
    }
}
\endqml
 
This example:
\list 1
\li Disables internal passes
\li Creates a render target texture (colorTarget)
\li Defines a render pass that renders to that texture
\li Uses RenderOutputProvider to expose the texture
\li Displays the result with SimpleQuadRenderer
\li Renders a sphere with standard material
\endlist
 
\section1 Working with Layers
 
The \l ContentLayer singleton provides constants for organizing objects into layers,
allowing fine-grained control over what renders in each pass.
 
\section2 Layer Constants
 
Qt Quick 3D provides 24 user-assignable layers:
\list
\li \c ContentLayer.Layer0 through \c ContentLayer.Layer23: Individual layers
\li \c ContentLayer.LayerAll: All user layers combined
\li \c ContentLayer.LayerNone: No layers
\endlist
 
\note Layers 24-31 are reserved for internal use.
 
\section2 Assigning Objects to Layers
 
Assign objects to layers using the \l{Model::layers}{layers} property:
 
\qml
Model {
    source: "#Cube"
    layers: ContentLayer.Layer0
    materials: PrincipledMaterial { baseColor: "red" }
}
 
Model {
    source: "#Sphere"
    layers: ContentLayer.Layer1 | ContentLayer.Layer2
    materials: PrincipledMaterial { baseColor: "blue" }
}
\endqml
 
Objects can belong to multiple layers using bitwise OR.
 
\section2 Filtering by Layer
 
Use \l RenderablesFilter in your render passes to select which layers to render:
 
\qml
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)
}
\endqml
 
\section2 Use Case: Selective Rendering
 
A practical example is rendering certain objects as wireframe overlays:
 
\qml
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" }
    }
}
\endqml
 
\section1 Texture Management
 
User render passes rely heavily on textures both as render targets and as inputs to
subsequent passes or materials.
 
\section2 Render Pass Texture Formats
 
\l RenderPassTexture supports various formats for different use cases:
 
\b{Color Formats:}
\table
\header
\li Format
\li Description
\li Use Case
\row
\li RGBA8
\li 8-bit per channel
\li Standard color output, lower memory usage
\row
\li RGBA16F
\li 16-bit floating point
\li HDR rendering, intermediate buffers
\row
\li RGBA32F
\li 32-bit floating point
\li High precision calculations
\row
\li R8, R16, R16F, R32F
\li Single channel variants
\li Grayscale data, specialized buffers
\endtable
 
\b{Depth Formats:}
\table
\header
\li Format
\li Description
\row
\li Depth16
\li 16-bit depth
\row
\li Depth24
\li 24-bit depth
\row
\li Depth32
\li 32-bit depth
\row
\li Depth24Stencil8
\li 24-bit depth + 8-bit stencil
\endtable
 
Example texture definitions:
 
\qml
RenderPassTexture {
    id: hdrColorBuffer
    format: RenderPassTexture.RGBA16F  // HDR color
}
 
RenderPassTexture {
    id: depthBuffer
    format: RenderPassTexture.Depth24Stencil8  // Depth + stencil
}
 
RenderPassTexture {
    id: normalBuffer
    format: RenderPassTexture.RGBA16F  // Store normals
}
\endqml
 
\section2 Sharing Textures Between Passes
 
Multiple passes can share the same depth texture, allowing depth testing across passes:
 
\qml
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
    ]
}
\endqml
 
\section2 Render Output Provider
 
The \l RenderOutputProvider exposes render pass outputs as \l Texture inputs:
 
\qml
// 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"
}
\endqml
 
The \c attachmentSelector property specifies which color attachment to use when a pass
has multiple render targets:
\list
\li \c RenderOutputProvider.Attachment0: First color attachment
\li \c RenderOutputProvider.Attachment1: Second color attachment
\li \c RenderOutputProvider.Attachment2: Third color attachment
\li \c RenderOutputProvider.Attachment3: Fourth color attachment
\endlist
 
\section2 Pass Chaining Example
 
Multiple passes can be chained together where each pass processes the output of the
previous pass:
 
\qml
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
            }
        }
    }
}
\endqml
 
\section1 Pipeline State Control
 
The \l PipelineStateOverride command provides detailed control over graphics pipeline state,
allowing customization of depth testing, blending, culling, and more.
 
\section2 Depth Testing and Writing
 
Control how depth values are tested and written:
 
\qml
PipelineStateOverride {
    depthTestEnabled: true
    depthWriteEnabled: true
    depthFunction: PipelineStateOverride.LessOrEqual
}
\endqml
 
The \c depthFunction property can be:
\list
\li \c Never, \c Less, \c Equal, \c LessOrEqual
\li \c Greater, \c NotEqual, \c GreaterOrEqual, \c Always
\endlist
 
\section2 Blending
 
Enable and configure blending for transparency:
 
\qml
PipelineStateOverride {
    blendEnabled: true
    // Uses default blend mode (source alpha blending)
}
\endqml
 
For multiple render targets, use per-target blend states. \l PipelineStateOverride
exposes the per-attachment value-type properties \c targetBlend0 through
\c targetBlend7 (of type \l renderTargetBlend) and the blend factor and
operation enums are in the \c RenderTargetBlend namespace:
 
\qml
PipelineStateOverride {
    targetBlend0.enable: true
    targetBlend0.srcColor: RenderTargetBlend.SrcAlpha
    targetBlend0.dstColor: RenderTargetBlend.OneMinusSrcAlpha
    targetBlend0.opColor:  RenderTargetBlend.Add
 
    targetBlend1.enable: false  // No blending for attachment 1
}
\endqml
 
\section2 Culling
 
Control face culling:
 
\qml
PipelineStateOverride {
    cullMode: PipelineStateOverride.Back   // Override material's cull mode to Back
}
\endqml
 
Setting \c cullMode here overrides the value the material would otherwise specify
for this pass. Options: \c None (no culling), \c Front (cull front faces),
\c Back (cull back faces).
 
\section2 Wireframe Rendering
 
Render geometry as wireframes:
 
\qml
PipelineStateOverride {
    polygonMode: PipelineStateOverride.Line
    cullMode: PipelineStateOverride.None  // Show both sides
}
\endqml
 
The \c polygonMode can be \c Fill (default) or \c Line (wireframe).
 
\section2 Scissor Rectangles
 
Limit rendering to a rectangular region:
 
\qml
PipelineStateOverride {
    usesScissor: true
    scissor: Qt.rect(100, 100, 400, 300)  // x, y, width, height
}
\endqml
 
\section2 Viewport Control
 
Override the viewport:
 
\qml
PipelineStateOverride {
    viewport: Qt.rect(0, 0, 800, 600)
}
\endqml
 
\section2 Complete Example: Wireframe Overlay
 
This example renders a scene normally, then overlays a wireframe version:
 
\qml
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
        }
    }
}
\endqml
 
\section1 Augment Shaders for Multiple Render Targets
 
When using \c{RenderPass.AugmentMaterial} mode, you provide an augment shader that injects
custom code into the material's fragment shader. This is particularly useful for deferred
rendering where you need to output material data to multiple render targets (MRT).
 
\section2 The MAIN_FRAGMENT_AUGMENT Function
 
Your augment shader file must define a \c{MAIN_FRAGMENT_AUGMENT()} function:
 
\badcode
void MAIN_FRAGMENT_AUGMENT()
{
    // Your custom shader code here
}
\endcode
 
This function is called during the fragment shader after material calculations are complete,
giving you access to material properties and the ability to write to custom outputs.
 
\section2 Available Built-in Variables
 
Inside \c{MAIN_FRAGMENT_AUGMENT()}, the engine substitutes a set of macros
that expose material pipeline data. Only the macros listed below are part of
the augment shader API:
 
\table
\header
\li Macro
\li Type
\li Description
\row
\li \c BASE_COLOR
\li vec4
\li Material base color (linear color space, after material processing).
\row
\li \c METALNESS
\li float
\li Material metalness in the range 0.0 to 1.0.
\row
\li \c ROUGHNESS
\li float
\li Material roughness in the range 0.0 to 1.0.
\row
\li \c WORLD_NORMAL
\li vec3
\li World-space surface normal (post normal-mapping).
\row
\li \c WORLD_TANGENT
\li vec3
\li World-space tangent vector.
\row
\li \c WORLD_BINORMAL
\li vec3
\li World-space binormal vector.
\row
\li \c DIFFUSE_LIGHT
\li vec3
\li Accumulated diffuse light contribution.
\row
\li \c SPECULAR_LIGHT
\li vec3
\li Accumulated specular light contribution.
\row
\li \c EMISSIVE_LIGHT
\li vec3
\li Material emissive contribution.
\row
\li \c F0
\li vec3
\li Fresnel reflectance at normal incidence.
\row
\li \c F90
\li vec3
\li Fresnel reflectance at grazing incidence.
\endtable
 
\note Some examples (including the deferred-rendering one below) read the
world-space fragment position via \c qt_varWorldPos. This is the engine's
underlying varying name, not an augment-shader macro, and falls into the
same \e {semi-public} category as the \c .glsllib files described in
\l{Built-in Shader Facilities}: it works in practice but is not guaranteed
to remain stable across releases.
 
\section2 Writing to Named Outputs
 
Color attachments in your render pass can have names that correspond to output variables
in your shader:
 
\qml
RenderPass {
    commands: [
        ColorAttachment { target: tex0; name: "GBUFFER0" },
        ColorAttachment { target: tex1; name: "GBUFFER1" },
        ColorAttachment { target: tex2; name: "GBUFFER2" }
    ]
}
\endqml
 
In your augment shader:
 
\badcode
void MAIN_FRAGMENT_AUGMENT()
{
    GBUFFER0 = vec4(...);  // Writes to first attachment
    GBUFFER1 = vec4(...);  // Writes to second attachment
    GBUFFER2 = vec4(...);  // Writes to third attachment
}
\endcode
 
Qt Quick 3D supports up to 4 simultaneous color attachments (GBUFFER0 through GBUFFER3).
 
\section2 Complete Augment Shader Example
 
Here's a complete example for a deferred rendering G-buffer pass:
 
\badcode
// 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);
}
\endcode
 
Used with a render pass (\c RenderPassTexture instances are declared as
direct children of the enclosing \c View3D and referenced by id):
 
\qml
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 { }
        ]
    }
}
\endqml
 
\section2 Preserving Material Behavior
 
The augment shader runs \e{in addition to} the normal material pipeline, not instead of it.
This means:
 
\list
\li The material's textures, properties, and calculations still occur
\li You're adding extra outputs, not replacing the primary color output
\li The original material's RGBA output is still written to the first color attachment unless overridden
\endlist
 
If you only need to output custom data and don't need the standard material calculations,
consider using \c{RenderPass.OverrideMaterial} instead.
 
\section2 When to Use Augment vs Override
 
Use \c AugmentMaterial when:
\list
\li You need material properties (metalness, roughness, normals) for G-buffers
\li You want to leverage existing material features like texture mapping
\li You need multiple render targets with material data
\endlist
 
Use \c OverrideMaterial when:
\list
\li You need identical behavior for all objects (depth prepass, shadow maps)
\li You don't need per-material properties
\li You want maximum performance by bypassing material calculations
\endlist
 
\section2 Built-in Shader Facilities
 
Augment shaders and custom materials used in render passes have access to Qt Quick 3D's
built-in shader infrastructure through an include system. These shader library files
(\c{.glsllib}) provide functionality for lighting, shadows, tonemapping, and more.
 
\b{Include Syntax:}
 
Use \c{\#include} directives in your shader code to import functionality:
 
\badcode
#include "tonemapping.glsllib"
#include "lightsData.glsllib"
#include "shadowMapping.glsllib"
#include "funcprocessPunctualLighting.glsllib"
 
void MAIN()
{
    // Use included functions
    vec3 color = qt_tonemap(hdrColor);
}
\endcode
 
\b{Available Shader Libraries:}
 
These shader libraries are located in the engine at \c{src/runtimerender/res/effectlib/}
and are considered \e{semi-public}: they are usable in user shaders but do not have the
same binary compatibility guarantees as the rest of Qt's public API.
 
\table
\header
\li Library
\li Description
\row
\li \c{tonemapping.glsllib}
\li Provides \c{qt_tonemap()} function for HDR to LDR conversion using the built-in
    tonemapping algorithm
\row
\li \c{lightsData.glsllib}
\li Contains scene lighting information (light positions, colors, directions, etc.)
    that can be accessed in custom lighting calculations
\row
\li \c{shadowMapping.glsllib}
\li Provides functions for sampling from the default shadow maps, enabling custom
    materials to receive shadows
\row
\li \c{funcprocessPunctualLighting.glsllib}
\li Contains \c{qt_processPunctualLighting()} and other built-in lighting functions
    for standard PBR lighting calculations
\row
\li \c{sampleProbe.glsllib}
\li Functions for sampling image-based lighting probes (\c{qt_sampleDiffuse()},
    \c{qt_sampleGlossyPrincipled()})
\endtable
 
\b{Example: Custom Lighting with Built-in Functions}
 
Here's an example fragment shader using the built-in lighting facilities:
 
\badcode
#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);
}
\endcode
 
\note These shader libraries are semi-public API. While they are stable and intended for
use in custom shaders, Qt does not guarantee that their internal implementation or
available functions will remain unchanged between releases. However, commonly used functions
like \c{qt_tonemap()} and \c{qt_processPunctualLighting()} are unlikely to change
significantly.
 
\section1 Advanced Example: Deferred Rendering
 
Deferred rendering is a technique where geometry information is rendered to multiple textures
(called a G-buffer or geometry buffer) in a first pass, and lighting calculations are performed
in a second pass using the stored geometry data. This approach is particularly efficient when
you have many lights, as each pixel is shaded only once regardless of the number of lights.
 
\section2 Deferred Rendering Architecture
 
The deferred rendering pipeline consists of two main passes:
 
\list 1
\li \b{Geometry Pass (G-Buffer Pass)}: Renders scene geometry to multiple render targets,
    storing material properties such as albedo, normals, roughness, metalness, and world position.
\li \b{Lighting Pass}: Renders a full-screen quad that samples the G-buffers and performs
    lighting calculations for each pixel based on the stored geometry data.
\endlist
 
\section2 G-Buffer Pass Implementation
 
First, define a G-buffer pass that outputs material data to multiple render targets:
 
\b{GBufferPass.qml:} The G-buffer render targets are exposed as required
properties so the enclosing \c View3D supplies them and can read their
outputs:
 
\qml
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
        }
    ]
}
\endqml
 
\b{gbuffer_augment.glsl:}
\badcode
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);
}
\endcode
 
The augment shader accesses material properties computed by the material pipeline and
writes them to the three G-buffer attachments. Normals are encoded from [-1,1] to [0,1]
range for storage.
 
\section2 Lighting Pass Implementation
 
The lighting pass renders a full-screen quad that samples the G-buffers and computes lighting:
 
\qml
// 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 }
    ]
}
\endqml
 
The lighting vertex shader (\c lighting.vert) creates a full-screen quad in normalized
device coordinates, and the fragment shader (\c lighting.frag) samples the G-buffers and
performs lighting calculations.
 
\section2 Complete Integration
 
Here's how to integrate both passes in a View3D:
 
\qml
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 }
}
\endqml
 
\section2 Rendering Flow
 
The rendering proceeds as follows:
 
\list 1
\li \b{G-buffer Pass}: Scene objects on Layer0 and Layer1 are rendered. For each object,
    the augment shader writes albedo, normals, roughness, metalness, and position to three
    color attachments. Depth is written to the shared depth texture.
\li \b{Lighting Pass}: The full-screen quad on Layer13 is rendered. Its custom material
    samples the three G-buffer textures and the depth texture, reconstructs the scene
    information, and performs lighting calculations (directional lights, image-based lighting,
    etc.) to produce the final lit color.
\li \b{Display}: The result of the lighting pass is displayed via SimpleQuadRenderer.
\endlist
 
\section2 Advantages and Limitations
 
\b{Advantages:}
\list
\li Efficient with many lights (each pixel lit once)
\li Lighting complexity independent of scene complexity
\li Easy to implement screen-space effects
\li Decouples geometry and lighting passes
\endlist
 
\b{Limitations:}
\list
\li Higher memory bandwidth due to G-buffer reads/writes
\li No hardware MSAA (requires alternative anti-aliasing)
\li Transparency requires separate forward pass
\li More complex pipeline to set up and maintain
\endlist
 
For a complete working example, see \l{Qt Quick 3D - User Passes Example}.
 
\section1 Complete Rendering Pipeline Example
 
A realistic custom rendering pipeline often needs to combine multiple pass types: opaque
geometry, skybox background, 2D overlays, and transparent objects. Here's a complete example
showing how to organize these using \c SubRenderPass for hierarchical composition:
 
\qml
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 }
}
\endqml
 
\section2 Key Concepts
 
\b{SubRenderPass for Hierarchical Organization:}
 
The main pass uses \c SubRenderPass commands to execute child passes in sequence. The
parent pass itself doesn't render anything (\c{RenderablesFilter.None}), it just
orchestrates the child passes. This provides a clear structure and allows depth buffer
sharing across all sub-passes.
 
\b{Pass Modes:}
 
\list
\li \c{RenderPass.UserPass} (default): Custom rendering with your geometry and materials
\li \c{RenderPass.SkyboxPass}: Renders the environment skybox from \l SceneEnvironment
\li \c{RenderPass.Item2DPass}: Renders 2D Qt Quick content embedded in the 3D scene
\endlist
 
\b{Render Order:}
 
\list 1
\li Opaque geometry rendered to G-buffer
\li Deferred lighting applied to full-screen quad
\li Skybox rendered behind geometry (depth test enabled, depth write disabled)
\li 2D UI overlays rendered on top
\li Transparent objects rendered last with blending
\endlist
 
\b{Depth Buffer Sharing:}
 
The \c mainDepthStencilTexture is shared across passes using \c PreserveDepthStencilContents.
This ensures skybox renders behind geometry and transparent objects test against opaque
geometry correctly.
 
\b{Item2D Content:}
 
Qt Quick 2D items (Button, Rectangle, Text, etc.) placed in \l Node objects are rendered
by \c{RenderPass.Item2DPass}. These items are positioned in 3D space but rendered as 2D
overlays that can receive mouse/touch input.
 
\section1 Performance Considerations
 
User-defined render passes provide maximum control but require careful consideration of
performance implications.
 
\section2 Texture Format Choices
 
Choose texture formats based on your needs:
 
\table
\header
\li Format
\li Size per Pixel
\li Use Case
\row
\li RGBA8
\li 4 bytes
\li Final output, simple color buffers
\row
\li RGBA16F
\li 8 bytes
\li HDR content, intermediate buffers, normals
\row
\li RGBA32F
\li 16 bytes
\li High precision calculations, positions
\row
\li R16F
\li 2 bytes
\li Single-channel HDR (depth, AO, etc.)
\endtable
 
For a 1920x1080 framebuffer:
\list
\li RGBA8: ~8 MB
\li RGBA16F: ~16 MB
\li RGBA32F: ~32 MB
\li Three RGBA16F G-buffers: ~48 MB
\endlist
 
\b{Recommendation:} Use RGBA16F for intermediate buffers and RGBA8 or R8 where sufficient.
 
\section2 Deferred vs Forward Rendering
 
\table
\header
\li Aspect
\li Deferred Rendering
\li Forward Rendering
\row
\li Many lights
\li Efficient (O(lights + pixels))
\li Expensive (O(lights * objects))
\row
\li Memory bandwidth
\li High (G-buffer reads/writes)
\li Lower
\row
\li Transparency
\li Requires separate pass
\li Natural support
\row
\li MSAA
\li Not directly supported
\li Hardware MSAA works
\row
\li Setup complexity
\li More complex
\li Simpler
\endtable
 
\b{Use deferred rendering when:}
\list
\li You have many lights (10+)
\li Screen-space effects are important
\li Scene is mostly opaque
\endlist
 
\b{Use forward rendering when:}
\list
\li Few lights (<5)
\li Lots of transparency
\li Memory bandwidth is constrained
\li Simpler pipeline is preferable
\endlist
 
\section2 Pass Ordering Optimization
 
Render passes execute in the order they are encountered. Optimize by:
 
\list
\li Rendering opaque geometry before transparent geometry
\li Using depth prepass when beneficial (reduces overdraw in complex scenes)
\li Minimizing render target switches
\li Reusing depth buffers across passes when possible
\endlist
 
\section2 Render Target Flags
 
The \l{RenderPass::renderTargetFlags}{renderTargetFlags} property controls memory behavior:
 
\qml
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
}
\endqml
 
\b{PreserveColorContents/PreserveDepthStencilContents:} Keep existing data (e.g., for
multi-pass rendering to same target).
 
\b{DoNotStoreDepthStencilContents:} Hint that depth/stencil can be discarded (on some
hardware this can improve performance by avoiding memory writes).
 
\section2 When to Use User Passes
 
Consider using user render passes when:
 
\list
\li Implementing deferred rendering
\li Creating complex multi-pass effects
\li Needing explicit control over render order
\li Implementing custom rendering techniques
\li Building screen-space effects that need geometry data
\endlist
 
\b{Avoid user passes when:}
\list
\li Default rendering meets your needs
\li You only need post-processing (use \l Effect instead)
\li You only need custom material shaders (use \l CustomMaterial instead)
\li Performance is critical and extra passes would be wasteful
\endlist
 
\section1 Common Patterns and Use Cases
 
User render passes enable many advanced rendering techniques. Here are some common patterns:
 
\section2 Deferred Shading/Lighting
 
Store geometry attributes in G-buffers and perform lighting in screen space. Covered in
detail in \l{Advanced Example: Deferred Rendering}.
 
\section2 Edge Detection and Outlining
 
Render scene normally, then apply edge detection in a second pass:
 
\qml
// 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
    }
}
\endqml
 
\section2 Custom Post-Processing Chains
 
Chain multiple post-processing effects together by feeding each pass's output
into the next via \l RenderOutputProvider. See
\l{Pass Chaining Example} for a worked example of a multi-stage chain
(\c scenePass → \c process1 → \c process2 → display).
 
\section2 Selective Wireframe Overlay
 
Render some objects solid and others as wireframe overlays. See the example in
\l{Working with Layers}.
 
\section2 Debug Visualization
 
Create debug passes that visualize normals, depth, or other data:
 
\qml
// 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 }
    ]
}
\endqml
 
\section2 Custom Shadow Mapping
 
Implement custom shadow mapping with explicit control:
 
\qml
// 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
\endqml
 
\section1 Important Considerations
 
When working with user render passes, keep these important points in mind:
 
\section2 Shadow Handling
 
User render passes do \b{not} automatically include Qt Quick 3D's internal shadow rendering.
If you disable internal passes and need shadows, you must:
 
\list
\li Implement your own shadow mapping passes
\li Render the scene from light's perspective to a depth texture
\li Sample the shadow map in your lighting calculations
\endlist
 
Alternatively, for simpler cases, you may not need shadows or can use pre-baked shadow maps.
 
\section2 HDR and Tonemapping
 
When using floating-point render targets (RGBA16F, RGBA32F), your rendering is in linear
HDR space. You must apply tonemapping in your final display pass to convert to displayable
LDR:
 
\qml
CustomMaterial {
    fragmentShader: "tonemap.frag"
}
\endqml
 
\badcode
// 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);
}
\endcode
 
Qt Quick 3D provides \c{qt_tonemap()} function in shaders that can be used for this purpose.
 
\section2 Depth Texture Generation
 
When you need depth as a texture (for effects like depth-of-field), use
\l DepthTextureAttachment instead of \l DepthStencilAttachment:
 
\qml
RenderPassTexture {
    id: depthTex
    format: RenderPassTexture.Depth24Stencil8
}
 
RenderPass {
    commands: [
        ColorAttachment { target: colorTex },
        DepthTextureAttachment { target: depthTex }
        // depthTex can now be sampled in shaders
    ]
}
\endqml
 
\section2 Clear Values and Render Target Management
 
Each pass can specify clear values:
 
\qml
RenderPass {
    clearColor: Qt.rgba(0.0, 0.0, 0.0, 0.0)
    depthClearValue: 1.0
    stencilClearValue: 0
}
\endqml
 
When a pass doesn't preserve contents (default), render targets are cleared to these values
before rendering. When \c PreserveColorContents or \c PreserveDepthStencilContents is set,
existing content is kept and clear values are ignored.
 
\section2 Layer Organization Best Practices
 
Organize your layers logically:
 
\list
\li \b{Layer0-2}: Main scene objects
\li \b{Layer3-4}: Transparent objects (separate pass)
\li \b{Layer10+}: Full-screen quads for post-processing
\li \b{Layer15+}: UI/debug overlays
\endlist
 
Document your layer usage in comments and be consistent across your application.
 
\section2 Shader Compatibility
 
Augment shaders and custom materials used in render passes must be compatible with Qt Quick
3D's shader infrastructure:
 
\list
\li Use GLSL-compatible syntax
\li Include appropriate \c{\#include} directives for Qt Quick 3D functions
\li Be aware of available built-in variables
\li Test on all target platforms (OpenGL, Vulkan, Metal, D3D)
\endlist
 
\section2 Multiple Render Targets Limitations
 
When using multiple render targets (MRT):
 
\list
\li Maximum of 4 color attachments
\li All attachments must have the same dimensions
\li Blend state can be specified per-attachment via \l PipelineStateOverride
\li Not all hardware supports MRT (check device capabilities)
\endlist
 
\section2 Transparency
 
Transparent objects are challenging with deferred rendering. Common approaches:
 
\list
\li \b{Forward pass for transparent}: Render opaque geometry deferred, transparent geometry
    in a separate forward pass
\li \b{Separate transparent G-buffer}: Render transparent geometry to a separate set of
    G-buffers with blending enabled
\li \b{Weighted blended order-independent transparency}: Use specialized OIT techniques
\endlist
 
For most cases, a separate forward pass for transparent objects is simplest.
 
\section1 API Reference
 
The following table provides a complete reference of all types related to user render passes:
 
\table
\header
\li Feature
\li QML Type
\li Description
\row
\li Main render pass definition
\li \l RenderPass
\li Defines a rendering pass with commands and material mode
\row
\li Render target textures
\li \l RenderPassTexture
\li Texture used as render target (color or depth/stencil)
\row
\li Texture output provider
\li \l RenderOutputProvider
\li Exposes render pass output as texture input
\row
\li Layer constants
\li \l ContentLayer
\li Singleton providing layer filtering constants
\row
\li Color output
\li \l ColorAttachment
\li Specifies a color render target
\row
\li Depth/stencil (default)
\li \l DepthStencilAttachment
\li Uses implicit depth/stencil buffer
\row
\li Depth/stencil (texture)
\li \l DepthTextureAttachment
\li Uses explicit depth texture
\row
\li Object filtering
\li \l RenderablesFilter
\li Filters objects by layer and type
\row
\li Pipeline state
\li \l PipelineStateOverride
\li Overrides graphics pipeline state
\row
\li Nested pass execution
\li \c SubRenderPass
\li Executes another render pass
\row
\li Shader defines
\li \l AddDefine
\li Adds shader preprocessor define
\row
\li Per-target blend state
\li \l renderTargetBlend
\li Blend configuration for MRT
\row
\li Display helper
\li \l SimpleQuadRenderer
\li Renders final output to View3D
\endtable
 
\section2 Related Types
 
\table
\header
\li Type
\li Description
\row
\li \l CustomMaterial
\li Custom material with vertex/fragment shaders
\row
\li \l Effect
\li Post-processing effects
\row
\li \l View3D
\li 3D view with \l{View3D::renderOverrides}{renderOverrides} property
\row
\li \l Model
\li 3D model with \l{Model::layers}{layers} property
\endtable
 
\section2 Examples
 
\list
\li \l{Qt Quick 3D - User Passes Example}: Complete deferred rendering example
\endlist
 
\section2 See Also
 
\list
\li \l{Programmable Materials, Effects, Geometry, and Texture data}: Overview of Qt Quick 3D
    customization features
\li \l{Qt Quick 3D Architecture}: Understanding the rendering pipeline
\endlist
 
*/