DirectionalLight¶

Inherits: Light < VisualInstance < CullInstance < Spatial < Node < Object

Directional light from a distance, as from the Sun.

Description¶

A directional light is a type of Light 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 DirectionalLight transform (origin) is ignored. Only the basis is used to determine light direction.

Tutorials¶

3D lights and shadows

Properties¶

float	directional_shadow_bias_split_scale	`0.25`
bool	directional_shadow_blend_splits	`false`
ShadowDepthRange	directional_shadow_depth_range	`0`
float	directional_shadow_fade_start	`0.8`
float	directional_shadow_max_distance	`100.0`
ShadowMode	directional_shadow_mode	`3`
float	directional_shadow_normal_bias	`0.8`
float	directional_shadow_split_1	`0.1`
float	directional_shadow_split_2	`0.2`
float	directional_shadow_split_3	`0.5`
float	shadow_bias	`0.1` (overrides Light)

Enumerations¶

enum ShadowMode:

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.

ShadowMode 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.

ShadowMode SHADOW_PARALLEL_3_SPLITS = 2

Splits the view frustum in 3 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.

ShadowMode SHADOW_PARALLEL_4_SPLITS = 3

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

enum ShadowDepthRange:

ShadowDepthRange SHADOW_DEPTH_RANGE_STABLE = 0

Keeps the shadow stable when the camera moves, at the cost of lower effective shadow resolution.

ShadowDepthRange SHADOW_DEPTH_RANGE_OPTIMIZED = 1

Tries to achieve maximum shadow resolution. May result in saw effect on shadow edges. This mode typically works best in games where the camera will often move at high speeds, such as most racing games.

Property Descriptions¶

float directional_shadow_bias_split_scale = 0.25

void set_param ( float value )
float get_param ( )

Amount of extra bias for shadow splits that are far away. If self-shadowing occurs only on the splits far away, increasing this value can fix them. This is ignored when directional_shadow_mode is SHADOW_ORTHOGONAL.

bool directional_shadow_blend_splits = false

void set_blend_splits ( bool value )
bool is_blend_splits_enabled ( )

If true, shadow detail is sacrificed in exchange for smoother transitions between splits. Enabling shadow blend splitting also has a moderate performance cost. This is ignored when directional_shadow_mode is SHADOW_ORTHOGONAL.

ShadowDepthRange directional_shadow_depth_range = 0

void set_shadow_depth_range ( ShadowDepthRange value )
ShadowDepthRange get_shadow_depth_range ( )

Optimizes shadow rendering for detail versus movement. See ShadowDepthRange.

float directional_shadow_fade_start = 0.8

void set_param ( float value )
float 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. The default value is a balance between smooth fading and distant shadow visibility. If the camera moves fast and the directional_shadow_max_distance is low, consider lowering directional_shadow_fade_start below 0.8 to make shadow transitions less noticeable. On the other hand, if you tuned directional_shadow_max_distance to cover the entire scene, you can set directional_shadow_fade_start to 1.0 to prevent the shadow from fading in the distance (it will suddenly cut off instead).

float directional_shadow_max_distance = 100.0

void set_param ( float value )
float get_param ( )

The maximum distance for shadow splits. Increasing this value will make directional shadows visible from further away, at the cost of lower overall shadow detail and performance (since more objects need to be included in the directional shadow rendering).

ShadowMode directional_shadow_mode = 3

void set_shadow_mode ( ShadowMode value )
ShadowMode get_shadow_mode ( )

The light's shadow rendering algorithm. See ShadowMode.

float directional_shadow_normal_bias = 0.8

void set_param ( float value )
float get_param ( )

Can be used to fix special cases of self shadowing when objects are perpendicular to the light.

float directional_shadow_split_1 = 0.1

void set_param ( float value )
float 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 = 0.2

void set_param ( float value )
float 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 = 0.5

void set_param ( float value )
float 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.