Engine API Reference - v2.24.0-beta.16
    Preparing search index...

    Class CameraFrameEffect

    Base class of an effect registered with a CameraFrame. 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.

    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. The chunk can be overridden by name like the built-in chunks: a chunk set in ShaderChunks 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 an effect never costs an additional full-screen pass.

    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, can also read it with getLinearScreenDepth(uv).

    Like the rest of the camera frame, an effect is configured when CameraFrame#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.
    • On CameraFrame#update, while CameraFrameEffect#active - CameraFrameEffect#update applies the parameters: the values of the uniforms with CameraFrameEffect#setUniform, and the defines that depend on them.
    • Each frame while it takes part - CameraFrameEffect#frameUpdate is called with the values of the frame being prepared, for the few effects which depend on them. Most effects do not need it.
    • Destroy - CameraFrameEffect#destroy releases what the constructor created. Whoever constructs an effect destroys it: the camera frame destroys its built-in effects, and an effect you add is yours to destroy.
    // 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();

    Hierarchy (View Summary)

    Index
    constructor
    cameraFrame device enabled
    active cameraExposureScale chunkName debugViews defineName entryPoint glsl id requires slot wgsl
    destroy frameUpdate getChunk setDefine setUniform update

    • Creates a new effect.

      Parameters

      • device: GraphicsDevice

        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.

      • Optionaloptions: {
            chunkName?: string;
            debugViews?: string[];
            entryPoint?: string;
            glsl?: string;
            requires?: string[];
            slot?: string;
            wgsl?: string;
        } = {}

        The declarations of the effect. All are optional.

        • OptionalchunkName?: string

          The name the compose chunk can be overridden under, when it should differ from the derived compose<Id>PS.

        • OptionaldebugViews?: string[]

          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.

        • OptionalentryPoint?: string

          The name of the function the composition calls, when it should differ from the derived apply<Id>.

        • Optionalglsl?: string

          The GLSL source of the compose chunk.

        • Optionalrequires?: string[]

          The frame resources the effect needs, the FRAMERESOURCE_* constants, see CameraFrameEffect#requires.

        • Optionalslot?: string

          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.

        • Optionalwgsl?: string

          The WGSL source of the compose chunk.

      Returns CameraFrameEffect

    cameraFrame: CameraFrame | null = null

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

    device: GraphicsDevice

    The graphics device.

    enabled: boolean = true

    Whether the effect is enabled. An effect can additionally disable itself from its own parameters, see CameraFrameEffect#active.

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

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

      Returns number

    • 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: colour slots take (vec3 color, vec2 uv) and return the colour, COMPOSESLOT_SCENE takes and returns a vec4.

      Returns string

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

      Returns string[]

    • 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, which is due before the next frame renders.

      Returns 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, 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

      Returns void

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

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

      Returns 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, or in CameraFrameEffect#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

        The value.

      Returns void

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods