
## Lights
Lights are used, as you would expect, to affect how meshes are seen, in terms of both illumination and colour.
All meshes allow light to pass through them unless shadow generation is activated. The default number of lights allowed is
four but this can be increased.

![Elements](/img/testlight.jpg)

_A pretty sphere with multiple lights_


## Types of Lights
There are four types of lights that can be used with a range of lighting properties.

### The Point Light
A point light is a light defined by an 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
var 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 when a distant planet is lit by the apparently parallel lines of light from its sun. Light in a downward direction will light
the top of an object.

```javascript
var 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 the speed of the decay of the light with distance (reach).

_A simple use of a spot light_

```javascript
var 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 an ambient environment light. A hemispheric light is defined by a direction, usually 'up' towards the sky. However it is by setting the color properties
that the full effect is achieved.

```javascript
var light = new BABYLON.HemisphericLight("HemiLight", new BABYLON.Vector3(0, 1, 0), scene);
```

## Color Properties
There are three properties of lights that affect color. Two of these _diffuse_ and _specular_ apply to all four types of light, the third, _groundColor_, only applies to an 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.jpg"/>

<Playground id="#20OAV9#1" title="Directional Light Example" description="Simple Example of adding a Directional Light to your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro2.jpg"/>

<Playground id="#20OAV9#3" title="Spot Light Example" description="Simple Example of adding a Spot Light to your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro3.jpg"/>

<Playground id="#20OAV9#5" title="Hemispheric Light Example" description="Simple Example of adding a Hemispheric Light to your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro4.jpg"/>

For a hemispheric light the _groundColor_ is the light in the opposite direction to the one specified during creation.
You can think of the _diffuse_ and _specular_ light as coming from the centre of the object in the given direction and the _groundColor_ light in the opposite direction.

<Playground id="#20OAV9#5" title="Hemispheric Light On 2 Spheres" description="Simple Example of a Hemispheric Light on 2 spheres." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro5.jpg"/>

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.jpg"/>

## Limitations
Babylon.js allows you to create and register as many lights as you choose, but know that a single StandardMaterial can only handle a defined number simultaneous lights (by default this value is equal to 4 which means the first four enabled lights of the scene's lights list).
You can change this number with this code:

```javascript
var material = new BABYLON.StandardMaterial("mat", scene);
material.maxSimultaneousLights = 6;
```
But beware! Because with more dynamic lights, Babylon.js will generate bigger shaders which may not be compatible with low end devices like mobiles or small tablets. In this case, babylon.js will try to recompile shaders with less lights.

<Playground id="#IRVAX#0" title="6 Intersecting Point Lights" description="Simple Example with 6 intersecting point lights." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro7.jpg"/>

## 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 values 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 add the ones not to be excluded to the _includedOnlyMeshes_ array. The number of meshes to be excluded can be one factor in deciding which method to use. In the following example two meshes are to be 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.jpg"/>

## Lighting Normals
How lights react to a mesh depend on values set for each mesh vertex termed _normals_, shown in the picture below as arrows giving the direction of the lighting normals. The picture shows two planes and two lights. One light is a spot light, the other is a point light. The front face of each plane is the one you see when the _normals_ are pointing towards you, the back face the opposite side.

![Elements](/img/how_to/Mesh/normals6.jpg)

_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
var lightmap = new BABYLON.Texture("lightmap.png", scene);
var material = new BABYLON.StandardMaterial("material", scene);
material.lightmapTexture = lightmap;
```
Note: To use the texture as a shadowmap instead of 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 will cause 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#2" title="Lightmaps Example" description="Simple Example of using lightmaps in your scene." image="/img/playgroundsAndNMEs/divingDeeperLightsIntro9.jpg"/>

## Projection Texture
In some cases it would be nice 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 that you are trying to simulate the light effects inside of a cathedral. The light going through the stained glasses will be projected on the ground. This is also true for the light coming from a projector or the light effects you can 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
var 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.jpg"/>

<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 the range in light space, there is no texture projection.
* ```projectionTextureLightFar``` : far range of the texture projection. If a plane is before the range in light space, there is no texture projection.
* ```projectionTextureUpDirection``` : helps defining the light space which is oriented towards the light direction and aligned with the up direction.

The projected information is multiplied against the normal light values to better fit in the Babylon JS lighting. It also only impact the diffuse value. So it might be necessary to change the specular color of the light to better fit with the scene.


## Introduction

Cascaded Shadow Maps (CSM) can greatly enhance the shadows in your scene, but it is only available for **directional lights**. It is generally used for large outdoor scenes, to simulate the sun.

This page will explain everything you need to know in order to setup 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](/start/chap7/shadows) does apply, so don't hesitate to read this page first.

Note that CSM requires WebGL 2+.

Here's a Playground demonstrating the CSM technique and the existing `ShadowGenerator`: <Playground id="#IIZ9UU#40" title="Cascaded Shadow Map Example" description="Simple Example of using the CSM system in your scene." image="/img/playgroundsAndNMEs/divingDeeperCSM1.jpg"/>

## Technical overview

A quick survey of the technique will help to understand the different properties of the `CascadedShadowGenerator` class. You can also have a look at the [references](/divingDeeper/lights/shadows_csm#references) provided at the end of this page for further details.

## Subdividing the frustum

CSM works by subdividing the view frustum (frustum of the camera, meaning what the camera can see) into several subfrusta, each of them being called a cascade (hence the name of the technique):

**Figure 1. View frustum partitionning (picture from \[[1](#references)\])**
![View frustum partitionning](/img/babylon101/csm/view-frustums-partitioned-arbitrarily.png)

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 the linear and logarithmic splitting, a `lambda` parameter being 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 the standard shadow generator does.

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.jpg)

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.jpg)

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
var csmShadowGenerator = new BABYLON.CascadedShadowGenerator(1024, light);
```

The first parameter is the shadow map size and the second one 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 just working out of the box!

**Important**: contrary to the standard `ShadowGenerator`, `light.shadowMinZ` and `light.shadowMaxZ` are NOT used, so don't bother to update 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 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.jpg)

### 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.jpg)

The right value (between 0 and 1) depends on your scene and how the camera is to 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.jpg)

