@babylonjs/core 7.32.5 → 7.34.0

package/Rendering/IBLShadows/iblShadowsRenderPipeline.d.ts

@@ -13,56 +13,68 @@ interface IblShadowsSettings {
      * shadows but are more expensive to compute and require more memory.
      * The resolution is calculated as 2 to the power of this number.
      */
-    resolutionExp: number;
+    resolutionExp?: number;
     /**
      * The number of different directions to sample during the voxel tracing pass. Higher
      * values will result in better quality, more stable shadows but are more expensive to compute.
      */
-    sampleDirections: number;
+    sampleDirections?: number;
     /**
      * How dark the shadows are. 1.0 is full opacity, 0.0 is no shadows.
      */
-    shadowOpacity: number;
+    shadowOpacity?: number;
     /**
-     * How long the shadows remain in the scene. 0.0 is no persistence, 1.0 is full persistence.
+     * 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.
      */
-    shadowRemenance: number;
+    envRotation?: number;
+    /**
+     * A factor that controls how long the shadows remain in the scene.
+     * 0.0 is no persistence, 1.0 is full persistence.
+     * This value applies only while the camera is moving. Once stationary, the pipeline
+     * increases remanence automatically to help the shadows converge.
+     */
+    shadowRemanence?: number;
     /**
      * Render the voxel grid from 3 different axis. This will result in better quality shadows with fewer
      * bits of missing geometry.
      */
-    triPlanarVoxelization: boolean;
+    triPlanarVoxelization?: boolean;
     /**
-     * A multiplier for the render size of the shadows. Used for rendering lower-resolution shadows
-     * to increase performance. Should be a value between 0 and 1.
+     * A size multiplier for the internal shadow render targets (default 1.0). A value of 1.0 represents full-resolution.
+     * Scaling this below 1.0 will result in blurry shadows and potentially more artifacts but
+     * could help increase performance on less powerful GPU's.
      */
-    shadowRenderSizeFactor: number;
+    shadowRenderSizeFactor?: number;
     /**
      * Separate control for the opacity of the voxel shadows.
      */
-    voxelShadowOpacity: number;
+    voxelShadowOpacity?: number;
     /**
      * Include screen-space shadows in the IBL shadow pipeline. This adds sharp shadows to small details
      * but only applies close to a shadow-casting object.
      */
-    ssShadowsEnabled: boolean;
+    ssShadowsEnabled?: boolean;
     /**
      * The number of samples used in the screen space shadow pass.
      */
-    ssShadowSampleCount: number;
+    ssShadowSampleCount?: number;
     /**
-     * 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.
      */
-    ssShadowStride: number;
+    ssShadowStride?: number;
     /**
-     * The maximum distance a shadow can be cast in screen space. This should usually be kept small
-     * as screenspace shadows are mostly useful for small details.
+     * 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.
      */
-    ssShadowDistanceScale: number;
+    ssShadowDistanceScale?: number;
     /**
-     * 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.
      */
-    ssShadowThicknessScale: number;
+    ssShadowThicknessScale?: number;
 }
 /**
  * Voxel-based shadow rendering for IBL's.
@@ -105,7 +117,8 @@ export declare class IblShadowsRenderPipeline extends PostProcessRenderPipeline
      */
     voxelGridSize: number;
     /**
-     * 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(): void;
     /**
@@ -132,23 +145,27 @@ export declare class IblShadowsRenderPipeline extends PostProcessRenderPipeline
     /**
      * The number of samples used in the screen space shadow pass.
      */
