# FramePass

Class · category: Graphics

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

A frame pass represents a node in the frame graph. It encapsulates a unit of work that
executes during frame rendering. Subclasses include [RenderPass](https://api.playcanvas.com/engine/classes/RenderPass.md) for GPU render passes
with render targets, and non-rendering passes for compute dispatches or other tasks.

In each frame a pass is part of, for example as a frame pass of a camera, or as a before or
after pass of another pass, it goes through these steps:

- While the frame is built, before anything renders: [FramePass#frameUpdate](https://api.playcanvas.com/engine/classes/FramePass.md#frameupdate) is called,
and then the [FramePass#beforePasses](https://api.playcanvas.com/engine/classes/FramePass.md#beforepasses) and [FramePass#afterPasses](https://api.playcanvas.com/engine/classes/FramePass.md#afterpasses) of the pass are
added to the frame around it. A disabled pass is skipped, together with those passes.
- While the frame renders: [FramePass#before](https://api.playcanvas.com/engine/classes/FramePass.md#before) and [FramePass#onBefore](https://api.playcanvas.com/engine/classes/FramePass.md#onbefore) are called,
then [FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute) while [FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is true, and then
[FramePass#after](https://api.playcanvas.com/engine/classes/FramePass.md#after) and [FramePass#onAfter](https://api.playcanvas.com/engine/classes/FramePass.md#onafter).

A pass can also be rendered on its own, outside of a frame, by calling [FramePass#render](https://api.playcanvas.com/engine/classes/FramePass.md#render).

## Constructors

### constructor

```ts
new FramePass(graphicsDevice: GraphicsDevice)
```

Creates an instance of the FramePass.

**Parameters**

- `graphicsDevice` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device.

## Properties

### afterPasses

```ts
afterPasses: FramePass[] = []
```

Frame passes which need to be executed after this pass. This pass does not own them, and
does not destroy them: whoever adds a pass to the list destroys it.

### beforePasses

```ts
beforePasses: FramePass[] = []
```

Frame passes which need to be executed before this pass. The engine does not change this
list, so the passes in it execute every frame this pass executes. This pass does not own
them, and does not destroy them: whoever adds a pass to the list destroys it.

### device

```ts
device: GraphicsDevice
```

The graphics device.

### executeEnabled

```ts
executeEnabled: boolean = true
```

True if the frame pass is enabled and execute function will be called. Note that before and
after functions are called regardless of this flag. Set it before the frame renders, at the
latest in frameUpdate, as the frame graph decides which passes to merge from it.

### onAfter

```ts
onAfter: ((pass: FramePass) => void) | null = null
```

Called when the pass renders, right after it executes: for a render pass once its GPU render
pass has ended, and after [FramePass#after](https://api.playcanvas.com/engine/classes/FramePass.md#after). The results the pass writes can be read
back here, as a read records its copy when it is requested, and so right after the pass.
Reads should not be immediate, as that submits the work of the frame recorded so far. Like
after, it is called even if [FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is false, but not when the pass
is disabled. A render pass with this callback is not merged with the pass after it into a
single GPU render pass, so the callback runs outside of one.

### onBefore

```ts
onBefore: ((pass: FramePass) => void) | null = null
```

Called when the pass renders, right before it executes: after [FramePass#before](https://api.playcanvas.com/engine/classes/FramePass.md#before), and
for a render pass before its GPU render pass starts. Work recorded here, such as setting the
parameters of the pass, or clearing a buffer it writes to, executes right before the pass.
Like before, it is called even if [FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is false, but not when the
pass is disabled. A render pass with this callback is not merged with the pass before it into
a single GPU render pass, so the callback runs outside of one.

## Accessors

### enabled

```ts
get enabled(): boolean
set enabled(value: boolean)
```

Gets whether the frame pass is enabled.

### name

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

Gets the name of the pass.

## Methods

### after

```ts
after(): void
```

Called while the pass renders, after [FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute). It is called even when
[FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is false and the pass did not execute, so an override
using the results of the execution can skip that work while executeEnabled is false.

### before

```ts
before(): void
```

Called while the pass renders, before [FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute). It is called even when
[FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is false and the pass does not execute, so an override
preparing only for the execution can skip that work while executeEnabled is false.

### destroy

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

Releases the resources the pass created. A pass owns only what it creates: it does not
destroy its [FramePass#beforePasses](https://api.playcanvas.com/engine/classes/FramePass.md#beforepasses) and [FramePass#afterPasses](https://api.playcanvas.com/engine/classes/FramePass.md#afterpasses), which are
destroyed by whoever added them. The code which creates a pass destroys it, once, and the
pass is not used after that - in debug builds, adding a destroyed pass to a frame reports an
error. Subclasses releasing their own resources call `super.destroy()`.

### execute

```ts
execute(): void
```

Records the work of the pass. Called while the frame renders, between
[FramePass#before](https://api.playcanvas.com/engine/classes/FramePass.md#before) and [FramePass#after](https://api.playcanvas.com/engine/classes/FramePass.md#after), and only while
[FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is true. For a [RenderPass](https://api.playcanvas.com/engine/classes/RenderPass.md), it runs inside the GPU
render pass, which starts right before it.

### frameUpdate

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

Called each frame the pass is added to the frame, while the frame is built and before
anything renders, and before its [FramePass#beforePasses](https://api.playcanvas.com/engine/classes/FramePass.md#beforepasses) and
[FramePass#afterPasses](https://api.playcanvas.com/engine/classes/FramePass.md#afterpasses) are added. Override to update the pass for the frame, for
example to resize its render targets, to set the textures it reads, to add or remove its
before and after passes and enable or disable them, or to set its
[FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled). It cannot disable the pass itself. It is not called for a
disabled pass, nor when the pass is rendered on its own with [FramePass#render](https://api.playcanvas.com/engine/classes/FramePass.md#render).

### onDisable

```ts
onDisable(): void
```

Called when the pass is disabled, by setting [FramePass#enabled](https://api.playcanvas.com/engine/classes/FramePass.md#enabled) to false while it is
true. Override to release what the pass does not need while it is disabled, such as its
render targets.

### onEnable

```ts
onEnable(): void
```

Called when the pass is enabled, by setting [FramePass#enabled](https://api.playcanvas.com/engine/classes/FramePass.md#enabled) to true while it is
false. Override to recreate what [FramePass#onDisable](https://api.playcanvas.com/engine/classes/FramePass.md#ondisable) released.

### render

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

Renders the pass: calls [FramePass#before](https://api.playcanvas.com/engine/classes/FramePass.md#before) and [FramePass#onBefore](https://api.playcanvas.com/engine/classes/FramePass.md#onbefore), then
[FramePass#execute](https://api.playcanvas.com/engine/classes/FramePass.md#execute) while [FramePass#executeEnabled](https://api.playcanvas.com/engine/classes/FramePass.md#executeenabled) is true, and then
[FramePass#after](https://api.playcanvas.com/engine/classes/FramePass.md#after) and [FramePass#onAfter](https://api.playcanvas.com/engine/classes/FramePass.md#onafter). It does nothing while the pass is
disabled. The frame graph calls this for each pass in the frame.

It can also be called directly, to render the pass on its own, outside of a frame, for
example to render into a texture once. The pass is then not prepared the way a frame
prepares it: its [FramePass#frameUpdate](https://api.playcanvas.com/engine/classes/FramePass.md#frameupdate) is not called, its before and after passes do
not render, and the frame graph does not merge it with neighboring passes, nor ask it to
store the attachments a later pass loads. A [RenderPass](https://api.playcanvas.com/engine/classes/RenderPass.md) rendered on its own keeps the
textures of its render target: its color buffers, resolved when multisampled, and its depth
buffer texture. It does not keep the samples of a multisampled attachment, the stencil, or a
depth buffer its render target creates internally, unless it is set to 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).
