DirectionalLight3D

Inherits: Light3D < VisualInstance3D < Node3D < Node < Object

Directional light from a distance, as from the Sun.

Description

A directional light is a type of Light3D node that models an infinite number of parallel rays covering the entire scene. It is used for lights with strong intensity that are located far away from the scene to model sunlight or moonlight. The worldspace location of the DirectionalLight3D transform (origin) is ignored. Only the basis is used to determine light direction.

Enumerations

enum ShadowMode:

  • SHADOW_ORTHOGONAL = 0 --- Renders the entire scene's shadow map from an orthogonal point of view. This is the fastest directional shadow mode. May result in blurrier shadows on close objects.

  • SHADOW_PARALLEL_2_SPLITS = 1 --- Splits the view frustum in 2 areas, each with its own shadow map. This shadow mode is a compromise between SHADOW_ORTHOGONAL and SHADOW_PARALLEL_4_SPLITS in terms of performance.

  • SHADOW_PARALLEL_4_SPLITS = 2 --- Splits the view frustum in 4 areas, each with its own shadow map. This is the slowest directional shadow mode.

Property Descriptions

  • bool directional_shadow_blend_splits

Default

false

Setter

set_blend_splits(value)

Getter

is_blend_splits_enabled()

If true, shadow detail is sacrificed in exchange for smoother transitions between splits.


  • float directional_shadow_fade_start

Default

0.8

Setter

set_param(value)

Getter

get_param()

Proportion of directional_shadow_max_distance at which point the shadow starts to fade. At directional_shadow_max_distance the shadow will disappear.


  • float directional_shadow_max_distance

Default

100.0

Setter

set_param(value)

Getter

get_param()

The maximum distance for shadow splits.


Default

2

Setter

set_shadow_mode(value)

Getter

get_shadow_mode()

The light's shadow rendering algorithm. See ShadowMode.


  • float directional_shadow_pancake_size

Default

20.0

Setter

set_param(value)

Getter

get_param()

Sets the size of the directional shadow pancake. The pancake offsets the start of the shadow's camera frustum to provide a higher effective depth resolution for the shadow. However, a high pancake size can cause artifacts in the shadows of large objects that are close to the edge of the frustum. Reducing the pancake size can help. Setting the size to 0 turns off the pancaking effect.


  • float directional_shadow_split_1

Default

0.1

Setter

set_param(value)

Getter

get_param()

The distance from camera to shadow split 1. Relative to directional_shadow_max_distance. Only used when directional_shadow_mode is SHADOW_PARALLEL_2_SPLITS or SHADOW_PARALLEL_4_SPLITS.


  • float directional_shadow_split_2

Default

0.2

Setter

set_param(value)

Getter

get_param()

The distance from shadow split 1 to split 2. Relative to directional_shadow_max_distance. Only used when directional_shadow_mode is SHADOW_PARALLEL_2_SPLITS or SHADOW_PARALLEL_4_SPLITS.


  • float directional_shadow_split_3

Default

0.5

Setter

set_param(value)

Getter

get_param()

The distance from shadow split 2 to split 3. Relative to directional_shadow_max_distance. Only used when directional_shadow_mode is SHADOW_PARALLEL_4_SPLITS.


  • bool use_in_sky_only

Default

false

Setter

set_sky_only(value)

Getter

is_sky_only()

If true, this DirectionalLight3D will not be used for anything except sky shaders. Use this for lights that impact your sky shader that you may want to hide from affecting the rest of the scene. For example, you may want to enable this when the sun in your sky shader falls below the horizon.