Class ShadowGenerator
Hierarchy
- ShadowGenerator
Implements
Index
Constructors
Properties
- custom
Allow Rendering - custom
Shader Options - enable
Soft Transparent Shadow - force
Back Faces Only - frustum
Edge Falloff - id
- on
After Shadow Map Render Mesh Observable - on
After Shadow Map Render Observable - on
Before Shadow Map Render Mesh Observable - on
Before Shadow Map Render Observable - use
Opacity Texture For Transparent Shadow - CLASSNAME
- DEFAULT_
ALPHA_ CUTOFF - FILTER_
BLURCLOSEEXPONENTIALSHADOWMAP - FILTER_
BLUREXPONENTIALSHADOWMAP - FILTER_
CLOSEEXPONENTIALSHADOWMAP - FILTER_
EXPONENTIALSHADOWMAP - FILTER_
NONE - FILTER_
PCF - FILTER_
PCSS - FILTER_
POISSONSAMPLING - QUALITY_
HIGH - QUALITY_
LOW - QUALITY_
MEDIUM
Accessors
- bias
- blur
Box Offset - blur
Kernel - blur
Scale - contact
Hardening Light SizeUVRatio - darkness
- depth
Scale - filter
- filtering
Quality - map
Size - normal
Bias - transparency
Shadow - use
Blur Close Exponential Shadow Map - use
Blur Exponential Shadow Map - use
Close Exponential Shadow Map - use
Contact Hardening Shadow - use
Exponential Shadow Map - use
Kernel Blur - use
Percentage Closer Filtering - use
Poisson Sampling
Methods
Constructors
constructor
Creates a ShadowGenerator object. A ShadowGenerator is the required tool to use the shadows. Each light casting shadows needs to use its own ShadowGenerator. Documentation : https://doc.babylonjs.com/babylon101/shadows
Parameters
mapSize: number
The size of the texture what stores the shadows. Example : 1024.
light: IShadowLight
The light object generating the shadows.
Optional usefullFloatFirst: 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.
Returns ShadowGenerator
Properties
custom Allow RenderingSearch playground for customAllowRendering
Type declaration
Gets or sets a custom function to allow/disallow rendering a sub mesh in the shadow map
Parameters
subMesh: SubMesh
Returns boolean
custom Shader OptionsSearch playground for customShaderOptions
Gets or sets the custom shader name to use
enable Soft Transparent ShadowSearch playground for enableSoftTransparentShadow
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!
force Back Faces OnlySearch playground for forceBackFacesOnly
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.
frustum Edge FalloffSearch playground for frustumEdgeFalloff
Controls the extent to which the shadows fade out at the edge of the frustum
idSearch playground for id
Gets or set the id of the shadow generator. It will be the one from the light if not defined
on After Shadow Map Render Mesh ObservableSearch playground for onAfterShadowMapRenderMeshObservable
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)
on After Shadow Map Render ObservableSearch playground for onAfterShadowMapRenderObservable
Observable triggered after the shadow is rendered. Can be used to restore internal effect state
on Before Shadow Map Render Mesh ObservableSearch playground for onBeforeShadowMapRenderMeshObservable
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)
on Before Shadow Map Render ObservableSearch playground for onBeforeShadowMapRenderObservable
Observable triggered before the shadow is rendered. Can be used to update internal effect state
use Opacity Texture For Transparent ShadowSearch playground for useOpacityTextureForTransparentShadow
If this is true, use the opacity texture's alpha channel for transparent shadows instead of the diffuse one
Static CLASSNAMESearch playground for CLASSNAME
Name of the shadow generator class
Static DEFAULT_ ALPHA_ CUTOFFSearch playground for DEFAULT_ALPHA_CUTOFF
Defines the default alpha cutoff value used for transparent alpha tested materials.
Static Readonly FILTER_ BLURCLOSEEXPONENTIALSHADOWMAPSearch playground for FILTER_BLURCLOSEEXPONENTIALSHADOWMAP
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)
Static Readonly FILTER_ BLUREXPONENTIALSHADOWMAPSearch playground for FILTER_BLUREXPONENTIALSHADOWMAP
Shadow generator mode ESM: Blurred Exponential Shadow Mapping. (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)
Static Readonly FILTER_ CLOSEEXPONENTIALSHADOWMAPSearch playground for FILTER_CLOSEEXPONENTIALSHADOWMAP
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)
Static Readonly FILTER_ EXPONENTIALSHADOWMAPSearch playground for FILTER_EXPONENTIALSHADOWMAP
Shadow generator mode ESM: Exponential Shadow Mapping. (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)
Static Readonly FILTER_ NONESearch playground for FILTER_NONE
Shadow generator mode None: no filtering applied.
Static Readonly FILTER_ PCFSearch playground for FILTER_PCF
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)
Static Readonly FILTER_ PCSSSearch playground for FILTER_PCSS
Shadow generator mode PCSS: Percentage Closering Soft Shadow. benefits from Webgl 2 shadow samplers. Fallback to Poisson Sampling in Webgl 1 Contact Hardening
Static Readonly FILTER_ POISSONSAMPLINGSearch playground for FILTER_POISSONSAMPLING
Shadow generator mode Poisson Sampling: Percentage Closer Filtering. (Multiple Tap around evenly distributed around the pixel are used to evaluate the shadow strength)
Static Readonly QUALITY_ HIGHSearch playground for QUALITY_HIGH
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.
Static Readonly QUALITY_ LOWSearch playground for QUALITY_LOW
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.
Static Readonly QUALITY_ MEDIUMSearch playground for QUALITY_MEDIUM
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.
Accessors
bias
Gets the bias: offset applied on the depth preventing acnea (in light direction).
Returns number
Sets the bias: offset applied on the depth preventing acnea (in light direction).
Parameters
bias: number
Returns void
blur Box Offset
Gets the blur box offset: offset applied during the blur pass. Only useful if useKernelBlur = false
Returns number
Sets the blur box offset: offset applied during the blur pass. Only useful if useKernelBlur = false
Parameters
value: number
Returns void
blur Kernel
Gets the blur kernel: kernel size of the blur pass. Only useful if useKernelBlur = true
Returns number
Sets the blur kernel: kernel size of the blur pass. Only useful if useKernelBlur = true
Parameters
value: number
Returns void
blur Scale
Gets the blur scale: scale of the blurred texture compared to the main shadow map. 2 means half of the size.
Returns number
Sets the blur scale: scale of the blurred texture compared to the main shadow map. 2 means half of the size.
Parameters
value: number
Returns void
contact Hardening Light SizeUVRatio
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
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
darkness
Gets or sets the actual darkness of a shadow
Returns number
Gets or sets the actual darkness of a shadow
Parameters
value: number
Returns void
depth Scale
Gets the depth scale used in ESM mode.
Returns number
Sets the depth scale used in ESM mode. This can override the scale stored on the light.
Parameters
value: number
Returns void
filter
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
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
filtering Quality
Gets the PCF or PCSS Quality. Only valid if usePercentageCloserFiltering or usePercentageCloserFiltering is true.
Returns number
Sets the PCF or PCSS Quality. Only valid if usePercentageCloserFiltering or usePercentageCloserFiltering is true.
Parameters
filteringQuality: number
Returns void
map Size
Gets or sets the size of the texture what stores the shadows
Returns number
Gets or sets the size of the texture what stores the shadows
Parameters
size: number
Returns void
normal Bias
Gets the normalBias: offset applied on the depth preventing acnea (along side the normal direction and proportional to the light/normal angle).
Returns number
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
transparency Shadow
Gets or sets the ability to have transparent shadow
Returns boolean
Gets or sets the ability to have transparent shadow
Parameters
value: boolean
Returns void
use Blur Close Exponential Shadow Map
Gets if the current filter is set to filtered "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).
Returns boolean
Sets the current filter to filtered "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).
Parameters
value: boolean
Returns void
use Blur Exponential Shadow Map
Gets if the current filter is set to filtered ESM.
Returns boolean
Gets if the current filter is set to filtered ESM.
Parameters
value: boolean
Returns void
use Close Exponential Shadow Map
Gets if the current filter is set to "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).
Returns boolean
Sets the current filter to "close ESM" (using the inverse of the exponential to prevent steep falloff artifacts).
Parameters
value: boolean
Returns void
use Contact Hardening Shadow
Gets if the current filter is set to "PCSS" (contact hardening).
Returns boolean
Sets the current filter to "PCSS" (contact hardening).
Parameters
value: boolean
Returns void
use Exponential Shadow Map
Gets if the current filter is set to ESM.
Returns boolean
Sets the current filter is to ESM.
Parameters
value: boolean
Returns void
use Kernel Blur
Gets whether the blur pass is a kernel blur (if true) or box blur. Only useful in filtered mode (useBlurExponentialShadowMap...)
Returns boolean
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
use Percentage Closer Filtering
Gets if the current filter is set to "PCF" (percentage closer filtering).
Returns boolean
Sets the current filter to "PCF" (percentage closer filtering).
Parameters
value: boolean
Returns void
use Poisson Sampling
Gets if the current filter is set to Poisson Sampling.
Returns boolean
Sets the current filter to Poisson Sampling.
Parameters
value: boolean
Returns void
Methods
add Shadow CasterSearch playground for addShadowCaster
Helper function to add a mesh and its descendants to the list of shadow casters.
Parameters
mesh: AbstractMesh
Mesh to add
Optional includeDescendants: boolean
boolean indicating if the descendants should be added. Default to true
Returns ShadowGenerator
the Shadow Generator itself
bind Shadow LightSearch playground for bindShadowLight
Binds the shadow related information inside of an effect (information like near, far, darkness... defined in the generator but impacting the effect).
Parameters
lightIndex: string
Index of the light in the enabled light list of the material owning the effect
effect: Effect
The effect we are binding the information for
Returns void
disposeSearch playground for dispose
Disposes the ShadowGenerator. Returns nothing.
Returns void
force CompilationSearch playground for forceCompilation
Forces all the attached effect to compile to enable rendering only once ready vs. lazily compiling effects.
Parameters
Optional onCompiled: ((generator: IShadowGenerator) => void)
Callback triggered at the and of the effects compilation
Parameters
generator: IShadowGenerator
Returns void
Optional options: Partial<{ useInstances: boolean }>
Sets of optional options forcing the compilation with different modes
Returns void
force Compilation AsyncSearch playground for forceCompilationAsync
Forces all the attached effect to compile to enable rendering only once ready vs. lazily compiling effects.
Parameters
Optional options: Partial<{ useInstances: boolean }>
Sets of optional options forcing the compilation with different modes
Returns Promise<void>
A promise that resolves when the compilation completes
get Class NameSearch playground for getClassName
Gets the class name of that object
Returns string
"ShadowGenerator"
get DarknessSearch playground for getDarkness
Returns the darkness value (float). This can only decrease the actual darkness of a shadow. 0 means strongest and 1 would means no shadow.
Returns number
the darkness.
get LightSearch playground for getLight
Returns the associated light object.
Returns IShadowLight
the light generating the shadow
get Shadow MapSearch playground for getShadowMap
Gets the main RTT containing the shadow map (usually storing depth from the light point of view).
Returns Nullable<RenderTargetTexture>
The render target texture if present otherwise, null
get Shadow Map For RenderingSearch playground for getShadowMapForRendering
Gets the RTT used during rendering (can be a blurred version of the shadow map or the shadow map itself).
Returns Nullable<RenderTargetTexture>
The render target texture if the shadow map is present otherwise, null
get Transform MatrixSearch playground for getTransformMatrix
Gets the transformation matrix used to project the meshes into the map from the light point of view. (eq to shadow projection matrix * light transform matrix)
Returns Matrix
The transform matrix used to create the shadow map
is ReadySearch playground for isReady
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
prepare DefinesSearch playground for prepareDefines
Prepare all the defines in a material relying on a shadow map at the specified light index.
Parameters
defines: any
Defines of the material we want to update
lightIndex: number
Index of the light in the enabled light list of the material
Returns void
recreate Shadow MapSearch playground for recreateShadowMap
Recreates the shadow map dependencies like RTT and post processes. This can be used during the switch between Cube and 2D textures for instance.
Returns void
remove Shadow CasterSearch playground for removeShadowCaster
Helper function to remove a mesh and its descendants from the list of shadow casters
Parameters
mesh: AbstractMesh
Mesh to remove
Optional includeDescendants: boolean
boolean indicating if the descendants should be removed. Default to true
Returns ShadowGenerator
the Shadow Generator itself
serializeSearch playground for serialize
Serializes the shadow generator setup to a json object.
Returns any
The serialized JSON object
set DarknessSearch playground for setDarkness
Sets the darkness value (float). This can only decrease the actual darkness of a shadow.
Parameters
darkness: number
The darkness value 0 means strongest and 1 would means no shadow.
Returns ShadowGenerator
the shadow generator allowing fluent coding.
set Transparency ShadowSearch playground for setTransparencyShadow
Sets the ability to have transparent shadow (boolean).
Parameters
transparent: boolean
True if transparent else False
Returns ShadowGenerator
the shadow generator allowing fluent coding
Static ParseSearch playground for Parse
Parses a serialized ShadowGenerator and returns a new ShadowGenerator.
Parameters
parsedShadowGenerator: any
The JSON object to parse
scene: Scene
The scene to create the shadow map for
Optional constr: ((mapSize: number, light: IShadowLight) => ShadowGenerator)
A function that builds a shadow generator or undefined to create an instance of the default shadow generator
Parameters
mapSize: number
light: IShadowLight
Returns ShadowGenerator
Returns ShadowGenerator
The parsed shadow generator
Default implementation IShadowGenerator. This is the main object responsible of generating shadows in the framework. Documentation: https://doc.babylonjs.com/babylon101/shadows