babylonjs-editor-tools 5.5.0 → 5.5.1-alpha.0

package/declaration/src/rendering/volumetric/pipeline.d.ts

@@ -0,0 +1,231 @@
+import { Scene } from "@babylonjs/core/scene";
+import { Camera } from "@babylonjs/core/Cameras/camera";
+import { AbstractEngine } from "@babylonjs/core/Engines/abstractEngine";
+import { ShaderLanguage } from "@babylonjs/core/Materials/shaderLanguage";
+import { PostProcessRenderPipeline } from "@babylonjs/core/PostProcesses/RenderPipeline/postProcessRenderPipeline";
+import { IVolumetricLightingConfiguration } from "./types";
+import { IVolumetricBudget, IVolumetricLightingStats } from "./selector";
+/**
+ * Defines a rendering pipeline computing single-scattering volumetric lighting: the light shafts are
+ * integrated through a participating medium the pipeline describes on its own, and are occluded either by
+ * the shadow map a light already renders or, when it has none, by the depth buffer of the scene.
+ *
+ * Every light of the scene can take part in the effect, including the lights that live inside a clustered
+ * light container, and each one is configured individually through "light.metadata.volumetricLighting".
+ *
+ * The cost of the effect scales with what is on screen rather than with the number of lights: a directional
+ * light is marched along the whole view ray, but a point or a spot light is only integrated over the part
+ * of the view ray crossing its volume, so a light costs nothing to the pixels whose view ray misses it.
+ *
+ * The pipeline is composed of four passes:
+ * - a pass keeping the color of the scene untouched and extracting its linear depth, which every later pass
+ *   reads instead of the depth map,
+ * - the raymarching pass, rendered at a fraction of the resolution of the canvas,
+ * - a separable depth aware blur denoising the result of the raymarching,
+ * - a composition pass upsampling the result and adding it to the color of the scene.
+ */
+export declare class VolumetricLightingRenderingPipeline extends PostProcessRenderPipeline {
+    /**
+     * Defines the name of the render effect keeping the color of the scene and extracting its linear depth.
+     */
+    static readonly SceneColorEffectName: string;
+    /**
+     * Defines the name of the render effect raymarching the participating medium.
+     */
+    static readonly ScatteringEffectName: string;
+    /**
+     * Defines the name of the render effect denoising the result of the raymarching.
+     */
+    static readonly BlurEffectName: string;
+    /**
+     * Defines the name of the render effect composing the light shafts over the color of the scene.
+     */
+    static readonly ComposeEffectName: string;
+    /**
+     * Returns the distance at which the medium becomes fully opaque to use as a default for the linear mode.
+     * @param scene defines the reference to the scene to measure.
+     * @param camera defines the reference to the camera, used when the scene has no geometry yet.
+     */
+    static GetDefaultFogEnd(scene: Scene, camera: Camera): number;
+    /**
+     * Returns the extinction coefficient to use as a default for the medium of the pipeline.
+     *
+     * There is no unit agnostic constant that works here: an extinction of 1 per unit is a thick smoke in a
+     * scene authored in metres and a vacuum in one authored in centimetres. Deriving it from the size of the
+     * scene gives an optical depth of about 1 from one end of the content to the other, which reads well
+     * whatever the project is authored in.
+     * @param scene defines the reference to the scene to measure.
+     * @param camera defines the reference to the camera, used when the scene has no geometry yet.
+     */
+    static GetDefaultFogDensity(scene: Scene, camera: Camera): number;
+    /**
+     * Returns wether or not the volumetric lighting rendering pipeline is supported by the given engine.
+     * The raymarching shader relies on shadow samplers, texture arrays and texel fetches, which need WebGL 2,
+     * and ships as both GLSL and hand written WGSL so WebGPU is supported without an external transpiler.
+     * @param engine defines the reference to the engine to check.
+     */
+    static IsSupported(engine: AbstractEngine): boolean;
+    /**
+     * Returns the language the shaders of the pipeline must be written in for the given engine.
+     * @param engine defines the reference to the engine to check.
+     */
+    static GetShaderLanguage(engine: AbstractEngine): ShaderLanguage;
+    private _scene;
+    private _camera;
+    private _configuration;
+    private _configurationProxy;
+    private _textureType;
+    private _shaderLanguage;
+    private _ldrEncode;
+    private _linearDepthPacked;
+    private _depthRenderer;
+    private _ownsDepthRenderer;
+    private _depthMode;
+    private _linearDepthPostProcess;
+    private _scatteringPostProcess;
+    private _blurPostProcesses;
+    private _composePostProcess;
+    private _selection;
+    private _budget;
+    private _linearDepthDefines;
+    private _scatteringDefines;
+    private _blurDefines;
+    private _composeDefines;
+    private _frameCount;
+    private _lightsDirty;
+    private _disposed;
+    private _beforeCameraRenderObserver;
+    private _lightAddedObserver;
+    private _lightRemovedObserver;
+    private _inverseViewProjection;
+    private _temporaryVector;
+    private _temporaryColor;
+    private _lightData;
+    private _lightDiffuse;
+    private _lightDirection;
+    private _lightFalloff;
+    private _shadowLightData;
+    private _shadowLightDiffuse;
+    private _shadowLightDirection;
+    private _shadowLightFalloff;
+    private _shadowInfo;
+    private _shadowMatrices;
+    private _csmLightData;
+    private _csmLightDiffuse;
+    private _csmLightDirection;
+    private _csmLightFalloff;
+    private _csmMatrices;
+    /**
+     * Constructor.
+     * @param name defines the name of the pipeline.
+     * @param scene defines the reference to the scene the pipeline belongs to.
+     * @param camera defines the reference to the camera the pipeline is attached to.
+     * @param configuration defines the optional configuration to apply on the pipeline.
+     */
+    constructor(name: string, scene: Scene, camera: Camera, configuration?: Partial<IVolumetricLightingConfiguration>);
+    /**
+     * Gets wether or not the pipeline was disposed. Babylon.js disposes a rendering pipeline on its own when
+     * one of its post-processes fails to compile, so this is not always the result of an explicit call.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Gets the reference to the scene the pipeline belongs to.
+     */
+    get scene(): Scene;
+    /**
+     * Gets the reference to the camera the pipeline is attached to.
+     */
+    get camera(): Camera;
+    /**
+     * Gets the live configuration of the pipeline. Assigning a property of the returned object applies the
+     * change immediately, rebuilding the chain of post-processes when the change requires it.
+     */
+    get configuration(): IVolumetricLightingConfiguration;
+    /**
+     * Gets the statistics of the last selection pass, used by the inspector to explain what each light does.
+     */
+    getStats(): IVolumetricLightingStats | null;
+    /**
+     * Gets the number of lights the raymarching shader can be compiled for on the current engine.
+     */
+    getBudget(): IVolumetricBudget;
+    /**
+     * Gets a string identifying the name of the class.
+     */
+    getClassName(): string;
+    /**
+     * Marks the list of lights contributing to the effect as dirty, forcing a new selection pass on the
+     * next frame. Called when the volumetric configuration of a light is edited in the inspector.
+     */
+    markLightsDirty(): void;
+    /**
+     * Applies the given configuration on the pipeline.
+     * @param data defines the configuration to apply.
+     */
+    applyConfiguration(data: Partial<IVolumetricLightingConfiguration>): void;
+    /**
+     * Serializes the configuration of the pipeline.
+     */
+    serializeConfiguration(): IVolumetricLightingConfiguration;
+    /**
+     * Disposes the pipeline and all the resources it owns.
+     */
+    dispose(): void;
+    private _onConfigurationChanged;
+    /**
+     * Adopts the depth renderer of the camera when one already exists (the SSAO and SSR pipelines create
+     * one) instead of paying for a second full depth pass, and detects the format it stores so the shader
+     * can be compiled for it.
+     */
+    private _setupDepthRenderer;
+    /**
+     * Binds the two values needed to turn the content of the depth map back into a distance along the view
+     * axis. The depth renderer stores "(clipZ + minZ) / (minZ + maxZ)", where "clipZ" is affine in the view
+     * space Z for both the perspective and the orthographic projections, so the inverse is affine too and
+     * can be derived exactly from the projection matrix instead of being approximated.
+     */
+    private _bindDepthUniforms;
+    private _getEnvironment;
+    /**
+     * Returns the defines of the passes reading the linear depth, which only depend on how it is stored.
+     */
+    private _buildLinearDepthReadDefines;
+    /**
+     * Returns the defines of the linear depth pass, the only one reading the depth map of the depth renderer.
+     */
+    private _buildLinearDepthDefines;
+    private _buildScatteringDefines;
+    private _buildBlurDefines;
+    private _buildComposeDefines;
+    private _createPostProcess;
+    private _buildRenderEffects;
+    private _disposePostProcesses;
+    /**
+     * Rebuilds the chain of post-processes. Changing the resolution of the scattering buffer or the number
+     * of blur passes changes the shape of the chain, which a post-process can't do in place.
+     */
+    private _rebuildRenderEffects;
+    /**
+     * Runs the selection pass and recompiles the shaders when, and only when, their defines changed. The
+     * identity, the number and the values of the point and spot lights change every frame and only cost a
+     * uniform update: only the directional lights and the kinds of the shadow maps shape the shader.
+     */
+    private _updateSelection;
+    /**
+     * Fills the four vectors describing a light in the raymarching shader. The packing follows what
+     * "Light.transferToEffect" writes for the surfaces of the scene so the shafts agree with them, except for
+     * the position of the point and spot lights, which is written relative to the camera: the raymarching
+     * works in that space, which keeps its precision whatever the distance of the scene to the origin.
+     */
+    private _writeLight;
+    private _bindLinearDepth;
+    private _bindScattering;
+    /**
+     * Binds the ratio between the resolution of the linear depth and the resolution of the scattering buffer.
+     * It is computed here rather than in the shaders so every pass rounds it exactly the same way, which is what
+     * makes them all associate each texel of the scattering buffer with the same texel of the linear depth.
+     */
+    private _bindDepthRatio;
+    private _bindBlur;
+    private _bindCompose;
+}

