babylonjs-editor-tools 5.5.1 → 5.5.2

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

@@ -22,10 +22,12 @@ import { VolumetricDepthSource } from "./depth";
  * 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:
+ * The pipeline is composed of the following 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,
+ * - when the temporal accumulation is enabled, a pass blending the result of the raymarching with the result of
+ *   the previous frames, which lets the raymarching compute a fraction of its samples each frame,
  * - 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.
  */
@@ -38,6 +40,10 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
      * Defines the name of the render effect raymarching the participating medium.
      */
     static readonly ScatteringEffectName: string;
+    /**
+     * Defines the name of the render effect accumulating the result of the raymarching over the frames.
+     */
+    static readonly TemporalEffectName: string;
     /**
      * Defines the name of the render effect denoising the result of the raymarching.
      */
@@ -82,30 +88,51 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
     private _textureType;
     private _shaderLanguage;
     private _ldrEncode;
+    private _linearDepthType;
     private _linearDepthPacked;
     private _msaaSamples;
     private _msaaSamplesAssigned;
     private _depthSource;
     private _depthRenderer;
     private _ownsDepthRenderer;
+    private _depthMapRenderedWithCamera;
     private _depthMode;
     private _prePassConfiguration;
     private _linearDepthPostProcess;
     private _scatteringPostProcess;
+    private _temporalPostProcess;
     private _blurPostProcesses;
     private _composePostProcess;
+    private _temporalSamplesDivider;
+    private _temporalClippingWidth;
+    private _temporalMotionTolerance;
+    private _previousCameraPosition;
+    private _historyTextures;
+    private _historyFrames;
+    private _historyEmpty;
+    private _historyIndex;
+    private _temporalFrame;
+    private _previousViewProjection;
+    private _previousViewProjectionRelative;
+    private _cameraTranslation;
     private _selection;
     private _budget;
     private _linearDepthDefines;
     private _scatteringDefines;
+    private _temporalDefines;
     private _blurDefines;
     private _composeDefines;
     private _frameCount;
     private _lightsDirty;
     private _disposed;
+    private _idle;
+    private _depthWarmup;
     private _beforeCameraRenderObserver;
+    private _afterCameraRenderObserver;
     private _lightAddedObserver;
     private _lightRemovedObserver;
+    private _meshAddedObserver;
+    private _meshRemovedObserver;
     private _inverseViewProjection;
     private _temporaryVector;
     private _temporaryColor;
@@ -150,6 +177,11 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
      * change immediately, rebuilding the chain of post-processes when the change requires it.
      */
     get configuration(): IVolumetricLightingConfiguration;
+    /**
+     * Gets wether or not the pipeline had nothing to draw at its last update: no light reaches the view of the camera
+     * and the medium neither glows nor attenuates the scene. Its passes then cost next to nothing.
+     */
+    get isIdle(): boolean;
     /**
      * Gets where the depth of the scene is currently read from. @see VolumetricDepthSource
      */
@@ -231,6 +263,19 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
      * depth pass, and detects the format it stores so the shader can be compiled for it.
      */
     private _setupDepthRenderer;
+    /**
+     * Returns wether or not the depth renderer of the camera the scene hands to the effects asking for it changed
+     * since the pipeline chose its own: created by another effect, or disabled by the one that created it.
+     */
+    private _hasDepthRendererOfCameraChanged;
+    /**
+     * Adds the depth map the pipeline owns to the render targets of the camera, or removes it. The scene collects
+     * its own render targets before the pipeline decides wether it has anything to draw this frame, but renders
+     * the ones of the camera after: the frame the pipeline has something to draw again, only the latter render the
+     * depth map in time. They are only used for that frame, rendering it with the ones of the scene costs less
+     * time to the CPU.
+     */
+    private _setDepthMapRenderedWithCamera;
     /**
      * 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
@@ -238,6 +283,15 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
      * can be derived exactly from the projection matrix instead of being approximated.
      */
     private _bindDepthUniforms;
