API
API|
@babylonjs/core|
CascadedShadowGenerator

Class CascadedShadowGenerator

A CSM implementation allowing casting shadows on large scenes. Documentation : https://doc.babylonjs.com/babylon101/cascadedShadows Based on: https://github.com/TheRealMJP/Shadows and https://johanmedestrom.wordpress.com/2016/03/18/opengl-cascaded-shadow-maps/

Hierarchy (View Summary)

Index
constructor
customAllowRendering customShaderOptions doNotSerialize enableSoftTransparentShadow forceBackFacesOnly frustumEdgeFalloff id onAfterShadowMapRenderMeshObservable onAfterShadowMapRenderObservable onBeforeShadowMapRenderMeshObservable onBeforeShadowMapRenderObservable penumbraDarkness stabilizeCascades useOpacityTextureForTransparentShadow CLASSNAME DEFAULT_ALPHA_CUTOFF DEFAULT_CASCADES_COUNT FILTER_BLURCLOSEEXPONENTIALSHADOWMAP FILTER_BLUREXPONENTIALSHADOWMAP FILTER_CLOSEEXPONENTIALSHADOWMAP FILTER_EXPONENTIALSHADOWMAP FILTER_NONE FILTER_PCF FILTER_PCSS FILTER_POISSONSAMPLING ForceGLSL MAX_CASCADES_COUNT MIN_CASCADES_COUNT QUALITY_HIGH QUALITY_LOW QUALITY_MEDIUM
autoCalcDepthBounds autoCalcDepthBoundsRefreshRate bias blurBoxOffset blurKernel blurScale camera cascadeBlendPercentage contactHardeningLightSizeUVRatio darkness debug depthClamp depthScale filter filteringQuality freezeShadowCastersBoundingInfo lambda light mapSize maxDistance minDistance normalBias numCascades projectionMatrix shaderLanguage shadowCastersBoundingInfo shadowMaxZ transparencyShadow useBlurCloseExponentialShadowMap useBlurExponentialShadowMap useCloseExponentialShadowMap useContactHardeningShadow useExponentialShadowMap useFloat32TextureType useKernelBlur usePercentageCloserFiltering usePoissonSampling useRedTextureFormat viewMatrix IsSupported
addShadowCaster bindShadowLight dispose forceCompilation forceCompilationAsync getCascadeMaxExtents getCascadeMinExtents getCascadeProjectionMatrix getCascadeTransformMatrix getCascadeViewMatrix getClassName getDarkness getLight getShadowMap getShadowMapForRendering getTransformMatrix isReady prepareDefines recreateShadowMap removeShadowCaster serialize setDarkness setDepthRenderer setMinMaxDistance setTransparencyShadow splitFrustum Parse

  • Creates a Cascaded Shadow Generator object. A ShadowGenerator is the required tool to use the shadows. Each directional light casting shadows needs to use its own ShadowGenerator. Documentation : https://doc.babylonjs.com/babylon101/cascadedShadows

    Parameters

    • mapSize: number

      The size of the texture what stores the shadows. Example : 1024.

    • light: DirectionalLight

      The directional light object generating the shadows.

    • OptionalusefulFloatFirst: boolean

      By default the generator will try to use half float textures but if you need precision (for self shadowing for instance), you can use this option to enforce full float texture.

    • Optionalcamera: Nullable<Camera>

      Camera associated with this shadow generator (default: null). If null, takes the scene active camera at the time we need to access it

    • useRedTextureType: boolean = true

      Forces the generator to use a Red instead of a RGBA type for the shadow map texture format (default: true)

    Returns CascadedShadowGenerator

customAllowRendering: (subMesh: SubMesh) => boolean

Gets or sets a custom function to allow/disallow rendering a sub mesh in the shadow map

customShaderOptions: ICustomShaderOptions

Gets or sets the custom shader name to use

doNotSerialize: boolean = false