It's a percentage value between 0 and 1. Try to use small values, else you may get rendering artifacts.

### stabilizeCascades (default: false)

When rotating the camera, you may see the edges of the shadows "swimm" / "shimmer". You may fix the problem with the `stabilizeCascades` property:
```javascript
csmShadowGenerator.stabilizeCascades = true;
```

Note however that you will loose some precision in the shadow rendering, so use it only if you need it.

**Figure 7. Precision lost when stabilization enabled (left: enabled, right: disabled)**
![stabilizeCascades](/img/babylon101/csm/stabilize-parameter.jpg)

### shadowMaxZ

It's 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.jpg)

### 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.jpg)


### 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 bouding 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.jpg)

When enabled, a depth rendering pass is first performed (with an internally created depth renderer or with the one you provide by calling `setDepthRenderer`). Then, a min/max reducing is applied on the depth map to compute the minimal and maximal depth 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 the frustum splitting are now lagging one frame behind the real values, so make testing 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 to use `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 rendering 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 than 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](/start/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.jpg)

## Culling

There's currently no culling applied on 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.jpg)

It's the very first sample linked in the [Shadow](/start/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.jpg)

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.jpg"/>

## 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. It 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 calling `splitFrustum`**
![Fail calling splitFrustum](/img/babylon101/csm/splitfrustum_nok.jpg)

PG: <Playground id="#IIZ9UU#41" title="Failing to Call SplitFrustum" description="Failing to call splitFrustum." image="/img/playgroundsAndNMEs/divingDeeperCSM3.jpg"/>


**Figure 15. `splitFrustum` called**
![splitFrustum called](/img/babylon101/csm/splitfrustum_ok.jpg)

PG: <Playground id="#IIZ9UU#37" title="Calling SplitFrustum" description="Successfully calling splitFrustum." image="/img/playgroundsAndNMEs/divingDeeperCSM4.jpg"/>

## 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 performances as some code is entirely removed from the fragment shader). Else, use the smallest possible value, as the larger value the more additional computation / texture lookups is 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 penality 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 rotation 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.jpg)

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 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.jpg)

## 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)

## How To Use the Volumetric LightScattering post-process
BABYLON.VolumetricLightScatteringPostProcess is a post-process that will compute the light scattering according to a light source mesh.

## How to use it? Easy! ##

```
var 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 postprocess 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 colour, 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:

