- Qt 6.12
- Qt Quick 3D
- QML Types
- RenderPass
- Qt Quick 3D | Commercial or GPLv3

# RenderPass QML Type

Defines a custom render pass for rendering 3D content. More...

Import Statement: | `import QtQuick3D`
Since: | Qt 6.11
Inherits: | Object3D

- List of all members, including inherited members

## Properties

- augmentShader : url
- clearColor : color
- commands : list<RenderCommand>
- depthClearValue : real
- materialMode : RenderPass::MaterialModes
- overrideMaterial : Material
- passMode : RenderPass::PassMode
- renderTargetFlags : RenderPass::RenderTargetFlags
- stencilClearValue : int

## Detailed Description

A RenderPass defines a rendering step and the render target it writes into. It is the combination of three concerns:

- Where to render — one or more output textures declared as ColorAttachment or DepthTextureAttachment commands in commands.
- What to render — which scene objects the pass draws, controlled by RenderablesFilter commands. Sub-divisions of work within the same render target are described using SubRenderPass commands.
- How to render — the materialMode and any PipelineStateOverride commands.

A RenderPass becomes active for a scene when it is placed as a child of a View3D or a Node.

The following example sets up a simple off-screen pass that renders all scene objects into a custom texture, which can then be consumed by a material or a SimpleQuadRenderer:

     import QtQuick3D

     View3D {
         // Declare the off-screen color buffer
         RenderPassTexture {
             id: myColorTexture
             format: RenderPassTexture.RGBA8
         }

         // The render pass: where + what + how
         RenderPass {
             id: myRenderPass
             commands: [
                 // Where: attach the texture as the color output
                 ColorAttachment {
                     name: "color0"
                     target: myColorTexture
                 },
                 // What: render all objects into it
                 RenderablesFilter {
                     renderableTypes: RenderablesFilter.Opaque | RenderablesFilter.Transparent
                 }
             ]
         }
     }

## Exposing data to the shaders

As with Effects and Custom Materials, the RenderPass will expose and update user-defined properties to the shaders automatically. Any QML properties declared on a RenderPass subtype will be available as uniforms in the shader.

See also SubRenderPass, RenderOutputProvider, and RenderablesFilter.

## Property Documentation

### augmentShader : url

This property holds the augment shader URL for the render pass when materialMode is set to `AugmentMaterial`.

The shader file should contain a function with the following signature:

     void MAIN_FRAGMENT_AUGMENT() {
         // Custom shader code here
     }

This function will be combined with the existing fragment shader of the material being used by the object being rendered in this render pass. Allowing users to augment the existing material shader with custom code.

### clearColor : color `[default: Qt.black]`

This property holds the clear color for the render pass.

### commands : list<RenderCommand>

This property holds the list of render commands for the render pass.

The commands in the list are executed in the order they appear in the list.

Note: The commands for RenderPass and Effects are similar but not the same, only those marked as compatible can be used with this RenderPass.

See also SubRenderPass, PipelineStateOverride, RenderablesFilter, RenderPassTexture, ColorAttachment, DepthTextureAttachment, DepthStencilAttachment, AddDefine, and renderTargetBlend.

### depthClearValue : real `[default: 1.0]`

This property holds the depth clear value for the render pass.

### materialMode : RenderPass::MaterialModes `[default: RenderPass.OriginalMaterial]`

Controls how object materials are handled when rendering into this pass.

Constant | Description
--- | ---
`RenderPass.OriginalMaterial` | Objects are rendered using their own assigned materials, with full lighting, textures, and material properties applied normally. This is the standard mode for rendering a faithful copy of the scene into a custom render target — for example, a secondary viewpoint for a reflection probe, a rear-view camera, or a picture-in-picture effect. The `overrideMaterial`, `augmentShader`, and `shaders` properties are not used in this mode.
`RenderPass.AugmentMaterial` | Each object is rendered with its own material, but the contents of the `MAIN_FRAGMENT_AUGMENT()` function defined in augmentShader are injected after the original material's output definition. This allows the augment code to read the material's computed color and write to additional color outputs defined by ColorAttachment commands in the pass. This is useful for multi-render-target (MRT) passes that need per-material shading, such as writing the lit color to one attachment and a world-space normal to another in a single draw call.
`RenderPass.OverrideMaterial` | All objects rendered by this pass use the single overrideMaterial instead of their own. This is useful for depth-only passes, shadow maps, silhouette or outline effects, and any other case where you want all geometry to be shaded identically regardless of what material is assigned to it. The `augmentShader` property is not used in this mode.

### overrideMaterial : Material

This property holds the override material for the render pass when materialMode is set to `OverrideMaterial`.

### passMode : RenderPass::PassMode `[default: RenderPass.UserPass]`

This property holds the pass mode for the render pass.

In addition to standard user render passes, Qt Quick 3D supports users to manually triggering internal render passes for rendering the skybox and 2D items.

Constant | Description
--- | ---
`RenderPass.UserPass` | A user specified render pass.
`RenderPass.SkyboxPass` | Qt Quick 3D's built-in skybox render pass.
`RenderPass.Item2DPass` | Qt Quick 3D's built-in 2D item render pass.

### renderTargetFlags : RenderPass::RenderTargetFlags `[default: RenderPass.None]`

This property holds the render target flags for the render pass. These flags affect how the render target contents are handled at the beginning and end of each frame.

Constant | Description
--- | ---
`RenderPass.None` | No special behavior. Color and depth/stencil contents are cleared at the start of each frame.
`RenderPass.PreserveColorContents` | Preserve the color contents of the render target between frames, so the previous frame's output remains until explicitly overwritten.
`RenderPass.PreserveDepthStencilContents` | Preserve the depth and stencil contents of the render target between frames.
`RenderPass.DoNotStoreDepthStencilContents` | Do not store the depth and stencil contents of the render target after rendering (may improve performance on tiled GPUs).

See also QRhiTextureRenderTarget::Flags.

### stencilClearValue : int `[default: 0]`

This property holds the stencil clear value for the render pass.