@babylonjs/core 7.33.0 → 7.34.0

package/Rendering/IBLShadows/iblShadowsRenderPipeline.js

@@ -25,7 +25,8 @@ import { Observable } from "../../Misc/observable.js";
  */
 export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
     /**
-     * Reset the shadow accumulation.
+     * Reset the shadow accumulation. This has a similar affect to lowering the remanence for a single frame.
+     * This is useful when making a sudden change to the IBL.
      */
     resetAccumulation() {
         this._accumulationPass.reset = true;
@@ -78,16 +79,17 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
     /**
      * The number of samples used in the screen space shadow pass.
      */
-    get ssShadowSamples() {
+    get ssShadowSampleCount() {
         return this._voxelTracingPass?.sssSamples;
     }
-    set ssShadowSamples(value) {
+    set ssShadowSampleCount(value) {
         if (!this._voxelTracingPass)
             return;
         this._voxelTracingPass.sssSamples = value;
     }
     /**
-     * The stride of the screen-space shadow pass. This controls the distance between samples.
+     * The stride of the screen-space shadow pass. This controls the distance between samples
+     * in pixels.
      */
     get ssShadowStride() {
         return this._voxelTracingPass?.sssStride;
@@ -98,8 +100,9 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         this._voxelTracingPass.sssStride = value;
     }
     /**
-     * A scale for the maximum distance a shadow can be cast in screen space.
-     * The absolute distance for SS shadows is derived from the voxel size and this scalar.
+     * A scale for the maximum distance a screen-space shadow can be cast in world-space.
+     * The maximum distance that screen-space shadows cast is derived from the voxel size
+     * and this value so shouldn't need to change if you scale your scene
      */
     get ssShadowDistanceScale() {
         return this._sssMaxDistScale;
@@ -109,7 +112,9 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         this._updateSSShadowParams();
     }
     /**
-     * Screen-space shadow thickness. This value controls the perceived thickness of the SS shadows.
+     * Screen-space shadow thickness scale. This value controls the assumed thickness of
+     * on-screen surfaces in world-space. It scales with the size of the shadow-casting
+     * region so shouldn't need to change if you scale your scene.
      */
     get ssShadowThicknessScale() {
         return this._sssThicknessScale;
@@ -213,14 +218,12 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         return this._dummyTexture2d;
     }
     /**
-     * Is the debug view of the G-Buffer enabled?
+     * Turn on or off the debug view of the G-Buffer. This will display only the targets
+     * of the g-buffer that are used by the shadow pipeline.
      */
     get gbufferDebugEnabled() {
         return this._gbufferDebugEnabled;
     }
-    /**
-     * Turn on or off the debug view of the G-Buffer
-     */
     set gbufferDebugEnabled(enabled) {
         if (enabled && !this.allowDebugPasses) {
             Logger.Warn("Can't enable G-Buffer debug view without setting allowDebugPasses to true.");
@@ -261,14 +264,14 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         }
     }
     /**
-     * Turn on or off the debug view of the voxel grid
+     * This displays the voxel grid in slices spread across the screen.
+     * It also displays what slices of the model are stored in each layer
+     * of the voxel grid. Each red stripe represents one layer while each gradient
+     * (from bright red to black) represents the layers rendered in a single draw call.
      */
     get voxelDebugEnabled() {
         return this._voxelRenderer?.voxelDebugEnabled;
     }
-    /**
-     * Turn on or off the debug view of the voxel grid
-     */
     set voxelDebugEnabled(enabled) {
         if (!this._voxelRenderer)
             return;
@@ -285,23 +288,20 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         }
     }
     /**
-     * Set the axis to display for the voxel grid debug view
-     * When using tri-axis voxelization, this will display the voxel grid for the specified axis
+     * When using tri-planar voxelization (the default), this value can be used to
+     * display only the voxelization result for that axis. z-axis = 0, y-axis = 1, x-axis = 2
      */
     get voxelDebugAxis() {
         return this._voxelRenderer?.voxelDebugAxis;
     }
-    /**
-     * Set the axis to display for the voxel grid debug view
-     * When using tri-axis voxelization, this will display the voxel grid for the specified axis
-     */
     set voxelDebugAxis(axisNum) {
         if (!this._voxelRenderer)
             return;
         this._voxelRenderer.voxelDebugAxis = axisNum;
     }
     /**
-     * Set the mip level to display for the voxel grid debug view
+     * Displays a given mip of the voxel grid. `voxelDebugAxis` must be undefined in this
+     * case because we only generate mips for the combined voxel grid.
      */
     set voxelDebugDisplayMip(mipNum) {
         if (!this._voxelRenderer)
@@ -309,14 +309,11 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         this._voxelRenderer.setDebugMipNumber(mipNum);
     }
     /**
-     * Display the debug view for the voxel tracing pass
+     * Display the debug view for just the shadow samples taken this frame.
      */
     get voxelTracingDebugEnabled() {
         return this._voxelTracingPass?.debugEnabled;
     }
-    /**
-     * Display the debug view for the voxel tracing pass
-     */
     set voxelTracingDebugEnabled(enabled) {
         if (!this._voxelTracingPass)
             return;
@@ -340,9 +337,6 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
     get spatialBlurPassDebugEnabled() {
         return this._spatialBlurPass.debugEnabled;
     }
-    /**
-     * Display the debug view for the spatial blur pass
-     */
     set spatialBlurPassDebugEnabled(enabled) {
         if (!this._spatialBlurPass)
             return;
@@ -361,14 +355,11 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         }
     }
     /**
-     * Display the debug view for the accumulation pass
+     * Display the debug view for the shadows accumulated over time.
      */
     get accumulationPassDebugEnabled() {
         return this._accumulationPass?.debugEnabled;
     }
-    /**
-     * Display the debug view for the accumulation pass
-     */
     set accumulationPassDebugEnabled(enabled) {
         if (!this._accumulationPass)
             return;
@@ -387,7 +378,8 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         }
     }
     /**
-     * Add a mesh to be used for shadow casting in the IBL shadow pipeline
+     * Add a mesh to be used for shadow-casting in the IBL shadow pipeline.
+     * These meshes will be written to the voxel grid.
      * @param mesh A mesh or list of meshes that you want to cast shadows
      */
     addShadowCastingMesh(mesh) {
@@ -405,7 +397,8 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         }
     }
     /**
-     * Remove a mesh from the shadow-casting list.
+     * Remove a mesh from the shadow-casting list. The mesh will no longer be written
+     * to the voxel grid and will not cast shadows.
      * @param mesh The mesh or list of meshes that you don't want to cast shadows.
      */
     removeShadowCastingMesh(mesh) {
@@ -432,11 +425,6 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
     get resolutionExp() {
         return this._voxelRenderer.voxelResolutionExp;
     }
-    /**
-     * The exponent of the resolution of the voxel shadow grid. Higher resolutions will result in sharper
-     * shadows but are more expensive to compute and require more memory.
-     * The resolution is calculated as 2 to the power of this number.
-     */
     set resolutionExp(newResolution) {
         if (newResolution === this._voxelRenderer.voxelResolutionExp)
             return;
@@ -444,7 +432,7 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
             Logger.Warn("Can't change the resolution of the voxel grid while voxelization is in progress.");
             return;
         }
-        this._voxelRenderer.voxelResolutionExp = newResolution;
+        this._voxelRenderer.voxelResolutionExp = Math.max(1, Math.min(newResolution, 8));
         this._accumulationPass.reset = true;
     }
     /**
@@ -464,25 +452,25 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
     /**
      * The decree to which the shadows persist between frames. 0.0 is no persistence, 1.0 is full persistence.
      **/
