Struct CascadeShadowConfigBuilder 

pub struct CascadeShadowConfigBuilder {
    pub num_cascades: usize,
    pub minimum_distance: f32,
    pub maximum_distance: f32,
    pub first_cascade_far_bound: f32,
    pub overlap_proportion: f32,
}

Builder for CascadeShadowConfig.

Fields

num_cascades: usize

The number of shadow cascades. More cascades increases shadow quality by mitigating perspective aliasing - a phenomenon where areas nearer the camera are covered by fewer shadow map texels than areas further from the camera, causing blocky looking shadows.

This does come at the cost increased rendering overhead, however this overhead is still less than if you were to use fewer cascades and much larger shadow map textures to achieve the same quality level.

In case rendered geometry covers a relatively narrow and static depth relative to camera, it may make more sense to use fewer cascades and a higher resolution shadow map texture as perspective aliasing is not as much an issue. Be sure to adjust minimum_distance and maximum_distance appropriately.

minimum_distance: f32

The minimum shadow distance, which can help improve the texel resolution of the first cascade. Areas nearer to the camera than this will likely receive no shadows.

NOTE: Due to implementation details, this usually does not impact shadow quality as much as first_cascade_far_bound and maximum_distance. At many view frustum field-of-views, the texel resolution of the first cascade is dominated by the width / height of the view frustum plane at first_cascade_far_bound rather than the depth of the frustum from minimum_distance to first_cascade_far_bound.

maximum_distance: f32

The maximum shadow distance. Areas further from the camera than this will likely receive no shadows.

first_cascade_far_bound: f32

Sets the far bound of the first cascade, relative to the view origin. In-between cascades will be exponentially spaced relative to the maximum shadow distance. NOTE: This is ignored if there is only one cascade, the maximum distance takes precedence.

overlap_proportion: f32

Sets the overlap proportion between cascades. The overlap is used to make the transition from one cascade’s shadow map to the next less abrupt by blending between both shadow maps.

Implementations

impl CascadeShadowConfigBuilder

pub fn build(&self) -> CascadeShadowConfig

Returns the cascade config as specified by this builder.

Examples found in repository

examples/animation/animated_mesh.rs (line 127)

fn setup_camera_and_environment(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // Camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(100.0, 100.0, 150.0).looking_at(Vec3::new(0.0, 20.0, 0.0), Vec3::Y),
    ));

    // Plane
    commands.spawn((
        Mesh3d(meshes.add(Plane3d::default().mesh().size(500000.0, 500000.0))),
        MeshMaterial3d(materials.add(Color::srgb(0.3, 0.5, 0.3))),
    ));

    // Light
    commands.spawn((
        Transform::from_rotation(Quat::from_euler(EulerRot::ZYX, 0.0, 1.0, -PI / 4.)),
        DirectionalLight {
            shadows_enabled: true,
            ..default()
        },
        CascadeShadowConfigBuilder {
            first_cascade_far_bound: 200.0,
            maximum_distance: 400.0,
            ..default()
        }
        .build(),
    ));
}

examples/3d/post_processing.rs (line 117)

fn spawn_scene(commands: &mut Commands, asset_server: &AssetServer) {
    // Spawn the main scene.
    commands.spawn(SceneRoot(asset_server.load(
        GltfAssetLabel::Scene(0).from_asset("models/TonemappingTest/TonemappingTest.gltf"),
    )));

    // Spawn the flight helmet.
    commands.spawn((
        SceneRoot(
            asset_server
                .load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
        ),
        Transform::from_xyz(0.5, 0.0, -0.5).with_rotation(Quat::from_rotation_y(-0.15 * PI)),
    ));

    // Spawn the light.
    commands.spawn((
        DirectionalLight {
            illuminance: 15000.0,
            shadows_enabled: true,
            ..default()
        },
        Transform::from_rotation(Quat::from_euler(EulerRot::ZYX, 0.0, PI * -0.15, PI * -0.15)),
        CascadeShadowConfigBuilder {
            maximum_distance: 3.0,
            first_cascade_far_bound: 0.9,
            ..default()
        }
        .build(),
    ));
}

examples/3d/color_grading.rs (line 372)

fn add_basic_scene(commands: &mut Commands, asset_server: &AssetServer) {
    // Spawn the main scene.
    commands.spawn(SceneRoot(asset_server.load(
        GltfAssetLabel::Scene(0).from_asset("models/TonemappingTest/TonemappingTest.gltf"),
    )));

    // Spawn the flight helmet.
    commands.spawn((
        SceneRoot(
            asset_server
                .load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
        ),
        Transform::from_xyz(0.5, 0.0, -0.5).with_rotation(Quat::from_rotation_y(-0.15 * PI)),
    ));

    // Spawn the light.
    commands.spawn((
        DirectionalLight {
            illuminance: 15000.0,
            shadows_enabled: true,
            ..default()
        },
        Transform::from_rotation(Quat::from_euler(EulerRot::ZYX, 0.0, PI * -0.15, PI * -0.15)),
        CascadeShadowConfigBuilder {
            maximum_distance: 3.0,
            first_cascade_far_bound: 0.9,
            ..default()
        }
        .build(),
    ));
}