+    /**
+     * Returns the number of samples the raymarching computes each frame, fewer with the temporal accumulation.
+     */
+    private _getSamplingSteps;
+    /**
+     * Returns the dithering mode the raymarching is compiled with. The temporal accumulation needs the samples of
+     * neighboring pixels to differ: it tells its own noise from the changes of the scene with it.
+     */
+    private _getDitherMode;
     private _getEnvironment;
     /**
      * Returns the defines of the passes reading the linear depth, which only depend on how it is stored.
@@ -248,11 +302,23 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
      */
     private _buildLinearDepthDefines;
     private _buildScatteringDefines;
+    private _buildTemporalDefines;
     private _buildBlurDefines;
     private _buildComposeDefines;
     private _createPostProcess;
     private _buildRenderEffects;
     private _disposePostProcesses;
+    /**
+     * Releases the textures holding the history of the temporal accumulation. The next frame starts over from the
+     * result of the raymarching alone.
+     */
+    private _disposeHistory;
+    /**
+     * Swaps the two textures holding the history of the temporal accumulation, as the pass is activated: the one
+     * written last frame is read back, the other one receives the result of this frame and is what the pass after
+     * it reads, the same way the TAA rendering pipeline of Babylon.js does.
+     */
+    private _prepareHistory;
     /**
      * 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.
@@ -264,6 +330,21 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
      * uniform update: only the directional lights and the kinds of the shadow maps shape the shader.
      */
     private _updateSelection;
+    /**
+     * Detects when the pipeline has nothing to draw: no light reaches the view of the camera and the medium neither
+     * glows nor attenuates the scene. Every pass then exits right away, the composition outputs the color of the
+     * scene exactly as it would under light shafts of zero intensity, and the depth renderer the pipeline owns stops
+     * rendering the scene a second time. This is driven by uniforms rather than by detaching the passes, so a light
+     * blinking on and off, a muzzle flash typically, never rebuilds anything.
+     */
+    private _updateIdleState;
+    /**
+     * Prepares the depth shaders of the meshes while the depth renderer the pipeline owns is off, a few meshes per
+     * frame. Without this, the first frame with something to draw after the scene got new meshes, or after the
+     * pipeline was created without anything to draw, would miss every mesh whose depth shader is still compiling.
+     * The checks are the ones the scene runs for its depth renderers when it waits to be ready.
+     */
+    private _warmUpDepthRenderer;
     /**
      * 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
@@ -279,6 +360,7 @@ export declare class VolumetricLightingRenderingPipeline extends PostProcessRend
      * makes them all associate each texel of the scattering buffer with the same texel of the linear depth.
      */
     private _bindDepthRatio;
+    private _bindTemporal;
     private _bindBlur;
     private _bindCompose;
 }

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

@@ -235,7 +235,7 @@ export interface IVolumetricShaderEnvironment {
     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.
+     * engine can't render to a float one.
      */
     linearDepthPacked: boolean;
     /**
@@ -245,7 +245,11 @@ export interface IVolumetricShaderEnvironment {
      */
     arrayLightCapacity: number;
     /**
-     * Defines the number of samples taken across the volume of each point and spot light.
+     * Defines the number of steps the directional lights are marched with each frame. @see getVolumetricSamplingSteps
+     */
+    steps: number;
+    /**
+     * Defines the number of samples taken across the volume of each point and spot light each frame.
      */
     lightSteps: number;
 }

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

@@ -7,6 +7,10 @@ export declare function buildVolumetricLightingLinearDepthShaderWGSL(): string;
  * @param shadowSlotCount defines the number of shadowed light slots the shader is generated for.
  */
 export declare function buildVolumetricLightingScatteringShaderWGSL(shadowSlotCount: number): string;
+/**
+ * The temporal accumulation pass. @see buildVolumetricLightingTemporalShader.
+ */
+export declare function buildVolumetricLightingTemporalShaderWGSL(): string;
 /**
  * The separable bilateral blur pass. @see buildVolumetricLightingBlurShader.
  */