-    get shadowRemenance() {
-        return this._accumulationPass?.remenance;
+    get shadowRemanence() {
+        return this._accumulationPass?.remanence;
     }
     /**
      * The decree to which the shadows persist between frames. 0.0 is no persistence, 1.0 is full persistence.
      **/
-    set shadowRemenance(value) {
+    set shadowRemanence(value) {
         if (!this._accumulationPass)
             return;
-        this._accumulationPass.remenance = value;
+        this._accumulationPass.remanence = value;
     }
     /**
-     * The global rotation of the IBL for shadows
+     * The global Y-axis rotation of the IBL for shadows. This should match the Y-rotation of the environment map applied to materials, skybox, etc.
      */
     get envRotation() {
         return this._voxelTracingPass?.envRotation;
     }
     /**
-     * The global rotation of the IBL for shadows
+     * The global Y-axis rotation of the IBL for shadows. This should match the Y-rotation of the environment map applied to materials, skybox, etc.
      */
     set envRotation(value) {
         if (!this._voxelTracingPass)
@@ -527,6 +515,65 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         }
         return engine._features.supportIBLShadows;
     }
+    /**
+     * Toggle the shadow tracing on or off
+     * @param enabled Toggle the shadow tracing on or off
+     */
+    toggleShadow(enabled) {
+        this._enabled = enabled;
+        this._voxelTracingPass.enabled = enabled;
+        this._spatialBlurPass.enabled = enabled;
+        this._accumulationPass.enabled = enabled;
+        this._materialsWithRenderPlugin.forEach((mat) => {
+            if (mat.pluginManager) {
+                const plugin = mat.pluginManager.getPlugin(IBLShadowsPluginMaterial.Name);
+                plugin.isEnabled = enabled;
+            }
+        });
+        this._setPluginParameters();
+    }
+    /**
+     * Trigger the scene to be re-voxelized. This should be run when any shadow-casters have been added, removed or moved.
+     */
+    updateVoxelization() {
+        if (this._shadowCastingMeshes.length === 0) {
+            Logger.Warn("IBL Shadows: updateVoxelization called with no shadow-casting meshes to voxelize.");
+            return;
+        }
+        this._voxelRenderer.updateVoxelGrid(this._shadowCastingMeshes);
+        this._updateSSShadowParams();
+    }
+    /**
+     * Trigger the scene bounds of shadow-casters to be calculated. This is the world size that the voxel grid will cover and will always be a cube.
+     */
+    updateSceneBounds() {
+        const bounds = {
+            min: new Vector3(Number.MAX_VALUE, Number.MAX_VALUE, Number.MAX_VALUE),
+            max: new Vector3(-Number.MAX_VALUE, -Number.MAX_VALUE, -Number.MAX_VALUE),
+        };
+        this._shadowCastingMeshes.forEach((mesh) => {
+            const localBounds = mesh.getHierarchyBoundingVectors(true);
+            bounds.min = Vector3.Minimize(bounds.min, localBounds.min);
+            bounds.max = Vector3.Maximize(bounds.max, localBounds.max);
+        });
+        const size = bounds.max.subtract(bounds.min);
+        this.voxelGridSize = Math.max(size.x, size.y, size.z);
+        if (this._shadowCastingMeshes.length === 0 || !isFinite(this.voxelGridSize) || this.voxelGridSize === 0) {
+            Logger.Warn("IBL Shadows: Scene size is invalid. Can't update bounds.");
+            this.voxelGridSize = 1.0;
+            return;
+        }
+        const halfSize = this.voxelGridSize / 2.0;
+        const centre = bounds.max.add(bounds.min).multiplyByFloats(-0.5, -0.5, -0.5);
+        const invWorldScaleMatrix = Matrix.Compose(new Vector3(1.0 / halfSize, 1.0 / halfSize, 1.0 / halfSize), new Quaternion(), new Vector3(0, 0, 0));
+        const invTranslationMatrix = Matrix.Compose(new Vector3(1.0, 1.0, 1.0), new Quaternion(), centre);
+        invTranslationMatrix.multiplyToRef(invWorldScaleMatrix, invWorldScaleMatrix);
+        this._voxelTracingPass.setWorldScaleMatrix(invWorldScaleMatrix);
+        this._voxelRenderer.setWorldScaleMatrix(invWorldScaleMatrix);
+        // Set world scale for spatial blur.
+        this._spatialBlurPass.setWorldScale(halfSize * 2.0);
+        this._updateSSShadowParams();
+    }
     /**
      * @param name The rendering pipeline name
      * @param scene The scene linked to this pipeline
@@ -602,13 +649,14 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         });
         this.sampleDirections = options.sampleDirections || 2;
         this.voxelShadowOpacity = options.voxelShadowOpacity ?? 1.0;
+        this.envRotation = options.envRotation ?? 0.0;
         this.shadowRenderSizeFactor = options.shadowRenderSizeFactor || 1.0;
         this.ssShadowOpacity = options.ssShadowsEnabled === undefined || options.ssShadowsEnabled ? 1.0 : 0.0;
         this.ssShadowDistanceScale = options.ssShadowDistanceScale || 1.25;
-        this.ssShadowSamples = options.ssShadowSampleCount || 16;
+        this.ssShadowSampleCount = options.ssShadowSampleCount || 16;
         this.ssShadowStride = options.ssShadowStride || 8;
         this.ssShadowThicknessScale = options.ssShadowThicknessScale || 1.0;
-        this.shadowRemenance = options.shadowRemenance ?? 0.75;
+        this.shadowRemanence = options.shadowRemanence ?? 0.75;
         this._noiseTexture = new Texture("https://assets.babylonjs.com/textures/blue_noise/blue_noise_rgb.png", this.scene, false, true, 1);
         if (this.scene.environmentTexture) {
             this._importanceSamplingRenderer.iblSource = this.scene.environmentTexture;
@@ -624,23 +672,6 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
             this.onNewIblReadyObservable.notifyObservers();
         });
     }
-    /**
-     * Toggle the shadow tracing on or off
-     * @param enabled Toggle the shadow tracing on or off
-     */
-    toggleShadow(enabled) {
-        this._enabled = enabled;
-        this._voxelTracingPass.enabled = enabled;
-        this._spatialBlurPass.enabled = enabled;
-        this._accumulationPass.enabled = enabled;
-        this._materialsWithRenderPlugin.forEach((mat) => {
-            if (mat.pluginManager) {
-                const plugin = mat.pluginManager.getPlugin(IBLShadowsPluginMaterial.Name);
-                plugin.isEnabled = enabled;
-            }
-        });
-        this._setPluginParameters();
-    }
     _handleResize() {
         this._voxelRenderer.resize();
         this._voxelTracingPass.resize(this.shadowRenderSizeFactor);
@@ -803,49 +834,6 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
             }
         }
     }