examples/3d/tonemapping.rs (line 131)

fn setup_basic_scene(mut commands: Commands, asset_server: Res<AssetServer>) {
    // Main scene
    commands.spawn((
        SceneRoot(asset_server.load(
            GltfAssetLabel::Scene(0).from_asset("models/TonemappingTest/TonemappingTest.gltf"),
        )),
        SceneNumber(1),
    ));

    // Flight Helmet
    commands.spawn((
        SceneRoot(
            asset_server
                .load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
        ),
        Transform::from_xyz(0.5, 0.0, -0.5).with_rotation(Quat::from_rotation_y(-0.15 * PI)),
        SceneNumber(1),
    ));

    // light
    commands.spawn((
        DirectionalLight {
            illuminance: 15_000.,
            shadows_enabled: true,
            ..default()
        },
        Transform::from_rotation(Quat::from_euler(EulerRot::ZYX, 0.0, PI * -0.15, PI * -0.15)),
        CascadeShadowConfigBuilder {
            maximum_distance: 3.0,
            first_cascade_far_bound: 0.9,
            ..default()
        }
        .build(),
        SceneNumber(1),
    ));
}

examples/3d/load_gltf.rs (line 44)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.7, 0.7, 1.0).looking_at(Vec3::new(0.0, 0.3, 0.0), Vec3::Y),
        EnvironmentMapLight {
            diffuse_map: asset_server.load("environment_maps/pisa_diffuse_rgb9e5_zstd.ktx2"),
            specular_map: asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2"),
            intensity: 250.0,
            ..default()
        },
    ));

    commands.spawn((
        DirectionalLight {
            shadows_enabled: true,
            ..default()
        },
        // This is a relatively small scene, so use tighter shadow
        // cascade bounds than the default for better quality.
        // We also adjusted the shadow map to be larger since we're
        // only using a single cascade.
        CascadeShadowConfigBuilder {
            num_cascades: 1,
            maximum_distance: 1.6,
            ..default()
        }
        .build(),
    ));
    commands.spawn(SceneRoot(asset_server.load(
        GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf"),
    )));
}

examples/3d/atmospheric_fog.rs (line 55)

fn setup_terrain_scene(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
    asset_server: Res<AssetServer>,
) {
    // Configure a properly scaled cascade shadow map for this scene (defaults are too large, mesh units are in km)
    let cascade_shadow_config = CascadeShadowConfigBuilder {
        first_cascade_far_bound: 0.3,
        maximum_distance: 3.0,
        ..default()
    }
    .build();

    // Sun
    commands.spawn((
        DirectionalLight {
            color: Color::srgb(0.98, 0.95, 0.82),
            shadows_enabled: true,
            ..default()
        },
        Transform::from_xyz(0.0, 0.0, 0.0).looking_at(Vec3::new(-0.15, -0.05, 0.25), Vec3::Y),
        cascade_shadow_config,
    ));

    // Terrain
    commands.spawn(SceneRoot(asset_server.load(
        GltfAssetLabel::Scene(0).from_asset("models/terrain/Mountains.gltf"),
    )));

    // Sky
    commands.spawn((
        Mesh3d(meshes.add(Cuboid::new(2.0, 1.0, 1.0))),
        MeshMaterial3d(materials.add(StandardMaterial {
            base_color: Srgba::hex("888888").unwrap().into(),
            unlit: true,
            cull_mode: None,
            ..default()
        })),
        Transform::from_scale(Vec3::splat(20.0)),
        NotShadowCaster,
    ));
}

Additional examples can be found in:

• examples/animation/animated_mesh_events.rs
• examples/3d/visibility_range.rs
• examples/animation/animated_mesh_control.rs
• examples/3d/atmosphere.rs
• examples/3d/shadow_caster_receiver.rs
• examples/3d/anti_aliasing.rs
• examples/3d/meshlet.rs
• examples/3d/split_screen.rs
• examples/stress_tests/many_foxes.rs
• examples/3d/deferred_rendering.rs
• examples/3d/lighting.rs

Trait Implementations

impl Default for CascadeShadowConfigBuilder

fn default() -> CascadeShadowConfigBuilder

Returns the “default value” for a type.

impl From<CascadeShadowConfigBuilder> for CascadeShadowConfig

fn from(builder: CascadeShadowConfigBuilder) -> CascadeShadowConfig

Converts to this type from the input type.