
## Introduction

When a scene has a lot of lights, per-pixel lighting calculations can get quite slow. This is because every single pixel needs to compute the lighting contribution from every single light, even if those lights might not really be affecting that pixel at all. One way to dramatically speed up these calculations is for the engine to have a rough idea of which lights affect the current pixel. This is the basis of clustered lighting, also referred to as Forward+.

In Babylon, clustered lighting is implemented as its own light type, to which other point or spot lights can be added:
```javascript
const lightContainer = new BABYLON.ClusteredLightContainer("clustered", [pointLight1, pointLight2], scene);
// More lights can be added or removed later
lightContainer.removeLight(pointLight1);
lightContainer.addLight(spotLight);
```

Clustered lighting usually follows a three-step approach along the lines of:
1. split the camera's view-space into 3D "clusters" (for example, AABB cubes)
2. for each cluster, figure out what lights affect it (within a certain range such that their contribution is significant)
3. at render time, find the cluster a pixel belongs to (using its screen position and depth value), and then only calculate lighting contribution from the lights for that cluster

Babylon takes a slightly different approach to clustered lighting, mainly inspired by [this SIGGRAPH talk](https://advances.realtimerendering.com/s2017/2017_Sig_Improved_Culling_final.pdf) for Call of Duty: Infinite Warfare. The main takeaway is that rather than grouping lights into 3D clusters, we instead group lights into both a 2D tile (ignoring depth) and a depth slice (ignoring screen position). At render time, we then find the intersection of lights within the current screen tile AND within the current depth slice. This lets us take advantage of traditional rendering hardware and fragment shaders for tiled clustering, while keeping depth clustering simple enough to run on the CPU.

This solution works on both WebGPU and WebGL 2 (if float color buffers are supported and blendable).

<Playground id="#CSCJO2#89" image="/img/playgroundsAndNMEs/pg-CSCJO2-75.webp" title="Sponza scene with 1000 lights" description="Example showing off the capabilities of clustered lighting by making the Sponza scene colorful" />
<Playground id="#6JYGXW#3" image="/img/playgroundsAndNMEs/pg-6JYGXW-1.webp" title="ClusteredLights corridor" description="A corridor lit by hundreds of colored point and spot lights" />

**Important**:
* For best performance, when creating a light intended for use in a clustered light container, do not add it to the scene! To do this, pass the value *true* for the **dontAddToScene** parameter of the light constructor.
* This can make a huge difference when you create all the lights in advance and pass them all at once to the clustered light container constructor (compared to creating the lights one by one and calling `ClusteredLightContainer.addLight()` for each one)!

## Tiled Clustering

By default, the screen is split into 64 tiles across and 64 tiles down, for a total of 4,096 tiles.

![The Sponza scene with the screen covered in randomly-colored tiles](/img/features/clusteredLighting/tiles64x64.webp)
<font size="2">The Sponza scene with the default tiling options. Each tile is tinted a different color.</font>

The amount of tiles can be changed using the `verticalTiles` and `horizontalTiles` options:
```javascript
lightContainer.verticalTiles = 16;
lightContainer.horizontalTiles = 9;
```

![The Sponza scene with the screen covered in less, but larger, randomly-colored tiles](/img/features/clusteredLighting/tiles16x9.webp)
<font size="2">The Sponza scene with only 16 tiles across and 9 tiles down.</font>

Configuring the total tile count is a balancing act between keeping the light clustering fast by reducing the amount of tiles, while keeping the per-pixel lighting fast by keeping the tiles small<sup>[1](#footnotes)</sup>, which makes the light list for that pixel more accurate. Increasing the tile count will also increase the GPU memory usage.

To cluster the lights into the tiles we render each light against the configured tile layout using a "light proxy" (or light mesh). In Babylon this light proxy is a simple square:
![The lion face from the Sponza scene with a single light and the wireframe of a square overtop the light](/img/features/clusteredLighting/proxy.webp)
<font size="2">The light proxy square.</font>

The light proxies are scaled by the `range` parameter of the light. By default, the range of lights is very large, so `ClusteredLightContainer` will clamp all lights to a smaller (yet still quite large) range. If you want lights with a larger range than the default max of 16383, this can be modified using the `maxRange` option:
```javascript
lightContainer.maxRange = 30000;
```
It is recommended to adjust the ranges of your lights so they don't all end up as the max range (which cancels out any clustering attempts).

When these light proxies are rendered they set a bit in a bitmask, which then gets iterated over during rendering. The way this bit is set differs between WebGL and WebGPU.

### WebGPU

WebGPU uses the simpler method of the two because it supports more advanced features than WebGL. The bitmasks in WebGPU are stored in an I32 storage buffer with the size `horizontalTiles x verticalTiles x numBatches`, where `numBatches` is the number of lights divided by 32. When rendering a light proxy, it finds the relevant bitmask for its screen position and batch number, and then sets the bit representing the light using an atomic OR operation. Notably, the light proxy does not render any color, and its fragment shader is used only for its side effects (writing to a storage buffer).

### WebGL 2

WebGL does not support storage buffers nor does it support any form of atomic writes. Instead WebGL takes advantage of the blending stage of the rendering pipeline by writing out the bit values and additively blending them together. A floating-point render target is used to ensure the blended values exactly match the fragment outputs, but sadly floating point values cannot accurately represent all 32 distinct bit values that a 32-bit int could. For this reason, the number of lights per batch in WebGL is equal to the number of fraction bits the hardware supports, which on most systems is 23.

![The Sponza scene with the screen covered in pixelated red circles of varying shades](/img/features/clusteredLighting/additiveBlending.webp)
<font size="2">The result of additively blending light proxies with different bit values.</font>

To support multiple batches (when more than 23 lights are rendered) the floating-point render target is expanded vertically by the number of batches, and the light proxy is shifted based on its batch number in the vertex shader.

### Conservative Rendering (or the lack thereof)

As one final note before going on to depth clustering, it's worth talking about a GPU feature called conservative rendering. Traditionally, fragment shaders are run only for pixels whose centers are covered by the triangle. However, this causes issues with our light proxies because we want fragment shaders to run for every pixel (which represents a tile) that the proxy intersects, regardless of how much it intersects it. The good news is that this feature exists and is called "conservative rendering"; the bad news is that not much hardware supports it, and neither WebGL nor WebGPU expose the functionality at the time of writing.

Infinity Ward also faced this issue with Call of Duty, and their solution presented in the slides is to render the light proxies at screen resolution. This works fine when writing out bits using atomic OR since multiple fragment shaders can set the same bit without issue<sup>[2](#footnotes)</sup>. For this to work in WebGL we'd have to post-process the results by reducing the full resolution down to a single pixel per tile.

Our solution to this problem, partly inspired by [this GitHub project](https://github.com/wizgrav/cl2), is to round the mesh vertices to the nearest corner away from the center (round down for vertices left of the center, round up for vertices right of the center). This means that no matter how far away from a light you are, its proxy will always render to at least one tile on the screen.

## Depth Clustering

Depth clustering is much simpler and can easily be done on the CPU, since we're dealing with only a single dimension (depth) instead of two (screen X and Y). The depth range of the camera (from `minZ` to `maxZ`) is split into 16 slices by default, with each slice containing the minimum and maximum light indices that intersect it. This provides a range of bitmasks (from the tiled clustering step) that the fragment shader needs to check. For these minimum and maximum indices to efficiently represent the lights within the slice, the lights are sorted by distance from the camera. Sorting is fast enough to be done each frame.

![The Sponza scene with the screen covered in randomly-colored slices getting further and further away from the camera](/img/features/clusteredLighting/slices16.webp)
<font size="2">The Sponza scene with the default depth slicing options. Each slice is tinted a different color.</font>

The number of slices can be tweaked using the `depthSlices` option. Additionally, the camera's `maxZ` property can be adjusted to bring the slices closer, which is recommended for smaller scenes:
```javascript
camera.maxZ = 100;
lightContainer.depthSlices = 64;
```

![The Sponza scene with the screen covered in more, but thinner, randomly-colored slices](/img/features/clusteredLighting/slices64.webp)
<font size="2">The Sponza scene with a max depth of 100 split into 64 slices.</font>

To find the intersection between tiled clustering and depth clustering, the lighting code in the fragment shader ends up looking something like this (overly simplified for the sake of demonstration):
```glsl
for (int i = firstBatch; i <= lastBatch; i += 1) {
    uint mask = getBatchMask(i);
    if (i == firstBatch) {
        // clear starting bits depending on first light index
    }
    if (i == lastBatch) {
        // clear ending bits depending on last light index
    }

    while (mask != 0u) {
        int trailing = firstTrailingBit(mask);
        // Clear the bit we found
        mask ^= 1u << trailing;

        SpotLight light = getClusteredSpotLight(
            i * batchSize + trailing);
        // Compute lighting contribution
    }
}
```

## Limitations / Additional remarks

In its current form, there are some limits to the clustered lighting implementation.

### Only spot and point lights are supported

Currently only spot and point lights are supported. Other lights will still need to be rendered separately using a non-clustered approach.

### Lights with extra textures are not supported

Some lights require binding extra textures per light. These include:
- shadow-generating lights
- spot lights with projection or IES textures

Because we don't know which lights we need until render time, we'd effectively need to bind every single texture and dynamically index them too. This is usually done with a generated texture atlas, but that's quite a bit of complex work. So for now, we simply don't support clustering these lights.

### Lights with a falloff other than `FALLOFF_DEFAULT` are not supported

To reduce branching in the shader, all lights are assumed to use the default falloff method (which makes it dependent on the material).

### Materials with a physical falloff may cause artefacts

The physical falloff is the only falloff method that ignores the `range` parameter on lights. This means that the range at which the light proxy is rendered might be shorter than the light's actual range of influence. This falloff is still supported; just be sure to adjust the `range` of your lights accordingly so they reach a point where the physical falloff is no longer very noticeable.

![The Sponza scene covered in lights but there are block artefacts where the lights end](/img/features/clusteredLighting/physicalFalloff.webp)
<font size="2">The artefacts that can occur from incorrect range parameters when using a physical falloff.</font>

The physical falloff can be disabled on all PBR materials using:
```javascript
for (const material of scene.materials) {
    if (material instanceof BABYLON.PBRMaterial) {
        material.usePhysicalLightFalloff = false;
        // ... or alternatively ...
        material.useGLTFLightFalloff = true;
    }
}
```

### Support for clustered lights in node materials

In order for your node material to support clustered lights, you must connect the **view** matrix to the **view** input of `LightBlock` / `PBRMetallicRoughnessBlock`. This input is mandatory for the latter, so you cannot miss it. However, it is optional for `LightBlock`. If you leave the **view** input unconnected and your scene has clustered lights, you will get an error such as `“vViewDepth”: undeclared identifier` (WebGL) or `error: structure member vViewDepth not found` (WebGPU).

If the engine is WebGPU and you are using a node material with clustered lights, the node material must be created with the `shaderLanguage: BABYLON.ShaderLanguage.WGSL` option to force native WGSL code generation. This is because converting the GLSL code used by WebGL to WGSL will not work, as the WebGPU implementation uses a storage buffer, which is not supported by WebGL. If you do not set this option, you will get an error such as `Sampler ‘tileMaskTexture0Sampler’ not found in the material context` and `Texture ‘tileMaskTexture0’ not found in the material context.`

When using `ParseFromSnippetAsync` to load your node material, you can pass the shader language via the 8th parameter:
```typescript
const mat = await BABYLON.NodeMaterial.ParseFromSnippetAsync("D7OZ4C#5", scene, undefined, undefined, undefined, undefined, undefined, {
    shaderLanguage: engine.isWebGPU ? BABYLON.ShaderLanguage.WGSL : BABYLON.ShaderLanguage.GLSL
});
```

---
### Footnotes
1. Making the tiles _too_ small can actually **hurt** lighting performance, since it will cause nearby pixels to branch more frequently, which dramatically hurts performance on modern GPUs. Additionally, it will require more memory fetches from the GPU to get the results for all the tiles.
2. Actually, having so many fragment shaders attempting to perform the same atomic operation makes for some really _really_ bad performance, but they use some wavefront ✨black magic✨ to work around that.



## Lights

Lights are used, as you would expect, to affect how meshes are seen, in terms of both illumination and color.
All meshes allow light to pass through them unless shadow generation is activated. The default number of allowed lights is
four, but this can be increased.

![Elements](/img/testlight.webp)

_A pretty sphere with multiple lights_

## Types of Lights

There are five types of lights that can be used, each with a range of lighting properties.

### The Point Light

A point light is a light defined by a unique point in world space. The light is emitted in every direction from this point. A good example of a point light is a standard light bulb.

```javascript
const light = new BABYLON.PointLight("pointLight", new BABYLON.Vector3(1, 10, 1), scene);
```

### The Directional Light

A directional light is defined by a direction (what a surprise!). The light is emitted from everywhere in the specified direction and has an infinite range.
An example of a directional light is a distant planet lit by the apparently parallel lines of light from its sun. Light shining downward will light
the top of an object.

```javascript
const light = new BABYLON.DirectionalLight("DirectionalLight", new BABYLON.Vector3(0, -1, 0), scene);
```

### The Spot Light

A spot light is defined by a position, a direction, an angle, and an exponent. These values define a cone of light starting from the position, emitting toward the direction.

The angle, in radians, defines the size (field of illumination) of the spotlight's conical beam, and the exponent defines how quickly the light decays with distance (reach).

_A simple use of a spot light_

```javascript
const light = new BABYLON.SpotLight("spotLight", new BABYLON.Vector3(0, 30, -10), new BABYLON.Vector3(0, -1, 0), Math.PI / 3, 2, scene);
```

### The Hemispheric Light

A hemispheric light is an easy way to simulate ambient environmental light. A hemispheric light is defined by a direction, usually 'up' toward the sky. However, the full effect is achieved by setting the color properties.

```javascript
const light = new BABYLON.HemisphericLight("HemiLight", new BABYLON.Vector3(0, 1, 0), scene);
```

### The Rectangular Area Light

A rectangular area light is defined by its position, width, and height. It emits light from the resulting surface towards the -Z direction. Even though the RectAreaLight class itself does not have a direction component, it can be attached to a transform node to be rotated and moved around.

```javascript
const light = new BABYLON.RectAreaLight("areaLight", new BABYLON.Vector3(0, 1, 0), 2, 2, scene);
```

One important thing to note is that, due to differences in implementation, StandardMaterial will reflect light based on its "roughness" value (instead of specular power, as with other lights). This difference in behavior is significant, and you should set the correct roughness value in the scene to achieve the desired look.

Also, the current implementation for RectAreaLight does not cast shadows, but we plan to implement this in the future.

### Using emission textures with RectAreaLight

Emission textures can be used as light sources for RectAreaLight by assigning them to the `.emissionTexture` property. However, these textures require pre-processing to work properly.

Pre-processing can be done offline (recommended) or at runtime using `AreaLightTextureTools`. Runtime processing takes several seconds for typical texture sizes (1024 or 2048), so offline processing is preferred for production use. The runtime tool is provided for prototyping and experimentation.

Here's how to use an emission texture at runtime:

```javascript
// AreaLightTextureTools can be created once and reused for processing multiple textures. 
const textureProcessor = new BABYLON.AreaLightTextureTools(engine);

// Create your RectAreaLight
const light = new BABYLON.RectAreaLight("areaLight", new BABYLON.Vector3(0, 1, 0), 2, 2, scene);

// Image that you want to use as emission.
const emissionTexture = new BABYLON.Texture(textureURL, scene);

// Preprocess the texture to get the one that should be used by RectAreaLight
light.emissionTexture = await textureProcessor.processAsync(emissionTexture);
```

We also provide an offline tool that can directly pre-process emission textures: [Babylon Texture Tools](https://babylonjs.com/tools/textures/index.html). By going to the "Area Light" tab, users can drag and drop a PNG into the tool and use the "Render" button to generate the pre-processed texture. The resulting texture can be directly assigned to `light.emissionTexture` without any additional steps.

<Playground id="#T7FXR8#104" title="Area Light with Emission" description="Area Light using emission texture." image="/img/playgroundsAndNMEs/areaLightEmissionSample.webp" isMain={true} category="Lights"/>


## Color Properties

There are three properties of lights that affect color. Two of these, _diffuse_ and _specular_, apply to all light types; the third, _groundColor_, applies only to a Hemispheric Light.

1. Diffuse gives the basic color to an object;
2. Specular produces a highlight color on an object.

In these playgrounds, see how the specular color (green) is combined with the diffuse color (red) to produce a yellow highlight.

<Playground id="#20OAV9" title="Point Light Example" description="Simple Example of adding a Point Light to your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro1.webp" isMain={true} category="Lights"/>

<Playground id="#20OAV9#1" title="Directional Light Example" description="Simple Example of adding a Directional Light to your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro2.webp" isMain={true} category="Lights"/>

<Playground id="#20OAV9#3" title="Spot Light Example" description="Simple Example of adding a Spot Light to your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro3.webp" isMain={true} category="Lights"/>

<Playground id="#20OAV9#5" title="Hemispheric Light Example" description="Simple Example of adding a Hemispheric Light to your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro4.webp" isMain={true} category="Lights"/>

<Playground id="#T7FXR8#20" title="Rectangular Area Light Example" description="Simple Example of adding a Rectangular Area Light to your scene." image="/img/playgroundsAndNMEs/areaLightStandardExample.webp" isMain={true} category="Lights"/>

For a hemispheric light, the _groundColor_ is the light in the opposite direction from the one specified during creation.
You can think of the _diffuse_ and _specular_ light as coming from the center of the object in the given direction, and the _groundColor_ light as coming from the opposite direction.

<Playground id="#20OAV9#6" title="Hemispheric Light On 2 Spheres" description="Simple Example of a Hemispheric Light on 2 spheres." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro5.webp"/>

White hemispheric light with a black groundColor is a useful lighting method.

### Intersecting Lights Colors

<Playground id="#20OAV9#9" title="Intersecting Spot Lights" description="Simple Example of a intersecting spot light colors." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro6.webp"/>

## Limitations

Babylon.js allows you to create and register as many lights as you choose, but note that a single material can only handle a defined number of simultaneous lights (by default, this value is 4, which means the first four enabled lights in the scene's lights list).
You can change this number with this code:

```javascript
const material = new BABYLON.StandardMaterial("mat", scene);
material.maxSimultaneousLights = 6;
```

But beware! By default, all meshes are considered lit by all lights, even when they are not physically lit. Calculating whether a mesh can be lit by a light would be too time-consuming. Also, with more dynamic lights, Babylon.js generates larger shaders, which may not be compatible with low-end devices such as phones or small tablets. In this case, Babylon.js will try to recompile shaders with fewer lights.

<Playground id="#IRVAX#0" title="6 Intersecting Point Lights" description="Simple Example with 6 intersecting point lights." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro7.webp"/>

## On, Off or Dimmer

Every light can be switched off using

```javascript
light.setEnabled(false);
```

and switched on with

```javascript
light.setEnabled(true);
```

Want to dim or brighten the light? Then set the _intensity_ property (default value is 1).

```javascript
light0.intensity = 0.5;
light1.intensity = 2.4;
```

For point and spot lights, you can set how far the light reaches using the _range_ property.

```javascript
light.range = 100;
```

## Choosing Meshes to Light

When a light is created, all current meshes will be lit by it. There are two ways to exclude some meshes from being lit.
A mesh can be added to the _excludedMeshes_ array, or the meshes that should not be excluded can be added to the _includedOnlyMeshes_ array. The number of meshes to exclude can help determine which method to use. In the following example, two meshes are excluded from _light0_ and twenty-three from _light1_. Commenting out lines 26 and 27 in turn will show the individual effect.

<Playground id="#20OAV9#8" title="Example of Excluding Meshes to Light" description="Simple Example of exluding meshes from being lit by a light." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro8.webp" isMain={true} category="Lights"/>

## Lighting Normals

How lights react to a mesh depends on values set for each mesh vertex, called _normals_, shown in the picture below as arrows indicating the direction of the lighting normals. The picture shows two planes and two lights. One light is a spot light and the other is a point light. The front face of each plane is the one you see when the _normals_ point toward you; the back face is the opposite side.

![Elements](/img/how_to/Mesh/normals6.webp)

_A blue back-faced plane and a blue front-faced plane, with a spot light and point light_

As you can see, the lights only affect the front face and not the back face.

## Lightmaps

Complex lighting can be computationally expensive to compute at runtime. To save on computation, lightmaps may be used to store calculated lighting in a texture which will be applied to a given mesh.

```javascript
const lightmap = new BABYLON.Texture("lightmap.png", scene);
const material = new BABYLON.StandardMaterial("material", scene);
material.lightmapTexture = lightmap;
```

Note: To use the texture as a shadow map instead of a lightmap, set the material.useLightmapAsShadowmap field to true.

The way that the scene lights are blended with the lightmap is based on the lightmapMode of the lights in the scene.

```javascript
light.lightmapMode = BABYLON.Light.LIGHTMAP_DEFAULT;
```

This causes the lightmap texture to be blended after the lighting from this light is applied.

```javascript
light.lightmapMode = BABYLON.Light.LIGHTMAP_SPECULAR;
```

This is the same as LIGHTMAP_DEFAULT except only the specular lighting and shadows from the light will be applied.

```javascript
light.lightmapMode = BABYLON.Light.LIGHTMAP_SHADOWSONLY;
```

This is the same as LIGHTMAP_DEFAULT except only the shadows cast from this light will be applied.

<Playground id="#ULACCM#37" title="Lightmaps Example" description="Simple Example of using lightmaps in your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro9.webp"/>

## Projection Texture

In some cases, it is useful to define the diffuse color of the light (Diffuse gives the basic color to an object) from a texture instead of a constant color. Imagine trying to simulate the light effects inside a cathedral. The light going through the stained glass will be projected onto the ground. The same is true for light coming from a projector or the light effects you see in a disco.

In order to support this feature, you can rely on the `projectionTexture` property of the lights. This is only supported by the **SpotLight** so far.

```javascript
const spotLight = new BABYLON.SpotLight("spot02", new BABYLON.Vector3(30, 40, 30), new BABYLON.Vector3(-1, -2, -1), 1.1, 16, scene);
spotLight.projectionTexture = new BABYLON.Texture("textures/stainedGlass.png", scene);
```

<Playground id="#CQNGRK" title="Projection Texture Example" description="Simple Example of using projection textures in your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro10.webp"/>

<Youtube id="qqMuuSM7GvI"/>

In order to control the projection orientation and range, you can also rely on the following properties:

- `projectionTextureLightNear` : near range of the texture projection. If a plane is before this range in light space, there is no texture projection.
- `projectionTextureLightFar` : far range of the texture projection. If a plane is beyond this range in light space, there is no texture projection.
- `projectionTextureUpDirection` : helps define the light space, which is oriented toward the light direction and aligned with the up direction.

The projected information is multiplied against the normal light values to better fit Babylon.js lighting. It also affects only the diffuse value. So, it might be necessary to change the specular color of the light to better fit the scene.

## IES Profile

Starting with Babylon v7.40.0, you can specify an [IES light](https://ieslibrary.com/) profile for your **SpotLight**.

This controls, based on the [IES specification](https://store.ies.org/product/lm-63-19-approved-method-ies-standard-file-format-for-the-electronic-transfer-of-photometric-data-and-related-information/?v=0b3b97fa6688), how the light falloff should be rendered.

To do so, you have to set the `spotLight.iesProfileTexture` to a texture loaded from an `.ies` file.

```
light.iesProfileTexture = new BABYLON.Texture("https://assets.babylonjs.com/meshes/EXT_lights_ies/LightProfile.ies");
```

<Playground id="#UIAXAU#29" title="Projection Texture Example" description="Simple Example of using an IES profile."/>



This article was written to keep track of how the depth metric is computed when generating shadow maps and rendering shadows in Babylon.js, as understanding how we ended up using the formula described below can be difficult at times, especially when you add support for the reverse depth buffer and the reduced NDC Z range used by WebGPU...

## Generating the shadow map

Shadow maps are generated by the `ShadowGenerator` class for standard shadows, and by the `CascadedShadowGenerator` class for cascaded shadow maps.

The idea is to generate a texture that contains the depth of the geometry closest to the light when rendering the scene from the light's point of view. Basically, this depth is the z coordinate of the 3D point after it is transformed into the light's view space (in this space, the Z axis points forward). So, if we have two points A and B, and `zA < zB` in this space, A is closer to the light than B and it is `zA` that will be written to the shadow map.

Babylon.js is not doing anything fancy here and is simply using the **transformation** matrix (**view** x **projection**) of the light to render the shadow casters and generate the shadow map. However, there are several cases to consider.

### PCF and PCSS filtering

When using PCF (_Percentage Closer Filtering_) and PCSS (_Percentage Closer Soft Shadows_) to render actual shadows, we are using as our shadow map the depth texture generated by the GPU when rendering the shadow casters. So, this texture is automatically generated as part of the rendering and we have nothing specific to do, except applying the bias value defined in the shadow generator. The shader code looks like this (in the _shadowMapVertexMetric.fx_ file):

```c
#if SM_DEPTHTEXTURE == 1
    #ifdef IS_NDC_HALF_ZRANGE
        #define BIASFACTOR 0.5
    #else
        #define BIASFACTOR 1.0
    #endif

    #if SM_USE_REVERSE_DEPTHBUFFER == 1
        gl_Position.z -= biasAndScaleSM.x * gl_Position.w * BIASFACTOR;
    #else
        gl_Position.z += biasAndScaleSM.x * gl_Position.w * BIASFACTOR;
    #endif
#endif
```

`SM_DEPTHTEXTURE` is set to 1 only when using PCF/PCSS filtering. `biasAndScaleSM.x` is the bias value (note that the _normal bias_ is applied earlier and modifies the world position of the 3D point).

We are multiplying by `gl_Position.w` because the GPU, as part of its computations, will do `gl_Position.z / gl_Position.w` before writing the value to the depth texture: by pre-multiplying by `gl_Position.w`, we make sure the final result is simply biased by a constant `biasAndScaleSM.x * BIASFACTOR` value.

When the NDC space has a `0..1` Z range (meaning **IS_NDC_HALF_ZRANGE** is defined), we use a bias factor of 0.5 so that the final bias applied to the position has the same scale as when the range is `-1..1`.

Note that in the standard case (when not using the reverse depth buffer), we **add** the bias to the position, so we move the depth value / geometry a little farther away. Another strategy would be not to apply the bias in the shadow map, but at the shadow rendering stage. In that case, we would **subtract** the bias from the current depth (from the light) of the pixel to achieve the same result.

Finally, when using the reverse depth buffer, we simply reverse (negate) the bias offset, as bigger z values now mean nearer geometries.

### Generating a depth metric

When not using PCF / PCSS modes (actually, we also need the depth metric described here in PCSS mode), we need to generate a depth metric, which is the depth value we will use when doing depth comparisons to compute the shadow level of a given pixel.

The computation we are doing to generate this value is (in the _shadowMapVertexMetric.fx_ file):

```c
#if SM_USE_REVERSE_DEPTHBUFFER == 1
    vDepthMetricSM = (-gl_Position.z + depthValuesSM.x) / depthValuesSM.y + biasAndScaleSM.x;
#else
    vDepthMetricSM = (gl_Position.z + depthValuesSM.x) / depthValuesSM.y + biasAndScaleSM.x;
#endif
```

The aim is to generate a normalized value between `0..1` from the `gl_Position.z` value, which is the z component of the 3D vertex after the **transformation** matrix (**view** x **projection**) has been applied.

In the next sections, we are going to explain which values to set in `depthValuesSM.x` and `depthValuesSM.y` to achieve this goal.

As a preamble, we will only focus on the **projection** matrix because we are only interested in how the projection remaps the z values to the NDC space and the **view** matrix does not come into play in this computation.

**Notes**:

- we could have used the depth texture described in the previous section in all cases to retrieve the depth values we need and avoid having to deal with this depth metric, but for historical reasons, and because WebGL1 does not support depth textures, we need this depth metric.
- this section assumes the NDC Z range is `-1..1`. We will handle the `0..1` range later.
- the reverse depth buffer case is handled simply by swapping the near and far planes of the light in the projection matrix
- the projection matrices we are dealing with are for a left-handed coordinate system, but the results are the same for a right-handed system
- the depth renderer is also using the same computation to generate the depth texture, so what we are describing below for the spotlight (perspective projection) is applicable to the depth renderer (the light being replaced by the camera).

#### Directional light

Directional lights are using an orthographic projection to transform points to NDC space (clip space to be precise). This projection is:

$$
Proj_{ortho} =\begin{bmatrix}
a & 0 & 0 & 0\\
0 & b & 0 & 0\\
0 & 0 & c & 0\\
i0 & i1 & d & 1
\end{bmatrix} \ with\ c=\frac{2}{f\ -\ n} \ and\ d\ =\ -\frac{f\ +\ n}{f\ -\ n}
$$

`n` and `f` are the near and far planes of the light (`light.shadowMinZ` / `light.shadowMaxZ` if defined, `camera.minZ` / `camera.maxZ` if not) respectively. Note that we are only interested in the transformation of the z coordinate, so we don't need the `a`, `b`, `i0` and `i1` values:

$$
z_{ortho} =\begin{bmatrix}
x & y & z & 1
\end{bmatrix}\begin{bmatrix}
. & . & 0 & .\\
. & . & 0 & .\\
. & . & c & .\\
. & . & d & .
\end{bmatrix} =cz+d=\frac{2z-( f+n)}{f-n}
$$

$$
z_{ortho}^{R} =\frac{2z-( n+f)}{n-f} \ ( z_{ortho} \ in\ the\ reverse\ depth\ buffer\ case)
$$

It's a linear function of z (which is something we want), but the range is not `0..1` when z takes values between `n` and `f`:

$$
z=n\ \mapsto \ z_{ortho} =\frac{2n-f-n}{f-n} =\frac{n-f}{f-n} =-1
$$

$$
z=f\ \mapsto \ z_{ortho} =\frac{2f-f-n}{f-n} =\frac{f-n}{f-n} =1
$$

So the range is `-1..1`. To remap this range to `0..1` we can simply add 1 to z and divide everything by 2.

Looking back at how `vDepthMetric` is defined:

```c
vDepthMetricSM = (gl_Position.z + depthValuesSM.x) / depthValuesSM.y + biasAndScaleSM.x;
```

(don't forget that `z_ortho = gl_Position.z`)

We simply need to have `depthValuesSM.x = 1` and `depthValuesSM.y = 2`.

In the JavaScript code, the `depthValuesSM` shader variable is set like this:

```javascript
effect.setFloat2("depthValuesSM", this.getLight().getDepthMinZ(scene.activeCamera), this.getLight().getDepthMinZ(scene.activeCamera) + this.getLight().getDepthMaxZ(scene.activeCamera));
```

So:

```javascript
depthValuesSM.x = this.getLight().getDepthMinZ(scene.activeCamera);
depthValuesSM.y = this.getLight().getDepthMinZ(scene.activeCamera) + this.getLight().getDepthMaxZ(scene.activeCamera);
```

Which means that for directional lights, `getDepthMinZ` must return `1` and `getDepthMaxZ` must also return `1`.

In the reverse depth buffer case:

$$
z=n\ \mapsto \ z_{ortho}^{R} =\frac{2n-n-f}{n-f} =\frac{n-f}{n-f} =1
$$

$$
z=f\ \mapsto \ z_{ortho}^{R} =\frac{2f-n-f}{n-f} =\frac{f-n}{n-f} =-1
$$

This time the range is `1..-1`. However, in the shader, for the reverse depth buffer case we have:

```c
    vDepthMetricSM = (-gl_Position.z + depthValuesSM.x) / depthValuesSM.y + biasAndScaleSM.x;
```

which means `z_ortho` is multiplied by `-1` before the addition with `depthValuesSM.x`. So, `1..-1` is becoming `-1..1` and we are now back to the same case as previously, so we need the same values in `depthValuesSM.x` and `depthValuesSM.y` (that is, 1 and 2 respectively).

#### Spot light

Spot lights use a perspective projection to transform points to NDC space (clip space, to be precise). This projection is:

$$
Proj_{persp} =\begin{bmatrix}
a & 0 & 0 & 0\\
0 & b & 0 & 0\\
0 & 0 & c & 1\\
0 & 0 & d & 0
\end{bmatrix} \ with\ c=\frac{f+n}{f\ -\ n} \ and\ d\ =\ -\frac{2fn}{f\ -\ n}
$$

$$
z_{persp} =\begin{bmatrix}
x & y & z & 1
\end{bmatrix}\begin{bmatrix}
. & . & 0 & .\\
. & . & 0 & .\\
. & . & c & .\\
. & . & d & .
\end{bmatrix} =cz+d=\frac{z( f+n) -2fn}{f-n}
$$

$$
z_{persp}^{R} =\frac{z( n+f) -2nf}{n-f}
$$

Regarding the range when z takes values between `n` and `f`:

$$
z=n\ \mapsto \ z_{persp} =\frac{n( f+n) -2fn}{f-n} =\frac{n( n-f)}{f-n} =-n
$$

$$
z=f\ \mapsto \ z_{persp} =\frac{f( f+n) -2fn}{f-n} =\frac{f( f-n)}{f-n} =f
$$

$$
z=n\ \mapsto \ z_{persp}^{R} =\frac{n( n+f) -2nf}{n-f} =\frac{n( n-f)}{n-f} =n
$$

$$
z=f\ \mapsto \ z_{persp}^{R} =\frac{f( n+f) -2nf}{n-f} =\frac{f( f-n)}{n-f} =-f
$$

The range is `-n..f`, which means that for spot lights we need `getDepthMinZ` to return `n` and `getDepthMaxZ` to return `f` to remap this range to `0..1` once we apply the computation (recall that `depthValuesSM.x = light.getDepthMinZ()` and `depthValuesSM.y = light.getDepthMinZ() + light.getDepthMaxZ()`):

```c
vDepthMetricSM = (gl_Position.z + depthValuesSM.x) / depthValuesSM.y + biasAndScaleSM.x;
```

As for the directional light case, the reverse depth buffer range is negated compared to the normal case, but because of the minus sign in front of `gl_Position.z` in the `vDepthMetricSM` formula, `getDepthMinZ` and `getDepthMaxZ` must return the same values.

#### Point light

Point lights use shadow maps that store the distance from the geometry to the light. This distance is computed as `length(position - lightPosition)`, which is then remapped to the `0..1` range (in the `shadowMapFragment.fx` file):

```c
depthSM = (length(vPositionWSM - lightDataSM) + depthValuesSM.x) / depthValuesSM.y + biasAndScaleSM.x;
```

It's the same computation as previously described except that we are using the distance to the light instead of the depth. `vPositionWSM` is the world position of the point and `lightDataSM` the world position of the light. There's no specific case for the reverse depth buffer mode as it is irrelevant: we are computing a distance, not a depth.

Note that in reality we are not remapping to `0..1` with this formula because `length(vPositionWSM - lightDataSM)` has no maximum bound, it can go to +infinity: `vPositionWSM` is constrained to be in the view frustum but the light can be positioned anywhere in the world. So, to simplify things, we setup the `getDepthMinZ` and `getDepthMaxZ` functions to return the same values as in the spot light case, meaning `n` and `f` respectively. It's not really important that we are not remapping strictly to `0..1` as long as we use the same computation when rendering shadows, so that both values can be compared.

Notes:

- Even if `length(position - lightPosition)` can go to +infinity in theory, the point light is generally not too far from the geometry which is currently in the view frustum because for lights that would be too far their contributions would be very small (or 0) and the light would not cast shadows anyway (every (point) light as a maximum distance after which it falls to 0 intensity)
- we could remove the remapping altogether and simply use `length(position - lightPosition)` as the depth metric, but that would require using a float texture in all cases. When in WebGL1 mode and if the float texture extension is not supported, we are using a UNORM 8 bits texture, so we need a `0..1` remapping

### Generating a depth metric (NDC `0..1` Z range)

When using a NDC space where the z coordinate is in the `0..1` range, the orthographic and perspective projection matrices do change. Let's see how it changes the results from the previous section.

#### Directional light

$$
Proj_{ortho} =\begin{bmatrix}
a & 0 & 0 & 0\\
0 & b & 0 & 0\\
0 & 0 & c & 0\\
i0 & i1 & d & 1
\end{bmatrix}\begin{bmatrix}
1 & 0 & 0 & 0\\
0 & 1 & 0 & 0\\
0 & 0 & 0.5 & 0\\
0 & 0 & 0.5 & 1
\end{bmatrix} =\begin{bmatrix}
. & . & 0 & .\\
. & . & 0 & .\\
. & . & 0.5c & .\\
. & . & 0.5d+0.5 & .
\end{bmatrix}
$$

$$
z_{ortho} =\begin{bmatrix}
x & y & z & 1
\end{bmatrix}\begin{bmatrix}
. & . & 0 & .\\
. & . & 0 & .\\
. & . & 0.5c & .\\
. & . & 0.5d+0.5 & .
\end{bmatrix} =0.5\left(\frac{2z}{f-n} -\frac{f+n}{f-n} +1\right) =\frac{z-n}{f-n}
$$

$$
z_{ortho}^{R} =\frac{z-f}{n-f}
$$

$$
z=n\ \mapsto \ z_{ortho} =\frac{n-n}{f-n} =0
$$

$$
z=f\ \mapsto \ z_{ortho} =\frac{f-n}{f-n} =1
$$

$$
z=n\ \mapsto \ z_{ortho}^{R} =\frac{n-f}{n-f} =1
$$

$$
z=f\ \mapsto \ z_{ortho}^{R} =\frac{f-f}{n-f} =0
$$

We can see that in the non reverse depth buffer case the remapping is already `0..1`, so `getDepthMinZ` should return 0 and `getDepthMaxZ` should return 1.

In the reverse depth buffer case, as we have a negation of z in the `vDepthMetric` formula, the `z_ortho` range is `-1..0`. We need to add 1 to remap to `0..1`. To do that, we can simply have `getDepthMinZ` return 1 and `getDepthMaxZ` return 0.

#### Spot light

$$
Proj_{persp} =\begin{bmatrix}
a & 0 & 0 & 0\\
0 & b & 0 & 0\\
0 & 0 & c & 1\\
0 & 0 & d & 0
\end{bmatrix}\begin{bmatrix}
1 & 0 & 0 & 0\\
0 & 1 & 0 & 0\\
0 & 0 & 0.5 & 0\\
0 & 0 & 0.5 & 1
\end{bmatrix} =\begin{bmatrix}
. & . & 0 & .\\
. & . & 0 & .\\
. & . & 0.5c+0.5 & .\\
. & . & 0.5d & .
\end{bmatrix}
$$

$$
z_{persp} =\begin{bmatrix}
x & y & z & 1
\end{bmatrix}\begin{bmatrix}
. & . & 0 & .\\
. & . & 0 & .\\
. & . & 0.5c+0.5 & .\\
. & . & 0.5d & .
\end{bmatrix} =0.5\frac{z(( f+n) +f-n) -2fn}{f-n} =f\frac{z-n}{f-n}
$$

$$
z_{persp}^{R} =n\frac{z-f}{n-f}
$$

$$
z=n\ \mapsto \ z_{persp} =f\frac{n-n}{f-n} =0
$$

$$
z=f\ \mapsto \ z_{persp} =f\frac{f-n}{f-n} =f
$$

$$
z=n\ \mapsto \ z_{persp}^{R} =n\frac{n-f}{n-f} =n
$$

$$
z=f\ \mapsto \ z_{persp}^{R} =n\frac{f-f}{n-f} =0
$$

In the non reverse depth buffer case, we need to remap `0..f` to `0..1`: we need to divide by `f`. To do that, `getDepthMinZ` should return 0 and `getDepthMaxZ` should return `f`.

In the reverse depth buffer case, we need to remap `-n..0` (don't forget that when using the reverse depth buffer we have `-gl_Position.z` in the `vDepthMetric` formula, not `gl_Position.z`) to `0..1`: we need to add `n` and divide by `n`. To do that, `getDepthMinZ` should return `n` and `getDepthMaxZ` should return 0.

#### Point light

Point lights are no different than in the NDC `-1..1` range case because we are exclusively dealing with distances, the NDC z range is irrelevant.

## Shadow rendering

There's not much to say regarding the shadow rendering part: we simply have to make sure we use the exact same formula to compute the depth metric of the current pixel as the one used to generate the shadow maps. The shader code used to compute the `vDepthMetric` value is, in this case, in the `shadowsVertex.fx` file:

```c
#if USE_REVERSE_DEPTHBUFFER
    vDepthMetric{X} = (-vPositionFromLight{X}.z + light{X}.depthValues.x) / light{X}.depthValues.y;
#else
    vDepthMetric{X} = (vPositionFromLight{X}.z + light{X}.depthValues.x) / light{X}.depthValues.y;
#endif
```

So, we must pass in `light{X}.depthValues.x` and `light{X}.depthValues.y` the same values that we passed in the `depthValuesSM.x` and `depthValuesSM.y` parameters when generating the shadow maps.

**To sum up**

First recall that:

```javascript
depthValues.x = light.getDepthMinZ(camera);
depthValues.y = light.getDepthMinZ(camera) + light.getDepthMaxZ(camera);
```

and that `n` is the near plane distance and `f` the far plane distance (`light.shadowMinZ` / `light.shadowMaxZ` if defined, `camera.minZ` / `camera.maxZ` else):

|                                  | Directional light | Spot light | Point light |
| -------------------------------- | ----------------- | ---------- | ----------- |
| NDC -1..1                        | minZ=1            | minZ=n     | minZ=n      |
|                                  | maxZ=1            | maxZ=f     | maxZ=f      |
| NDC -1..1 + reverse depth buffer | minZ=1            | minZ=n     | minZ=n      |
|                                  | maxZ=1            | maxZ=f     | maxZ=f      |
| NDC 0..1                         | minZ=0            | minZ=0     | minZ=n      |
|                                  | maxZ=1            | maxZ=f     | maxZ=f      |
| NDC 0..1 + reverse depth buffer  | minZ=1            | minZ=n     | minZ=n      |
|                                  | maxZ=0            | maxZ=0     | maxZ=f      |

In this table, `minZ` is for `getDepthMinZ` and `maxZ` is for `getDepthMaxZ`.



## Introduction

Cascaded Shadow Maps (CSM) can greatly enhance the shadows in your scene, but they are only available for **directional lights**. They are generally used for large outdoor scenes to simulate the sun.

This page explains everything you need to know to set up this shadow rendering technique and get the best out of your shadows!

This is a shadow map technique, so a lot of what is said in [Shadows](/features/introductionToFeatures/chap7/shadows) applies, so don't hesitate to read that page first.

Note that CSM requires WebGL 2+.

Here's a Playground demonstrating the CSM technique: <Playground id="#KY0N7T#68" title="Cascaded Shadow Map Example" description="Simple Example of using the CSM system in your scene." isMain={true} category="Shadows"/>

## Technical overview

A quick survey of the technique will help you understand the different properties of the `CascadedShadowGenerator` class. You can also look at the [references](/features/featuresDeepDive/lights/shadows_csm#references) provided at the end of this page for further details.

## Subdividing the frustum

CSM works by subdividing the view frustum (the frustum of the camera, meaning what the camera can see) into several subfrusta, each of which is called a cascade (hence the name of the technique):

**Figure 1. View frustum partitioning (picture from \[[1](#references)\])**
![View frustum partitioning](/img/babylon101/csm/view-frustums-partitioned-arbitrarily.webp)

The subdivision of the camera frustum is done either linearly (each subfrustum has the same length) or logarithmically (the length of the first subfrustum is a lot smaller than the length of the last one). It can also be a combination of linear and logarithmic splitting, with a `lambda` parameter used to combine both (a `0` value means the splitting is fully linear, `1` means it is fully logarithmic, and a value in between implies a mix of both).

## Computing the shadow level

For each subfrustum, a shadow map is generated in much the same way as with the standard shadow generator.

When rendering a mesh, the right shadow map is determined for a given pixel and is sampled to get the shadow level.

**Figure 2. Cascade rendering (picture from \[[1](#references)\])**
![Cascade rendering](/img/babylon101/csm/interval-based-cascade-selection.webp)

In figure 2, pixels pertaining to different cascades are drawn with different colors, so that they are clearly visible.

## Blend between cascades

Sometimes, there can be visible seams between cascades:

**Figure 3. Cascade seams (picture from \[[1](#references)\])**
![Cascade seams](/img/babylon101/csm/cascade-seams.webp)

A blend parameter can be used to smooth the transition (see picture on the right in figure 3).

## Filtering

As for the standard shadow generator, filtering methods can be used to improve / make soft shadows. For CSM, only the PCF (Percentage Closer Filtering) and PCSS (Contact hardening shadows) methods are currently supported (as well as no filtering at all!).

## The `CascadedShadowGenerator` class

## Creation

You create a `CascadedShadowGenerator` instance in exactly the same way as a standard `ShadowGenerator`:

```javascript
const csmShadowGenerator = new BABYLON.CascadedShadowGenerator(1024, light);
```

The first parameter is the shadow map size, and the second is the (directional) light to use the generator for.

To add shadow casters, do as for `ShadowGenerator`:

```javascript
csmShadowGenerator.getShadowMap().renderList.push(torus);
```

or:

- `csmShadowGenerator.addShadowCaster(mesh, includeDescendants)`: Helper function to add a mesh and its descendants to the list of shadow casters
- `csmShadowGenerator.removeShadowCaster(mesh, includeDescendants)`: Helper function to remove a mesh and its descendants from the list of shadow casters

And for the mesh(es) that should receive (display) shadows:

```javascript
mesh.receiveShadows = true;
```

In fact, the class has been designed to be interface-compatible with `ShadowGenerator`, except of course for the parameters specific to CSM and for the fact that only PCF and PCSS are supported as filtering methods. So, you should be able to simply replace:

```javascript
new BABYLON.ShadowGenerator(...)
```

with:

```javascript
new BABYLON.CascadedShadowGenerator(...)
```

in your code and have CSM working out of the box!

**Important**: Unlike the standard `ShadowGenerator`, `light.shadowMinZ` and `light.shadowMaxZ` are NOT used, so don't bother updating them!

## Properties

### numCascades (default: 4)

By default, the generator uses 4 cascades, but you can change this at any time through the `numCascades` property (allowed values are between 2 and 4):

```javascript
csmShadowGenerator.numCascades = 3;
```

**Figure 4. num cascades is 2 on the left, 4 on the right**
![numCascades](/img/babylon101/csm/numcascades-parameter.webp)

### lambda (default: 0.5)

The `lambda` parameter (described in the technical overview) can be set with:

```javascript
csmShadowGenerator.lambda = 0.5;
```

**Figure 5. lambda=0.5 on the left, lambda=0.7 on the right**
![lambda](/img/babylon101/csm/lambda-parameter.webp)

The right value (between 0 and 1) depends on your scene and how the camera will be used: near the ground or high in the sky. You should experiment with different values and see what works best for you.

### cascadeBlendPercentage (default: 0.1)

The cascade blend factor can be set with:

```javascript
csmShadowGenerator.cascadeBlendPercentage = 0.05;
```

**Figure 6. Cascade blend (picture from \[[1](#references)\])**
![cascadeBlendPercentage](/img/babylon101/csm/cascade-seams.webp)

It's a percentage value between 0 and 1. Try to use small values; otherwise, you may get rendering artifacts.

### stabilizeCascades (default: false)

When rotating the camera, you may see the edges of the shadows "swim" / "shimmer". You may fix the problem with the `stabilizeCascades` property:

```javascript
csmShadowGenerator.stabilizeCascades = true;
```

Note however that you will lose some precision in the shadow rendering, so use it only if you need it.

**Figure 7. Precision lost when stabilization is enabled (left: enabled, right: disabled)**
![stabilizeCascades](/img/babylon101/csm/stabilize-parameter.webp)

### shadowMaxZ

This is the limit beyond which shadows are not displayed. It defaults to `camera.maxZ` when constructing the generator.

**Figure 8. shadowMaxZ equal to camera.maxZ on the left, is smaller on the right**
![shadowMaxZ](/img/babylon101/csm/shadowmaxz-parameter.webp)

### depthClamp (default: true)

When enabled, it improves the shadow quality because the near z plane of the different cascade light frusta don't need to be adjusted to account for the shadow casters far away.

Note that this property is incompatible with PCSS filtering, so it won't be used in that case.

### debug (default: false)

When enabled, the cascades are materialized by different colors on the screen:

**Figure 9. Cascade rendering (picture from \[[1](#references)\])**
![Cascade rendering](/img/babylon101/csm/interval-based-cascade-selection.webp)

### freezeShadowCastersBoundingInfo (default: false) and shadowCastersBoundingInfo

Enables or disables the shadow casters and receivers bounding info computation. If your shadow casters and receivers don't move, you can disable this feature. If it is enabled, the bounding box computation is done every frame and the `shadowCastersBoundingInfo` property is updated with the data. The bounding info is used to set the min and max z values of the cascade light frusta.

You can provide your own bounding info by setting the `shadowCastersBoundingInfo` property (don't forget to disable the automatic computation first with `csmShadowGenerator.freezeShadowCastersBoundingInfo = true`!)

### autoCalcDepthBounds (default: false)

_Note: it corresponds to the implementation of the first pass of the Sample Distribution Shadow Maps technique, see [3](#references) for details._

You can greatly improve the shadow rendering (depending on your scene) by setting `autoCalcDepthBounds` to `true`, at the expense of more GPU work.

```javascript
csmShadowGenerator.autoCalcDepthBounds = true;
```

**Figure 10. Same settings for both sides, except for `autoCalcDepthBounds = true` on the right**
![autoCalcDepthBounds](/img/babylon101/csm/sdsm-first-pass.webp)

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 reduction is applied to the depth map to compute the minimal and maximal depth values of the map, and those values are used as inputs for the `setMinMaxDistance()` function.

You can instruct the generator to compute those values less often than each frame with the `autoCalcDepthBoundsRefreshRate` property:

```javascript
csmShadowGenerator.autoCalcDepthBoundsRefreshRate = 2;
```

will perform the computation every two frames. It can produce some visual artifacts, however, as the values used for frustum splitting now lag one frame behind the real values, so test it to see what works best for you.

Note that if you provided your own depth renderer through a call to `setDepthRenderer`, you are responsible for setting the refresh rate on the renderer yourself!

When using `autoCalcDepthBounds = true`, you should increase the value of the `lambda` parameter, and even set it to 1 for best results (experimenting is still the best option, though).

There's no point in using `stabilizeCascades = true` when `autoCalcDepthBounds = true` because the cascade splits are recomputed every frame. So, set this property to `false` for additional resolution in the shadow maps.

You should call `setDepthRenderer` if you already have a depth renderer enabled in your scene, to avoid doing multiple depth renderings each frame. If you provide your own depth renderer, make sure it stores **linear depth**!

Note that you can also call `setMinMaxDistance()` yourself (values between 0 and 1 for min and max), if you know the minimal and maximal z values by some custom means.

### Filtering

The filtering capabilities are the same as for the standard `ShadowGenerator` (except that only PCF and PCSS are supported), so we won't delve into the details here, just refer to [this page](/features/introductionToFeatures/chap7/shadows).

### penumbraDarkness (default: 1)

When using the PCSS filtering method, you can change the 'darkness' of the soft shadows by updating this property:

```javascript
csmShadowGenerator.penumbraDarkness = 0.7;
```

**Figure 11. Value of 0.7 on the left, 0.17 on the right**
![penumbraDarkness](/img/babylon101/csm/penumbra-darkness.webp)

## Culling

There's currently no culling applied to the shadow caster list before rendering the meshes into each of the cascade shadow maps.

However, you can implement your own culling strategy by using this code as a basis:

```typescript
let rtt = csmShadowGenerator.getShadowMap();

rtt.getCustomRenderList = (layer, renderList, renderListLength) => {
  let meshList = [];
  // here do the culling for the cascade with index 'layer' by using the
  // getCascadeViewMatrix(layer), getCSMTransformMatrix(layer), getCascadeMinExtents(layer), etc
  // from csmShadowGenerator
  // note: the renderList entry parameter is the list of all shadow casters defined for the CSM generator,
  // that is csmShadowGenerator.getShadowMap().renderList. If you need to traverse renderList, use
  // renderListLength for the length, not renderList.length, as the array may hold dummy elements!
  return meshList;
};
```

`getCustomRenderList` is called by `RenderTargetTexture` each time it must render a mesh list into a cascade. If you return a regular array of meshes, this array will be used for the rendering into the cascade `layer`. If you return `null`, the `RenderTargetTexture` will proceed with the regular mesh list (that is, the `RenderTargetTexture.renderList` property, in CSM case it is the list of shadow casters).

## Using the `CascadedShadowGenerator` class

## Camera far plane

Perhaps the most important parameter to set is the camera `maxZ` property! Indeed, the CSM technique works by splitting the camera range (`camera.maxZ - camera.minZ`) into cascades, so if the value is not set properly you will get bad shadows.

In the Playground samples, the camera `maxZ` value is generally not explicitly set and so ends up with a value of `10000`, which is too large for most of the cases. See:

**Figure 12. Standard shadows and CSM shadows on PG example**
![CSM and bad camera range](/img/babylon101/csm/bad-camera-maxz.webp)

It's the very first sample linked in the [Shadow](/features/introductionToFeatures/chap7/shadows) page (left part of the picture) where `ShadowGenerator` has simply been changed to `CascadedShadowGenerator` (right part of the picture). As you can see, the shadows on the right are very bad because the `camera.maxZ` value is not set and so is equal to `10000`.

Now, if we set `camera.maxZ` to `200`:

**Figure 13. Same sample with CSM and good camera.maxZ**
![CSM and good camera range](/img/babylon101/csm/good-camera-maxz.webp)

Much better!

Here's the updated PG: <Playground id="#IIZ9UU#36" title="Cascaded Shadow Map Example 2" description="Simple Example of using the CSM system in your scene." image="/img/playgroundsAndNMEs/divingDeeperCSM2.webp"/>

## Changing the camera near / far planes

The generator must recalculate the frustum splits when a number of parameters change: `lambda`, `shadowMaxZ`, `min`/`max` distance properties. This is done automatically by the generator.

However, the splits must also be recomputed if the camera near and/or far planes are changed manually! If you do change the `camera.minZ` and/or `camera.maxZ` values after the generator is created, you must call `CascadedShadowGenerator.splitFrustum()` to trigger a recalculation.

Here's what happens if you change `camera.maxZ` after the generator is created without calling `splitFrustum()`:

**Figure 14. Failing to call `splitFrustum`**
![Fail calling splitFrustum](/img/babylon101/csm/splitfrustum_nok.webp)

PG: <Playground id="#IIZ9UU#41" title="Failing to Call SplitFrustum" description="Failing to call splitFrustum." image="/img/playgroundsAndNMEs/divingDeeperCSM3.webp"/>

**Figure 15. `splitFrustum` called**
![splitFrustum called](/img/babylon101/csm/splitfrustum_ok.webp)

PG: <Playground id="#IIZ9UU#37" title="Calling SplitFrustum" description="Successfully calling splitFrustum." image="/img/playgroundsAndNMEs/divingDeeperCSM4.webp"/>

## Optimizing for speed

If you don't use `shadowMaxZ` (general case, as you normally want your shadows to cover all the camera view area), set it equal to `camera.maxZ`: in that case, some code is removed from the fragment shader, speeding things up a little.

Use smaller values for `cascadeBlendPercentage`. If you can afford it, use a `0` value for this property (best performance, as some code is entirely removed from the fragment shader). Otherwise, use the smallest possible value, because the larger the value, the more additional computation / texture lookups are performed in the shader, as the system must compute the shadow value for the next cascade before blending it with the value for the current cascade.

If using `autoCalcDepthBounds = true`, you can lower the frequency with which the min/max computation is performed by raising the value of `autoCalcDepthBoundsRefreshRate`, but be aware of the rendering artifacts that may show up because of this.

If your shadow casters and receivers don't move, set `freezeShadowCastersBoundingInfo = true`. Even if some of them do move, as long as the whole bounding box does not change, it is safe to set `freezeShadowCastersBoundingInfo` to `true`.

Set `depthClamp = false`. There is a (very) small GPU penalty to enable this property because of a few additional instructions in the depth rendering shaders.

## Optimizing for quality

Best shadow quality is generally achieved by:

- tightening as much as possible the `camera.maxZ - camera.minZ` range
- setting the `camera.minZ` value as high as possible
- using the maximum number of cascades (4)
- using the highest possible map size
- setting `autoCalcDepthBounds = true` with `lambda = 1`
- setting `depthClamp = true`
- setting `stabilizeCascades = false` will improve shadow resolution, but you may experience some "swimming" at the shadow edges when rotating the camera. It's up to you to decide which is better for you: stabilized or improved shadows. As explained above, however, always use `stabilizeCascades = false` if `autoCalcDepthBounds = true` because stabilization is not possible in that case anyway.
- setting `filteringQuality` to high

**Figure 16. Comparing quality**
![High quality](/img/babylon101/csm/high-quality.webp)

On the left:

- cascades stabilized
- `autoCalcDepthBounds = false`
- lambda = 0.7
- shadow map sizes 1024x1024
- `depthClamp = false`
- filtering is PCF medium

On the right:

- cascades not stabilized
- `autoCalcDepthBounds = true`
- lambda = 1
- shadow map sizes 2048x2048
- `depthClamp = true`
- filtering is PCF high

For comparison's sake, here is the same part rendered with the standard `ShadowGenerator` (far right, map size is 2048x2048):

**Figure 17. Comparing with standard `ShadowGenerator`**
![Comparison](/img/babylon101/csm/comparison-with-standard.webp)

## References

Microsoft [Cascaded Shadow Maps](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps) DirectX Sample

[A sampling of Shadow Techniques](https://mynameismjp.wordpress.com/2013/09/10/shadow-maps/) by MJP

[Sample Distribution Shadow Maps](https://software.intel.com/en-us/articles/sample-distribution-shadow-maps) by Andrew Lauritzen (Intel), Kohei, Komono, Aaron Lefohn (Intel)



## The Volumetric LightScattering post-process

BABYLON.VolumetricLightScatteringPostProcess is a post-process that computes light scattering based on a light source mesh.

### How to use it? Easy!

```javascript
const vls = new BABYLON.VolumetricLightScatteringPostProcess("vls", 1.0, camera, lightSourceMesh, samplesNum, BABYLON.Texture.BILINEAR_SAMPLINGMODE, engine, false);
```

**_ Parameters _**

- name \{string\} - The post-process name.
- ratio \{any\} - The size of the post-process and/or internal pass (0.5 means that your post-process will have a _width = canvas.width \* 0.5_ and a _height = canvas.height \* 0.5_.)
- camera \{BABYLON.Camera\} - The camera that the post-process will be attached to.
- lightSourceMesh \{BABYLON.Mesh\} - The mesh used as a light source, to create the light scattering effect (for example, a billboard with its texture simulating the sun.)
- samplesNum \{number\} - The post-process quality. Default is 100.
- samplingMode \{number\} - The post-process filtering mode.
- engine \{BABYLON.Engine\} - The Babylon engine.
- reusable \{boolean\} - If the post-process is reusable.
- scene \{BABYLON.Scene\} - If the _camera_ parameter is null (adding the post-process in a rendering pipeline), the _scene_ is needed to configure the internal pass.

The lightSourceMesh is a mesh that will contain the light color, typically a billboard with a diffuse texture. If your light source is coming from the floor, you can use the floor/ground mesh to compute the light scattering effect.

**Note: The light source mesh can be null. This causes a default lightSourceMesh to be created for you as a billboard.**

To create the default mesh before the post-process, there is a static method that returns a billboard as the default:

```javascript
const defaultMesh = BABYLON.VolumetricLightScatteringPostProcess.CreateDefaultMesh("meshName", scene);
```

You can access and modify the mesh using:

```javascript
const mesh = vls.mesh;
```

By default, the post-process computes light scattering using the internal mesh position. You can modify it and set a custom position using the following code (typically for the floor as the internal mesh):

```javascript
vls.useCustomMeshPosition = true;
vls.setCustomMeshPosition(new BABYLON.Vector3(5.0, 0.0, 5.0));
```

**Warning: If the custom light position is too far from the light source, the result will be distorted.**

You can access the custom position using:

```javascript
const position = vls.getCustomMeshPosition();
```

To customize the light scattering, you can modify the vertical direction of the light rays. If _invert_ is set to true, the rays will go downward. If _invert_ is set to false, the rays will go upward.

```javascript
vls.invert = true;
```

To optimize performance, you can customize the rendering quality. In fact, this post-process uses an internal pass (render target texture) that helps the post-process compute the light scattering effect. Of course, you can compute the pass at a lower ratio, like this:

```javascript
const vls = new BABYLON.VolumetricLightScatteringPostProcess("vls", { postProcessRatio: 1.0, passRatio: 0.5 }, camera, lightSourceMesh, 75, BABYLON.Texture.BILINEAR_SAMPLINGMODE, engine, false);
```

`vls.useDiffuseColor` is used to force rendering the diffuse color of the light source mesh instead of its diffuse texture.

- If useDiffuseColor is true or material.diffuseTexture is undefined, use the diffuse color

- If useDiffuseColor is false and material.diffuseTexture is not undefined, use diffuse texture

- If useDiffuseColor is false and material.diffuseTexture is undefined, use diffuse color

Using `material.diffuseColor` instead of `material.diffuseTexture` (the default) for the light's color:

```javascript
vls.useDiffuseColor = true; // False as default
vls.mesh.material.diffuseColor = new BABYLON.Color3(0.0, 1.0, 0.0);
```

Using the material.diffuseTexture for the light's color:

```javascript
vls.useDiffuseColor = false; // False as default
vls.mesh.material.diffuseTexture= new BABYLON.Texture(...);
```

### And now, it's time to play

Feel free to explore some examples of Volumetric LightScattering in the Playground:

- <Playground id="#AU5641" title="Basic Example" description="Simple example of adding a basic light scattering post process to your scene." image="/img/playgroundsAndNMEs/divingDeeperVolumetricLightScatterPP1.webp"/>
- <Playground id="#HYFQJ" title="Spherical Harmonics as Source" description="Simple example of adding a light scattering post process with spherical harmonics as a source." image="/img/playgroundsAndNMEs/divingDeeperVolumetricLightScatterPP2.webp"/>
- <Playground id="#UUXLX#37" title="VLS through CSG-created slots" description="Simple example of adding a light scattering post process through CSG-created slots." image="/img/playgroundsAndNMEs/divingDeeperVolumetricLightScatterPP3.webp"/>

Have fun!

## The Volumetric Lighting Task

Starting with Babylon 9.0, you can use a new volumetric lighting effect, but it is only available with frame graphs: the [FrameGraphVolumetricLightingTask](/features/featuresDeepDive/frameGraph/frameGraphClassFramework/frameGraphTaskList#framegraphvolumetriclightingtask).

The implementation is based on the article “Participating media using extruded light volumes” that you can find in [GPU Zen 1](https://www.amazon.com/GPU-Zen-Advanced-Rendering-Techniques/dp/0998822892). You can also find information in the [GDC slides](https://d29g4g2dyqv443.cloudfront.net/sites/default/files/akamai/gameworks/downloads/papers/NVVL/Fast_Flexible_Physically-Based_Volumetric_Light_Scattering.pdf).

The `FrameGraphVolumetricLightingTask` task renders a mesh using the technique described in the links above. In general, you will want this mesh to represent the volume that a light can reach in your scene: use the [FrameGraphLightingVolumeTask](/features/featuresDeepDive/frameGraph/frameGraphClassFramework/frameGraphTaskList#framegraphlightingvolumetask) to generate such a mesh:

```typescript
// Create first a shadowGeneratorTask and a renderTask instance [...]
// Then
const lightingVolumeTask = new BABYLON.FrameGraphLightingVolumeTask("lightingVolume", frameGraph);

lightingVolumeTask.shadowGenerator = shadowGeneratorTask;

const lightVolume = lightingVolumeTask.lightingVolume;

lightVolume.frequency = isWebGPU ? 1 : 4;
lightVolume.tesselation = isWebGPU ? 1024 : 256;

frameGraph.addTask(lightingVolumeTask);

const volumetricLightingTask = new BABYLON.FrameGraphVolumetricLightingTask("volumetricLighting", frameGraph, true /*enableExtinction*/);

volumetricLightingTask.targetTexture = renderTask.outputTexture;
volumetricLightingTask.depthTexture = renderTask.outputDepthTexture;
volumetricLightingTask.camera = camera;
volumetricLightingTask.lightingVolumeMesh = lightingVolumeTask.outputMeshLightingVolume;
volumetricLightingTask.light = light;
volumetricLightingTask.lightPower = new BABYLON.Color3(0.8, 0.8, 0.8);
volumetricLightingTask.extinction = new BABYLON.Vector3(0.01, 0.01, 0.03);
volumetricLightingTask.phaseG = 0.05;

frameGraph.addTask(volumetricLightingTask);
```

This effect works best in WebGPU because we can use a compute shader to update the lighting volume, whereas in WebGL, we have to read back the shadow map texture and update the volume on the CPU side.

That's why, in the code above, we reduce the **frequency** of volume updates when using WebGL (4 means we update every 4 frames) and use a lower **tessellation** value (i.e., fewer triangles) for the mesh to improve performance.

Please refer to the [FrameGraphVolumetricLightingTask](/features/featuresDeepDive/frameGraph/frameGraphClassFramework/frameGraphTaskList#framegraphvolumetriclightingtask) page for detailed information on task parameters and PG examples.

<Playground engine="webgpu" id="#WLGEJB#44" image="/img/playgroundsAndNMEs/pg-WLGEJB-3.webp" title="Volumetric lighting task" description="Example of a frame graph using the volumetric lighting task"/>




## Lights and Shadows

Lights are, of course, necessary to see meshes and affect their brightness and color. Although lights illuminate meshes, they only produce shadows when shadow generation is enabled for the mesh. The default number of allowed lights is four, but this can be increased.

There are five types of lights that can be used, each with a range of lighting properties.

- The Point Light - think light bulb.
- The Directional Light - think planet lit by a distant sun.
- The Spot Light - think of a focused beam of light.
- The Hemispheric Light - think of the ambient light.
- The Rectangular Area Light - think LED panel.

Color properties for all lights include _emissive_, _diffuse_ and _specular_.

Overlapping lights will interact as you would expect, with the overlap of red, green, and blue producing white light. Every light can be switched on or off, and when it is on, its intensity can be set with a value from 0 to 1.

For shadows a _shadowGenerator_ object is needed. There is also an extension, **shadows only**, that allows shadows on a transparent mesh.

To understand how meshes react to light, you need to know about the normals of a mesh, since they form part of the calculations that determine color and illumination.



# Gaussian Splatting File Import
Babylon.js supports multiple Gaussian splatting file formats:
- .PLY
- .Splat
- .compressed.PLY
- Niantic .SPZ
- .SOG/SOGS Self-Organizing Gaussian https://github.com/fraunhoferhhi/Self-Organizing-Gaussians

To use it, you just have to reference it after Babylon.js:

```html
<script src="Babylon.js"></script>
<script src="babylon.splatFileLoader.js"></script>
```

If you want to import splat files statically (not recommended), you can do so via:

```javascript
import "@babylonjs/loaders/SPLAT/splatFileLoader";
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport).


Lights

Lights and Shadows

Coming next

Shadows

Learn how to leverage shadows in Babylon.js

Introduction To Lights

Learn the basics of lights in Babylon.js

Cascaded Shadow Maps

Learn how to utilize Cascaded Shadow Maps in Babylon.js

Volumetric Light Scattering Post Process

Learn how to utilize a Babylon.js post process to simulate light scattering.

Global Illumination with Reflective Shadow Maps

Learn how to utilize Babylon.js to render scenes with global illumination

Mathematics of the depth metric when generating shadow maps and rendering with shadows

Some in-depth knowledge on how Babylon.js is computing the depth metric used in shadow map generation and shadows rendering when in normal / reverse depth buffer mode and when using either the -1..1 or 0..1 NDC Z range

Clustered Lighting

Learn about Babylon's clustered lighting implementation