-    /**
-     * Trigger the scene to be re-voxelized. This is useful when the scene has changed and the voxel grid needs to be updated.
-     */
-    updateVoxelization() {
-        if (this._shadowCastingMeshes.length === 0) {
-            Logger.Warn("IBL Shadows: updateVoxelization called with no shadow-casting meshes to voxelize.");
-            return;
-        }
-        this._voxelRenderer.updateVoxelGrid(this._shadowCastingMeshes);
-        this._updateSSShadowParams();
-    }
-    /**
-     * Trigger the scene bounds of shadow-casters to be updated. This is useful when the scene has changed and the bounds need
-     * to be recalculated. This will also trigger a re-voxelization.
-     */
-    updateSceneBounds() {
-        const bounds = {
-            min: new Vector3(Number.MAX_VALUE, Number.MAX_VALUE, Number.MAX_VALUE),
-            max: new Vector3(-Number.MAX_VALUE, -Number.MAX_VALUE, -Number.MAX_VALUE),
-        };
-        this._shadowCastingMeshes.forEach((mesh) => {
-            const localBounds = mesh.getHierarchyBoundingVectors(true);
-            bounds.min = Vector3.Minimize(bounds.min, localBounds.min);
-            bounds.max = Vector3.Maximize(bounds.max, localBounds.max);
-        });
-        const size = bounds.max.subtract(bounds.min);
-        this.voxelGridSize = Math.max(size.x, size.y, size.z);
-        if (this._shadowCastingMeshes.length === 0 || !isFinite(this.voxelGridSize) || this.voxelGridSize === 0) {
-            Logger.Warn("IBL Shadows: Scene size is invalid. Can't update bounds.");
-            this.voxelGridSize = 1.0;
-            return;
-        }
-        const halfSize = this.voxelGridSize / 2.0;
-        const centre = bounds.max.add(bounds.min).multiplyByFloats(-0.5, -0.5, -0.5);
-        const invWorldScaleMatrix = Matrix.Compose(new Vector3(1.0 / halfSize, 1.0 / halfSize, 1.0 / halfSize), new Quaternion(), new Vector3(0, 0, 0));
-        const invTranslationMatrix = Matrix.Compose(new Vector3(1.0, 1.0, 1.0), new Quaternion(), centre);
-        invTranslationMatrix.multiplyToRef(invWorldScaleMatrix, invWorldScaleMatrix);
-        this._voxelTracingPass.setWorldScaleMatrix(invWorldScaleMatrix);
-        this._voxelRenderer.setWorldScaleMatrix(invWorldScaleMatrix);
-        // Set world scale for spatial blur.
-        this._spatialBlurPass.setWorldScale(halfSize * 2.0);
-        this._updateSSShadowParams();
-    }
     /**
      * Update the SS shadow max distance and thickness based on the voxel grid size and resolution.
      * The max distance should be just a little larger than the world size of a single voxel.
@@ -855,7 +843,8 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         this._voxelTracingPass.sssThickness = this._sssThicknessScale * 0.005 * this.voxelGridSize;
     }
     /**
-     * Apply the shadows to a material or array of materials.
+     * Apply the shadows to a material or array of materials. If no material is provided, all
+     * materials in the scene will be added.
      * @param material Material that will be affected by the shadows. If not provided, all materials of the scene will be affected.
      */
     addShadowReceivingMaterial(material) {
@@ -876,8 +865,9 @@ export class IblShadowsRenderPipeline extends PostProcessRenderPipeline {
         }
     }
     /**
-     * Remove a material from receiving shadows
-     * @param material The material that will no longer receive shadows
+     * Remove a material from the list of materials that receive shadows. If no material
+     * is provided, all materials in the scene will be removed.
+     * @param material The material or array of materials that will no longer receive shadows
      */
     removeShadowReceivingMaterial(material) {
         if (Array.isArray(material)) {