Struct bevy::pbr::DirectionalLight

pub struct DirectionalLight {
    pub color: Color,
    pub illuminance: f32,
    pub shadows_enabled: bool,
    pub shadow_projection: OrthographicProjection,
    pub shadow_depth_bias: f32,
    pub shadow_normal_bias: f32,
}

Expand description

A Directional light.

Directional lights don’t exist in reality but they are a good approximation for light sources VERY far away, like the sun or the moon.

The light shines along the forward direction of the entity’s transform. With a default transform this would be along the negative-Z axis.

Valid values for illuminance are:

Illuminance (lux)	Surfaces illuminated by
0.0001	Moonless, overcast night sky (starlight)
0.002	Moonless clear night sky with airglow
0.05–0.3	Full moon on a clear night
3.4	Dark limit of civil twilight under a clear sky
20–50	Public areas with dark surroundings
50	Family living room lights
80	Office building hallway/toilet lighting
100	Very dark overcast day
150	Train station platforms
320–500	Office lighting
400	Sunrise or sunset on a clear day.
1000	Overcast day; typical TV studio lighting
10,000–25,000	Full daylight (not direct sun)
32,000–100,000	Direct sunlight

Source: Wikipedia

Shadows

To enable shadows, set the shadows_enabled property to true.

While directional lights contribute to the illumination of meshes regardless of their (or the meshes’) positions, currently only a limited region of the scene (the shadow volume) can cast and receive shadows for any given directional light.

The shadow volume is a rectangular cuboid, with left/right/bottom/top/near/far planes controllable via the shadow_projection field. It is affected by the directional light entity’s GlobalTransform, and as such can be freely repositioned in the scene, (or even scaled!) without affecting illumination in any other way, by simply moving (or scaling) the entity around. The shadow volume is always oriented towards the light entity’s forward direction.

For smaller scenes, a static directional light with a preset volume is typically sufficient. For larger scenes with movable cameras, you might want to introduce a system that dynamically repositions and scales the light entity (and therefore its shadow volume) based on the scene subject’s position (e.g. a player character) and its relative distance to the camera.

Shadows are produced via shadow mapping. To control the resolution of the shadow maps, use the DirectionalLightShadowMap resource:

App::new()
    .insert_resource(DirectionalLightShadowMap { size: 2048 });

Note: Very large shadow map resolutions (> 4K) can have non-negligible performance and memory impact, and not work properly under mobile or lower-end hardware. To improve the visual fidelity of shadow maps, it’s typically advisable to first reduce the shadow_projection left/right/top/bottom to a scene-appropriate size, before ramping up the shadow map resolution.

Fields§

§color: Color§illuminance: f32

Illuminance in lux

§shadows_enabled: bool§shadow_projection: OrthographicProjection

A projection that controls the volume in which shadow maps are rendered

§shadow_depth_bias: f32§shadow_normal_bias: f32

A bias applied along the direction of the fragment’s surface normal. It is scaled to the shadow map’s texel size so that it is automatically adjusted to the orthographic projection.