Chapter 531: CSM

Core Idea

An implementation of Cascade Shadow Maps (CSM).

This module can only be used with WebGLRenderer. When using WebGPURenderer, use CSMShadowNode instead.

Key Concepts

• breaks : Array.<number>: An array of numbers in the range [0,1] the defines how the mainCSM frustum should be split up.
• camera : Camera: The scene's camera.
• cascades : number: The number of cascades.
• customSplitsCallback : function: Custom split callback when using mode='custom'.
• fade : boolean: Whether to fade between cascades or not.
• frustums : Array.<CSMFrustum>: An array of frustums representing the cascades.
• lightDirection : Vector3: The light direction.
• lightFar : number: The light far value.
• lightIntensity : number: The light intensity.
• lightMargin : number: The light margin.

Code Examples

import { CSM } from 'three/addons/csm/CSM.js';

• What it demonstrates: Typical usage of CSM.

Reference Tables

Constructor

Signature
new CSM( data : CSM~Data )

Properties

Property	Description
.breaks : Array.<number>	An array of numbers in the range [0,1] the defines how the mainCSM frustum should be split up.
.camera : Camera	The scene's camera.
.cascades : number	The number of cascades.
.customSplitsCallback : function	Custom split callback when using mode='custom'.
.fade : boolean	Whether to fade between cascades or not.
.frustums : Array.<CSMFrustum>	An array of frustums representing the cascades.
.lightDirection : Vector3	The light direction.
.lightFar : number	The light far value.
.lightIntensity : number	The light intensity.
.lightMargin : number	The light margin.
.lightNear : number	The light near value.
.lights : Array.<DirectionalLight>	An array of directional lights which cast the shadows for the different cascades. There is one directional light for each cascade.
.mainFrustum : CSMFrustum	The main frustum.
.maxFar : number	The maximum far value.
`.mode : 'practical'	'uniform'
.parent : Object3D	The parent object, usually the scene.
.shaders : Map.<Material, Object>	A Map holding enhanced material shaders.
.shadowBias : number	The shadow bias.
.shadowMapSize : number	The shadow map size.

Methods

Method	Description
.dispose()	Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.
.remove()	Applications must call this method when they remove the CSM usage from their scene.
.setupMaterial( material : Material )	Applications must call this method for all materials that should be affected by CSM.
.update()	Updates the CSM. This method must be called in your animation loop before calling renderer.render().
.updateFrustums()	Applications must call this method every time they change camera or CSM settings.

Key Takeaways

1. Most relevant properties: breaks, camera, cascades, customSplitsCallback.
2. Key methods: dispose, remove, setupMaterial, update.

Connects To

• Source: examples/jsm/csm/CSM.js