/** * Properties related to scene rendering, encompassing settings that control the rendering resolution, * pixel format, multi-sampling for anti-aliasing, tone-mapping and similar. */ export type Rendering = { /** * - The preferred render formats of the frame buffer, in order of * preference. First format from this list that is supported by the hardware is used. When none of * the formats are supported, {@link PIXELFORMAT_RGBA8} is used, but this automatically disables * bloom effect, which requires HDR format. The list can contain the following formats: * {@link PIXELFORMAT_RG11B10F}, {@link PIXELFORMAT_RGBA16F}, {@link PIXELFORMAT_RGBA32F} and {@link * PIXELFORMAT_RGBA8}. Typically the default option should be used, which prefers the faster formats, * but if higher dynamic range is needed, the list can be adjusted to prefer higher precision formats. * Defaults to [{@link PIXELFORMAT_RG11B10F}, {@link PIXELFORMAT_RGBA16F}, {@link PIXELFORMAT_RGBA32F}]. */ renderFormats: number[]; /** * - Whether the render buffer has a stencil buffer. Defaults to false. */ stencil: boolean; /** * - The scale of the render target, 0.1-1 range. This allows the * scene to be rendered to a lower resolution render target as an optimization. The post-processing * is also applied at this lower resolution. The image is then up-scaled to the full resolution and * any UI rendering that follows is applied at the full resolution. Defaults to 1 which represents * full resolution rendering. */ renderTargetScale: number; /** * - The number of samples of the {@link RenderTarget} used for the scene * rendering, in 1-4 range. Value of 1 disables multisample anti-aliasing, other values enable * anti-aliasing, Typically set to 1 when TAA is used, even though both anti-aliasing options can be * used together at a higher cost. Defaults to 1. */ samples: number; /** * - Whether rendering generates a scene color map. Defaults to false. */ sceneColorMap: boolean; /** * - Whether rendering generates a scene depth map. Defaults to false. */ sceneDepthMap: boolean; /** * - The tone mapping. Can be: * * - {@link TONEMAP_LINEAR} * - {@link TONEMAP_FILMIC} * - {@link TONEMAP_HEJL} * - {@link TONEMAP_ACES} * - {@link TONEMAP_ACES2} * - {@link TONEMAP_NEUTRAL} * - {@link TONEMAP_AGX} * - {@link TONEMAP_AGX_PUNCHY} * * Defaults to {@link TONEMAP_LINEAR}. */ toneMapping: number; /** * - The sharpening intensity, 0-1 range. This can be used to increase * the sharpness of the rendered image. Often used to counteract the blurriness of the TAA effect, * but also blurriness caused by rendering to a lower resolution render target by using * rendering.renderTargetScale property. Defaults to 0. */ sharpness: number; }; /** * @typedef {Object} Rendering * Properties related to scene rendering, encompassing settings that control the rendering resolution, * pixel format, multi-sampling for anti-aliasing, tone-mapping and similar. * @property {number[]} renderFormats - The preferred render formats of the frame buffer, in order of * preference. First format from this list that is supported by the hardware is used. When none of * the formats are supported, {@link PIXELFORMAT_RGBA8} is used, but this automatically disables * bloom effect, which requires HDR format. The list can contain the following formats: * {@link PIXELFORMAT_RG11B10F}, {@link PIXELFORMAT_RGBA16F}, {@link PIXELFORMAT_RGBA32F} and {@link * PIXELFORMAT_RGBA8}. Typically the default option should be used, which prefers the faster formats, * but if higher dynamic range is needed, the list can be adjusted to prefer higher precision formats. * Defaults to [{@link PIXELFORMAT_RG11B10F}, {@link PIXELFORMAT_RGBA16F}, {@link PIXELFORMAT_RGBA32F}]. * @property {boolean} stencil - Whether the render buffer has a stencil buffer. Defaults to false. * @property {number} renderTargetScale - The scale of the render target, 0.1-1 range. This allows the * scene to be rendered to a lower resolution render target as an optimization. The post-processing * is also applied at this lower resolution. The image is then up-scaled to the full resolution and * any UI rendering that follows is applied at the full resolution. Defaults to 1 which represents * full resolution rendering. * @property {number} samples - The number of samples of the {@link RenderTarget} used for the scene * rendering, in 1-4 range. Value of 1 disables multisample anti-aliasing, other values enable * anti-aliasing, Typically set to 1 when TAA is used, even though both anti-aliasing options can be * used together at a higher cost. Defaults to 1. * @property {boolean} sceneColorMap - Whether rendering generates a scene color map. Defaults to false. * @property {boolean} sceneDepthMap - Whether rendering generates a scene depth map. Defaults to false. * @property {number} toneMapping - The tone mapping. Can be: * * - {@link TONEMAP_LINEAR} * - {@link TONEMAP_FILMIC} * - {@link TONEMAP_HEJL} * - {@link TONEMAP_ACES} * - {@link TONEMAP_ACES2} * - {@link TONEMAP_NEUTRAL} * - {@link TONEMAP_AGX} * - {@link TONEMAP_AGX_PUNCHY} * * Defaults to {@link TONEMAP_LINEAR}. * @property {number} sharpness - The sharpening intensity, 0-1 range. This can be used to increase * the sharpness of the rendered image. Often used to counteract the blurriness of the TAA effect, * but also blurriness caused by rendering to a lower resolution render target by using * rendering.renderTargetScale property. Defaults to 0. */ /** * Implementation of a simple to use camera rendering pass, which supports SSAO, Bloom and * other rendering effects. * * Overriding compose shader chunks: * The final compose pass registers its shader chunks in a way that does not override any chunks * that were already provided. To customize the compose pass output, set your shader chunks on the * {@link ShaderChunks} map before creating the `CameraFrame`. Those chunks will be picked up by * the compose pass and preserved. * * Example (GLSL): * * @example * // Provide custom compose chunk(s) before constructing CameraFrame * ShaderChunks.get(graphicsDevice, SHADERLANGUAGE_GLSL).set('composeVignettePS', ` * vec3 applyVignette(vec3 color, vec2 uv) { * return color * uv.x; * } * `); * * // For WebGPU, use SHADERLANGUAGE_WGSL instead. * * @category Graphics */ export class CameraFrame { /** * Returns whether a device is able to let the gaussian splats contribute to the scene depth, which * the volumetric fog and the depth of field need in order to be bounded by the splats instead of * drawing through them. Their contribution additionally has to be turned on using * {@link GSplatParams#sceneDepthWrite}; this reports whether doing so can take effect, so that an * application rendering gaussian splats can disable those effects on the devices which cannot * respect them. * * This tests the device alone, and so can be called before any camera frame is created. Whether a * particular one then renders the depth this way also depends on its own settings - multi-sampling * and a camera not clearing the whole of its render target both rule it out - and a debug build * warns, naming the reason, when the splats end up not contributing. * * @param {GraphicsDevice} device - The graphics device. * @returns {boolean} True if the splats can contribute to the scene depth. */ static isSplatSceneDepthSupported(device: GraphicsDevice): boolean; /** * Creates a new CameraFrame instance. * * @param {AppBase} app - The application. * @param {CameraComponent} cameraComponent - The camera component. */ constructor(app: AppBase, cameraComponent: CameraComponent); /** @private */ private _enabled; /** * Rendering settings. * * @type {Rendering} */ rendering: Rendering; /** * The screen space ambient occlusion effect, registered with this camera frame. Its parameters * are assigned directly. * * @type {SsaoEffect} */ ssao: SsaoEffect; /** * The bloom effect, registered with this camera frame. Its parameters are assigned directly. * * @type {BloomEffect} */ bloom: BloomEffect; /** * The color grading effect, registered with this camera frame. Its parameters are assigned * directly. * * @type {GradingEffect} */ grading: GradingEffect; /** * The color lookup table (LUT) effect, registered with this camera frame. Its parameters are * assigned directly. * * @type {ColorLutEffect} */ colorLUT: ColorLutEffect; /** * The vignette effect, registered with this camera frame. Its parameters are assigned * directly. * * @type {VignetteEffect} */ vignette: VignetteEffect; /** * The effects registered with this camera frame, in the order they are applied within their * compose slot. The built-in effects are registered by the constructor; add your own with * {@link CameraFrame#addEffect}. Treat the array as read-only; use the methods of the camera * frame to change it. * * @type {CameraFrameEffect[]} */ effects: CameraFrameEffect[]; /** * The built-in effects this camera frame constructed, and so destroys. * * @type {CameraFrameEffect[]} * @private */ private _builtInEffects; /** * The scene format, see {@link CameraFrame#hdrFormat}. * * @type {number} * @private */ private _hdrFormat; /** * The effects taking part in the frames, in registration order: the active ones, as of the * last time the effects were applied by {@link CameraFrame#update}, or when the camera frame * was enabled. * * @type {CameraFrameEffect[]} * @ignore */ _activeEffects: CameraFrameEffect[]; /** * The time the application advanced by in its updates since the camera frame last rendered, in * seconds, handed to the effects as the time of the frame. See {@link CameraFrameEffectContext}. * * @type {number} * @ignore */ _frameTime: number; /** * The sharpening effect, whose sharpness is exposed as `rendering.sharpness`. * * @type {CasEffect} * @private */ private _cas; /** * The temporal anti-aliasing effect, registered with this camera frame. Its parameters are * assigned directly. * * @type {TaaEffect} */ taa: TaaEffect; /** * The fringing effect, registered with this camera frame. Its parameters are assigned * directly. * * @type {FringingEffect} */ fringing: FringingEffect; /** * The color enhancement effect, registered with this camera frame. Its parameters are * assigned directly. * * @type {ColorEnhanceEffect} */ colorEnhance: ColorEnhanceEffect; /** * The depth of field effect, registered with this camera frame. Its parameters are assigned * directly. * * @type {DofEffect} */ dof: DofEffect; /** * The volumetric fog effect, registered with this camera frame. Its parameters are assigned * directly. * * @type {VolumetricFogEffect} */ volumetricFog: VolumetricFogEffect; /** * Debug rendering, which displays an intermediate value of the frame in place of the composed * result. This never changes what the frame renders - a mode whose value this frame does not * generate simply displays nothing: 'depth' renders black when no effect has produced the scene * depth, and the modes of a disabled effect are ignored. Set to null to disable. * * Besides the built-in modes, this accepts the name of a debug view provided by an effect * registered with this camera frame, see {@link CameraFrameEffect#debugViews}. * * @type {null|'scene'|'ssao'|'bloom'|'vignette'|'dofcoc'|'dofblur'|'depth'|(string & {})} */ debug: null | "scene" | "ssao" | "bloom" | "vignette" | "dofcoc" | "dofblur" | "depth" | (string & {}); options: CameraFrameOptions; /** * The camera component the camera frame renders, for example for the passes of an effect * which depend on the camera. * * @type {CameraComponent} * @readonly */ readonly cameraComponent: CameraComponent; /** * @type {FramePassCameraFrame|null} * @ignore */ renderPassCamera: FramePassCameraFrame | null; app: AppBase; cameraLayersChanged: import("../../index.js").EventHandle; _appUpdate: import("../../index.js").EventHandle; /** * Destroys the camera frame, removing all render passes. */ destroy(): void; /** * The graphics device. * * @type {GraphicsDevice} * @ignore */ get device(): GraphicsDevice; /** * The format of the render target the scene is rendered to: the first of the preferred render * formats the device can render to, or {@link PIXELFORMAT_RGBA8} when none of them is * available. Chosen by {@link CameraFrame#update}, before the frame passes are built, so that * the effects can depend on it. * * @type {number} * @ignore */ get hdrFormat(): number; /** * Registers an effect with this camera frame. The effect is applied at the compose slot it * declares, after any effect already registered to that slot, from the next call to * {@link CameraFrame#update}. The effect stays owned by the caller: removing it or destroying * the camera frame does not destroy it. * * @param {CameraFrameEffect} effect - The effect to add. * @example * const tint = new TintEffect(app.graphicsDevice); * cameraFrame.addEffect(tint); * cameraFrame.update(); */ addEffect(effect: CameraFrameEffect): void; /** * Registers an effect with this camera frame, applying it before another registered effect * when both share a compose slot, and running its passes before those of the other effect at * the stages of the frame they share. The effect is applied from the next call to * {@link CameraFrame#update}. * * @param {CameraFrameEffect} effect - The effect to add. * @param {CameraFrameEffect|string} before - The effect, or the id of the effect, to apply * this one before. * @example * // apply the tint before the built-in vignette, which also runs at COMPOSESLOT_LDR * cameraFrame.insertEffectBefore(tint, 'vignette'); */ insertEffectBefore(effect: CameraFrameEffect, before: CameraFrameEffect | string): void; /** * Registers an effect at the given position of the effect list. * * @param {CameraFrameEffect} effect - The effect to add. * @param {number} index - The position. * @private */ private insertEffect; /** * Removes an effect from this camera frame. The effect stops being applied from the next call * to {@link CameraFrame#update}. * * @param {CameraFrameEffect} effect - The effect to remove. * @example * cameraFrame.removeEffect(tint); * cameraFrame.update(); */ removeEffect(effect: CameraFrameEffect): void; /** * Returns the registered effect with the given id, or undefined when no effect of that type is * registered. * * @param {string} id - The id the effect was constructed with, for example `'vignette'`. * @returns {CameraFrameEffect|undefined} The effect. */ getEffect(id: string): CameraFrameEffect | undefined; /** * Applies the effects: decides which take part in the frames rendered until they are next * applied, has each of them apply its parameters, and hands them to the composition, which * rebuilds its shader only when they or their defines changed. Called by * {@link CameraFrame#update} and when the camera frame is enabled, after the frame passes are * built. * * @private */ private _applyEffects; enable(): void; disable(): void; /** * Creates a frame pass for the camera frame. Override this method to utilize a custom frame * pass, typically one that extends `FramePassCameraFrame`. * * @returns {FramePassCameraFrame} - The frame pass. * @ignore */ createRenderPass(): FramePassCameraFrame; /** * Sets the enabled state of the camera frame. Passing false will release associated resources. * * @type {boolean} */ set enabled(value: boolean); /** * Gets the enabled state of the camera frame. * * @type {boolean} */ get enabled(): boolean; updateOptions(): void; /** * Applies any changes made to the properties of this instance. */ update(): void; } import { SsaoEffect } from '../effects/ssao/ssao-effect.js'; import { BloomEffect } from '../effects/bloom/bloom-effect.js'; import { GradingEffect } from '../effects/grading/grading-effect.js'; import { ColorLutEffect } from '../effects/color-lut/color-lut-effect.js'; import { VignetteEffect } from '../effects/vignette/vignette-effect.js'; import type { CameraFrameEffect } from './camera-frame-effect.js'; import { TaaEffect } from '../effects/taa/taa-effect.js'; import { FringingEffect } from '../effects/fringing/fringing-effect.js'; import { ColorEnhanceEffect } from '../effects/color-enhance/color-enhance-effect.js'; import { DofEffect } from '../effects/dof/dof-effect.js'; import { VolumetricFogEffect } from '../effects/volumetric-fog/volumetric-fog-effect.js'; import { CameraFrameOptions } from './frame-pass-camera-frame.js'; import type { CameraComponent } from '../../framework/components/camera/component.js'; import { FramePassCameraFrame } from './frame-pass-camera-frame.js'; import type { AppBase } from '../../framework/app-base.js'; import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js';