# RenderPass

Class · extends [`FramePass`](https://api.playcanvas.com/engine/classes/FramePass.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/64089771243fe28a9b9d2b4de538b99b07c75097/src/platform/graphics/render-pass.js#L265

A render pass is a [FramePass](https://api.playcanvas.com/engine/classes/FramePass.md) which draws into a render target. Its draw calls are
recorded inside a GPU render pass, which starts right before the pass executes and ends right
after. It is the base class for passes which draw, for example a pass rendering a quad with a
shader, see [RenderPassShaderQuad](https://api.playcanvas.com/engine/classes/RenderPassShaderQuad.md). For work which does not draw, such as compute
dispatches, use [FramePass](https://api.playcanvas.com/engine/classes/FramePass.md) or [ComputePass](https://api.playcanvas.com/engine/classes/ComputePass.md) instead.

## Setting up the pass

Once the pass is created, call [RenderPass#init](https://api.playcanvas.com/engine/classes/RenderPass.md#init) with the [RenderTarget](https://api.playcanvas.com/engine/classes/RenderTarget.md) to draw
into, or with null to draw into the back buffer. The pass does not own its render target, and
does not destroy it. When init is given options, the pass also resizes its render target each
frame, to the size of a texture, a render target or the back buffer, scaled by
[RenderPass#scaleX](https://api.playcanvas.com/engine/classes/RenderPass.md#scalex) and [RenderPass#scaleY](https://api.playcanvas.com/engine/classes/RenderPass.md#scaley), see [RenderPass#resizeSource](https://api.playcanvas.com/engine/classes/RenderPass.md#resizesource).

## Loading and clearing the attachments

The attachments of the render target are its color buffers, and its depth and stencil buffers.
By default, the GPU render pass loads their content, and the pass draws over it. To start from a
single value instead, clear them with [RenderPass#setClearColor](https://api.playcanvas.com/engine/classes/RenderPass.md#setclearcolor),
[RenderPass#setClearDepth](https://api.playcanvas.com/engine/classes/RenderPass.md#setcleardepth) and [RenderPass#setClearStencil](https://api.playcanvas.com/engine/classes/RenderPass.md#setclearstencil). When the pass covers an
attachment completely, clearing it is also faster than loading it on tiled mobile GPUs, which
then do not read the previous content from memory.

## Storing the attachments

When the GPU render pass ends, the pass keeps what it rendered into the textures of its render
target, so they can be sampled, or loaded by a later pass: its color buffers, resolved when the
render target is multisampled, and its depth buffer texture. Other attachments are discarded:
the samples of a multisampled color buffer which is resolved, the stencil, and a depth buffer
the render target creates internally. When a later pass of the same frame draws into the same
render target and loads them, the frame graph stores them automatically. Otherwise, store them
with [RenderPass#setStoreColor](https://api.playcanvas.com/engine/classes/RenderPass.md#setstorecolor),
[RenderPass#setStoreDepth](https://api.playcanvas.com/engine/classes/RenderPass.md#setstoredepth) and [RenderPass#setStoreStencil](https://api.playcanvas.com/engine/classes/RenderPass.md#setstorestencil). The mipmaps of color
buffers with mipmaps are generated at this point too, which
[RenderPass#setGenerateMipmaps](https://api.playcanvas.com/engine/classes/RenderPass.md#setgeneratemipmaps) can turn off, for example when another pass draws into
the same render target after this one.

## Writing a pass

A subclass records its draw calls in [FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute), which is called while the GPU
render pass is active. It can also override [RenderPass#postInit](https://api.playcanvas.com/engine/classes/RenderPass.md#postinit) to set up its clears
once the pass is initialized, and [RenderPass#frameUpdate](https://api.playcanvas.com/engine/classes/RenderPass.md#frameupdate) to update the pass before each
frame renders, calling `super.frameUpdate()` to keep the resize. It releases what it created in
[FramePass#destroy](https://api.playcanvas.com/engine/classes/FramePass.md#destroy), calling `super.destroy()`.

## Rendering the pass

A pass renders in one of two ways:

- As part of a frame, for example as a frame pass of a camera, or as a before or after pass of
another pass. The frame graph then calls its [RenderPass#frameUpdate](https://api.playcanvas.com/engine/classes/RenderPass.md#frameupdate), and merges
consecutive passes drawing into the same render target into a single GPU render pass, unless
something separates them, for example a clear of the later pass.
- On its own, by calling [RenderPass#render](https://api.playcanvas.com/engine/classes/RenderPass.md#render), for example to render into a texture each
time its content needs to change. See [FramePass#render](https://api.playcanvas.com/engine/classes/FramePass.md#render) for the steps a frame performs,
which are skipped then.

**Example**

```ts
// A pass drawing a quad with a shader, covering its whole render target
class MyPass extends RenderPass {
    constructor(device, shader) {
        super(device);
        this.quadRender = new QuadRender(shader);
    }

    execute() {
        // the default draw states suit a quad: no blending, and no depth test or write
        this.device.setDrawStates();
        this.quadRender.render();
    }

    destroy() {
        this.quadRender.destroy();
        super.destroy();
    }
}

const renderTarget = new RenderTarget({ colorBuffer: texture, depth: false });
const pass = new MyPass(device, shader);
pass.name = 'MyPass';
pass.init(renderTarget);

// the quad covers the whole target, so clear it instead of loading its content
pass.setClearColor(Color.BLACK);

// draw into the texture
pass.render();

// destroy the pass, and then the render target, which the pass does not own
pass.destroy();
renderTarget.destroy();
```

## Properties

### renderTarget

```ts
renderTarget: RenderTarget | null | undefined
```

The render target the pass draws into, or null when it draws into the back buffer. It is set
by [RenderPass#init](https://api.playcanvas.com/engine/classes/RenderPass.md#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](https://api.playcanvas.com/engine/classes/FramePass.md)
instead. It is undefined until the pass is initialized. The render pass does not own the
render target, and does not destroy it.

## Accessors

### resizeSource

```ts
get resizeSource(): Texture | RenderTarget | null | undefined
set resizeSource(value: Texture | RenderTarget | null | undefined)
```

Gets what the render target of the pass is resized to.

### scaleX

```ts
get scaleX(): number
set scaleX(value: number)
```

Gets the scale factor of the width of the render target. It is 1 while the render target is
not resized.

### scaleY

```ts
get scaleY(): number
set scaleY(value: number)
```

Gets the scale factor of the height of the render target. It is 1 while the render target
is not resized.

## Methods

### frameUpdate

```ts
frameUpdate(): void
```

Resizes the render target to the size of its resize source, scaled by
[RenderPass#scaleX](https://api.playcanvas.com/engine/classes/RenderPass.md#scalex) and [RenderPass#scaleY](https://api.playcanvas.com/engine/classes/RenderPass.md#scaley), while the pass resizes its render
target, see [RenderPass#resizeSource](https://api.playcanvas.com/engine/classes/RenderPass.md#resizesource). See [FramePass#frameUpdate](https://api.playcanvas.com/engine/classes/FramePass.md#frameupdate). Subclasses
overriding it call `super.frameUpdate()` to keep the resize.

### init

```ts
init(renderTarget?: RenderTarget | null, options?: object): void
```

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](https://api.playcanvas.com/engine/classes/RenderPass.md#setclearcolor), [RenderPass#setStoreColor](https://api.playcanvas.com/engine/classes/RenderPass.md#setstorecolor),
[RenderPass#setGenerateMipmaps](https://api.playcanvas.com/engine/classes/RenderPass.md#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](https://api.playcanvas.com/engine/classes/RenderPass.md#rendertarget) directly.

When options are provided, the render target is resized each frame, in
[RenderPass#frameUpdate](https://api.playcanvas.com/engine/classes/RenderPass.md#frameupdate), to the size of the resize source scaled by
[RenderPass#scaleX](https://api.playcanvas.com/engine/classes/RenderPass.md#scalex) and [RenderPass#scaleY](https://api.playcanvas.com/engine/classes/RenderPass.md#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](https://api.playcanvas.com/engine/classes/RenderPass.md#resizesource), scaleX and scaleY instead.

**Parameters**

- `renderTarget` ([`RenderTarget`](https://api.playcanvas.com/engine/classes/RenderTarget.md) `| null`, optional, default `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.
- `options` (`object`, optional): Object for passing optional arguments.
    - `options.resizeSource` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md) `|` [`RenderTarget`](https://api.playcanvas.com/engine/classes/RenderTarget.md) `| null`, optional): The texture or render target whose
      size the render target is resized to, or null for the back buffer. Defaults to null.
    - `options.scaleX` (`number`, optional): The scale factor for the render target width. Defaults to 1.
    - `options.scaleY` (`number`, optional): The scale factor for the render target height. Defaults to 1.

### postInit

```ts
postInit(): void
```

Called at the end of [RenderPass#init](https://api.playcanvas.com/engine/classes/RenderPass.md#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.

### render

```ts
render(): void
```

Renders the pass, as [FramePass#render](https://api.playcanvas.com/engine/classes/FramePass.md#render) describes, starting its GPU render pass right
before [FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute) and ending it right after. A pass the frame graph merged
with a neighboring pass on the same render target shares a single GPU render pass with it.
The pass needs to be initialized with [RenderPass#init](https://api.playcanvas.com/engine/classes/RenderPass.md#init) before it renders.

### setClearColor

```ts
setClearColor(color: Color | undefined, index?: number): void
```

Mark render pass as clearing the full color buffer.

**Parameters**

- `color` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md) `| undefined`): The color to clear to, or undefined to preserve the existing
  content.
- `index` (`number`, optional): The index of the color attachment to modify. When not specified,
  all color attachments are modified.

### setClearDepth

```ts
setClearDepth(depthValue: number | undefined): void
```

Mark render pass as clearing the full depth buffer.

**Parameters**

- `depthValue` (`number | undefined`): The depth value to clear to, or undefined to preserve
  the existing content.

### setClearStencil

```ts
setClearStencil(stencilValue: number | undefined): void
```

Mark render pass as clearing the full stencil buffer.

**Parameters**

- `stencilValue` (`number | undefined`): The stencil value to clear to, or undefined to
  preserve the existing content.

### setGenerateMipmaps

```ts
setGenerateMipmaps(generate: boolean, index?: number): void
```

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](https://api.playcanvas.com/engine/classes/RenderTarget.md#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](https://api.playcanvas.com/engine/classes/RenderPass.md#init) resets it.

**Parameters**

- `generate` (`boolean`): True to generate the mipmaps of the color buffers which support
  them, false to not generate them.
- `index` (`number`, optional): The index of the color attachment to modify. When not specified,
  all color attachments are modified.

### setStoreColor

```ts
setStoreColor(store: boolean, index?: number): void
```

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](https://api.playcanvas.com/engine/classes/FramePass.md#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](https://api.playcanvas.com/engine/classes/RenderPass.md#init) resets it.

**Parameters**

- `store` (`boolean`): True to store the attachments, false to discard them.
- `index` (`number`, optional): The index of the color attachment to modify. When not specified,
  all color attachments are modified.

### setStoreDepth

```ts
setStoreDepth(store: boolean): void
```

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](https://api.playcanvas.com/engine/classes/FramePass.md#render). Set it once the pass is
initialized, as [RenderPass#init](https://api.playcanvas.com/engine/classes/RenderPass.md#init) resets it.

**Parameters**

- `store` (`boolean`): True to store the depth, false to discard it.

### setStoreStencil

```ts
setStoreStencil(store: boolean): void
```

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](https://api.playcanvas.com/engine/classes/FramePass.md#render). Set it once the pass is
initialized, as [RenderPass#init](https://api.playcanvas.com/engine/classes/RenderPass.md#init) resets it.

**Parameters**

- `store` (`boolean`): True to store the stencil, false to discard it.

## Inherited from [FramePass](https://api.playcanvas.com/engine/classes/FramePass.md)

- `new RenderPass(graphicsDevice: GraphicsDevice)`
- `afterPasses: FramePass[] = []`
- `beforePasses: FramePass[] = []`
- `device: GraphicsDevice`
- `executeEnabled: boolean = true`
- `onAfter: ((pass: FramePass) => void) | null = null`
- `onBefore: ((pass: FramePass) => void) | null = null`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `get name(): string` · `set name(value: string)`
- `after(): void`
- `before(): void`
- `destroy(): void`
- `execute(): void`
- `onDisable(): void`
- `onEnable(): void`
