/** * A render pass is a {@link 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 {@link RenderPassShaderQuad}. For work which does not draw, such as compute * dispatches, use {@link FramePass} or {@link ComputePass} instead. * * ## Setting up the pass * * Once the pass is created, call {@link RenderPass#init} with the {@link 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 * {@link RenderPass#scaleX} and {@link RenderPass#scaleY}, see {@link RenderPass#resizeSource}. * * ## Loading and clearing the attachments * * 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 {@link RenderPass#setClearColor}, * {@link RenderPass#setClearDepth} and {@link 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. * * ## Storing the attachments * * 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 {@link RenderPass#setStoreColor}, * {@link RenderPass#setStoreDepth} and {@link RenderPass#setStoreStencil}. The mipmaps of color * buffers with mipmaps are generated at this point too, which * {@link RenderPass#setGenerateMipmaps} can turn off, for example when another pass draws into * the same render target after this one. * * ## Writing a pass * * A subclass records its draw calls in {@link FramePass#execute}, which is called while the GPU * render pass is active. It can also override {@link RenderPass#postInit} to set up its clears * once the pass is initialized, and {@link RenderPass#frameUpdate} to update the pass before each * frame renders, calling `super.frameUpdate()` to keep the resize. It releases what it created in * {@link FramePass#destroy}, calling `super.destroy()`. * * ## Rendering the pass * * 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 {@link 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 {@link RenderPass#render}, for example to render into a texture each * time its content needs to change. See {@link FramePass#render} for the steps a frame performs, * which are skipped then. * * @example * // 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(); * * @category Graphics */ export class RenderPass extends FramePass { /** * The render target the pass draws into, or null when it draws into the back buffer. It is set * by {@link 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 {@link FramePass} * instead. It is undefined until the pass is initialized. The render pass does not own the * render target, and does not destroy it. * * @type {RenderTarget|null|undefined} */ renderTarget: RenderTarget | null | undefined; /** * How the render target is resized: what to, null for the back buffer, and the scale factors. * Undefined when the render target is not resized. * * @type {{ resizeSource: Texture|RenderTarget|null, scaleX: number, scaleY: number }|undefined} * @private */ private _options; /** * Number of samples. 0 if no render target, otherwise number of samples from the render target, * or the main framebuffer if render target is null. * * @ignore */ samples: number; /** * Array of color attachment operations. The first element corresponds to the color attachment * 0, and so on. * * @type {Array} * @ignore */ colorArrayOps: Array; /** * Color attachment operations for the first color attachment. * * @type {ColorAttachmentOps} * @ignore */ get colorOps(): ColorAttachmentOps; /** * Depth and stencil attachment operations. * * @type {DepthStencilAttachmentOps} * @ignore */ depthStencilOps: DepthStencilAttachmentOps; /** * True if the render pass uses the full viewport / scissor for rendering into the render target. * * @ignore */ fullSizeClearRect: boolean; /** * Sets what the render target of the pass is resized to each frame: a texture or a render * target, whose size, scaled by {@link RenderPass#scaleX} and {@link 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 {@link 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 {@link 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. * * @type {Texture|RenderTarget|null|undefined} */ set resizeSource(value: Texture | RenderTarget | null | undefined); /** * Gets what the render target of the pass is resized to. * * @type {Texture|RenderTarget|null|undefined} */ get resizeSource(): Texture | RenderTarget | null | undefined; /** * Sets the scale factor of the width of the render target, relative to the size of its resize * source, see {@link RenderPass#resizeSource}. Only valid while the render target is resized. * Defaults to 1. * * @type {number} */ set scaleX(value: number); /** * Gets the scale factor of the width of the render target. It is 1 while the render target is * not resized. * * @type {number} */ get scaleX(): number; /** * Sets the scale factor of the height of the render target, relative to the size of its resize * source, see {@link RenderPass#resizeSource}. Only valid while the render target is resized. * Defaults to 1. * * @type {number} */ set scaleY(value: number); /** * Gets the scale factor of the height of the render target. It is 1 while the render target * is not resized. * * @type {number} */ get scaleY(): number; /** * Sets how the render target is resized, from the options of {@link RenderPass#init}, which * are copied, so the object passed in is not kept. * * @param {{ resizeSource?: Texture|RenderTarget|null, scaleX?: number, scaleY?: number }|undefined} value - The * options, or undefined to not resize the render target. * @ignore */ set options(value: { resizeSource?: Texture | RenderTarget | null; scaleX?: number; scaleY?: number; } | undefined); /** * Gets how the render target is resized. * * @type {{ resizeSource: Texture|RenderTarget|null, scaleX: number, scaleY: number }|undefined} * @ignore */ get options(): { resizeSource: Texture | RenderTarget | null; scaleX: number; scaleY: number; } | undefined; /** * 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 {@link RenderPass#setClearColor}, {@link RenderPass#setStoreColor}, * {@link 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 {@link RenderPass#renderTarget} directly. * * When options are provided, the render target is resized each frame, in * {@link RenderPass#frameUpdate}, to the size of the resize source scaled by * {@link RenderPass#scaleX} and {@link 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 {@link RenderPass#resizeSource}, scaleX and scaleY instead. * * @param {RenderTarget|null} [renderTarget] - 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. * @param {object} [options] - Object for passing optional arguments. * @param {Texture|RenderTarget|null} [options.resizeSource] - The texture or render target whose * size the render target is resized to, or null for the back buffer. Defaults to null. * @param {number} [options.scaleX] - The scale factor for the render target width. Defaults to 1. * @param {number} [options.scaleY] - The scale factor for the render target height. Defaults to 1. */ init(renderTarget?: RenderTarget | null, options?: { resizeSource?: Texture | RenderTarget | null; scaleX?: number; scaleY?: number; }): void; /** * Allocates the operations of the attachments of the render target, with their defaults. The * operations allocated by a previous initialization are reset and reused, as a pass can be * initialized every frame, for example to render to a different render target. * * @ignore */ allocateAttachments(): void; /** * Called at the end of {@link RenderPass#init}, once the pass is set up for its render * target. Override to finish the setup, for example to set the clears the pass uses. */ postInit(): void; /** * Mark render pass as clearing the full color buffer. * * @param {Color|undefined} color - The color to clear to, or undefined to preserve the existing * content. * @param {number} [index] - The index of the color attachment to modify. When not specified, * all color attachments are modified. */ setClearColor(color: Color | undefined, index?: number): void; /** * Mark render pass as clearing the full depth buffer. * * @param {number|undefined} depthValue - The depth value to clear to, or undefined to preserve * the existing content. */ setClearDepth(depthValue: number | undefined): void; /** * Mark render pass as clearing the full stencil buffer. * * @param {number|undefined} stencilValue - The stencil value to clear to, or undefined to * preserve the existing content. */ setClearStencil(stencilValue: number | undefined): 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 {@link FramePass#render}. Not storing a single-sampled color buffer discards * what the pass renders into it. Set it once the pass is initialized, as * {@link RenderPass#init} resets it. * * @param {boolean} store - True to store the attachments, false to discard them. * @param {number} [index] - The index of the color attachment to modify. When not specified, * all color attachments are modified. */ setStoreColor(store: boolean, index?: number): 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 {@link FramePass#render}. Set it once the pass is * initialized, as {@link RenderPass#init} resets it. * * @param {boolean} store - True to store the depth, false to discard it. */ setStoreDepth(store: boolean): 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 {@link FramePass#render}. Set it once the pass is * initialized, as {@link RenderPass#init} resets it. * * @param {boolean} store - True to store the stencil, false to discard it. */ setStoreStencil(store: boolean): 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 {@link 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 {@link RenderPass#init} resets it. * * @param {boolean} generate - True to generate the mipmaps of the color buffers which support * them, false to not generate them. * @param {number} [index] - The index of the color attachment to modify. When not specified, * all color attachments are modified. */ setGenerateMipmaps(generate: boolean, index?: number): void; log(device: any, index?: number): void; } /** * @import { RenderTarget } from '../graphics/render-target.js' * @import { Texture } from './texture.js' */ /** * Reports the clear values of integer format color attachments which are not representable in * their format. The components of the clear color of an integer format attachment are the raw * integer values, and so a non-integer value would be silently truncated by WebGL, and generates a * validation error on WebGPU. * * @param {RenderPass} renderPass - The render pass to validate. * @ignore */ export function validateClearValues(renderPass: RenderPass): void; import { FramePass } from './frame-pass.js'; import type { RenderTarget } from '../graphics/render-target.js'; /** * The operations a {@link RenderPass} performs on one of its color attachments: whether it is * cleared before the pass renders, and whether it is stored, resolved and has its mipmaps * generated after. {@link RenderPass#init} allocates them with defaults matching the render * target. * * @ignore */ declare class ColorAttachmentOps { /** * A color used to clear the color attachment when the clear is enabled, specified in sRGB * space. Set it with {@link RenderPass#setClearColor}, which also updates the linear value * used to clear sRGB attachments. */ clearValue: Color; /** * A color used to clear the color attachment when the clear is enabled, specified in linear * space. Kept in sync with the clearValue by {@link RenderPass#setClearColor}. */ clearValueLinear: Color; /** * True if the attachment should be cleared before rendering, false to preserve * the existing content. */ clear: boolean; /** * True if the attachment needs to be stored after the render pass. False if it can be * discarded. Note: This relates to the surface that is getting rendered to, and can be either * single or multi-sampled. Further, if a multi-sampled surface is used, the resolve flag * further specifies if this gets resolved to a single-sampled surface. This behavior matches * the WebGPU specification. */ store: boolean; /** * True if the attachment needs to be resolved. */ resolve: boolean; /** * True if the attachment needs to have mipmaps generated. */ genMipmaps: boolean; /** * Resets the operations to their defaults, the values the properties are initialized with. */ reset(): void; } /** * The operations a {@link RenderPass} performs on its depth and stencil attachment: whether they * are cleared before the pass renders, and whether they are stored and resolved after. * {@link RenderPass#init} allocates them with defaults matching the render target. * * @ignore */ declare class DepthStencilAttachmentOps { /** * A depth value used to clear the depth attachment when the clear is enabled. */ clearDepthValue: number; /** * A stencil value used to clear the stencil attachment when the clear is enabled. */ clearStencilValue: number; /** * True if the depth attachment should be cleared before rendering, false to preserve * the existing content. */ clearDepth: boolean; /** * True if the stencil attachment should be cleared before rendering, false to preserve * the existing content. */ clearStencil: boolean; /** * True if the depth attachment needs to be stored after the render pass. False * if it can be discarded. */ storeDepth: boolean; /** * True if the depth attachment needs to be resolved. */ resolveDepth: boolean; /** * True if the stencil attachment needs to be stored after the render pass. False * if it can be discarded. */ storeStencil: boolean; /** * Resets the operations to their defaults, the values the properties are initialized with. */ reset(): void; } import type { Texture } from './texture.js'; import { Color } from '../../core/math/color.js'; export {};