Class DirectionalLightShadow

This is used internally by DirectionalLights for calculating shadows. Unlike the other shadow classes, this uses an OrthographicCamera to calculate the shadows, rather than a PerspectiveCamera

Remarks

This is because light rays from a DirectionalLight are parallel.

Example

//Create a WebGLRenderer and turn on shadows in the renderer
const renderer = new THREE.WebGLRenderer();
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap; // default THREE.PCFShadowMap
//Create a DirectionalLight and turn on shadows for the light
const light = new THREE.DirectionalLight(0xffffff, 1);
light.position.set(0, 1, 0); //default; light shining from top
light.castShadow = true; // default false
scene.add(light);
//Set up shadow properties for the light
light.shadow.mapSize.width = 512; // default
light.shadow.mapSize.height = 512; // default
light.shadow.camera.near = 0.5; // default
light.shadow.camera.far = 500; // default
//Create a sphere that cast shadows (but does not receive them)
const sphereGeometry = new THREE.SphereGeometry(5, 32, 32);
const sphereMaterial = new THREE.MeshStandardMaterial({
    color: 0xff0000
});
const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
sphere.castShadow = true; //default is false
sphere.receiveShadow = false; //default
scene.add(sphere);
//Create a plane that receives shadows (but does not cast them)
const planeGeometry = new THREE.PlaneGeometry(20, 20, 32, 32);
const planeMaterial = new THREE.MeshStandardMaterial({
    color: 0x00ff00
})
const plane = new THREE.Mesh(planeGeometry, planeMaterial);
plane.receiveShadow = true;
scene.add(plane);
//Create a helper for the shadow camera (optional)
const helper = new THREE.CameraHelper(light.shadow.camera);
scene.add(helper);

See

Hierarchy (view full)

Constructors

constructor

Properties

autoUpdate bias blurSamples camera isDirectionalLightShadow map mapPass mapSize matrix needsUpdate normalBias radius

Methods

clone copy dispose getFrameExtents getFrustum getViewport getViewportCount toJSON updateMatrices

Constructors

constructor

Properties

autoUpdate

autoUpdate: boolean

Enables automatic updates of the light's shadow. If you do not require dynamic lighting / shadows, you may set this to false.

Default Value

true

bias

bias: number

Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.

Remark

The Very tiny adjustments here (in the order of 0.0001) may help reduce artifacts in shadows.

Remarks

Expects a Float

Default Value

0

blurSamples

blurSamples: number

The amount of samples to use when blurring a VSM shadow map.

Remarks

Expects a Integer

Default Value

8

camera

camera: OrthographicCamera

The light's view of the world.

Remarks

This is used to generate a depth map of the scene; objects behind other objects from the light's perspective will be in shadow.

Default Value

is an {@link THREE.OrthographicCamera | OrthographicCamera} with
{@link OrthographicCamera.left | left} and {@link OrthographicCamera.bottom | bottom} set to -5,
{@link OrthographicCamera.right | right} and {@link OrthographicCamera.top | top} set to 5,
the {@link OrthographicCamera.near | near} clipping plane at 0.5 and
the {@link OrthographicCamera.far | far} clipping plane at 500.

Readonly isDirectionalLightShadow

isDirectionalLightShadow: true

Read-only flag to check if a given object is of type DirectionalLightShadow.

Remarks

This is a constant value

Default Value

true

map

map: null | WebGLRenderTarget<Texture>

The depth map generated using the internal camera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.

Default Value

null

mapPass

mapPass: null | WebGLRenderTarget<Texture>

The distribution map generated using the internal camera; an occlusion is calculated based on the distribution of depths. Computed internally during rendering.

Default Value

null

mapSize

mapSize: Vector2

A Vector2 defining the width and height of the shadow map.

Remarks

Higher values give better quality shadows at the cost of computation time.

Default Value

new THREE.Vector2(512, 512)

matrix

matrix: Matrix4

Model to shadow camera space, to compute location and depth in shadow map. Stored in a Matrix4.

Remarks

This is computed internally during rendering.

Default Value

new THREE.Matrix4()

needsUpdate

needsUpdate: boolean

When set to true, shadow maps will be updated in the next render call. If you have set autoUpdate to false, you will need to set this property to true and then make a render call to update the light's shadow.

Default Value

false

normalBias

normalBias: number

Defines how much the position used to query the shadow map is offset along the object normal.

Remark

The Increasing this value can be used to reduce shadow acne especially in large scenes where light shines onto geometry at a shallow angle.

Remark

The cost is that shadows may appear distorted.

Remarks

Expects a Float

Default Value

0

radius

radius: number

Setting this to values greater than 1 will blur the edges of the shadow.toi

Remark

High values will cause unwanted banding effects in the shadows - a greater mapSize will allow for a higher value to be used here before these effects become visible. @remark If {@link THREE.WebGLRenderer.shadowMap.type | WebGLRenderer.shadowMap.type is set to PCFSoftShadowMap, radius has no effect and it is recommended to increase softness by decreasing mapSize instead.

Remark

Note that this has no effect if the WebGLRenderer.shadowMap.type is set to BasicShadowMap.

Remarks

Expects a Float

Default Value

1

Methods

clone

  • clone(recursive?): this

  • Creates a new LightShadow with the same properties as this one.

    Parameters

    • Optional recursive: boolean

    Returns this

copy

  • copy(source): this

  • Copies value of all the properties from the {@link LightShadow | source} to this Light.

    Parameters

    Returns this

dispose

  • dispose(): void

  • Frees the GPU-related resources allocated by this instance

    Returns void

    Remarks

    Call this method whenever this instance is no longer used in your app.

getFrameExtents

  • getFrameExtents(): Vector2

  • Used internally by the renderer to extend the shadow map to contain all viewports

    Returns Vector2

getFrustum

  • getFrustum(): Frustum

  • Gets the shadow cameras frustum

    Returns Frustum

    Remarks

    Used internally by the renderer to cull objects.

getViewport

  • getViewport(viewportIndex): Vector4

  • Parameters

    • viewportIndex: number

    Returns Vector4

getViewportCount

  • getViewportCount(): number

  • Used internally by the renderer to get the number of viewports that need to be rendered for this shadow.

    Returns number

toJSON

  • toJSON(): {}

  • Serialize this LightShadow.

    Returns {}

    updateMatrices

    • updateMatrices(light): void

    • Update the matrices for the camera and shadow, used internally by the renderer.

      Parameters

      Returns void

    Settings

    Member Visibility

    On This Page

    constructorautoUpdatebiasblurSamplescameraisDirectionalLightShadowmapmapPassmapSizematrixneedsUpdatenormalBiasradiusclonecopydisposegetFrameExtentsgetFrustumgetViewportgetViewportCounttoJSONupdateMatrices