-    get ssShadowSamples(): number;
-    set ssShadowSamples(value: number);
+    get ssShadowSampleCount(): number;
+    set ssShadowSampleCount(value: number);
     /**
-     * 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(): number;
     set ssShadowStride(value: number);
     private _sssMaxDistScale;
     /**
-     * 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(): number;
     set ssShadowDistanceScale(value: number);
     private _sssThicknessScale;
     /**
-     * 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(): number;
     set ssShadowThicknessScale(value: number);
@@ -204,12 +221,10 @@ export declare class IblShadowsRenderPipeline extends PostProcessRenderPipeline
     private _gbufferDebugEnabled;
     private _gBufferDebugSizeParams;
     /**
-     * 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(): boolean;
-    /**
-     * Turn on or off the debug view of the G-Buffer
-     */
     set gbufferDebugEnabled(enabled: boolean);
     /**
      * Turn on or off the debug view of the CDF importance sampling data
@@ -220,58 +235,48 @@ export declare class IblShadowsRenderPipeline extends PostProcessRenderPipeline
      */
     set importanceSamplingDebugEnabled(enabled: boolean);
     /**
-     * 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(): boolean;
-    /**
-     * Turn on or off the debug view of the voxel grid
-     */
     set voxelDebugEnabled(enabled: boolean);
     /**
-     * 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(): number;
-    /**
-     * 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: number);
     /**
-     * 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: number);
     /**
-     * Display the debug view for the voxel tracing pass
+     * Display the debug view for just the shadow samples taken this frame.
      */
     get voxelTracingDebugEnabled(): boolean;
-    /**
-     * Display the debug view for the voxel tracing pass
-     */
     set voxelTracingDebugEnabled(enabled: boolean);
     /**
      * Display the debug view for the spatial blur pass
      */
     get spatialBlurPassDebugEnabled(): boolean;
-    /**
-     * Display the debug view for the spatial blur pass
-     */
     set spatialBlurPassDebugEnabled(enabled: boolean);
     /**
-     * Display the debug view for the accumulation pass
+     * Display the debug view for the shadows accumulated over time.
      */
     get accumulationPassDebugEnabled(): boolean;
-    /**
-     * Display the debug view for the accumulation pass
-     */
     set accumulationPassDebugEnabled(enabled: boolean);
     /**
-     * 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: Mesh | Mesh[]): void;
     /**
-     * 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: Mesh | Mesh[]): void;
@@ -281,11 +286,6 @@ export declare class IblShadowsRenderPipeline extends PostProcessRenderPipeline
      * The resolution is calculated as 2 to the power of this number.
      */
     get resolutionExp(): number;
-    /**
-     * 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: number);
     /**
      * The number of different directions to sample during the voxel tracing pass
@@ -298,17 +298,17 @@ export declare 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(): number;
+    get shadowRemanence(): number;
     /**
      * The decree to which the shadows persist between frames. 0.0 is no persistence, 1.0 is full persistence.
      **/
-    set shadowRemenance(value: number);
+    set shadowRemanence(value: number);
     /**
-     * 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(): number;
     /**
-     * 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: number);
     /**
@@ -323,6 +323,19 @@ export declare class IblShadowsRenderPipeline extends PostProcessRenderPipeline
      *  Support test.
      */
     static get IsSupported(): boolean;
+    /**
+     * Toggle the shadow tracing on or off
+     * @param enabled Toggle the shadow tracing on or off
+     */
+    toggleShadow(enabled: boolean): void;
+    /**
+     * Trigger the scene to be re-voxelized. This should be run when any shadow-casters have been added, removed or moved.
+     */
+    updateVoxelization(): void;
+    /**
+     * 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(): void;
     /**
      * @param name The rendering pipeline name
      * @param scene The scene linked to this pipeline
@@ -330,39 +343,27 @@ export declare class IblShadowsRenderPipeline extends PostProcessRenderPipeline
      * @param cameras Cameras to apply the pipeline to.
      */
     constructor(name: string, scene: Scene, options?: Partial<IblShadowsSettings>, cameras?: Camera[]);
-    /**
-     * Toggle the shadow tracing on or off
-     * @param enabled Toggle the shadow tracing on or off
-     */
-    toggleShadow(enabled: boolean): void;
     private _handleResize;
     private _getGBufferDebugPass;
     private _createDebugPasses;
     private _disposeEffectPasses;
     private _disposeDebugPasses;
     private _updateDebugPasses;
-    /**
-     * Trigger the scene to be re-voxelized. This is useful when the scene has changed and the voxel grid needs to be updated.
-     */
-    updateVoxelization(): void;
-    /**
-     * 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(): void;
     /**
      * 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.
      */
     private _updateSSShadowParams;
     /**
-     * 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?: Material | Material[]): void;
     /**
-     * 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: Material | Material[]): void;
     protected _addShadowSupportToMaterial(material: Material): void;