package/declaration/src/rendering/volumetric/selector.d.ts

@@ -0,0 +1,263 @@
+import { Scene } from "@babylonjs/core/scene";
+import { Light } from "@babylonjs/core/Lights/light";
+import { Camera } from "@babylonjs/core/Cameras/camera";
+import { Vector3 } from "@babylonjs/core/Maths/math.vector";
+import { AbstractEngine } from "@babylonjs/core/Engines/abstractEngine";
+import { ShadowGenerator } from "@babylonjs/core/Lights/Shadows/shadowGenerator";
+import { CascadedShadowGenerator } from "@babylonjs/core/Lights/Shadows/cascadedShadowGenerator";
+import { IVolumetricLightConfiguration, IVolumetricLightingConfiguration } from "./types";
+/**
+ * Defines the type of sampler needed to read the shadow map of a light.
+ */
+export declare enum VolumetricShadowKind {
+    /**
+     * Regular 2d texture storing the depth encoded in its color channels.
+     */
+    Texture2D = 0,
+    /**
+     * Hardware comparison sampler, used by the percentage closer filtering.
+     */
+    Sampler2DShadow = 1,
+    /**
+     * Cube texture storing the radial distance to the light, used by point lights.
+     */
+    Cube = 2
+}
+/**
+ * Defines how the value stored in a shadow map must be interpreted.
+ */
+export declare enum VolumetricShadowMode {
+    /**
+     * The shadow map stores the depth, the comparison is a simple "greater than".
+     */
+    Standard = 0,
+    /**
+     * The shadow map stores the exponential of the depth.
+     */
+    Esm = 1,
+    /**
+     * The shadow map stores the exponential of the depth, compared in the "close" space.
+     */
+    CloseEsm = 2
+}
+/**
+ * Defines how the transmittance of the medium is evaluated by the raymarching shader.
+ */
+export declare enum VolumetricTransmittanceMode {
+    /**
+     * Closed form of the three fog modes, for a medium whose density doesn't depend on the altitude.
+     */
+    Analytic = 0,
+    /**
+     * Closed form of the exponential fog mode combined with the height falloff.
+     */
+    AnalyticHeight = 1,
+    /**
+     * Optical depth integrated numerically along the view ray, for the other fog modes combined with the
+     * height falloff, which have no closed form.
+     */
+    Numeric = 2
+}
+/**
+ * Defines the state of a light regarding the volumetric lighting, as reported to the inspector.
+ */
+export type VolumetricLightState = "shadowed" | "unshadowed" | "culled" | "dropped" | "disabled";
+/**
+ * Defines the status of a light regarding the volumetric lighting.
+ */
+export interface IVolumetricLightStatus {
+    /**
+     * Defines the state of the light. @see VolumetricLightState
+     */
+    state: VolumetricLightState;
+    /**
+     * Defines the index of the shadowed slot used by the light, or -1.
+     */
+    slot: number;
+    /**
+     * Defines a human readable explanation of the state, drawn in the inspector of the light.
+     */
+    reason: string;
+}
+/**
+ * Defines the statistics of the last selection pass of the volumetric lighting rendering pipeline.
+ */
+export interface IVolumetricLightingStats {
+    /**
+     * Defines the number of lights of the scene that have volumetric lighting enabled.
+     */
+    candidateCount: number;
+    /**
+     * Defines the number of candidates that were outside the frustum of the camera.
+     */
+    culledCount: number;
+    /**
+     * Defines the number of candidates that got a shadowed slot.
+     */
+    shadowedCount: number;
+    /**
+     * Defines the number of candidates that contribute without casting volumetric shadows.
+     */
+    unshadowedCount: number;
+    /**
+     * Defines the number of candidates that didn't fit in the budget of the shader.
+     */
+    droppedCount: number;
+    /**
+     * Defines the status of each candidate, keyed by the unique id of the light.
+     */
+    perLight: Map<number, IVolumetricLightStatus>;
+}
+/**
+ * Defines a light of the scene that has volumetric lighting enabled.
+ */
+export interface IVolumetricLightCandidate {
+    light: Light;
+    config: IVolumetricLightConfiguration;
+    isClustered: boolean;
+    typeId: number;
+    score: number;
+}
+/**
+ * Defines the shadow map of a light, classified for the raymarching shader.
+ */
+export interface IVolumetricShadowSlot {
+    generator: ShadowGenerator;
+    kind: VolumetricShadowKind;
+    mode: VolumetricShadowMode;
+    packed: boolean;
+    mapSize: number;
+    /**
+     * Defines wether or not the light of the slot has a bounded volume (point and spot lights). Those are
+     * integrated only over the part of the view ray crossing their volume, the others along the whole ray.
+     */
+    local: boolean;
+}
+/**
+ * Defines the result of a selection pass.
+ */
+export interface IVolumetricLightSelection {
+    shadowed: {
+        candidate: IVolumetricLightCandidate;
+        shadow: IVolumetricShadowSlot;
+    }[];
+    /**
+     * Defines the lights evaluated without a shadow map. The first "directionalCount" entries are the
+     * directional lights, the point and spot lights follow.
+     */
+    unshadowed: IVolumetricLightCandidate[];
+    /**
+     * Defines the number of directional lights at the start of "unshadowed".
+     */
+    directionalCount: number;
+    csm: {
+        candidate: IVolumetricLightCandidate;
+        generator: CascadedShadowGenerator;
+        cascades: number;
+        kind: VolumetricShadowKind;
+        packed: boolean;
+    } | null;
+    stats: IVolumetricLightingStats;
+}
+/**
+ * Defines the number of lights the shader can be compiled for on the current engine.
+ */
+export interface IVolumetricBudget {
+    maxShadowSlots: number;
+    maxArrayLights: number;
+    maxDirectionalLights: number;
+    allowCsm: boolean;
+}
+/**
+ * Computes the number of lights the raymarching shader can be compiled for, from the real capabilities
+ * of the engine rather than from a hardcoded guess.
+ * @param engine defines the reference to the engine to get its capabilities.
+ * @param configuration defines the configuration of the pipeline, used as an upper bound.
+ */
+export declare function computeVolumetricBudget(engine: AbstractEngine, configuration: IVolumetricLightingConfiguration): IVolumetricBudget;
+/**
+ * Returns the list of all the lights of the scene, including the ones that live inside a clustered light
+ * container. Adding a light to a container removes it from "scene.lights", so walking "scene.lights" alone
+ * misses exactly the lights this pipeline is meant to scale to.
+ * @param scene defines the reference to the scene to get its lights.
+ */
+export declare function getAllVolumetricCandidateLights(scene: Scene): {
+    light: Light;
+    isClustered: boolean;
+}[];
+/**
+ * Returns the shadow generator of the given light classified for the raymarching shader, or null when the
+ * light has no shadow map that can be sampled by the volumetric pass.
+ * @param light defines the reference to the light to resolve its shadow map.
+ * @param scene defines the reference to the scene the light belongs to.
+ */
+export declare function resolveVolumetricShadowSlot(light: Light, scene: Scene): IVolumetricShadowSlot | null;
+/**
+ * Returns the world position of the given light, taking its parent into account.
+ * @param light defines the reference to the light to get its position.
+ * @param result defines the vector the position is written to.
+ */
+export declare function getVolumetricLightWorldPosition(light: Light, result: Vector3): Vector3;
+/**
+ * Returns the normalized world direction of the given light, taking its parent into account.
+ * @param light defines the reference to the light to get its direction.
+ * @param result defines the vector the direction is written to.
+ */
+export declare function getVolumetricLightWorldDirection(light: Light, result: Vector3): Vector3;
+/**
+ * Returns the radius of the volume reached by the given light, as used by the raymarching shader.
+ * "Light.range" defaults to Number.MAX_VALUE, anything past the reach of the march means no attenuation at all.
+ * @param light defines the reference to the light to get its radius.
+ * @param config defines the volumetric configuration of the light.
+ * @param configuration defines the configuration of the pipeline.
+ */
+export declare function getVolumetricLightRange(light: Light, config: IVolumetricLightConfiguration, configuration: IVolumetricLightingConfiguration): number;
+/**
+ * Selects the lights of the scene that contribute to the volumetric lighting for the given camera, splits
+ * them between the shadowed and the unshadowed tiers of the shader and reports why each one ended where it did.
+ * @param scene defines the reference to the scene to select the lights from.
+ * @param camera defines the reference to the camera the pipeline is attached to.
+ * @param configuration defines the configuration of the pipeline.
+ * @param budget defines the number of lights the shader can be compiled for.
+ * @param previous defines the result of the previous selection pass, used to keep the slots stable over time.
+ */
+export declare function selectVolumetricLights(scene: Scene, camera: Camera, configuration: IVolumetricLightingConfiguration, budget: IVolumetricBudget, previous: IVolumetricLightSelection | null): IVolumetricLightSelection;
+/**
+ * Defines everything that ends up in a "#define" of the raymarching shader. Any change to this key
+ * requires the shader to be recompiled, everything else is a simple uniform update.
+ */
+export interface IVolumetricShaderEnvironment {
+    depthMode: 0 | 1 | 2;
+    ldrEncode: boolean;
+    reverseDepth: boolean;
+    ndcHalfZ: boolean;
+    fogMode: number;
+    transmittance: VolumetricTransmittanceMode;
+    /**
+     * Defines wether or not the linear depth of the scene is packed in an 8 bits RGBA texture because the
+     * engine can't render to a 32 bits float one.
+     */
+    linearDepthPacked: boolean;
+    /**
+     * Defines the size of the uniform arrays holding the lights evaluated without a shadow map. The number of
+     * lights actually stored in them is a uniform, which is what lets lights enter and leave the frustum of
+     * the camera without recompiling anything.
+     */
+    arrayLightCapacity: number;
+    /**
+     * Defines the number of samples taken across the volume of each point and spot light.
+     */
+    lightSteps: number;
+}
+/**
+ * Computes a key that changes whenever the raymarching shader must be recompiled.
+ * @param selection defines the result of the last selection pass.
+ * @param configuration defines the configuration of the pipeline.
+ * @param environment defines the state of the engine and of the scene the shader depends on.
+ */
+export declare function computeVolumetricShapeKey(selection: IVolumetricLightSelection, configuration: IVolumetricLightingConfiguration, environment: IVolumetricShaderEnvironment): string;
+/**
+ * Returns wether or not the given light can be used by the volumetric lighting rendering pipeline.
+ * @param light defines the reference to the light to check.
+ */
+export declare function isVolumetricLightSupported(light: Light): boolean;

