Creates a new RenderTarget instance. A color buffer or a depth buffer must be set.
Optionaloptions: {Object for passing optional arguments.
OptionalautoResolve?: booleanIf samples > 1, enables or disables automatic MSAA
resolve after rendering to this RT (see resolve). Applies to the implicit
multisampled path only - resolves of explicit multisampled attachments (a multisampled
colorBuffer with a resolveBuffer, or a multisampled depthBuffer with a
depthResolveBuffer) are controlled by the per-pass resolve flags instead. Defaults to
true.
OptionalcolorBuffer?: TextureThe texture that this render target will treat as a
rendering surface. This can be a multisampled texture (a texture created with samples > 1,
WebGPU only), in which case the render target renders directly into its samples, the sample
count is inferred from the texture, and an optional resolveBuffer receives the hardware
resolve.
OptionalcolorBuffers?: Texture[]The textures that this render target will treat as a rendering surfaces. If this option is set, the colorBuffer option is ignored. All textures must have the same sample count.
Optionaldepth?: booleanIf set to true, depth buffer will be created. Defaults to true. Ignored if depthBuffer is defined.
OptionaldepthBuffer?: TextureThe texture that this render target will treat as a
depth/stencil surface. If set, the 'depth' and 'stencil' properties are ignored. The texture
must use PIXELFORMAT_DEPTH, PIXELFORMAT_DEPTH16 or
PIXELFORMAT_DEPTHSTENCIL format. On WebGPU this can be a multisampled texture (a
texture created with samples > 1), in which case the render target renders directly into
its depth samples, which can later be read in a shader using textureLoad on a
texture_depth_multisampled_2d, or resolved into an optional depthResolveBuffer.
OptionaldepthResolveBuffer?: TextureA single-sampled PIXELFORMAT_R32F
texture that the multisampled depth buffer is resolved into at the end of a render pass,
using a shader-based resolve controlled by RenderTarget#depthResolveMode (WebGPU
only - no hardware depth resolve exists). Only valid when depthBuffer is a multisampled
texture, and must match its dimensions.
OptionaldepthResolveMode?: stringHow the samples of the multisampled depth
buffer are resolved into a single depth value, whenever the depth of this render target is
resolved by a shader-based resolve (WebGPU only) - the depth grab pass (sceneDepthMap), a
depth copy, or the automatic resolve into a provided depthBuffer. Can be:
Defaults to DEPTHRESOLVE_MIN. Ignored on WebGL2, where the sample selection of the depth resolve is defined by the implementation. Can also be changed at any time using the depthResolveMode property.
Optionalface?: numberIf the colorBuffer parameter is a cubemap, use this option to specify the face of the cubemap to render to. Can be:
Defaults to CUBEFACE_POSX.
OptionalmipLevel?: numberIf set to a number greater than 0, the render target will render to the specified mip level of the color buffer. Defaults to 0.
Optionalname?: stringThe name of the render target.
Optionalorigin?: stringControls the vertical orientation of the image stored in the render target. Choose based on how the texture is sampled. Can be:
Takes precedence over the deprecated flipY option. Defaults to
RENDERTARGET_ORIGIN_NATIVE.
OptionalresolveBuffer?: Texture | nullA single-sampled texture that the
multisampled color buffer is hardware-resolved into at the end of a render pass. Only valid
when colorBuffer is a multisampled texture, and must match its format and dimensions. When
not provided, the multisampled samples are stored instead, to be read in a shader using
textureLoad (a custom resolve). Note that integer formats and PIXELFORMAT_R32F
cannot be hardware-resolved.
OptionalresolveBuffers?: (Texture | null)[]Per-attachment resolve textures
matching colorBuffers by index; use null for attachments that should not be
hardware-resolved. If this option is set, the resolveBuffer option must not be used.
Optionalsamples?: numberNumber of hardware anti-aliasing samples. Default is 1.
Optionalstencil?: booleanIf set to true, depth buffer will include stencil. Defaults to false. Ignored if depthBuffer is defined or depth is false.
OptionaltransientColor?: booleanIf set to true, the multi-sampled (MSAA) color
attachment is allocated as a transient ("memoryless") attachment, allowing tile-based GPUs to
keep its contents in on-chip memory and avoid VRAM allocation. WebGPU only, and only effective
when samples > 1 - it has no effect on single-sampled color (which is always stored). Ignored
on devices without transient attachment support. The attachment must be cleared on load and
discarded on store, so it is incompatible with a scene color grab pass (sceneColorMap).
Defaults to false.
OptionaltransientDepth?: booleanIf set to true, the (engine-allocated) depth
attachment is allocated as a transient ("memoryless") attachment (see transientColor).
Applies to both single- and multi-sampled depth. WebGPU only; ignored on devices without
transient attachment support, and ignored (with a warning) when an explicit depthBuffer is
provided. Incompatible with a scene depth grab pass (sceneDepthMap), a depth prepass, or any
depth resolve, as the depth cannot be sampled or copied out. Defaults to false.
// Create a 512x512x24-bit render target with a depth buffer
const colorBuffer = new Texture(graphicsDevice, {
width: 512,
height: 512,
format: PIXELFORMAT_RGB8
});
const renderTarget = new RenderTarget({
colorBuffer: colorBuffer,
depth: true
});
// Set the render target on a camera component
camera.renderTarget = renderTarget;
// Destroy render target at a later stage. Note that the color buffer needs
// to be destroyed separately.
renderTarget.colorBuffer.destroy();
renderTarget.destroy();
camera.renderTarget = null;
Color buffer set up on the render target.
The number of color buffers (attachments) set up on the render target.
True if the render target contains the depth attachment.
Depth buffer set up on the render target. Only available, if depthBuffer was set in constructor. Not available if depth property was used instead.
The single-sampled texture the multisampled depth buffer is resolved into at the end of a
render pass. See the depthResolveBuffer constructor option. Null when not provided.
Gets how the samples of the multisampled depth buffer are resolved into a single depth value.
Sets how the samples of the multisampled depth buffer are resolved into a single depth
value (WebGPU only). Can be changed at any time - the mode is used at the time the depth is
resolved. See the depthResolveMode constructor option.
If the render target is bound to a cubemap, this property specifies which face of the cubemap is rendered to. Can be:
Height of the render target in pixels.
Mip level of the render target.
True if the mipmaps are automatically generated for the color buffer(s) if it contains a mip chain.
Gets the vertical orientation of the image stored in this render target, as resolved at
construction from the origin option, or derived from the deprecated flipY option or
property. Can be RENDERTARGET_ORIGIN_TOP, RENDERTARGET_ORIGIN_BOTTOM or
RENDERTARGET_ORIGIN_NATIVE. See the origin option of the constructor for
details.
The resolve texture of the first color attachment, when the render target uses explicit
multisampled color buffers and a resolve buffer was provided. See the resolveBuffer
constructor option. Null otherwise.
Number of antialiasing samples the render target uses.
True if the render target contains the stencil attachment.
True if the multi-sampled color attachment is allocated as a transient ("memoryless")
attachment (WebGPU only). See the transientColor constructor option.
True if the depth attachment is allocated as a transient ("memoryless") attachment (WebGPU
only). See the transientDepth constructor option.
Width of the render target in pixels.
Copies color and/or depth contents of source render target to this one. Formats, sizes and anti-aliasing samples must match.
A depth copy is supported in these cases:
depthBuffer of this render
target with an equal sample count and matching format - a full depth snapshot, including
the individual samples.Source render target to copy from.
Optionalcolor: boolean
If true, will copy the color buffer. Defaults to false.
Optionaldepth: boolean
If true, will copy the depth buffer. Defaults to false.
True if the copy was successful, false otherwise.
Frees resources associated with this render target.
Accessor for multiple render target color buffers.
Index of the color buffer to get.
Accessor for the per-attachment resolve textures. See the resolveBuffers constructor
option.
Optionalindex: number = 0
Index of the color attachment. Defaults to 0.
Resizes the render target to the specified width and height. Internally this resizes all the assigned texture color and depth buffers.
The width of the render target in pixels.
The height of the render target in pixels.
If samples > 1, resolves the anti-aliased render target (WebGL2 only). When you're rendering to an anti-aliased render target, pixels aren't written directly to the readable texture. Instead, they're first written to a MSAA buffer, where each sample for each pixel is stored independently. In order to read the results, you first need to 'resolve' the buffer - to average all samples and create a simple texture with one color per pixel. This function performs this averaging and updates the colorBuffer and the depthBuffer. If autoResolve is set to true, the resolve will happen after every rendering to this render target, otherwise you can do it manually, during the app update or similar.
Optionalcolor: boolean = true
Resolve color buffer. Defaults to true.
Optionaldepth: boolean = ...
Resolve depth buffer. Defaults to true if the render target has a depth buffer.
A render target is a rectangular rendering surface that can be rendered into, instead of the screen. It wraps one or more color buffer Textures and an optional depth (and stencil) buffer. Once a camera or a render pass has rendered into it, the color texture holds the result and can be used anywhere a normal texture can - applied to a material to display it in the scene, or fed into further processing. This underpins effects such as in-world screens, mirrors and portals, reflections, picking and custom multi-pass pipelines.
Usage
Create a texture to render into, wrap it in a render target and assign it to a camera. The texture must use a renderable, uncompressed format:
When the result is sampled as a regular texture like this, specify the
originoption as RENDERTARGET_ORIGIN_TOP, which stores the image in the same orientation on all graphics APIs. Multiple color buffers can be attached using thecolorBuffersoption, to render into all of them simultaneously from a single pass (MRT).A live example: https://playcanvas.github.io/#/graphics/render-to-texture
Multisampling (MSAA)
Set the
samplesoption to a value greater than 1 to render with hardware anti-aliasing. The render target internally allocates a multisampled buffer to render into, and automatically resolves it into the single-sampledcolorBufferat the end of a render pass - the color texture is used the same way as in the single-sampled case.Explicit multisampled color buffers and custom resolves (WebGPU)
A multisampled texture (a Texture created with
samplesgreater than 1, WebGPU only) can be used as the color buffer directly. The render target then renders into its samples, and the sample count is inferred from the texture. Provide aresolveBufferto get the standard hardware resolve, or omit it to keep the individual samples: these are then read in a shader usingtextureLoadon atexture_multisampled_2d, typically by a follow-up pass implementing a custom resolve - an operation the hardware resolve cannot express, such as a tonemapped or min/max resolve. This is also the only way to use multisampling with formats the hardware cannot resolve, such as integer formats.A live example: https://playcanvas.github.io/#/graphics-advanced/custom-msaa-resolve