[Merged by Bors] - Better cascades config defaults + builder, tweak example configs

crates/bevy_pbr/src/light.rs

@@ -234,23 +234,21 @@ impl Default for DirectionalLightShadowMap {
 }
 
 /// Controls how cascaded shadow mapping works.
+/// Prefer using [`CascadeShadowConfigBuilder`] to construct an instance.
 #[derive(Component, Clone, Debug, Reflect)]
 #[reflect(Component)]
 pub struct CascadeShadowConfig {
     /// The (positive) distance to the far boundary of each cascade.
     pub bounds: Vec<f32>,
     /// The proportion of overlap each cascade has with the previous cascade.
     pub overlap_proportion: f32,
+    /// The (positive) distance to the near boundary of the first cascade.
+    pub minimum_distance: f32,
 }
 
 impl Default for CascadeShadowConfig {
     fn default() -> Self {
-        if cfg!(feature = "webgl") {
-            // Currently only support one cascade in webgl.
-            Self::new(1, 5.0, 100.0, 0.2)
-        } else {
-            Self::new(4, 5.0, 1000.0, 0.2)
-        }
+        CascadeShadowConfigBuilder::new().build()
     }
 }
 
@@ -268,31 +266,125 @@ fn calculate_cascade_bounds(
         .collect()
 }
 
