/** * The context handed to {@link CameraFrameEffect#frameUpdate} by the camera frame the effect is * registered with: the values of the frame being prepared. Valid only for the duration of that * call - the object is reused, and its contents change from frame to frame. * * The texture is this frame's, but its size is final only once the frame's passes are updated, * after that call - when the canvas or the render target scale changes, it still has the size of * the previous frame. Use the sizes in the context instead of the texture's own. */ export type CameraFrameEffectContext = { /** * - The scene color the composition reads this frame, once it is * resolved: the output of the temporal anti-aliasing when it is enabled, which alternates between * two textures from frame to frame, and the scene render target's color otherwise. */ sceneTexture: Texture; /** * - The width of the scene texture this frame, in pixels. It is the * width the scene renders at, unless the scene is resolved to another resolution, as the temporal * anti-aliasing does when it upscales. */ sceneWidth: number; /** * - The height of the scene texture this frame, in pixels. */ sceneHeight: number; /** * - The width the scene renders at this frame, in pixels - the size * of the scene render target, which the passes rendering into the scene have. */ renderWidth: number; /** * - The height the scene renders at this frame, in pixels. */ renderHeight: number; /** * - The time since the camera frame last rendered, in seconds - the time the * application advanced by in its updates since, as scripts are updated by: scaled by * {@link AppBase#timeScale} and limited by {@link AppBase#maxDeltaTime} per update. It is 0 for a * frame rendered again without the application updating, and while the application is paused. */ dt: number; }; /** * The scene being resolved, handed to {@link CameraFrameEffect#resolveScene} by the camera frame * every frame, to each effect in turn in the order they are registered: the scene color the * effects before it resolved, which the effect replaces with its own output. One object, reused * from frame to frame. */ export type CameraFrameEffectScene = { /** * - The scene color. An effect resolving the scene reads this as its * input, and sets it to the texture its passes render to this frame. */ texture: Texture; /** * - The width of the scene color this frame, in pixels. Its texture can * still have the size of the previous frame - see {@link CameraFrameEffectContext}. An effect * resolving the scene to another resolution sets this, and the height, to that resolution. */ width: number; /** * - The height of the scene color this frame, in pixels. */ height: number; }; /** * The scene depth handed to {@link CameraFrameEffect#createPasses}, for an effect requiring * FRAMERESOURCE_DEPTH or FRAMERESOURCE_PREPASSDEPTH. How the depth is stored depends on what * renders it, so shaders read it with the `getLinearScreenDepth` function of the `screenDepthPS` * chunk, given the defines describing the storage, rather than sampling the texture. */ export type CameraFrameEffectDepth = { /** * - The texture the depth is rendered to, the size of the scene - for * sizing render targets. */ texture: Texture; /** * - The defines a shader reading the depth with * `getLinearScreenDepth` needs. Shared by the effects, so copy them rather than change them. */ defines: Map; /** * - A key identifying those defines, to add to the unique name of such a * shader, so that differently stored depths do not share a compiled shader. */ key: string; }; /** * The frame resources handed to {@link CameraFrameEffect#createPasses}: those the effect lists in * {@link CameraFrameEffect#requires}, under the values of the FRAMERESOURCE_* constants. Each * stays the same object for the life of the passes, and the textures are resized with the scene. */ export type CameraFrameEffectResources = { /** * - The scene depth, see FRAMERESOURCE_DEPTH. */ depth?: CameraFrameEffectDepth; /** * - The scene depth rendered by a prepass, see * FRAMERESOURCE_PREPASSDEPTH. */ prepassDepth?: CameraFrameEffectDepth; /** * - The half resolution scene color, see * FRAMERESOURCE_SCENECOLORHALF. */ sceneColorHalf?: Texture; /** * - The handle of the mipmapped copy of the opaque * scene color, see FRAMERESOURCE_SCENECOLORGRAB. The copy is a new texture whenever the scene * resizes, which the handle always identifies, and it is published to the `uSceneColorMap` * texture the shaders sample before the passes at the postOpaque stage run. */ sceneColorGrab?: SceneColorMapHandle; /** * - The scene render target, see FRAMERESOURCE_SCENETARGET. */ sceneTarget?: RenderTarget; }; /** * The stages of the frame an effect's passes run at, handed to * {@link CameraFrameEffect#createPasses}, each an empty array the effect adds its passes for that * stage to, in execution order. */ export type CameraFrameEffectPasses = { /** * - Passes running before the scene renders, after the prepass * when one renders - for output the scene's materials read. */ preScene: FramePass[]; /** * - Passes running after the opaque geometry, the skybox and the * copy of the scene color, before the transparent geometry - for passes rendering into the scene * which the transparent geometry renders over. */ postOpaque: FramePass[]; /** * - Passes running after the scene, before it is resolved - for * passes rendering into the scene. */ postScene: FramePass[]; /** * - Passes resolving the scene, such as the temporal anti-aliasing: * they read the scene color and render a new one, which the rest of the frame reads in its place. * The effect hands over the texture they render to in {@link CameraFrameEffect#resolveScene}. */ resolve: FramePass[]; /** * - Passes running after the scene is resolved and its half * resolution copy is made, before the composition. */ postResolve: FramePass[]; }; /** * Base class of an effect registered with a {@link 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 {@link 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`. 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 {@link CameraFrameEffect#setDefine}. The chunk can be overridden by name like the built-in * chunks: a chunk set in {@link ShaderChunks} under `composePS` replaces the effect's own * source. `` (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()` 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 * {@link CameraFrameEffect#createPasses}, from the frame resources it * {@link CameraFrameEffect#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 * {@link CameraFrameEffect#setUniform}. An effect whose passes resolve the scene, such as an * anti-aliasing, replaces the scene color the rest of the frame reads in * {@link CameraFrameEffect#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 {@link CameraFrameEffect#requires}, can also read it with `getLinearScreenDepth(uv)`. * * Like the rest of the camera frame, an effect is configured when {@link 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 * {@link CameraFrameEffect#setDefine}. * - **On {@link CameraFrame#update}, while {@link CameraFrameEffect#active}** - an effect owning * passes creates them in {@link CameraFrameEffect#createPasses} when the camera frame builds its * passes: the first time, and again each time it rebuilds them, after * {@link CameraFrameEffect#destroyPasses} released them - when the * {@link CameraFrameEffect#buildKey} or the {@link CameraFrameEffect#requires} of an effect * owning passes change, or the options of the camera frame do. Then * {@link CameraFrameEffect#update} applies the parameters: the values of the uniforms with * {@link CameraFrameEffect#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 {@link CameraFrameEffect#resolveScene}, and then * {@link CameraFrameEffect#frameUpdate} is called with the values of the frame being prepared, * for the few effects which depend on them. Most effects need neither. * - **Destroy** - {@link CameraFrameEffect#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 * // 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 * // 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; * 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; * } * } * @category Graphics */ export class CameraFrameEffect { /** * Creates a new effect. * * @param {GraphicsDevice} device - The graphics device. * @param {string} id - 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. * @param {object} [options] - The declarations of the effect. All are optional. * @param {string} [options.slot] - 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. * @param {string} [options.glsl] - The GLSL source of the compose chunk. * @param {string} [options.wgsl] - The WGSL source of the compose chunk. * @param {string[]} [options.debugViews] - The names of the debug views the chunk provides. Each * view `name` requires the chunk to declare a `vec3 debug()` function, and is available * while the effect is active. * @param {string} [options.chunkName] - The name the compose chunk can be overridden under, when * it should differ from the derived `composePS`. * @param {string} [options.entryPoint] - The name of the function the composition calls, when it * should differ from the derived `apply`. * @param {string[]} [options.requires] - The frame resources the effect needs, the * FRAMERESOURCE_* constants, see {@link CameraFrameEffect#requires}. */ constructor(device: GraphicsDevice, id: string, options?: { slot?: string; glsl?: string; wgsl?: string; debugViews?: string[]; chunkName?: string; entryPoint?: string; requires?: string[]; }); /** * The graphics device. * * @type {GraphicsDevice} */ device: GraphicsDevice; /** * Whether the effect is enabled. An effect can additionally disable itself from its own * parameters, see {@link CameraFrameEffect#active}. * * @type {boolean} */ enabled: boolean; /** * The camera frame the effect is registered with, or null. * * @type {CameraFrame|null} */ cameraFrame: CameraFrame | null; /** * A number unique to this instance, telling apart effects constructed with the same id - such * as an effect replaced by a new instance of it. * * @type {number} * @ignore */ _uid: number; /** @private */ private _id; /** @private */ private _slot; /** @private */ private _glsl; /** @private */ private _wgsl; /** @private */ private _debugViews; /** @private */ private _chunkName; /** @private */ private _entryPoint; /** @private */ private _requires; /** * The compose defines the effect has set, see {@link CameraFrameEffect#setDefine}. * * @type {Map} * @ignore */ _defines: Map; /** * Incremented when the defines change, so the composition can detect it cheaply. * * @type {number} * @ignore */ _definesVersion: number; /** * The uniform values set with {@link CameraFrameEffect#setUniform}, bound right before the * compose pass renders. * * @type {Map} * @private */ private _uniforms; /** * Gets the identifier of the effect. * * @type {string} */ get id(): string; /** * Gets the compose slot the entry function is called at, or null for an effect that does not * take part in the composition. * * @type {string|null} */ get slot(): string | null; /** * Gets the GLSL source of the compose chunk, or null when the effect has none. * * @type {string|null} */ get glsl(): string | null; /** * Gets the WGSL source of the compose chunk, or null when the effect has none. * * @type {string|null} */ get wgsl(): string | null; /** * Gets the names of the debug views the chunk provides. * * @type {string[]} */ get debugViews(): string[]; /** * Gets the name the compose chunk can be overridden under in {@link ShaderChunks}, the same * way as the built-in chunks. Derived from the id as `composePS` unless given. * * @type {string} */ get chunkName(): string; /** * Gets the name of the function the composition calls at the effect's slot. Derived from the * id as `apply` unless given. The signature depends on the slot: color slots take * `(vec3 color, vec2 uv)` and return the color, {@link COMPOSESLOT_SCENE} takes and returns a * `vec4`. * * @type {string} */ get entryPoint(): string; /** * Gets the define set on the compose shader while the effect is active: the id in upper snake * case, `colorEnhance` giving `COLOR_ENHANCE`. * * @type {string} */ get defineName(): 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 {@link CameraFrame#update}. * * @type {string[]} */ get requires(): string[]; /** * Whether the effect owns passes, which it does by implementing * {@link CameraFrameEffect#createPasses}. * * @type {boolean} * @ignore */ get _ownsPasses(): boolean; /** * Gets whether the effect contributes to the frame. Defaults to {@link CameraFrameEffect#enabled}. * Effects gated on a parameter - a zero intensity, a missing texture - override this. * * @type {boolean} */ get active(): boolean; /** * Returns the compose chunk source for a shader language. * * @param {string} shaderLanguage - SHADERLANGUAGE_GLSL or SHADERLANGUAGE_WGSL. * @returns {string|null} The source, or null when the effect has no chunk. */ getChunk(shaderLanguage: string): string | null; /** * 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 * {@link CameraFrameEffect#update}. A value of false, null or undefined removes it. Changing a * define rebuilds the compose shader. * * @param {string} name - The define name. * @param {*} value - The value. */ setDefine(name: string, value: any): void; /** * Creates the passes the effect owns, when it has any. Called by {@link CameraFrame#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 * {@link CameraFrameEffect#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 {@link CameraFrameEffect#frameUpdate} instead. * * @param {CameraFrameEffectResources} resources - The frame resources the effect requires. * @param {CameraFrameEffectPasses} passes - An empty array for each stage of the frame, to add * the passes to. */ createPasses(resources: CameraFrameEffectResources, passes: CameraFrameEffectPasses): void; /** * Destroys the passes and any resources {@link CameraFrameEffect#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 * {@link CameraFrameEffect#createPasses}, including inactive effects that never created any. {@link CameraFrameEffect#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; * } * ``` */ destroyPasses(): void; /** * 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 * {@link CameraFrame#update} while the effect is active: when it differs from the previous * update, the camera frame releases the passes with {@link CameraFrameEffect#destroyPasses} and * creates them again with {@link CameraFrameEffect#createPasses}. Parameters the passes pick up * in {@link CameraFrameEffect#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. */ buildKey(): string; /** * Resolves the scene, for an effect whose passes run at the resolve stage - see * {@link CameraFrameEffectPasses}. Called every frame while the effect's passes take part in * the frame, before any pass renders and before {@link CameraFrameEffect#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. * * @param {CameraFrameEffectScene} scene - The scene being resolved. */ resolveScene(scene: CameraFrameEffectScene): void; /** * Gets the intensity of the camera jitter the effect needs while it is active, 0-1 range - the * offset of the projection by a different fraction of a pixel every frame, which effects * accumulating the frames over time rely on. The camera frame applies the largest intensity * any active effect needs. Defaults to 0. * * @type {number} * @ignore */ get cameraJitter(): number; /** * Gets whether the effect renders the sky for the camera while it is active. The camera then * does not render the sky of the scene, which the effect replaces. Defaults to false. * * @type {boolean} * @ignore */ get rendersSky(): boolean; /** * 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 * {@link 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. * * ```javascript * // an effect brightening the image by one stop * get cameraExposureScale() { * return 2; * } * ``` * * @type {number} */ get cameraExposureScale(): number; /** * 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 {@link CameraFrameEffect#update}, or in {@link CameraFrameEffect#frameUpdate} for * a value which changes every frame. * * @param {string} name - The name of the uniform, as declared in the chunk. * @param {number|number[]|ArrayBufferView|Texture} value - The value. */ setUniform(name: string, value: number | number[] | ArrayBufferView | Texture): void; /** * Binds the uniform values, right before the compose pass renders. * * @ignore */ _bindUniforms(): void; /** * Applies the effect's parameters. Called by {@link CameraFrame#update} while the effect is * active: set the uniform values with {@link CameraFrameEffect#setUniform} here, and the * defines which depend on the parameters. * Everything it sets is what the frames rendered until the next update use. */ update(): 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 {@link 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`. * * @param {CameraFrameEffectContext} frame - The values of this frame. Read them during this * call only. */ frameUpdate(frame: CameraFrameEffectContext): 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 {@link CameraFrame#update}, which * is due before the next frame renders. */ destroy(): void; /** * @param {CameraFrame} cameraFrame - The camera frame the effect was added to. * @ignore */ _attach(cameraFrame: CameraFrame): void; /** * @ignore */ _detach(): void; } import type { Texture } from '../../platform/graphics/texture.js'; import type { SceneColorMapHandle } from '../../platform/graphics/scene-color-map-handle.js'; import type { RenderTarget } from '../../platform/graphics/render-target.js'; import type { FramePass } from '../../platform/graphics/frame-pass.js'; import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js'; import type { CameraFrame } from './camera-frame.js';