# CameraFrameEffect

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/64089771243fe28a9b9d2b4de538b99b07c75097/src/extras/render-passes/camera-frame-effect.js#L274

Base class of an effect registered with a [CameraFrame](https://api.playcanvas.com/engine/classes/CameraFrame.md). An effect is constructed with the
graphics device, its id and its declarations - the compose slot it applies at and its shader
chunk - and exposes its parameters as fields. Declarations are fixed for the life of the effect;
anything that depends on a parameter is a getter instead, like [CameraFrameEffect#active](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#active).

An effect contributes to the composition: you supply its shader chunk (GLSL and WGSL) and write
its entry function under a conventional name, `apply<Id>`. The camera frame generates the call to
that function at the effect's slot, and rebuilds the compose shader when an effect becomes active
or inactive, or changes one of its defines. The chunk is only included while the effect is
active, so it needs no `#ifdef` guard of its own - defines are for an effect's own variants, set
with [CameraFrameEffect#setDefine](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#setdefine). The chunk can be overridden by name like the built-in
chunks: a chunk set in [ShaderChunks](https://api.playcanvas.com/engine/classes/ShaderChunks.md) under `compose<Id>PS` replaces the effect's own
source. `<ID>` (the id in upper snake case) is defined while the effect is active, should
another chunk need to know. Each debug view `name` the effect lists is backed the same way as
the entry function, by a `debug<Name>()` function in the chunk.

All effects registered to a compose slot are called in registration order from within the single
compose pass, so contributing to the composition never costs an additional full-screen pass.

An effect can also own passes, for work the composition cannot do in a single sample per pixel,
such as a blur at a lower resolution or rendering into the scene. It creates them in
[CameraFrameEffect#createPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#createpasses), from the frame resources it
[CameraFrameEffect#requires](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#requires), adding each to the stage of the frame it runs at, and its
chunk reads what they render through the uniforms it sets with
[CameraFrameEffect#setUniform](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#setuniform). An effect whose passes resolve the scene, such as an
anti-aliasing, replaces the scene color the rest of the frame reads in
[CameraFrameEffect#resolveScene](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#resolvescene). An effect owning passes does not need a compose slot.

Every chunk can read what the composition provides: the scene color, `sceneTexture`, and
`sceneTextureSize` - the width, height, 1 / width and 1 / height of the scene texture. Use the
size for anything which depends on the resolution, such as texel offsets, pixel sizes or the
aspect ratio, as it is always current for the camera being drawn. An effect requiring the scene
depth, see [CameraFrameEffect#requires](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#requires), can also read it with `getLinearScreenDepth(uv)`.

Like the rest of the camera frame, an effect is configured when [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update) is
called: changes to its parameters, and adding or removing it, take effect at the next update,
and every frame rendered after it uses exactly what the update applied.

Lifetime:

- **Construct** - pass the device, the id and the declarations to the constructor; declare the
  parameters as fields. Resources the effect keeps for its whole life - a lookup texture, a noise
  texture - are created here, and fixed defines can be set with
  [CameraFrameEffect#setDefine](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#setdefine).
- **On [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update), while [CameraFrameEffect#active](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#active)** - an effect owning
  passes creates them in [CameraFrameEffect#createPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#createpasses) when the camera frame builds its
  passes: the first time, and again each time it rebuilds them, after
  [CameraFrameEffect#destroyPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#destroypasses) released them - when the
  [CameraFrameEffect#buildKey](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#buildkey) or the [CameraFrameEffect#requires](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#requires) of an effect
  owning passes change, or the options of the camera frame do. Then
  [CameraFrameEffect#update](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#update) applies the parameters: the values of the uniforms with
  [CameraFrameEffect#setUniform](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#setuniform), and the defines that depend on them.
- **Each frame while it takes part** - an effect whose passes resolve the scene hands them the
  scene color in [CameraFrameEffect#resolveScene](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#resolvescene), and then
  [CameraFrameEffect#frameUpdate](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#frameupdate) is called with the values of the frame being prepared,
  for the few effects which depend on them. Most effects need neither.
- **Destroy** - [CameraFrameEffect#destroy](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#destroy) releases what the constructor created, and the
  passes. Whoever constructs an effect destroys it: the camera frame destroys its built-in
  effects, and an effect you add is yours to destroy.

**Example**

```ts
// A tint applied in display space, after tone mapping. The chunk declares its uniform and the
// entry function applyTint, which the composition calls as `result = applyTint(result, uv)`.
class TintEffect extends CameraFrameEffect {
    color = new Color(1, 0.9, 0.8);

    tintColor = new Float32Array(3);

    constructor(device) {
        super(device, 'tint', {
            slot: COMPOSESLOT_LDR,
            glsl: `
                uniform vec3 tintColor;
                vec3 applyTint(vec3 color, vec2 uv) {
                    return color * tintColor;
                }
            `,
            wgsl: `
                uniform tintColor: vec3f;
                fn applyTint(color: vec3f, uv: vec2f) -> vec3f {
                    return color * uniform.tintColor;
                }
            `
        });
    }

    update() {
        this.tintColor[0] = this.color.r;
        this.tintColor[1] = this.color.g;
        this.tintColor[2] = this.color.b;
        this.setUniform('tintColor', this.tintColor);
    }
}

cameraFrame.addEffect(new TintEffect(app.graphicsDevice));
cameraFrame.update();

// The same effect without a class, for effects driven by data
const tint = new CameraFrameEffect(app.graphicsDevice, 'tint', { slot: COMPOSESLOT_LDR, glsl, wgsl });
tint.setUniform('tintColor', new Float32Array([1, 0.9, 0.8]));
cameraFrame.addEffect(tint);
cameraFrame.update();
```

**Example**

```ts
// A glow owning a pass: the pass blurs the half resolution scene into a render target of the
// effect, which the chunk adds to the scene. GlowPass is a RenderPassShaderQuad blurring the
// texture it is given, see RenderPassShaderQuad.
class GlowEffect extends CameraFrameEffect {
    constructor(device) {
        super(device, 'glow', {
            slot: COMPOSESLOT_HDR,
            requires: [FRAMERESOURCE_SCENECOLORHALF],
            glsl: `
                uniform sampler2D glowTexture;
                vec3 applyGlow(vec3 color, vec2 uv) {
                    return color + texture2DLod(glowTexture, uv, 0.0).rgb;
                }
            `,
            wgsl: `
                var glowTexture: texture_2d<f32>;
                var glowTextureSampler: sampler;
                fn applyGlow(color: vec3f, uv: vec2f) -> vec3f {
                    return color + textureSampleLevel(glowTexture, glowTextureSampler, uv, 0.0).rgb;
                }
            `
        });
    }

    createPasses(resources, passes) {
        // the render target of the pass is resized to the half resolution scene every frame
        const { sceneColorHalf } = resources;
        this._target = new RenderTarget({
            colorBuffer: new Texture(this.device, {
                name: 'GlowTexture',
                width: 1,
                height: 1,
                format: this.cameraFrame.hdrFormat,
                mipmaps: false
            }),
            depth: false
        });

        this._pass = new GlowPass(this.device, sceneColorHalf);
        this._pass.init(this._target, { resizeSource: sceneColorHalf });
        passes.postResolve.push(this._pass);

        this.setUniform('glowTexture', this._target.colorBuffer);
    }

    destroyPasses() {
        this._pass?.destroy();
        this._pass = null;
        this._target?.destroyTextureBuffers();
        this._target?.destroy();
        this._target = null;
    }
}
```

## Constructors

### constructor

```ts
new CameraFrameEffect(device: GraphicsDevice, id: string, options?: object)
```

Creates a new effect.

**Parameters**

- `device` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device.
- `id` (`string`): The identifier of the effect, unique among the effects of a camera frame.
  The names of the chunk, its entry function and its define are derived from it.
- `options` (`object`, optional, default `{}`): The declarations of the effect. All are optional.
    - `options.chunkName` (`string`, optional): The name the compose chunk can be overridden under, when
      it should differ from the derived `compose<Id>PS`.
    - `options.debugViews` (`string[]`, optional): The names of the debug views the chunk provides. Each
      view `name` requires the chunk to declare a `vec3 debug<Name>()` function, and is available
      while the effect is active.
    - `options.entryPoint` (`string`, optional): The name of the function the composition calls, when it
      should differ from the derived `apply<Id>`.
    - `options.glsl` (`string`, optional): The GLSL source of the compose chunk.
    - `options.requires` (`string[]`, optional): The frame resources the effect needs, the
      FRAMERESOURCE_* constants, see [CameraFrameEffect#requires](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#requires).
    - `options.slot` (`string`, optional): The compose slot the entry function is called at, one of the
      COMPOSESLOT_* constants. Omit for an effect that does not take part in the composition, for
      example one that only owns passes.
    - `options.wgsl` (`string`, optional): The WGSL source of the compose chunk.

## Properties

### cameraFrame

```ts
cameraFrame: CameraFrame | null = null
```

The camera frame the effect is registered with, or null.

### device

```ts
device: GraphicsDevice
```

The graphics device.

### enabled

```ts
enabled: boolean = true
```

Whether the effect is enabled. An effect can additionally disable itself from its own
parameters, see [CameraFrameEffect#active](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#active).

## Accessors

### active

```ts
get active(): boolean
```

Gets whether the effect contributes to the frame. Defaults to [CameraFrameEffect#enabled](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#enabled).
Effects gated on a parameter - a zero intensity, a missing texture - override this.

### cameraExposureScale

```ts
get cameraExposureScale(): number
```

Gets the scale the effect applies to the exposure of the camera this frame, multiplying the
exposure of the scene, or of the physical camera with physical units - for effects adapting
the exposure to what the camera sees. Read every frame while the effect takes part, after
[CameraFrameEffect#frameUpdate](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#frameupdate); the camera frame applies the product of the scales of
the effects taking part, and the camera renders with its own exposure again once none does.
Defaults to 1.

```javascript
// an effect brightening the image by one stop
get cameraExposureScale() {
    return 2;
}
```

### chunkName

```ts
get chunkName(): string
```

Gets the name the compose chunk can be overridden under in [ShaderChunks](https://api.playcanvas.com/engine/classes/ShaderChunks.md), the same
way as the built-in chunks. Derived from the id as `compose<Id>PS` unless given.

### debugViews

```ts
get debugViews(): string[]
```

Gets the names of the debug views the chunk provides.

### defineName

```ts
get defineName(): string
```

Gets the define set on the compose shader while the effect is active: the id in upper snake
case, `colorEnhance` giving `COLOR_ENHANCE`.

### entryPoint

```ts
get entryPoint(): string
```

Gets the name of the function the composition calls at the effect's slot. Derived from the
id as `apply<Id>` unless given. The signature depends on the slot: color slots take
`(vec3 color, vec2 uv)` and return the color, [COMPOSESLOT_SCENE](https://api.playcanvas.com/engine/variables/COMPOSESLOT_SCENE.md) takes and returns a
`vec4`.

### glsl

```ts
get glsl(): string | null
```

Gets the GLSL source of the compose chunk, or null when the effect has none.

### id

```ts
get id(): string
```

Gets the identifier of the effect.

### requires

```ts
get requires(): string[]
```

Gets the frame resources the effect needs, the FRAMERESOURCE_* constants - for its passes,
or for its compose chunk, such as the scene depth. The camera frame provides them while the
effect is active. Requirements which depend on the device are computed when constructing the
effect; override this as a getter when they depend on a parameter, and the camera frame
provides what it returns from the next [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update).

### slot

```ts
get slot(): string | null
```

Gets the compose slot the entry function is called at, or null for an effect that does not
take part in the composition.

### wgsl

```ts
get wgsl(): string | null
```

Gets the WGSL source of the compose chunk, or null when the effect has none.

## Methods

### buildKey

```ts
buildKey(): string
```

Returns a string which changes whenever the effect's passes need recreating - the parameters
which alter the pass graph rather than just its uniforms. Read on each
[CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update) while the effect is active: when it differs from the previous
update, the camera frame releases the passes with [CameraFrameEffect#destroyPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#destroypasses) and
creates them again with [CameraFrameEffect#createPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#createpasses). Parameters the passes pick up
in [CameraFrameEffect#update](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#update) do not belong in it. Effects without passes do not
implement this.

```javascript
buildKey() {
    // a pass more renders at the high quality
    return `${this.highQuality}`;
}
```

**Returns** `string`: The key.

### createPasses

```ts
createPasses(resources: CameraFrameEffectResources, passes: CameraFrameEffectPasses): void
```

Creates the passes the effect owns, when it has any. Called by [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update)
when it builds the frame graph, for an active effect registered with the camera frame.
Implementing it is what makes an effect own passes. The effect adds each pass to the array of
the stage it runs at, in execution order - one effect can run passes at several stages:

```javascript
createPasses(resources, passes) {
    this._pass = new MyPass(this.device, resources.sceneColorHalf);
    passes.postResolve.push(this._pass);
}
```

The effect owns the passes it creates: it releases them in
[CameraFrameEffect#destroyPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#destroypasses).

The resources are stable: each texture stays the same object until the passes are
destroyed, so it can be handed to the passes once, here. Its size can change, as render
targets resize with the canvas, so its dimensions must not be cached. Values which change
from frame to frame, the resolved scene color among them, are never resources - they are
handed to [CameraFrameEffect#frameUpdate](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#frameupdate) instead.

**Parameters**

- `resources` ([`CameraFrameEffectResources`](https://api.playcanvas.com/engine/interfaces/CameraFrameEffectResources.md)): The frame resources the effect requires.
- `passes` ([`CameraFrameEffectPasses`](https://api.playcanvas.com/engine/interfaces/CameraFrameEffectPasses.md)): An empty array for each stage of the frame, to add
  the passes to.

### destroy

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

Destroys the effect, removing it from its camera frame if it is still registered and
releasing everything it owns, the passes it created included. Subclasses which create
resources in their constructor release them in an override, calling `super.destroy()`. The
removal takes effect for the frames rendered after the next [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update), which
is due before the next frame renders.

### destroyPasses

```ts
destroyPasses(): void
```

Destroys the passes and any resources [CameraFrameEffect#createPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#createpasses) created.

It is also called when the effect has no passes. Each time the camera frame rebuilds the
frame graph, it calls this on every registered effect implementing
[CameraFrameEffect#createPasses](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#createpasses), including inactive effects that never created any. [CameraFrameEffect#destroy](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#destroy) calls it too, including
after the camera frame has already released the passes. So destroy only what exists, and
clear the references:

```javascript
destroyPasses() {
    this._pass?.destroy();
    this._pass = null;
}
```

### frameUpdate

```ts
frameUpdate(frame: CameraFrameEffectContext): void
```

Called every frame while the effect takes part in the frame, while the frame is being
prepared and before any pass renders, with the values of that frame. Most effects do not
need it: their configuration belongs in [CameraFrameEffect#update](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#update), which runs only
when the camera frame is updated. Values derived from the resolution, which can change
without an update, are computed here from the sizes in the frame, or in the shader from
`sceneTextureSize`. Anything which changes over time advances here by the time of the frame,
its `dt`.

**Parameters**

- `frame` ([`CameraFrameEffectContext`](https://api.playcanvas.com/engine/interfaces/CameraFrameEffectContext.md)): The values of this frame. Read them during this
  call only.

### getChunk

```ts
getChunk(shaderLanguage: string): string | null
```

Returns the compose chunk source for a shader language.

**Parameters**

- `shaderLanguage` (`string`): SHADERLANGUAGE_GLSL or SHADERLANGUAGE_WGSL.

**Returns** `string | null`: The source, or null when the effect has no chunk.

### resolveScene

```ts
resolveScene(scene: CameraFrameEffectScene): void
```

Resolves the scene, for an effect whose passes run at the resolve stage - see
[CameraFrameEffectPasses](https://api.playcanvas.com/engine/interfaces/CameraFrameEffectPasses.md). Called every frame while the effect's passes take part in
the frame, before any pass renders and before [CameraFrameEffect#frameUpdate](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#frameupdate) is called
on any effect, in the order the effects are registered. The effect hands its passes the scene
color the effects before it resolved, and replaces it with the texture they render to this
frame, which the effects after it, the half resolution copy of the scene and the composition
then read:

```javascript
resolveScene(scene) {
    this._pass.setSourceTexture(scene.texture);
    scene.texture = this._pass.outputTexture;
}
```

An effect resolving the scene to another resolution also sets the width and the height. The
default implementation leaves the scene unchanged.

**Parameters**

- `scene` ([`CameraFrameEffectScene`](https://api.playcanvas.com/engine/interfaces/CameraFrameEffectScene.md)): The scene being resolved.

### setDefine

```ts
setDefine(name: string, value: any): void
```

Sets a define on the compose shader. The define persists until changed, so fixed defines
can be set once in the constructor and those depending on the parameters from
[CameraFrameEffect#update](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#update). A value of false, null or undefined removes it. Changing a
define rebuilds the compose shader.

**Parameters**

- `name` (`string`): The define name.
- `value` (`any`): The value.

### setUniform

```ts
setUniform(name: string, value: number | number[] | ArrayBufferView<ArrayBufferLike> | Texture): void
```

Sets the value of a uniform the effect's shader chunk reads. Like a material parameter, the
value is stored by reference, so an array or a texture can be updated in place. Set the
values in [CameraFrameEffect#update](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#update), or in [CameraFrameEffect#frameUpdate](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#frameupdate) for
a value which changes every frame.

**Parameters**

- `name` (`string`): The name of the uniform, as declared in the chunk.
- `value` (`number | number[] | ArrayBufferView<ArrayBufferLike> |` [`Texture`](https://api.playcanvas.com/engine/classes/Texture.md)): The value.

### update

```ts
update(): void
```

Applies the effect's parameters. Called by [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update) while the effect is
active: set the uniform values with [CameraFrameEffect#setUniform](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#setuniform) here, and the
defines which depend on the parameters.
Everything it sets is what the frames rendered until the next update use.