Specifies if the ShadowGenerator should be serialized, true to skip serialization. Note a ShadowGenerator will not be serialized if its light has doNotSerialize=true

enableSoftTransparentShadow: boolean = false

Enables or disables shadows with varying strength based on the transparency When it is enabled, the strength of the shadow is taken equal to mesh.visibility If you enabled an alpha texture on your material, the alpha value red from the texture is also combined to compute the strength: mesh.visibility * alphaTexture.a The texture used is the diffuse by default, but it can be set to the opacity by setting useOpacityTextureForTransparentShadow Note that by definition transparencyShadow must be set to true for enableSoftTransparentShadow to work!

forceBackFacesOnly: boolean = false

If true the shadow map is generated by rendering the back face of the mesh instead of the front face. This can help with self-shadowing as the geometry making up the back of objects is slightly offset. It might on the other hand introduce peter panning.

frustumEdgeFalloff: number = 0

Controls the extent to which the shadows fade out at the edge of the frustum

id: string

Gets or set the id of the shadow generator. It will be the one from the light if not defined

onAfterShadowMapRenderMeshObservable: Observable<Mesh> = ...

Observable triggered after a mesh is rendered in the shadow map. Can be used to update internal effect state (that you can get from the onAfterShadowMapRenderObservable)

onAfterShadowMapRenderObservable: Observable<Effect> = ...

Observable triggered after the shadow is rendered. Can be used to restore internal effect state

onBeforeShadowMapRenderMeshObservable: Observable<Mesh> = ...

Observable triggered before a mesh is rendered in the shadow map. Can be used to update internal effect state (that you can get from the onBeforeShadowMapRenderObservable)

onBeforeShadowMapRenderObservable: Observable<Effect> = ...

Observable triggered before the shadow is rendered. Can be used to update internal effect state

penumbraDarkness: number

Gets or sets the actual darkness of the soft shadows while using PCSS filtering (value between 0. and 1.)

stabilizeCascades: boolean

Sets this to true if you want that the edges of the shadows don't "swimm" / "shimmer" when rotating the camera. The trade off is that you lose some precision in the shadow rendering when enabling this setting.

useOpacityTextureForTransparentShadow: boolean = false

If this is true, use the opacity texture's alpha channel for transparent shadows instead of the diffuse one

CLASSNAME: string = "CascadedShadowGenerator"

Name of the CSM class

DEFAULT_ALPHA_CUTOFF: number = 0.5

Defines the default alpha cutoff value used for transparent alpha tested materials.

DEFAULT_CASCADES_COUNT: 4

Defines the default number of cascades used by the CSM.

FILTER_BLURCLOSEEXPONENTIALSHADOWMAP: 5

Shadow generator mode ESM: Blurred Exponential Shadow Mapping using the inverse of the exponential preventing edge artifacts on steep falloff. (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)

FILTER_BLUREXPONENTIALSHADOWMAP: 3

Shadow generator mode ESM: Blurred Exponential Shadow Mapping. (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)

FILTER_CLOSEEXPONENTIALSHADOWMAP: 4

Shadow generator mode ESM: Exponential Shadow Mapping using the inverse of the exponential preventing edge artifacts on steep falloff. (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)

FILTER_EXPONENTIALSHADOWMAP: 1

Shadow generator mode ESM: Exponential Shadow Mapping. (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)

FILTER_NONE: 0

Shadow generator mode None: no filtering applied.

FILTER_PCF: 6