@@ -16,6 +20,6 @@ export declare function buildVolumetricLightingBlurShaderWGSL(): string;
  */
 export declare function buildVolumetricLightingComposeShaderWGSL(): string;
 /**
- * Returns the four WGSL sources of the pipeline, keyed by the name they are registered under.
+ * Returns the WGSL sources of the passes 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

@@ -7,6 +7,10 @@ export declare const volumetricLightingLinearDepthShaderName = "volumetricLighti
  * Defines the name of the raymarching shader in the shader store of Babylon.js.
  */
 export declare const volumetricLightingScatteringShaderName = "volumetricLightingScattering";
+/**
+ * Defines the name of the temporal accumulation shader in the shader store of Babylon.js.
+ */
+export declare const volumetricLightingTemporalShaderName = "volumetricLightingTemporal";
 /**
  * Defines the name of the bilateral blur shader in the shader store of Babylon.js.
  */
@@ -19,8 +23,8 @@ export declare const volumetricLightingComposeShaderName = "volumetricLightingCo
  * 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 source: a single 32 bits
- * channel is half the memory traffic of the 16 bits RGBA depth map, which matters for the thousands of reads
+ * Every later pass reads this texture instead of the depth map of the depth source: a single 16 bits
+ * channel is a fraction of the memory traffic of the 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.
  */
@@ -39,6 +43,16 @@ export declare function buildVolumetricLightingLinearDepthShader(): string;
  * @param shadowSlotCount defines the number of shadowed light slots the shader is generated for.
  */
 export declare function buildVolumetricLightingScatteringShader(shadowSlotCount: number): string;
+/**
+ * The temporal accumulation pass. Blends the scattering of the current frame, whose samples are offset from one
+ * frame to the next, with the scattering accumulated over the previous frames: the result converges to the
+ * integral the samples of all these frames estimate together, which is what lets each frame compute fewer of them.
+ *
+ * The history is reprojected on the current view, and clipped to the range of values the current frame shows
+ * around the pixel so that a moving light, a moving occluder or a surface revealed by the motion of the camera
+ * never leaves a trail. The blend follows the "factor" of the TAA rendering pipeline: the weight of the current frame.
+ */
+export declare function buildVolumetricLightingTemporalShader(): string;
 /**
  * The separable bilateral blur pass. Denoises the low resolution scattering buffer without letting the
  * light shafts bleed across the silhouettes of the geometry.

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

@@ -21,6 +21,12 @@ export declare const maxVolumetricArrayLights = 256;
  * point and spot lights, a directional light lights the whole view ray, so each one costs a full march.
  */
 export declare const maxVolumetricDirectionalLights = 4;
+/**
+ * Defines by how much the temporal accumulation divides the number of samples the raymarching computes each
+ * frame. The samples of consecutive frames are offset from each other, so the accumulated result still
+ * averages at least as many positions along each view ray as the configured steps.
+ */
+export declare const volumetricTemporalSamplesDivider = 3;
 /**
  * Defines the available step distributions used while raymarching the participating medium.
  */
