Engine API Reference - v2.24.0-beta.28
    Preparing search index...

    Class RenderPassShaderQuad

    A render pass which draws a quad with a shader into its render target. This is how most image processing is done, such as post effects, blurs, or generating a texture, as the shader then runs once for each pixel the quad covers. The pass creates the quad for its RenderPassShaderQuad#shader, sets the render states, and draws the quad when it executes. It can be used directly, by setting its shader, or as a base class of a pass which creates the shader and sets its parameters. For a single draw, such as generating a texture once, drawQuadWithShader draws a quad with a shader without setting up a pass.

    The vertex shader receives the corners of the quad in an attribute using SEMANTIC_POSITION. The quadVS shader chunk implements it, and passes the uv coordinates of the quad to the fragment shader in the uv0 varying. Create the shader with ShaderUtils.createShader, with the fragment shader in both GLSL and WGSL, so the pass works on both WebGL2 and WebGPU. The pass does not destroy its shader, as shaders are shared.

    The textures and uniforms of the shader are set on the scope of the graphics device, see GraphicsDevice#scope. Resolve them once, when the pass is created, and set their values in an override of FramePass#execute, right before the quad is drawn by calling super.execute(). Other passes can set parameters with the same names, so values set earlier might not be the values the quad is drawn with.

    By default, the quad covers the whole render target, and is drawn without blending, depth test or face culling, replacing what the render target contains. As the content is then not needed, clearing the render target with RenderPass#setClearColor saves loading it. To combine the quad with the content instead, set a RenderPassShaderQuad#blendState, and to test it against the depth or the stencil of the render target, set a RenderPassShaderQuad#depthState or the stencil parameters. To draw into a part of the render target only, set its RenderPassShaderQuad#viewport.

    To draw many quads which differ only by the data each reads for its index, such as sprites, set RenderPassShaderQuad#numInstances to draw them in a single instanced draw. To draw several quads with different parameters, for example one for each light, override FramePass#execute, and for each quad set its parameters, or its viewport, and call super.execute(), which draws it with the render states of the pass.

    // A pass drawing a texture into its render target, multiplied by a color
    class TintPass extends RenderPassShaderQuad {
        constructor(device, sourceTexture) {
            super(device);
            this.name = 'TintPass';
            this.sourceTexture = sourceTexture;
            this.tint = new Float32Array([1, 0.5, 0.5]);

            this.shader = ShaderUtils.createShader(device, {
                uniqueName: 'TintShader',
                attributes: { aPosition: SEMANTIC_POSITION },
                vertexChunk: 'quadVS',
                fragmentGLSL: `
                    uniform sampler2D sourceTexture;
                    uniform vec3 tint;
                    varying vec2 uv0;

                    void main() {
                        vec4 color = texture2D(sourceTexture, uv0);
                        gl_FragColor = vec4(color.rgb * tint, color.a);
                    }
                `,
                fragmentWGSL: `
                    var sourceTexture: texture_2d<f32>;
                    var sourceTextureSampler: sampler;
                    uniform tint: vec3f;
                    varying uv0: vec2f;

                    @fragment fn fragmentMain(input: FragmentInput) -> FragmentOutput {
                        var output: FragmentOutput;
                        let color = textureSample(sourceTexture, sourceTextureSampler, input.uv0);
                        output.color = vec4f(color.rgb * uniform.tint, color.a);
                        return output;
                    }
                `
            });

            // resolve the shader parameters once
            this.sourceTextureId = device.scope.resolve('sourceTexture');
            this.tintId = device.scope.resolve('tint');
        }

        execute() {
            // set the parameters right before the quad is drawn
            this.sourceTextureId.setValue(this.sourceTexture);
            this.tintId.setValue(this.tint);
            super.execute();
        }
    }

    const pass = new TintPass(device, sourceTexture);
    pass.init(renderTarget);

    // the quad covers the whole render target, so clear it instead of loading its content
    pass.setClearColor(Color.BLACK);
    pass.render();

    // Use the pass directly, to draw a shader into a 256x256 tile of a texture atlas. The atlas
    // is loaded and not cleared, so its other tiles keep their content.
    const pass = new RenderPassShaderQuad(device);
    pass.name = 'AtlasTile';
    pass.shader = tileShader;
    pass.init(atlasRenderTarget);

    pass.viewport = new Vec4(256, 0, 256, 256);
    pass.render();

    // blend a second shader over the same tile
    pass.shader = overlayShader;
    pass.blendState = BlendState.ALPHABLEND;
    pass.render();

    pass.destroy();

    Hierarchy (View Summary)

    Index
    constructor
    afterPasses beforePasses blendState cullMode depthState device executeEnabled frontFace numInstances onAfter onBefore renderTarget scissor stencilBack stencilFront viewport
    enabled name resizeSource scaleX scaleY shader
    after before destroy execute frameUpdate init onDisable onEnable postInit render setClearColor setClearDepth setClearStencil setGenerateMipmaps setStoreColor setStoreDepth setStoreStencil
    afterPasses: FramePass[] = []

    Frame passes which need to be executed after this pass. This pass does not own them, and does not destroy them: whoever adds a pass to the list destroys it.

    beforePasses: FramePass[] = []

    Frame passes which need to be executed before this pass. The engine does not change this list, so the passes in it execute every frame this pass executes. This pass does not own them, and does not destroy them: whoever adds a pass to the list destroys it.

    blendState: BlendState = BlendState.NOBLEND

    A blend state to use when rendering the quad. Defaults to BlendState.NOBLEND.

    cullMode: number = CULLFACE_NONE

    The cull mode to use when rendering the quad. Defaults to CULLFACE_NONE.

    depthState: DepthState = DepthState.NODEPTH

    A depth state to use when rendering the quad. Defaults to DepthState.NODEPTH.

    device: GraphicsDevice

    The graphics device.

    executeEnabled: boolean = true

    True if the frame pass is enabled and execute function will be called. Note that before and after functions are called regardless of this flag. Set it before the frame renders, at the latest in frameUpdate, as the frame graph decides which passes to merge from it.

    frontFace: number = FRONTFACE_CCW

    The front face to use when rendering the quad. Defaults to FRONTFACE_CCW.

    numInstances: number | undefined

    The number of instances of the quad to draw, using instanced drawing, or undefined to draw a single quad without instancing. Each instance can read its index, gl_InstanceID in GLSL and pcInstanceIndex in WGSL, to fetch the data of its quad, for example to place it. Zero draws nothing, while the pass still renders, so it still clears its render target. Defaults to undefined.

    onAfter: ((pass: FramePass) => void) | null = null

    Called when the pass renders, right after it executes: for a render pass once its GPU render pass has ended, and after FramePass#after. The results the pass writes can be read back here, as a read records its copy when it is requested, and so right after the pass. Reads should not be immediate, as that submits the work of the frame recorded so far. Like after, it is called even if FramePass#executeEnabled is false, but not when the pass is disabled. A render pass with this callback is not merged with the pass after it into a single GPU render pass, so the callback runs outside of one.

    onBefore: ((pass: FramePass) => void) | null = null

    Called when the pass renders, right before it executes: after FramePass#before, and for a render pass before its GPU render pass starts. Work recorded here, such as setting the parameters of the pass, or clearing a buffer it writes to, executes right before the pass. Like before, it is called even if FramePass#executeEnabled is false, but not when the pass is disabled. A render pass with this callback is not merged with the pass before it into a single GPU render pass, so the callback runs outside of one.

    renderTarget: RenderTarget | null | undefined

    The render target the pass draws into, or null when it draws into the back buffer. It is set by RenderPass#init, which sets up the pass for the attachments of the render target, and which is called again to switch the pass to a render target with different attachments. Assigning a render target directly is only supported for a render target with the same layout: the same color buffers and their formats, the same depth and stencil buffers, and the same number of samples. For example, a pass can alternate between two such render targets each frame. For work which does not draw into a render target, use FramePass instead. It is undefined until the pass is initialized. The render pass does not own the render target, and does not destroy it.

    scissor: Vec4 | undefined

    Optional scissor rectangle (x, y, width, height). If set, pixels outside this region are discarded. Only used when viewport is also set. Defaults to the viewport if not specified.

    stencilBack: StencilParameters | null = null

    Stencil parameters for back faces to use when rendering the quad. Defaults to null.

    stencilFront: StencilParameters | null = null

    Stencil parameters for front faces to use when rendering the quad. Defaults to null.

    viewport: Vec4 | undefined

    Optional viewport rectangle (x, y, width, height). If set, the quad renders only to this region and the original viewport is restored after rendering.

    • get enabled(): boolean

      Gets whether the frame pass is enabled.

      Returns boolean

    • set enabled(value: boolean): void

      Sets whether the frame pass is enabled. A disabled pass is skipped when the frame is built, together with its FramePass#beforePasses and FramePass#afterPasses, and its frameUpdate is not called. To skip only the execution of the pass, while still updating it and its before and after passes, use FramePass#executeEnabled instead. Change it before the frame is built: the frameUpdate of a pass, or of its before-passes, cannot disable the pass itself. Defaults to true.

      Parameters

      • value: boolean

      Returns void

    • get name(): string

      Gets the name of the pass.

      Returns string

    • set name(value: string): void

      Sets the name of the pass, which identifies it in debug output, GPU profiling and graphics debuggers. Defaults to the name of its class, which minified builds can shorten, so set it explicitly for a readable name.

      Parameters

      • value: string

      Returns void

    • get resizeSource(): Texture | RenderTarget | null | undefined

      Gets what the render target of the pass is resized to.

      Returns Texture | RenderTarget | null | undefined

    • set resizeSource(value: Texture | RenderTarget | null | undefined): void

      Sets what the render target of the pass is resized to each frame: a texture or a render target, whose size, scaled by RenderPass#scaleX and RenderPass#scaleY, the render target takes, or null to take the size of the back buffer. Undefined, the default, leaves the size of the render target as it is. The options of RenderPass#init set it, and init resets it, so set it once the pass is initialized. Change it when the size is to follow another texture, for example when the texture a pass processes is replaced.

      The render target is resized while the frame is built, in RenderPass#frameUpdate, and has the new size only once the pass is updated for the frame. On a frame the size changes, the passes updated before it in the frame still see the previous size, including the pass it is a before pass of, which is updated before its before passes.

      Parameters

      Returns void

    • get scaleX(): number

      Gets the scale factor of the width of the render target. It is 1 while the render target is not resized.

      Returns number

    • set scaleX(value: number): void

      Sets the scale factor of the width of the render target, relative to the size of its resize source, see RenderPass#resizeSource. Only valid while the render target is resized. Defaults to 1.

      Parameters

      • value: number

      Returns void

    • get scaleY(): number

      Gets the scale factor of the height of the render target. It is 1 while the render target is not resized.

      Returns number

    • set scaleY(value: number): void

      Sets the scale factor of the height of the render target, relative to the size of its resize source, see RenderPass#resizeSource. Only valid while the render target is resized. Defaults to 1.

      Parameters

      • value: number

      Returns void

    • Initializes the pass to draw into a render target, or into the back buffer. A render pass needs to be initialized before it renders, and before its clears, stores and mipmaps are set with RenderPass#setClearColor, RenderPass#setStoreColor, RenderPass#setGenerateMipmaps and the related setters. It sets up the operations of the attachments of the render target with their defaults, so the attachments are not cleared until a clear is set.

      Call it again to switch the pass to a render target with different attachments, which resets its clears, stores and mipmaps to the defaults. A render target with the same layout can also be assigned to RenderPass#renderTarget directly.

      When options are provided, the render target is resized each frame, in RenderPass#frameUpdate, to the size of the resize source scaled by RenderPass#scaleX and RenderPass#scaleY. Without options, it is not resized. The options are copied, so later changes to the object passed in have no effect - change them with RenderPass#resizeSource, scaleX and scaleY instead.

      Parameters

      • OptionalrenderTarget: RenderTarget | null = null

        The render target to draw into, or null to draw into the back buffer. Defaults to null. The render pass does not own the render target.

      • Optionaloptions: {
            resizeSource?: Texture | RenderTarget | null;
            scaleX?: number;
            scaleY?: number;
        }

        Object for passing optional arguments.

        • OptionalresizeSource?: Texture | RenderTarget | null

          The texture or render target whose size the render target is resized to, or null for the back buffer. Defaults to null.

        • OptionalscaleX?: number

          The scale factor for the render target width. Defaults to 1.

        • OptionalscaleY?: number

          The scale factor for the render target height. Defaults to 1.

      Returns void

    • Mark render pass as clearing the full color buffer.

      Parameters

      • color: Color | undefined

        The color to clear to, or undefined to preserve the existing content.

      • Optionalindex: number

        The index of the color attachment to modify. When not specified, all color attachments are modified.

      Returns void

    • Mark render pass as clearing the full depth buffer.

      Parameters

      • depthValue: number | undefined

        The depth value to clear to, or undefined to preserve the existing content.

      Returns void

    • Mark render pass as clearing the full stencil buffer.

      Parameters

      • stencilValue: number | undefined

        The stencil value to clear to, or undefined to preserve the existing content.

      Returns void

    • Sets whether the pass generates the mipmaps of its color attachments once it renders. By default, they are generated for color buffers with mipmaps, unless the render target renders into a single mip level, see RenderTarget#mipLevel, or the buffer uses an integer format. When several passes render to the same render target, the mipmaps are only needed after the last of them, so disabling them for the others avoids generating them more than once. Set it once the pass is initialized, as RenderPass#init resets it.

      Parameters

      • generate: boolean

        True to generate the mipmaps of the color buffers which support them, false to not generate them.

      • Optionalindex: number

        The index of the color attachment to modify. When not specified, all color attachments are modified.

      Returns void

    • Sets whether the pass stores its color attachments once it renders, so that a later pass can load them. By default, single-sampled color buffers are stored, while the samples of a multisampled color buffer are stored only when it has no resolve buffer, as the resolved color is the output of the pass. Within a frame, the frame graph also stores the attachments a later pass on the same render target loads, so this is needed for passes rendered on their own, see FramePass#render. Not storing a single-sampled color buffer discards what the pass renders into it. Set it once the pass is initialized, as RenderPass#init resets it.

      Parameters

      • store: boolean

        True to store the attachments, false to discard them.

      • Optionalindex: number

        The index of the color attachment to modify. When not specified, all color attachments are modified.

      Returns void

    • Sets whether the pass stores its depth attachment once it renders, so that a later pass can load it. By default, the depth buffer texture of the render target is stored, while a depth buffer the render target creates internally is discarded. Within a frame, the frame graph also stores the depth a later pass on the same render target loads, so this is needed for passes rendered on their own, see FramePass#render. Set it once the pass is initialized, as RenderPass#init resets it.

      Parameters

      • store: boolean

        True to store the depth, false to discard it.

      Returns void

    • Sets whether the pass stores its stencil attachment once it renders, so that a later pass can load it. By default, the stencil is discarded. Within a frame, the frame graph also stores the stencil a later pass on the same render target loads, so this is needed for passes rendered on their own, see FramePass#render. Set it once the pass is initialized, as RenderPass#init resets it.

      Parameters

      • store: boolean

        True to store the stencil, false to discard it.

      Returns void

    Settings
    Member Visibility

    On This Page
    The shaderThe shader parametersRender states and the drawn areaDrawing several quads
    Constructors
    Properties
    Accessors
    Methods