Create a new RenderPassForward instance.
The graphics device.
The scene whose layers the pass renders.
The camera component used to render the layers.
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.
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.
ReadonlycameraThe camera component used to render the layers.
The graphics device.
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.
The gamma correction setting for the render pass. If not set, the setting from the camera is used. This allows render passes to override the camera's gamma correction during the render pass.
For HDR pipelines, scene render passes typically set this to GAMMA_NONE to output linear values to an HDR render target, while subsequent passes (like UI) leave it undefined to use the camera's default GAMMA_SRGB for correct display output.
Can be:
undefined (uses camera setting)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.
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.
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.
The tone mapping setting for the render pass, one of the TONEMAP_* constants, for example TONEMAP_ACES. If not set, the setting from the camera is used.
Gets whether the frame pass is enabled.
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.
Gets the name of the pass.
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.
Gets what the render target of the pass is resized to.
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.
Gets the scale factor of the width of the render target. It is 1 while the render target is not resized.
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.
Gets the scale factor of the height of the render target. It is 1 while the render target is not resized.
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.
Adds a layer to be rendered by this pass, after the layers added before it. Call RenderPass#init before adding layers. The camera of the pass needs to render the layer, see CameraComponent#layers.
The layer to be added.
True to render the transparent sub-layer of the layer, false to render its opaque sub-layer. To render both, add the layer twice.
OptionalautoClears: boolean = true
True to clear the render target before the layer renders, as the clear flags of the layer request, together with those of the camera for the first layer added. Defaults to true.
Called while the pass renders, after FramePass#execute. It is called even when FramePass#executeEnabled is false and the pass did not execute, so an override using the results of the execution can skip that work while executeEnabled is false.
Called while the pass renders, before FramePass#execute. It is called even when FramePass#executeEnabled is false and the pass does not execute, so an override preparing only for the execution can skip that work while executeEnabled is false.
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().
Records the work of the pass. Called while the frame renders, between FramePass#before and FramePass#after, and only while FramePass#executeEnabled is true. For a RenderPass, it runs inside the GPU render pass, which starts right before it.
Resizes the render target to the size of its resize source, scaled by
RenderPass#scaleX and RenderPass#scaleY, while the pass resizes its render
target, see RenderPass#resizeSource. See FramePass#frameUpdate. Subclasses
overriding it call super.frameUpdate() to keep the resize.
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.
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: {Object for passing optional arguments.
OptionalresizeSource?: Texture | RenderTarget | nullThe texture or render target whose size the render target is resized to, or null for the back buffer. Defaults to null.
OptionalscaleX?: numberThe scale factor for the render target width. Defaults to 1.
OptionalscaleY?: numberThe scale factor for the render target height. Defaults to 1.
Called when the pass is disabled, by setting FramePass#enabled to false while it is true. Override to release what the pass does not need while it is disabled, such as its render targets.
Called when the pass is enabled, by setting FramePass#enabled to true while it is false. Override to recreate what FramePass#onDisable released.
Called at the end of 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.
Renders the pass, as FramePass#render describes, starting its GPU render pass right before FramePass#execute and ending it right after. A pass the frame graph merged with a neighbouring pass on the same render target shares a single GPU render pass with it. The pass needs to be initialized with RenderPass#init before it renders.
Mark render pass as clearing the full color buffer.
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.
Mark render pass as clearing the full depth buffer.
The depth value to clear to, or undefined to preserve the existing content.
Mark render pass as clearing the full stencil buffer.
The stencil value to clear to, or undefined to preserve the existing content.
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.
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.
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.
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.
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.
True to store the depth, false to discard it.
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.
True to store the stencil, false to discard it.
A render pass rendering layers of the scene with a single camera. The engine renders the scene with these passes, and you can use them in the CameraComponent#framePasses of a camera to render the scene into a render target of your own, for example to process it with your own passes before it is displayed.
Call RenderPass#init with the render target before adding the layers to render with RenderPassForward#addLayer. Each frame, the pass:
A RenderPassForward cannot be nested under another one, which is among its before-passes or after-passes, or among the before-passes of its camera, which it executes before itself. To render the layers with another camera first, render the passes one after the other, for example as the before-passes of a FramePass, or render them with a camera of a lower priority.
Example