@@ -168,16 +174,34 @@ export interface IVolumetricLightingConfiguration {
     stepDistribution: VolumetricStepDistribution;
     /**
      * Defines the dithering mode used to hide the banding produced by a low step count. @see VolumetricDitherMode
+     * With the temporal accumulation, "None" falls back on the interleaved gradient noise: the accumulation needs
+     * the samples of neighboring pixels to differ to tell the noise from the changes of the scene.
      */
     ditherMode: VolumetricDitherMode;
     /**
-     * Defines the strength of the dithering applied to the starting offset of the rays.
+     * Defines the strength of the dithering applied to the starting offset of the rays. Not used by the temporal
+     * accumulation, which always spreads the samples over their whole segment.
      */
     ditherStrength: number;
     /**
      * Defines wether or not the dithering pattern is animated over time. Requires temporal anti-aliasing to converge.
+     * Not used by the temporal accumulation, which animates the samples on its own.
      */
     temporalJitter: boolean;
+    /**
+     * Defines wether or not the light shafts are accumulated over the frames. Each frame only computes a fraction
+     * of the samples of the raymarching, offset from one frame to the next, and blends them with the result of the
+     * previous frames reprojected on the current view: the result converges to the quality of the configured
+     * steps, or better, for a fraction of their cost. @see volumetricTemporalSamplesDivider
+     */
+    temporalAccumulation: boolean;
+    /**
+     * Defines the weight of the current frame when it is blended with the accumulated previous frames, like the
+     * "factor" of the TAA rendering pipeline. Lower values average more frames, which gives smoother light shafts,
+     * but make them slower to follow the changes of the scene. The current frame weighs more than this while the
+     * camera moves quickly compared to the distance of what it looks at, so the light shafts never lag behind it.
+     */
+    temporalAccumulationFactor: number;
     /**
      * Defines how the density of the medium evolves with the distance to the camera. @see VolumetricFogMode
      */
@@ -330,6 +354,27 @@ export declare function getDefaultVolumetricLightingConfiguration(): IVolumetric
  * @param configuration defines the configuration of the pipeline.
  */
 export declare function getVolumetricLightSteps(configuration: IVolumetricLightingConfiguration): number;
+/**
+ * Defines the number of samples the raymarching computes for each pixel during a single frame.
+ */
+export interface IVolumetricSamplingSteps {
+    /**
+     * Defines the number of steps of the march of the directional lights, and the minimum density of samples
+     * along the view ray for the point and spot lights.
+     */
+    steps: number;
+    /**
+     * Defines the number of samples taken across the volume of each point and spot light.
+     */
+    lightSteps: number;
+}
+/**
+ * Returns the number of samples the raymarching computes each frame. With the temporal accumulation the
+ * configured values are divided, the history of the previous frames providing the samples each frame skips.
+ * @param configuration defines the configuration of the pipeline.
+ * @param temporalSamplesDivider defines by how much the temporal accumulation divides the number of samples.
+ */
+export declare function getVolumetricSamplingSteps(configuration: IVolumetricLightingConfiguration, temporalSamplesDivider?: number): IVolumetricSamplingSteps;
 /**
  * Normalizes the given serialized per-light volumetric configuration by merging it over the default one.
  * This is what makes projects saved by an older version of the editor load without any migration step.

package/declaration/src/rendering/volumetric-lighting.d.ts

@@ -1,7 +1,7 @@
 import { Scene } from "@babylonjs/core/scene";
 import { Camera } from "@babylonjs/core/Cameras/camera";
-import { VolumetricLightingRenderingPipeline } from "./volumetric/pipeline";
 import { IRenderingOptions } from "./tools";
+import { VolumetricLightingRenderingPipeline } from "./volumetric/pipeline";
 export declare function getVolumetricLightingRenderingPipelineConfiguration(): any;
 export declare function setVolumetricLightingRenderingPipelineConfiguration(config: any): void;
 export declare function getVolumetricLightingRenderingPipeline(): VolumetricLightingRenderingPipeline | null;

package/declaration/src/tools/scene.d.ts

@@ -1,4 +1,5 @@
 import { Scene } from "@babylonjs/core/scene";
+import { AssetContainer } from "@babylonjs/core/assetContainer";
 /**
  * Returns the node with the given name in the given scene.
  * This method also retrieves light nodes from clustered light containers.
@@ -6,7 +7,7 @@ import { Scene } from "@babylonjs/core/scene";
  * @param scene defines the reference to the scene to search the node in.
  * @returns the node if found, otherwise null.
  */
-export declare function getNodeByName(name: string, scene: Scene): import("@babylonjs/core").Node | null;
+export declare function getNodeByName(name: string, scene: Scene, container?: AssetContainer | null): import("@babylonjs/core").Node | null;
 /**
  * Returns the node with the given id in the given scene.
  * This method also retrieves light nodes from clustered light containers.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "babylonjs-editor-tools",
-	"version": "5.5.1",
+	"version": "5.5.2",
 	"description": "Babylon.js Editor Tools is a set of tools to help you create, edit and manage your Babylon.js scenes made using the Babylon.js Editor",
 	"productName": "Babylon.js Editor Tools",
 	"scripts": {