```
var defaultMesh = BABYLON.VolumetricLightScatteringPostProcess.CreateDefaultMesh("meshName", scene);
```

You can access and modify the mesh using:

```
var mesh = vls.mesh;
```

By default, the post-process is computing the light scattering using the internal mesh position.  You can modify and set a custom position using (typically for the floor as the internal mesh):

```
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:

```
var 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. Upward, if invert is set false.

```
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 will help the post-process to compute the light scattering effect. Of course, you can compute the pass in a lower ratio like:

```
var 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 the material.diffuseColor instead of material.diffuseTexture (as default) for the light's color:

```
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:

```
vls.useDiffuseColor = false; // False as default
vls.mesh.material.diffuseTexture= new BABYLON.Texture(...);
```

## And now, it's time to play ! ##

Feel free to tour 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.jpg"/>
- <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.jpg"/>
- <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.jpg"/>



Have fun !


## Introduction

Downloading large assets is often slow even with a decent internet connection. Progressively loading discrete levels of detail (LODs) is one technique to combat this. The idea is to store multiple LODs in the asset and progressively load them from low to high quality. This method improves the time to first render since the lowest quality LOD is often dramatically smaller than the highest quality LOD.

<Playground id="#ARN6TJ#5" title="Progressive Loading With LODs" description="Simple Example of progressively loading assets with levels of detail." image="/img/playgroundsAndNMEs/divingDeeperProgressivelyLoading1.jpg"/>

This demo playground loads a glTF binary (a.k.a. GLB) asset which is a single file store on the server. It uses HTTP range requests to partially download parts of the GLB. The glTF loader minimizes the amount of HTTP requests sent to the server for optimal efficiency. It also shows progress of each stage of the download. Console logging is enabled to show what the glTF loader is doing.

## About MSFT_lod

[MSFT_lod](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/MSFT_lod) is a Microsoft glTF extension for discrete LODs. It has support for both node and material LODs. Babylon.js currently only supports progressively loading these LODs for the purpose of reducing the time to first render. LODs that switch based on rendering distance or screen coverage is not currently supported.

There are not many tools that can create assets with MSFT_lod at the moment. The asset in the demo above is exported from [Adobe Dimension](https://www.adobe.com/products/dimension.html) for sharing on the web. [BabylonPolymorph](https://github.com/BabylonJS/BabylonPolymorph) will eventually be able to do this, but this project is still very early. There is also [glTF-Toolkit](https://github.com/Microsoft/glTF-Toolkit) for Windows Mixed Reality which unfortunately is not well suited for Babylon.js, but perhaps it can be modified to work better.

## Using HTTP Range Requests

A glTF asset can be either loose files or packed together into a glTF binary (GLB). Serving files as GLB on a server is typically not a good idea except when using [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests). Using range requests will enable the loader to partially download a range of the asset instead of all at once. The glTF loader in Babylon.js supports range requests. It can be enabled like this:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.useRangeRequests = true;
    }
});
```

## Caveats
- The HTTP server hosting the asset must support range requests.
- The LODs in the GLB should be authored with a contiguous range per LOD for maximum efficiency.

## Showing Progress