package/declaration/src/rendering/volumetric/shaders-wgsl.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The linear depth pass. @see buildVolumetricLightingLinearDepthShader.
+ */
+export declare function buildVolumetricLightingLinearDepthShaderWGSL(): string;
+/**
+ * The raymarching pass. @see buildVolumetricLightingScatteringShader for what it computes.
+ * @param shadowSlotCount defines the number of shadowed light slots the shader is generated for.
+ */
+export declare function buildVolumetricLightingScatteringShaderWGSL(shadowSlotCount: number): string;
+/**
+ * The separable bilateral blur pass. @see buildVolumetricLightingBlurShader.
+ */
+export declare function buildVolumetricLightingBlurShaderWGSL(): string;
+/**
+ * The composition pass. @see buildVolumetricLightingComposeShader.
+ */
+export declare function buildVolumetricLightingComposeShaderWGSL(): string;
+/**
+ * Returns the four WGSL sources of the pipeline, keyed by the name they are registered under.
+ */
+export declare function getVolumetricLightingShadersWGSL(): Record<string, string>;

package/declaration/src/rendering/volumetric/shaders.d.ts

@@ -0,0 +1,60 @@
+import { ShaderLanguage } from "@babylonjs/core/Materials/shaderLanguage";
+/**
+ * Defines the name of the linear depth shader in the shader store of Babylon.js.
+ */
+export declare const volumetricLightingLinearDepthShaderName = "volumetricLightingLinearDepth";
+/**
+ * Defines the name of the raymarching shader in the shader store of Babylon.js.
+ */
+export declare const volumetricLightingScatteringShaderName = "volumetricLightingScattering";
+/**
+ * Defines the name of the bilateral blur shader in the shader store of Babylon.js.
+ */
+export declare const volumetricLightingBlurShaderName = "volumetricLightingBlur";
+/**
+ * Defines the name of the composition shader in the shader store of Babylon.js.
+ */
+export declare const volumetricLightingComposeShaderName = "volumetricLightingCompose";
+/**
+ * The linear depth pass. It is the first pass of the pipeline, so its input is the untouched color of the
+ * scene that the composition reads back, and it writes the distance along the view axis of each pixel.
+ *
+ * Every later pass reads this texture instead of the depth map of the depth renderer: a single 32 bits
+ * channel is half the memory traffic of the 16 bits RGBA depth map, which matters for the thousands of reads
+ * of the depth-buffer occlusion, and it needs neither unpacking nor linearization. It is kept at the full
+ * resolution so the occlusion sees the geometry exactly as the surfaces of the scene draw it.
+ */
+export declare function buildVolumetricLightingLinearDepthShader(): string;
+/**
+ * The raymarching pass. Accumulates the single-scattering integral of every enabled light of the scene
+ * along the view ray, through the participating medium described by the configuration of the pipeline.
+ *
+ * The lights are not all marched together: a directional light lights the whole view ray and is marched
+ * along it, but a point or a spot light only reaches the part of the ray crossing its volume, so each one is
+ * integrated over that part alone, with samples of its own. A light the ray doesn't cross costs a single
+ * ray/volume intersection, and a small light gets as many samples as a big one instead of the few steps of
+ * the global march that happened to fall inside it.
+ *
+ * The result is written as (rgb = in-scattered radiance, a = transmittance of the medium at the end of the ray).
+ * @param shadowSlotCount defines the number of shadowed light slots the shader is generated for.
+ */
+export declare function buildVolumetricLightingScatteringShader(shadowSlotCount: number): string;
+/**
+ * The separable bilateral blur pass. Denoises the low resolution scattering buffer without letting the
+ * light shafts bleed across the silhouettes of the geometry.
+ */
+export declare function buildVolumetricLightingBlurShader(): string;
+/**
+ * The composition pass. Upsamples the low resolution scattering buffer using a depth aware filter and
+ * adds it to the color of the scene.
+ */
+export declare function buildVolumetricLightingComposeShader(): string;
+/**
+ * Registers the shaders of the volumetric lighting rendering pipeline in the shader store of Babylon.js.
+ * Calling this function multiple times for the same language has no effect.
+ *
+ * The WGSL sources are hand written rather than transpiled from the GLSL ones: Babylon.js can only convert
+ * GLSL to WGSL by downloading twgsl from its CDN, which an offline application can't rely on.
+ * @param shaderLanguage defines the language the shaders are registered for.
+ */
+export declare function registerVolumetricLightingShaders(shaderLanguage: ShaderLanguage): void;