API Reference

Class List

RenderTarget

A render target is a rectangular rendering surface.

// Create a 512x512x24-bit render target with a depth buffer
var colorBuffer = new pc.Texture(graphicsDevice, {
    width: 512,
    height: 512,
    format: pc.PIXELFORMAT_R8_G8_B8
});
var renderTarget = new pc.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;

Summary

Properties

colorBuffer

Color buffer set up on the render target.

depth

True if the render target contains the depth attachment.

depthBuffer

Depth buffer set up on the render target.

face

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

height

Height of the render target in pixels.

samples

Number of antialiasing samples the render target uses.

stencil

True if the render target contains the stencil attachment.

width

Width of the render target in pixels.

Methods

copy

Copies color and/or depth contents of source render target to this one.

destroy

Frees resources associated with this render target.

resolve

If samples > 1, resolves the anti-aliased render target (WebGL2 only).

Details

Constructor

RenderTarget(options)

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

// Create a 512x512x24-bit render target with a depth buffer
var colorBuffer = new pc.Texture(graphicsDevice, {
    width: 512,
    height: 512,
    format: pc.PIXELFORMAT_R8_G8_B8
});
var renderTarget = new pc.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;

Parameters

optionsobject

Object for passing optional arguments.

options.autoResolveboolean

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

options.colorBufferTexture

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

options.depthboolean

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

options.depthBufferTexture

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.

options.facenumber

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

options.flipYboolean

When set to true the image will be flipped in Y. Default is false.

options.namestring

The name of the render target.

options.samplesnumber

Number of hardware anti-aliasing samples (WebGL2 only). Default is 1.

options.stencilboolean

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

Properties

TexturecolorBuffer

Color buffer set up on the render target.

booleandepth

True if the render target contains the depth attachment.

TexturedepthBuffer

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

numberface

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

numberheight

Height of the render target in pixels.

numbersamples

Number of antialiasing samples the render target uses.

booleanstencil

True if the render target contains the stencil attachment.

numberwidth

Width of the render target in pixels.

Methods

copy(source, [color], [depth])

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

sourceRenderTarget

Source render target to copy from.

colorboolean

If true will copy the color buffer. Defaults to false.

depthboolean

If true will copy the depth buffer. Defaults to false.

Returns

boolean

True if the copy was successful, false otherwise.

destroy()

Frees resources associated with this render target.

resolve([color], [depth])

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 inside a Command.

Parameters

colorboolean

Resolve color buffer. Defaults to true.

depthboolean

Resolve depth buffer. Defaults to true if the render target has a depth buffer.