Shadow generator mode PCF: Percentage Closer Filtering benefits from Webgl 2 shadow samplers. Fallback to Poisson Sampling in Webgl 1 (https://developer.nvidia.com/gpugems/GPUGems/gpugems_ch11.html)

FILTER_PCSS: 7

Shadow generator mode PCSS: Percentage Closering Soft Shadow. benefits from Webgl 2 shadow samplers. Fallback to Poisson Sampling in Webgl 1 Contact Hardening

FILTER_POISSONSAMPLING: 2

Shadow generator mode Poisson Sampling: Percentage Closer Filtering. (Multiple Tap around evenly distributed around the pixel are used to evaluate the shadow strength)

ForceGLSL: boolean = false

Force all the shadow generators to compile to glsl even on WebGPU engines. False by default. This is mostly meant for backward compatibility.

MAX_CASCADES_COUNT: number = 4

Defines the maximum number of cascades used by the CSM.

MIN_CASCADES_COUNT: number = 2

Defines the minimum number of cascades used by the CSM.

QUALITY_HIGH: 0

Reserved for PCF and PCSS Highest Quality.

Execute PCF on a 5*5 kernel improving a lot the shadow aliasing artifacts.

Execute PCSS with 32 taps blocker search and 64 taps PCF.

QUALITY_LOW: 2

Reserved for PCF and PCSS The lowest quality but the fastest.

Execute PCF on a 1*1 kernel.

Execute PCSS with 16 taps blocker search and 16 taps PCF.

QUALITY_MEDIUM: 1

Reserved for PCF and PCSS Good tradeoff for quality/perf cross devices

Execute PCF on a 3*3 kernel.

Execute PCSS with 16 taps blocker search and 32 taps PCF.

  • get autoCalcDepthBounds(): boolean

    Gets or sets the autoCalcDepthBounds property.

    When enabled, a depth rendering pass is first performed (with an internally created depth renderer or with the one you provide by calling setDepthRenderer). Then, a min/max reducing is applied on the depth map to compute the minimal and maximal depth of the map and those values are used as inputs for the setMinMaxDistance() function. It can greatly enhance the shadow quality, at the expense of more GPU works. When using this option, you should increase the value of the lambda parameter, and even set it to 1 for best results.

    Returns boolean

  • set autoCalcDepthBounds(value: boolean): void

    Parameters

    • value: boolean

    Returns void

  • get contactHardeningLightSizeUVRatio(): number

    Gets the Light Size (in shadow map uv unit) used in PCSS to determine the blocker search area and the penumbra size. Using a ratio helps keeping shape stability independently of the map size.

    It does not account for the light projection as it was having too much instability during the light setup or during light position changes.

    Only valid if useContactHardeningShadow is true.

    Returns number

  • set contactHardeningLightSizeUVRatio(
        contactHardeningLightSizeUVRatio: number,
    ): void

    Sets the Light Size (in shadow map uv unit) used in PCSS to determine the blocker search area and the penumbra size. Using a ratio helps keeping shape stability independently of the map size.

    It does not account for the light projection as it was having too much instability during the light setup or during light position changes.

    Only valid if useContactHardeningShadow is true.

    Parameters

    • contactHardeningLightSizeUVRatio: number

    Returns void

  • get filter(): number

    Gets the current mode of the shadow generator (normal, PCF, ESM...). The returned value is a number equal to one of the available mode defined in ShadowMap.FILTER_x like _FILTER_NONE

    Returns number

  • set filter(value: number): void

    Sets the current mode of the shadow generator (normal, PCF, ESM...). The returned value is a number equal to one of the available mode defined in ShadowMap.FILTER_x like _FILTER_NONE

    Parameters

    • value: number

    Returns void

  • get filteringQuality(): number

    Gets the PCF or PCSS Quality. Only valid if usePercentageCloserFiltering or usePercentageCloserFiltering is true.

    Returns number

  • set filteringQuality(filteringQuality: number): void

    Sets the PCF or PCSS Quality. Only valid if usePercentageCloserFiltering or usePercentageCloserFiltering is true.

    Parameters

    • filteringQuality: number

    Returns void

  • get normalBias(): number

    Gets the normalBias: offset applied on the depth preventing acnea (along side the normal direction and proportional to the light/normal angle).

    Returns number

  • set normalBias(normalBias: number): void

    Sets the normalBias: offset applied on the depth preventing acnea (along side the normal direction and proportional to the light/normal angle).

    Parameters

    • normalBias: number

    Returns void

  • get useBlurCloseExponentialShadowMap(): boolean

    Gets if the current filter is set to filtered "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).

    Returns boolean

  • set useBlurCloseExponentialShadowMap(value: boolean): void

    Sets the current filter to filtered "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).

    Parameters

    • value: boolean

    Returns void

  • get useCloseExponentialShadowMap(): boolean

    Gets if the current filter is set to "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).

    Returns boolean

  • set useCloseExponentialShadowMap(value: boolean): void

    Sets the current filter to "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).

    Parameters

    • value: boolean

    Returns void

  • get useFloat32TextureType(): boolean

    Gets or sets a value indicating whether the shadow map should use full float texture type (instead of half float, which is the default). Use this option when you need more precision (for self shadowing, for instance).

    Returns boolean

  • set useFloat32TextureType(useFloat32TextureType: boolean): void

    Parameters

    • useFloat32TextureType: boolean

    Returns void

  • get useKernelBlur(): boolean

    Gets whether the blur pass is a kernel blur (if true) or box blur. Only useful in filtered mode (useBlurExponentialShadowMap...)

    Returns boolean

  • set useKernelBlur(value: boolean): void

    Sets whether the blur pass is a kernel blur (if true) or box blur. Only useful in filtered mode (useBlurExponentialShadowMap...)

    Parameters

    • value: boolean

    Returns void

  • get useRedTextureFormat(): boolean

    Gets or sets a value indicating whether the shadow map should use a red-channel-only texture format. Using a single-channel format reduces memory usage when color data is not needed.

    Returns boolean

  • set useRedTextureFormat(useRedTextureFormat: boolean): void

    Parameters

    • useRedTextureFormat: boolean

    Returns void

  • Forces all the attached effect to compile to enable rendering only once ready vs. lazily compiling effects.

    Parameters

    • OptionalonCompiled: (generator: IShadowGenerator) => void

      Callback triggered at the and of the effects compilation

    • Optionaloptions: Partial<{ useInstances: boolean }>

      Sets of optional options forcing the compilation with different modes

    Returns void

  • Forces all the attached effect to compile to enable rendering only once ready vs. lazily compiling effects.

    Parameters

    • Optionaloptions: Partial<{ useInstances: boolean }>

      Sets of optional options forcing the compilation with different modes

    Returns Promise<void>

    A promise that resolves when the compilation completes

  • Determine whether the shadow generator is ready or not (mainly all effects and related post processes needs to be ready).

    Parameters

    • subMesh: SubMesh

      The submesh we want to render in the shadow map

    • useInstances: boolean

      Defines whether will draw in the map using instances

    • isTransparent: boolean

      Indicates that isReady is called for a transparent subMesh

    Returns boolean

    true if ready otherwise, false

  • Sets the depth renderer to use when autoCalcDepthBounds is enabled.

    Note that if no depth renderer is set, a new one will be automatically created internally when necessary.

    You should call this function if you already have a depth renderer enabled in your scene, to avoid doing multiple depth rendering each frame. If you provide your own depth renderer, make sure it stores linear depth!

    Parameters

    • depthRenderer: Nullable<DepthRenderer>

      The depth renderer to use when autoCalcDepthBounds is enabled. If you pass null or don't call this function at all, a depth renderer will be automatically created

    Returns void

  • Sets the minimal and maximal distances to use when computing the cascade breaks.

    The values of min / max are typically the depth zmin and zmax values of your scene, for a given frame. If you don't know these values, simply leave them to their defaults and don't call this function.

    Parameters

    • min: number

      minimal distance for the breaks (default to 0.)

    • max: number

      maximal distance for the breaks (default to 1.)

    Returns void

  • Create the cascade breaks according to the lambda, shadowMaxZ and min/max distance properties, as well as the camera near and far planes. This function is automatically called when updating lambda, shadowMaxZ and min/max distances, however you should call it yourself if you change the camera near/far planes!

    Returns void