Class RenderTarget

constructor

• new RenderTarget(
      options?: {
          autoResolve?: boolean;
          colorBuffer?: Texture;
          colorBuffers?: Texture[];
          depth?: boolean;
          depthBuffer?: Texture;
          face?: number;
          mipLevel?: number;
          name?: string;
          origin?: string;
          samples?: number;
          stencil?: boolean;
          transientColor?: boolean;
          transientDepth?: boolean;
      },
  ): RenderTarget

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

  Parameters

  • Optionaloptions: {
        autoResolve?: boolean;
        colorBuffer?: Texture;
        colorBuffers?: Texture[];
        depth?: boolean;
        depthBuffer?: Texture;
        face?: number;
        mipLevel?: number;
        name?: string;
        origin?: string;
        samples?: number;
        stencil?: boolean;
        transientColor?: boolean;
        transientDepth?: boolean;
    } = {}

    Object for passing optional arguments.

    • OptionalautoResolve?: boolean

      If samples > 1, enables or disables automatic MSAA resolve after rendering to this RT (see resolve). Defaults to true.

    • OptionalcolorBuffer?: Texture

      The texture that this render target will treat as a rendering surface.

    • OptionalcolorBuffers?: Texture[]

      The textures that this render target will treat as a rendering surfaces. If this option is set, the colorBuffer option is ignored.

    • Optionaldepth?: boolean

      If set to true, depth buffer will be created. Defaults to true. Ignored if depthBuffer is defined.

    • OptionaldepthBuffer?: Texture

      The texture that this render target will treat as a depth/stencil surface (WebGL2 only). If set, the 'depth' and 'stencil' properties are ignored. Texture must have PIXELFORMAT_DEPTH or PIXELFORMAT_DEPTHSTENCIL format.

    • Optionalface?: number

      If the colorBuffer parameter is a cubemap, use this option to specify the face of the cubemap to render to. Can be:

      • CUBEFACE_POSX
      • CUBEFACE_NEGX
      • CUBEFACE_POSY
      • CUBEFACE_NEGY
      • CUBEFACE_POSZ
      • CUBEFACE_NEGZ

      Defaults to CUBEFACE_POSX.

    • OptionalmipLevel?: number

      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.

    • Optionalname?: string

      The name of the render target.

    • Optionalorigin?: string

      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: 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: 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 is the better long-term choice. Internally the image is rendered upside-down on WebGPU.
      • RENDERTARGET_ORIGIN_NATIVE: 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.

    • Optionalsamples?: number

      Number of hardware anti-aliasing samples. Default is 1.

    • Optionalstencil?: boolean

      If set to true, depth buffer will include stencil. Defaults to false. Ignored if depthBuffer is defined or depth is false.

    • OptionaltransientColor?: boolean

      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.

    • OptionaltransientDepth?: boolean

      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.

  Returns RenderTarget

  Example

  // 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;
  Copy

autoResolve

name

colorBuffer

• get colorBuffer(): Texture

  Color buffer set up on the render target.

  Returns Texture

depth

• get depth(): boolean

  True if the render target contains the depth attachment.

  Returns boolean

depthBuffer

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

  Returns Texture

face

• 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
  • CUBEFACE_NEGX
  • CUBEFACE_POSY
  • CUBEFACE_NEGY
  • CUBEFACE_POSZ
  • CUBEFACE_NEGZ

  Returns number

height

• get height(): number

  Height of the render target in pixels.

  Returns number

mipLevel

• get mipLevel(): number

  Mip level of the render target.

  Returns number

mipmaps

• get mipmaps(): boolean

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

  Returns boolean

origin

• 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, RENDERTARGET_ORIGIN_BOTTOM or RENDERTARGET_ORIGIN_NATIVE. See the origin option of the constructor for details.

  Returns string

samples

• get samples(): number

  Number of antialiasing samples the render target uses.

  Returns number

stencil

• get stencil(): boolean

  True if the render target contains the stencil attachment.

  Returns boolean

transientColor

• get transientColor(): boolean

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

  Returns boolean

transientDepth

• get transientDepth(): boolean

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

  Returns boolean

width

• get width(): number

  Width of the render target in pixels.

  Returns number

copy

• 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. Depth buffer can only be copied on WebGL 2.0.

  Parameters

  • source: RenderTarget

    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.

  Returns boolean

  True if the copy was successful, false otherwise.

destroy

• destroy(): void

  Frees resources associated with this render target.

  Returns void

getColorBuffer

• getColorBuffer(index: number): Texture

  Accessor for multiple render target color buffers.

  Parameters

  • index: number

    Index of the color buffer to get.

  Returns Texture

  • Color buffer at the specified index.

resize

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

  Returns void

resolve

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

  Parameters

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

  Returns void