# RenderTarget

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/platform/graphics/render-target.js#L94

A render target is a rectangular rendering surface that can be rendered into, instead of the
screen. It wraps one or more color buffer [Texture](https://api.playcanvas.com/engine/classes/Texture.md)s 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:

```javascript
const texture = new Texture(device, {
    width: 512,
    height: 512,
    format: PIXELFORMAT_SRGBA8,
    mipmaps: false,
    minFilter: FILTER_LINEAR,
    magFilter: FILTER_LINEAR
});

const renderTarget = new RenderTarget({
    colorBuffer: texture,
    depth: true,
    origin: RENDERTARGET_ORIGIN_TOP
});

// the camera renders into the texture instead of the screen
cameraEntity.camera.renderTarget = renderTarget;

// and the texture can be used as any other, for example by a material
material.emissiveMap = texture;
```

When the result is sampled as a regular texture like this, specify the `origin` option as
[RENDERTARGET_ORIGIN_TOP](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_TOP.md), which stores the image in the same orientation on all graphics
APIs. Multiple color buffers can be attached using the `colorBuffers` option, to render into
all of them simultaneously from a single pass (MRT).

A live example: [https://playcanvas.github.io/#/graphics/render-to-texture](https://playcanvas.github.io/#/graphics/render-to-texture)

## Multisampling (MSAA)
Set the `samples` option 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-sampled `colorBuffer` at the end of a render pass - the color
texture is used the same way as in the single-sampled case.

```javascript
const renderTarget = new RenderTarget({ colorBuffer: texture, depth: true, samples: 4 });
```

## Explicit multisampled color buffers and custom resolves (WebGPU)
A multisampled texture (a [Texture](https://api.playcanvas.com/engine/classes/Texture.md) created with `samples` greater 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 a `resolveBuffer` to get the standard
hardware resolve, or omit it to keep the individual samples: these are then read in a shader
using `textureLoad` on a `texture_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.

```javascript
// a multisampled texture, rendered into directly
const msColor = new Texture(device, {
    width: 512,
    height: 512,
    format: PIXELFORMAT_RGBA16F,
    samples: 4
});

// renders into the samples of msColor, which are stored (no resolve buffer),
// to be read by a custom resolve pass using textureLoad
const renderTarget = new RenderTarget({ colorBuffer: msColor, depth: true });
```

A live example: [https://playcanvas.github.io/#/graphics-advanced/custom-msaa-resolve](https://playcanvas.github.io/#/graphics-advanced/custom-msaa-resolve)

## Constructors

### constructor

```ts
new RenderTarget(options?: object)
```

Creates a new RenderTarget instance. A color buffer or a depth buffer must be set.

**Parameters**

- `options` (`object`, optional, default `{}`): Object for passing optional arguments.
    - `options.autoResolve` (`boolean`, optional): If samples > 1, enables or disables automatic MSAA
      resolve after rendering to this RT (see [resolve](https://api.playcanvas.com/engine/classes/RenderTarget.md#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.
    - `options.colorBuffer` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md), optional): The 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.
    - `options.colorBuffers` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md)`[]`, optional): 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.
    - `options.depth` (`boolean`, optional): If set to true, depth buffer will be created. Defaults to
      true. Ignored if depthBuffer is defined.
    - `options.depthBuffer` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md), optional): The 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](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTH.md), [PIXELFORMAT_DEPTH16](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTH16.md) or
      [PIXELFORMAT_DEPTHSTENCIL](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTHSTENCIL.md) 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`.
    - `options.depthResolveBuffer` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md), optional): A single-sampled [PIXELFORMAT_R32F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_R32F.md)
      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](https://api.playcanvas.com/engine/classes/RenderTarget.md#depthresolvemode) (WebGPU
      only - no hardware depth resolve exists). Only valid when `depthBuffer` is a multisampled
      texture, and must match its dimensions.
    - `options.depthResolveMode` (`string`, optional): How 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](https://api.playcanvas.com/engine/classes/RenderTarget.md#copy), or the automatic resolve into a provided `depthBuffer`. Can be:

      - [DEPTHRESOLVE_MIN](https://api.playcanvas.com/engine/variables/DEPTHRESOLVE_MIN.md): the minimum sample value - with a standard depth buffer this
      selects the nearest surface, a conservative and stable choice for depth-consuming effects.
      - [DEPTHRESOLVE_MAX](https://api.playcanvas.com/engine/variables/DEPTHRESOLVE_MAX.md): the maximum sample value - the farthest surface.
      - [DEPTHRESOLVE_SAMPLE0](https://api.playcanvas.com/engine/variables/DEPTHRESOLVE_SAMPLE0.md): the value of the sample at index 0.

      Defaults to [DEPTHRESOLVE_MIN](https://api.playcanvas.com/engine/variables/DEPTHRESOLVE_MIN.md). 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
      [RenderTarget#depthResolveMode](https://api.playcanvas.com/engine/classes/RenderTarget.md#depthresolvemode) property.
    - `options.face` (`number`, optional): If the colorBuffer parameter is a cubemap, use this option
      to specify the face of the cubemap to render to. Can be:

      - [CUBEFACE_POSX](https://api.playcanvas.com/engine/variables/CUBEFACE_POSX.md)
      - [CUBEFACE_NEGX](https://api.playcanvas.com/engine/variables/CUBEFACE_NEGX.md)
      - [CUBEFACE_POSY](https://api.playcanvas.com/engine/variables/CUBEFACE_POSY.md)
      - [CUBEFACE_NEGY](https://api.playcanvas.com/engine/variables/CUBEFACE_NEGY.md)
      - [CUBEFACE_POSZ](https://api.playcanvas.com/engine/variables/CUBEFACE_POSZ.md)
      - [CUBEFACE_NEGZ](https://api.playcanvas.com/engine/variables/CUBEFACE_NEGZ.md)

      Defaults to [CUBEFACE_POSX](https://api.playcanvas.com/engine/variables/CUBEFACE_POSX.md).
    - `options.mipLevel` (`number`, optional): If set to a number greater than 0, the render target
      will render to the specified mip level of the color buffer. Defaults to 0.
    - `options.name` (`string`, optional): The name of the render target.
    - `options.origin` (`string`, optional): Controls the vertical orientation of the image stored
      in the render target. Choose based on how the texture is sampled. Can be:

      - [RENDERTARGET_ORIGIN_TOP](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_TOP.md): row 0 of the stored image is the top row of the
      rendered image, on all graphics APIs - the same layout image textures use. Use for
      anything treated as a picture: sampling with mesh UVs, cube map faces, or pixel readback
      saved as an image. Recommended for all new content - write the sampling code as if the
      texture was a loaded image. Internally the image is rendered upside-down on WebGL2.
      - [RENDERTARGET_ORIGIN_BOTTOM](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_BOTTOM.md): row 0 of the stored image is the bottom row of the
      rendered image, on all graphics APIs - replicating WebGL2's native layout. Use to keep
      consuming code written against WebGL conventions working unchanged on all APIs: shaders
      deriving UVs from projected (NDC) coordinates or a projection scale-bias matrix, and
      texture atlases addressing cells by viewport rectangles (on WebGPU this also switches
      viewport / scissor rectangles to raw texel-row addressing). If a render target that worked
      on WebGL2 appears upside-down on WebGPU, this is the drop-in fix; migrating the sampling
      code to image orientation and [RENDERTARGET_ORIGIN_TOP](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_TOP.md) is the better long-term
      choice. Internally the image is rendered upside-down on WebGPU.
      - [RENDERTARGET_ORIGIN_NATIVE](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_NATIVE.md): the image is stored in the native orientation of the
      graphics API and the row order differs between WebGL2 (bottom-up) and WebGPU (top-down).
      No flipping takes place. Only appropriate for orientation-agnostic consumers: UVs derived
      from gl_FragCoord, sampling via the same matrix the target was rendered with (shadow
      maps), or integer texel fetch.

      Takes precedence over the deprecated `flipY` option. Defaults to
      [RENDERTARGET_ORIGIN_NATIVE](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_NATIVE.md).
    - `options.resolveBuffer` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md) `| null`, optional): A 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](https://api.playcanvas.com/engine/variables/PIXELFORMAT_R32F.md)
      cannot be hardware-resolved.
    - `options.resolveBuffers` (`(`[`Texture`](https://api.playcanvas.com/engine/classes/Texture.md) `| null)[]`, optional): 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.
    - `options.samples` (`number`, optional): Number of hardware anti-aliasing samples. Default is 1.
    - `options.stencil` (`boolean`, optional): If set to true, depth buffer will include stencil.
      Defaults to false. Ignored if depthBuffer is defined or depth is false.
    - `options.transientColor` (`boolean`, optional): If 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.
    - `options.transientDepth` (`boolean`, optional): If 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.

**Example**

```ts
// 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;
```

## Properties

### autoResolve

```ts
autoResolve: boolean
```

### name

```ts
name: string
```

The name of the render target.

## Accessors

### colorBuffer

```ts
get colorBuffer(): Texture
```

Color buffer set up on the render target.

### colorBufferCount

```ts
get colorBufferCount(): number
```

The number of color buffers (attachments) set up on the render target.

### depth

```ts
get depth(): boolean
```

True if the render target contains the depth attachment.

### depthBuffer

```ts
get depthBuffer(): Texture
```

Depth buffer set up on the render target. Only available, if depthBuffer was set in
constructor. Not available if depth property was used instead.

### depthResolveBuffer

```ts
get depthResolveBuffer(): Texture | null
```

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.

### depthResolveMode

```ts
get depthResolveMode(): string
set depthResolveMode(value: string)
```

Gets how the samples of the multisampled depth buffer are resolved into a single depth
value.

### face

```ts
get face(): number
```

If the render target is bound to a cubemap, this property specifies which face of the
cubemap is rendered to. Can be:

- [CUBEFACE_POSX](https://api.playcanvas.com/engine/variables/CUBEFACE_POSX.md)
- [CUBEFACE_NEGX](https://api.playcanvas.com/engine/variables/CUBEFACE_NEGX.md)
- [CUBEFACE_POSY](https://api.playcanvas.com/engine/variables/CUBEFACE_POSY.md)
- [CUBEFACE_NEGY](https://api.playcanvas.com/engine/variables/CUBEFACE_NEGY.md)
- [CUBEFACE_POSZ](https://api.playcanvas.com/engine/variables/CUBEFACE_POSZ.md)
- [CUBEFACE_NEGZ](https://api.playcanvas.com/engine/variables/CUBEFACE_NEGZ.md)

### height

```ts
get height(): number
```

Height of the render target in pixels.

### mipLevel

```ts
get mipLevel(): number
```

Mip level of the render target.

### mipmaps

```ts
get mipmaps(): boolean
```

True if the mipmaps are automatically generated for the color buffer(s) if it contains
a mip chain.

### origin

```ts
get origin(): string
```

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](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_TOP.md), [RENDERTARGET_ORIGIN_BOTTOM](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_BOTTOM.md) or
[RENDERTARGET_ORIGIN_NATIVE](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_NATIVE.md). See the `origin` option of the constructor for
details.

### resolveBuffer

```ts
get resolveBuffer(): Texture | null
```

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.

### samples

```ts
get samples(): number
```

Number of antialiasing samples the render target uses.

### stencil

```ts
get stencil(): boolean
```

True if the render target contains the stencil attachment.

### transientColor

```ts
get transientColor(): boolean
```

True if the multi-sampled color attachment is allocated as a transient ("memoryless")
attachment (WebGPU only). See the `transientColor` constructor option.

### transientDepth

```ts
get transientDepth(): boolean
```

True if the depth attachment is allocated as a transient ("memoryless") attachment (WebGPU
only). See the `transientDepth` constructor option.

### width

```ts
get width(): number
```

Width of the render target in pixels.

## Methods

### copy

```ts
copy(source: RenderTarget, color?: boolean, depth?: boolean): boolean
```

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:

- On WebGL 2.0, between render targets with matching sample counts.
- On WebGPU, between single-sampled render targets.
- On WebGPU, from a multisampled source into a multisampled `depthBuffer` of this render
target with an equal sample count and matching format - a full depth snapshot, including
the individual samples.
- On WebGPU, from a multisampled source into a single-sampled [PIXELFORMAT_R32F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_R32F.md)
color buffer of this render target - a shader-based resolve controlled by the source's
[RenderTarget#depthResolveMode](https://api.playcanvas.com/engine/classes/RenderTarget.md#depthresolvemode).

**Parameters**

- `source` ([`RenderTarget`](https://api.playcanvas.com/engine/classes/RenderTarget.md)): Source render target to copy from.
- `color` (`boolean`, optional): If true, will copy the color buffer. Defaults to false.
- `depth` (`boolean`, optional): If true, will copy the depth buffer. Defaults to false.

**Returns** `boolean`: True if the copy was successful, false otherwise.

### destroy

```ts
destroy(): void
```

Frees resources associated with this render target.

### getColorBuffer

```ts
getColorBuffer(index: number): Texture
```

Accessor for multiple render target color buffers.

**Parameters**

- `index` (`number`): Index of the color buffer to get.

**Returns** [`Texture`](https://api.playcanvas.com/engine/classes/Texture.md): - Color buffer at the specified index.

### getResolveBuffer

```ts
getResolveBuffer(index?: number): Texture | null
```

Accessor for the per-attachment resolve textures. See the `resolveBuffers` constructor
option.

**Parameters**

- `index` (`number`, optional, default `0`): Index of the color attachment. Defaults to 0.

**Returns** [`Texture`](https://api.playcanvas.com/engine/classes/Texture.md) `| null`: - The resolve texture at the specified index, or null when the
attachment has none.

### resize

```ts
resize(width: number, height: number): void
```

Resizes the render target to the specified width and height. Internally this resizes all the
assigned texture color and depth buffers.

**Parameters**

- `width` (`number`): The width of the render target in pixels.
- `height` (`number`): The height of the render target in pixels.

### resolve

```ts
resolve(color?: boolean, depth?: boolean): void
```

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 an 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.

**Parameters**

- `color` (`boolean`, optional, default `true`): Resolve color buffer. Defaults to true.
- `depth` (`boolean`, optional): Resolve depth buffer. Defaults to true if the render target has a
  depth buffer.