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

    Class RenderPass

    A render pass is a FramePass which draws into a render target. Its draw calls are recorded inside a GPU render pass, which starts right before the pass executes and ends right after. It is the base class for passes which draw, for example a pass rendering a quad with a shader, see RenderPassShaderQuad. For work which does not draw, such as compute dispatches, use FramePass or ComputePass instead.

    Once the pass is created, call RenderPass#init with the RenderTarget to draw into, or with null to draw into the back buffer. The pass does not own its render target, and does not destroy it. When init is given options, the pass also resizes its render target each frame, to the size of a texture, a render target or the back buffer, scaled by RenderPass#scaleX and RenderPass#scaleY, see RenderPass#resizeSource.

    The attachments of the render target are its color buffers, and its depth and stencil buffers. By default, the GPU render pass loads their content, and the pass draws over it. To start from a single value instead, clear them with RenderPass#setClearColor, RenderPass#setClearDepth and RenderPass#setClearStencil. When the pass covers an attachment completely, clearing it is also faster than loading it on tiled mobile GPUs, which then do not read the previous content from memory.

    When the GPU render pass ends, the pass keeps what it rendered into the textures of its render target, so they can be sampled, or loaded by a later pass: its color buffers, resolved when the render target is multisampled, and its depth buffer texture. Other attachments are discarded: the samples of a multisampled color buffer which is resolved, the stencil, and a depth buffer the render target creates internally. When a later pass of the same frame draws into the same render target and loads them, the frame graph stores them automatically. Otherwise, store them with RenderPass#setStoreColor, RenderPass#setStoreDepth and RenderPass#setStoreStencil. The mipmaps of color buffers with mipmaps are generated at this point too, which RenderPass#setGenerateMipmaps can turn off, for example when another pass draws into the same render target after this one.

    A subclass records its draw calls in FramePass#execute, which is called while the GPU render pass is active. It can also override RenderPass#postInit to set up its clears once the pass is initialized, and RenderPass#frameUpdate to update the pass before each frame renders, calling super.frameUpdate() to keep the resize. It releases what it created in FramePass#destroy, calling super.destroy().

    A pass renders in one of two ways:

    • As part of a frame, for example as a frame pass of a camera, or as a before or after pass of another pass. The frame graph then calls its RenderPass#frameUpdate, and merges consecutive passes drawing into the same render target into a single GPU render pass, unless something separates them, for example a clear of the later pass.
    • On its own, by calling RenderPass#render, for example to render into a texture each time its content needs to change. See FramePass#render for the steps a frame performs, which are skipped then.
    // A pass drawing a quad with a shader, covering its whole render target
    class MyPass extends RenderPass {
        constructor(device, shader) {
            super(device);
            this.quadRender = new QuadRender(shader);
        }

        execute() {
            // the default draw states suit a quad: no blending, and no depth test or write
            this.device.setDrawStates();
            this.quadRender.render();
        }

        destroy() {
            this.quadRender.destroy();
            super.destroy();
        }
    }

    const renderTarget = new RenderTarget({ colorBuffer: texture, depth: false });
    const pass = new MyPass(device, shader);
    pass.name = 'MyPass';
    pass.init(renderTarget);

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

    // draw into the texture
    pass.render();

    // destroy the pass, and then the render target, which the pass does not own
    pass.destroy();
    renderTarget.destroy();

    Hierarchy (View Summary)

    Index
    constructor
    afterPasses beforePasses device executeEnabled onAfter onBefore renderTarget
    enabled name resizeSource scaleX scaleY
    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.

    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.

    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.

    • 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

    • Releases the resources the pass created. A pass owns only what it creates: it does not destroy its FramePass#beforePasses and FramePass#afterPasses, which are destroyed by whoever added them. The code which creates a pass destroys it, once, and the pass is not used after that - in debug builds, adding a destroyed pass to a frame reports an error. Subclasses releasing their own resources call super.destroy().

      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
    Setting up the passLoading and clearing the attachmentsStoring the attachmentsWriting a passRendering the pass
    Constructors
    Properties
    Accessors
    Methods