-impl CascadeShadowConfig {
-    /// Returns a cascade config for `num_cascades` cascades, with the first cascade
-    /// having far bound `nearest_bound` and the last cascade having far bound `shadow_maximum_distance`.
-    /// In-between cascades will be exponentially spaced.
-    pub fn new(
-        num_cascades: usize,
-        nearest_bound: f32,
-        shadow_maximum_distance: f32,
-        overlap_proportion: f32,
-    ) -> Self {
+/// Builder for [`CascadeShadowConfig`].
+pub struct CascadeShadowConfigBuilder {
+    num_cascades: usize,
+    minimum_distance: f32,
+    maximum_distance: f32,
+    first_cascade_far_bound: f32,
+    overlap_proportion: f32,
+}
+
+impl CascadeShadowConfigBuilder {
+    /// Constructs a new builder.
+    pub fn new() -> Self {
+        if cfg!(feature = "webgl") {
+            // Currently only support one cascade in webgl.
+            Self {
+                num_cascades: 1,
+                minimum_distance: 0.1,
+                maximum_distance: 100.0,
+                first_cascade_far_bound: 5.0,
+                overlap_proportion: 0.2,
+            }
+        } else {
+            Self {
+                num_cascades: 4,
+                minimum_distance: 0.1,
+                maximum_distance: 1000.0,
+                first_cascade_far_bound: 5.0,
+                overlap_proportion: 0.2,
+            }
+        }
+    }
+
+    /// Sets the number of shadow cascades.
+    /// More cascades increases shadow quality by mitigating perspective aliasing - a phenomenom 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 leveland much larger shadow map textures to achieve the same quality level
+    ///
+    /// In cases 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.
+    pub fn num_cascades(mut self, n: usize) -> Self {
+        self.num_cascades = n;
+        self
+    }
+
+    /// Sets the minimum shadow distance.
+    /// Areas nearer to the camera than this will likely receive no shadows.
+    pub fn minimum_distance(mut self, d: f32) -> Self {
+        self.minimum_distance = d;
+        self
+    }
+
+    /// Sets the maximum shadow distance.
+    /// Areas further from the camera than this will likely receive no shadows.
+    pub fn maximum_distance(mut self, d: f32) -> Self {
+        self.maximum_distance = d;
+        self
+    }
+
+    /// Sets the far bound of the first cascade.
+    /// 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.
+    pub fn first_cascade_far_bound(mut self, bound: f32) -> Self {
+        self.first_cascade_far_bound = bound;
+        self
+    }
+
+    /// 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.
+    pub fn overlap_proportion(mut self, p: f32) -> Self {
+        self.overlap_proportion = p;
+        self
+    }
+
+    /// Returns the cascade config as specified by this builder.
+    pub fn build(&self) -> CascadeShadowConfig {
         assert!(
-            num_cascades > 0,
-            "num_cascades must be positive, but was {num_cascades}",
+            self.num_cascades > 0,
+            "num_cascades must be positive, but was {}",
+            self.num_cascades
         );
         assert!(
-            (0.0..1.0).contains(&overlap_proportion),
-            "overlap_proportion must be in [0.0, 1.0) but was {overlap_proportion}",
+            (0.0..self.first_cascade_far_bound).contains(&self.minimum_distance),
+            "minimum_distance must be in [0.0, first_cascade_far_bound), but was {}",
+            self.minimum_distance
         );
-        Self {
-            bounds: calculate_cascade_bounds(num_cascades, nearest_bound, shadow_maximum_distance),
-            overlap_proportion,
+        assert!(
+            self.maximum_distance >= 0.0,
+            "maximum_distance must be non-negative, but was {}",
+            self.maximum_distance
+        );
+        assert!(
+            (0.0..1.0).contains(&self.overlap_proportion),
+            "overlap_proportion must be in [0.0, 1.0) but was {}",
+            self.overlap_proportion
+        );
+        CascadeShadowConfig {
+            bounds: calculate_cascade_bounds(
+                self.num_cascades,
+                self.first_cascade_far_bound,
+                self.maximum_distance,
+            ),
+            overlap_proportion: self.overlap_proportion,
+            minimum_distance: self.minimum_distance,
         }
     }
 }
 
+impl Default for CascadeShadowConfigBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 #[derive(Component, Clone, Debug, Default, Reflect)]
 #[reflect(Component)]
 pub struct Cascades {
@@ -375,7 +467,7 @@ pub fn update_directional_light_cascades(
                             (1.0 - cascades_config.overlap_proportion)
                                 * -cascades_config.bounds[idx - 1]
                         } else {
-                            0.0
+                            -cascades_config.minimum_distance
                         },
                         -far_bound,
                     )

examples/3d/atmospheric_fog.rs

@@ -8,7 +8,7 @@
 //! | `S`                | Toggle Directional Light Fog Influence |
 
 use bevy::{
-    pbr::{CascadeShadowConfig, NotShadowCaster},
+    pbr::{CascadeShadowConfigBuilder, NotShadowCaster},
     prelude::*,
 };
 
@@ -49,9 +49,10 @@ fn setup_terrain_scene(
     asset_server: Res<AssetServer>,
 ) {
     // Configure a properly scaled cascade shadow map for this scene (defaults are too large, mesh units are in km)
-    // For WebGL we only support 1 cascade level for now
-    let cascade_shadow_config =
-        CascadeShadowConfig::new(if cfg!(feature = "webgl") { 1 } else { 4 }, 0.5, 2.5, 0.2);
+    let cascade_shadow_config = CascadeShadowConfigBuilder::new()
+        .first_cascade_far_bound(0.5)
+        .maximum_distance(2.0)
+        .build();
 
     // Sun
     commands.spawn(DirectionalLightBundle {

examples/3d/fxaa.rs

@@ -4,6 +4,7 @@ use std::f32::consts::PI;
 
 use bevy::{
     core_pipeline::fxaa::{Fxaa, Sensitivity},
+    pbr::CascadeShadowConfigBuilder,
     prelude::*,
     render::{
         render_resource::{Extent3d, SamplerDescriptor, TextureDimension, TextureFormat},
@@ -81,6 +82,10 @@ fn setup(
             PI * -0.15,
             PI * -0.15,
         )),
+        cascade_shadow_config: CascadeShadowConfigBuilder::new()
+            .maximum_distance(3.0)
+            .first_cascade_far_bound(0.7)
+            .build(),
         ..default()
     });
 

examples/3d/lighting.rs

@@ -3,7 +3,7 @@
 
 use std::f32::consts::PI;
 
-use bevy::{pbr::CascadeShadowConfig, prelude::*};
+use bevy::{pbr::CascadeShadowConfigBuilder, prelude::*};
 
 fn main() {
     App::new()
@@ -199,7 +199,10 @@ fn setup(
         // The default cascade config is designed to handle large scenes.
         // As this example has a much smaller world, we can tighten the shadow
         // far bound for better visual quality.
-        cascade_shadow_config: CascadeShadowConfig::new(4, 5.0, 30.0, 0.2),
+        cascade_shadow_config: CascadeShadowConfigBuilder::new()
+            .first_cascade_far_bound(5.0)
+            .maximum_distance(30.0)
+            .build(),
         ..default()
     });
 

examples/3d/load_gltf.rs

@@ -2,7 +2,7 @@
 
 use std::f32::consts::*;
 
-use bevy::{pbr::CascadeShadowConfig, prelude::*};
+use bevy::{pbr::CascadeShadowConfigBuilder, prelude::*};
 
 fn main() {
     App::new()
@@ -28,7 +28,11 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
         },
         // This is a relatively small scene, so use tighter shadow
         // cascade bounds than the default for better quality.
-        cascade_shadow_config: CascadeShadowConfig::new(1, 1.1, 1.5, 0.3),
+        cascade_shadow_config: CascadeShadowConfigBuilder::new()
+            .num_cascades(1)
+            .minimum_distance(0.5)
+            .maximum_distance(1.0)
+            .build(),
         ..default()
     });
     commands.spawn(SceneBundle {

examples/3d/shadow_caster_receiver.rs

@@ -3,7 +3,7 @@
 use std::f32::consts::PI;
 
 use bevy::{
-    pbr::{NotShadowCaster, NotShadowReceiver},
+    pbr::{CascadeShadowConfigBuilder, NotShadowCaster, NotShadowReceiver},
     prelude::*,
 };
 
@@ -109,6 +109,9 @@ fn setup(
             PI / 2.,
             -PI / 4.,
         )),
+        cascade_shadow_config: CascadeShadowConfigBuilder::new()
+            .maximum_distance(30.0)
+            .build(),
         ..default()
     });
 

examples/3d/split_screen.rs

@@ -3,8 +3,8 @@
 use std::f32::consts::PI;
 
 use bevy::{
-    core_pipeline::clear_color::ClearColorConfig, prelude::*, render::camera::Viewport,
-    window::WindowResized,
+    core_pipeline::clear_color::ClearColorConfig, pbr::CascadeShadowConfigBuilder, prelude::*,
+    render::camera::Viewport, window::WindowResized,
 };
 
 fn main() {
@@ -41,6 +41,9 @@ fn setup(
             shadows_enabled: true,
             ..default()
         },
+        cascade_shadow_config: CascadeShadowConfigBuilder::new()
+            .maximum_distance(300.0)
+            .build(),
         ..default()
     });
 

examples/animation/animated_fox.rs

@@ -3,6 +3,7 @@
 use std::f32::consts::PI;
 use std::time::Duration;
 
+use bevy::pbr::CascadeShadowConfigBuilder;
 use bevy::prelude::*;
 
 fn main() {
@@ -55,6 +56,9 @@ fn setup(
             shadows_enabled: true,
             ..default()
         },
+        cascade_shadow_config: CascadeShadowConfigBuilder::new()
+            .maximum_distance(400.0)
+            .build(),
         ..default()
     });
 

examples/stress_tests/many_foxes.rs

@@ -6,6 +6,7 @@ use std::time::Duration;
 
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
+    pbr::CascadeShadowConfigBuilder,
     prelude::*,
     window::{PresentMode, WindowPlugin},
 };
@@ -172,6 +173,10 @@ fn setup(
             shadows_enabled: true,
             ..default()
         },
+        cascade_shadow_config: CascadeShadowConfigBuilder::new()
+            .first_cascade_far_bound(1.2 * radius)
+            .maximum_distance(2.0 * radius)
+            .build(),
         ..default()
     });