When loading large assets either using loose files or with range requests, it is useful to show the download progress. Progress is supported through the progress callback of `BABYLON.SceneLoader` methods which is a small subset of the HTTP request [progress event](https://developer.mozilla.org/en-US/docs/Web/API/ProgressEvent). Here is an example from the demo above:

```javascript
BABYLON.SceneLoader.AppendAsync(url, undefined, scene, function (event) {
    // Compute the percentage for each stage unless the length is not computable.
    // The lengthComputable is often false when serving content that is gzipped.
    const percentage = event.lengthComputable ? " " + Math.floor(event.loaded / event.total * 100) + "%" : "";

    // Check if an LOD is loading yet.
    if (lodNext === null) {
        // Ignore GLB header progress.
        if (event.total === 20) return;

        // Show that the glTF is downloading.
        bottomLine.text = "Loading glTF..." + percentage;
    }
    else {
        // Show that the LOD is downloading.
        bottomLine.text = "Loading '" + lodNames[lodNext] + "' LOD..." + percentage;
    }
}, ".glb")
```

## Key Notes
- Gzipped content hosted on server often results in `lengthComputable` equaling `false` which in turn causes the `total` to be zero. When this happens, the only choices are to not show the progress or show the number of bytes downloaded instead.
- When using HTTP range requests with a GLB, the first thing that is downloaded is the GLB header which downloads very quickly and is almost always 20 bytes loaded and 20 bytes total when the progress event fires. Ignore it by checking when `total` is exactly 20.

## Debugging LODs

It is useful to stop at a specific LOD to inspect the results. This can be achieved by setting the `maxLODsToLoad` property on the MSFT_lod loader extension:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.onExtensionLoadedObservable.add(function (extension) {
            if (extension.name === "MSFT_lod") {
                // Stop at the first LOD.
                extension.maxLODsToLoad = 1;
            }
        }
    }
}
```

## Enabling Logging

Enabling logging is often useful to understand and debug the loading of a glTF asset. This is especially true for MSFT_lod assets. Logging can be enabled like this:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.loggingEnabled = true;
    }
});
```

Here is an example console log from the demo above:
```
BJS - [16:31:29]: Binary version: 2
BJS - [16:31:29]: JSON length: 59200
BJS - [16:31:29]: Loading 0
BJS - [16:31:29]: Asset version: 2.0
BJS - [16:31:29]: Asset generator: Adobe Dimension - 9ce31d2be91132df879a9b9136f9df4ef7b7fa2c
BJS - [16:31:29]: LOADING
BJS - [16:31:29]: /scenes/0 scene
BJS - [16:31:29]:   /nodes/0 render_camera_n3d
BJS - [16:31:29]:     /cameras/0 render_camera
BJS - [16:31:29]:   /nodes/1 ground_plane_n3d
BJS - [16:31:29]:   /nodes/2 sportsCar_4K
BJS - [16:31:29]:     /nodes/3 car_lores.obj
BJS - [16:31:29]:       /nodes/4 g car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:         /nodes/5 car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:           /meshes/0 car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:             /meshes/0/primitives/0
BJS - [16:31:29]:               deferred
BJS - [16:31:30]:               /materials/12/extensions/MSFT_lod
BJS - [16:31:30]:                 /materials/0 details_lod2
BJS - [16:31:30]:                   /materials/0/normalTexture
BJS - [16:31:30]:                     /textures/2 tmp_image_pie_10f1_2c55_943e
BJS - [16:31:30]:                       /images/2 normal
BJS - [16:31:30]:                         deferred
BJS - [16:31:30]:                   /materials/0/occlusionTexture
BJS - [16:31:30]:                     /textures/1 ambient_roughness_metallic
BJS - [16:31:30]:                       /images/1 ambient_roughness_metallic
BJS - [16:31:30]:                         deferred
...
BJS - [16:31:32]: Loading buffer range [0-4864522]
BJS - [16:31:37]: READY
BJS - [16:31:37]: Loading buffer range [4864523-8856965]
BJS - [16:31:39]: Loaded material LOD 1
BJS - [16:31:39]: Loading buffer range [8856966-67953580]
BJS - [16:32:00]: Loaded material LOD 2
BJS - [16:32:00]: COMPLETE
```

Note the `deferred` message when loading primitives and images. The loader is deferring the download until it has determined what ranges of the GLB is necessary for the LODs. Once the ranges are determined, the loader loads the range for the first LOD before the state changes to `READY` which indicates the asset is ready for viewing. Then it loads the remaining LODs in sequence until all the LODs are loaded before the state changes to `COMPELTE` which indicates the asset is completely loaded.

Lights

Lights and Shadows

Coming next

Introduction To Lights

Learn the basics of lights in Babylon.js

Shadows

Learn how to leverage shadows 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.