Change light defaults & fix light examples (#11581)

# Objective

Fix #11577.

## Solution

Fix the examples, add a few constants to make setting light values
easier, and change the default lighting settings to be more realistic.
(Now designed for an overcast day instead of an indoor environment)

---

I did not include any example-related changes in here.

## Changelogs (not including breaking changes)

### bevy_pbr

- Added `light_consts` module (included in prelude), which contains
common lux and lumen values for lights.
- Added `AmbientLight::NONE` constant, which is an ambient light with a
brightness of 0.
- Added non-EV100 variants for `ExposureSettings`'s EV100 constants,
which allow easier construction of an `ExposureSettings` from a EV100
constant.

## Breaking changes

### bevy_pbr

The several default lighting values were changed:

- `PointLight`'s default `intensity` is now `2000.0`
- `SpotLight`'s default `intensity` is now `2000.0`
- `DirectionalLight`'s default `illuminance` is now
`light_consts::lux::OVERCAST_DAY` (`1000.`)
- `AmbientLight`'s default `brightness` is now `20.0`

crates/bevy_pbr/src/lib.rs

@@ -42,7 +42,7 @@ pub mod prelude {
             SpotLightBundle,
         },
         fog::{FogFalloff, FogSettings},
-        light::{AmbientLight, DirectionalLight, PointLight, SpotLight},
+        light::{light_consts, AmbientLight, DirectionalLight, PointLight, SpotLight},
         light_probe::{
             environment_map::{EnvironmentMapLight, ReflectionProbeBundle},
             LightProbe,

crates/bevy_pbr/src/light.rs

@@ -21,6 +21,61 @@ use bevy_utils::tracing::warn;
 
 use crate::*;
 
+/// Constants for operating with the light units: lumens, and lux.
+pub mod light_consts {
+    /// Approximations for converting the wattage of lamps to lumens.
+    ///
+    /// The **lumen** (symbol: **lm**) is the unit of [luminous flux], a measure
+    /// of the total quantity of [visible light] emitted by a source per unit of
+    /// time, in the [International System of Units] (SI).
+    ///
+    /// For more information, see [wikipedia](https://en.wikipedia.org/wiki/Lumen_(unit))
+    ///
+    /// [luminous flux]: https://en.wikipedia.org/wiki/Luminous_flux
+    /// [visible light]: https://en.wikipedia.org/wiki/Visible_light
+    /// [International System of Units]: https://en.wikipedia.org/wiki/International_System_of_Units
+    pub mod lumens {
+        pub const LUMENS_PER_LED_WATTS: f32 = 90.0;
+        pub const LUMENS_PER_INCANDESCENT_WATTS: f32 = 13.8;
+        pub const LUMENS_PER_HALOGEN_WATTS: f32 = 19.8;
+    }
+
+    /// Predefined for lux values in several locations.
+    ///
+    /// The **lux** (symbol: **lx**) is the unit of [illuminance], or [luminous flux] per unit area,
+    /// in the [International System of Units] (SI). It is equal to one lumen per square metre.
+    ///
+    /// For more information, see [wikipedia](https://en.wikipedia.org/wiki/Lux)
+    ///
+    /// [illuminance]: https://en.wikipedia.org/wiki/Illuminance
+    /// [luminous flux]: https://en.wikipedia.org/wiki/Luminous_flux
+    /// [International System of Units]: https://en.wikipedia.org/wiki/International_System_of_Units
+    pub mod lux {
+        /// The amount of light (lux) in a moonless, overcast night sky. (starlight)
+        pub const MOONLESS_NIGHT: f32 = 0.0001;
+        /// The amount of light (lux) during a full moon on a clear night.
+        pub const FULL_MOON_NIGHT: f32 = 0.05;
+        /// The amount of light (lux) during the dark limit of civil twilight under a clear sky.
+        pub const CIVIL_TWILIGHT: f32 = 3.4;
+        /// The amount of light (lux) in family living room lights.
+        pub const LIVING_ROOM: f32 = 50.;
+        /// The amount of light (lux) in an office building's hallway/toilet lighting.
+        pub const HALLWAY: f32 = 80.;
+        /// The amount of light (lux) in very dark overcast day
+        pub const DARK_OVERCAST_DAY: f32 = 100.;
+        /// The amount of light (lux) in an office.
+        pub const OFFICE: f32 = 320.;
+        /// The amount of light (lux) during sunrise or sunset on a clear day.
+        pub const CLEAR_SUNRISE: f32 = 400.;
+        /// The amount of light (lux) on a overcast day; typical TV studio lighting
+        pub const OVERCAST_DAY: f32 = 1000.;
+        /// The amount of light (lux) in full daylight (not direct sun).
+        pub const FULL_DAYLIGHT: f32 = 10_000.;
+        /// The amount of light (lux) in direct sunlight.
+        pub const DIRECT_SUNLIGHT: f32 = 50_000.;
+    }
+}
+
 /// A light that emits light in all directions from a central point.
 ///
 /// Real-world values for `intensity` (luminous power in lumens) based on the electrical power
@@ -58,7 +113,7 @@ impl Default for PointLight {
     fn default() -> Self {
         PointLight {
             color: Color::rgb(1.0, 1.0, 1.0),
-            intensity: 800.0, // Roughly a 60W non-halogen incandescent bulb
+            intensity: 2000.0, // Roughly a 20-watt LED bulb
             range: 20.0,
             radius: 0.0,
             shadows_enabled: false,
@@ -126,7 +181,7 @@ impl Default for SpotLight {
         // a quarter arc attenuating from the center
         Self {
             color: Color::rgb(1.0, 1.0, 1.0),
-            intensity: 800.0, // Roughly a 60W non-halogen incandescent bulb
+            intensity: 2000.0, // Roughly a 20-watt LED bulb
             range: 20.0,
             radius: 0.0,
             shadows_enabled: false,
@@ -207,7 +262,7 @@ impl Default for DirectionalLight {
     fn default() -> Self {
         DirectionalLight {
             color: Color::rgb(1.0, 1.0, 1.0),
-            illuminance: 100000.0,
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: false,
             shadow_depth_bias: Self::DEFAULT_SHADOW_DEPTH_BIAS,
             shadow_normal_bias: Self::DEFAULT_SHADOW_NORMAL_BIAS,
@@ -567,7 +622,7 @@ fn calculate_cascade(
 /// # use bevy_ecs::system::ResMut;
 /// # use bevy_pbr::AmbientLight;
 /// fn setup_ambient_light(mut ambient_light: ResMut<AmbientLight>) {
-///    ambient_light.brightness = 20.0;
+///    ambient_light.brightness = 100.0;
 /// }
 /// ```
 #[derive(Resource, Clone, Debug, ExtractResource, Reflect)]
@@ -581,11 +636,17 @@ pub struct AmbientLight {
 impl Default for AmbientLight {
     fn default() -> Self {
         Self {
-            color: Color::rgb(1.0, 1.0, 1.0),
-            brightness: 8.0,
+            color: Color::WHITE,
+            brightness: 20.0,
         }
     }
 }
+impl AmbientLight {
+    pub const NONE: AmbientLight = AmbientLight {
+        color: Color::WHITE,
+        brightness: 0.0,
+    };
+}
 
 /// Add this component to make a [`Mesh`](bevy_render::mesh::Mesh) not cast shadows.
 #[derive(Component, Reflect, Default)]

crates/bevy_render/src/camera/camera.rs

@@ -96,6 +96,16 @@ pub struct ExposureSettings {
 }
 
 impl ExposureSettings {
+    pub const SUNLIGHT: Self = Self {
+        ev100: Self::EV100_SUNLIGHT,
+    };
+    pub const OVERCAST: Self = Self {
+        ev100: Self::EV100_OVERCAST,
+    };
+    pub const INDOOR: Self = Self {
+        ev100: Self::EV100_INDOOR,
+    };
+
     pub const EV100_SUNLIGHT: f32 = 15.0;
     pub const EV100_OVERCAST: f32 = 12.0;
     pub const EV100_INDOOR: f32 = 7.0;
@@ -116,9 +126,7 @@ impl ExposureSettings {
 
 impl Default for ExposureSettings {
     fn default() -> Self {
-        Self {
-            ev100: Self::EV100_INDOOR,
-        }
+        Self::INDOOR
     }
 }
 

examples/3d/3d_gizmos.rs

@@ -41,13 +41,13 @@ fn setup(
         ..default()
     });
     // light
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
-            intensity: 250000.0,
+    commands.spawn(DirectionalLightBundle {
+        directional_light: DirectionalLight {
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },
-        transform: Transform::from_xyz(4.0, 8.0, 4.0),
+        transform: Transform::from_xyz(4.0, 8.0, 4.0).looking_at(Vec3::ZERO, Vec3::Y),
         ..default()
     });
 

examples/3d/3d_scene.rs

@@ -30,13 +30,13 @@ fn setup(
         ..default()
     });
     // light
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
-            intensity: 250_000.0,
+    commands.spawn(DirectionalLightBundle {
+        directional_light: DirectionalLight {
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },
-        transform: Transform::from_xyz(4.0, 8.0, 4.0),
+        transform: Transform::from_xyz(4.0, 8.0, 4.0).looking_at(Vec3::ZERO, Vec3::Y),
         ..default()
     });
     // camera

examples/3d/3d_shapes.rs

@@ -64,14 +64,13 @@ fn setup(
         ));
     }
 
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
-            intensity: 1500000.0,
-            range: 100.,
+    commands.spawn(DirectionalLightBundle {
+        directional_light: DirectionalLight {
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },
-        transform: Transform::from_xyz(8.0, 16.0, 8.0),
+        transform: Transform::from_xyz(8.0, 16.0, 8.0).looking_at(Vec3::ZERO, Vec3::Y),
         ..default()
     });
 

examples/3d/3d_viewport_to_world.rs

@@ -66,10 +66,7 @@ fn setup(
     // light
     commands.spawn(DirectionalLightBundle {
         transform: Transform::from_translation(Vec3::ONE).looking_at(Vec3::ZERO, Vec3::Y),
-        directional_light: DirectionalLight {
-            illuminance: 2000.0,
-            ..default()
-        },
+        directional_light: DirectionalLight::default(),
         ..default()
     });
 

examples/3d/animated_material.rs

@@ -25,7 +25,7 @@ fn setup(
         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: 1500.0,
+            intensity: 1_000.0,
         },
     ));
 

examples/3d/anti_aliasing.rs

@@ -289,7 +289,7 @@ fn setup(
     // Light
     commands.spawn(DirectionalLightBundle {
         directional_light: DirectionalLight {
-            illuminance: 3000.0,
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },

examples/3d/atmospheric_fog.rs

@@ -61,7 +61,7 @@ fn setup_terrain_scene(
     commands.spawn(DirectionalLightBundle {
         directional_light: DirectionalLight {
             color: Color::rgb(0.98, 0.95, 0.82),
-            illuminance: 3000.0,
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },

examples/3d/blend_modes.rs

@@ -167,12 +167,12 @@ fn setup(
     }
 
     // Light
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
-            intensity: 150_000.0,
+    commands.spawn(DirectionalLightBundle {
+        directional_light: DirectionalLight {
+            illuminance: light_consts::lux::OVERCAST_DAY,
             ..default()
         },
-        transform: Transform::from_xyz(4.0, 8.0, 4.0),
+        transform: Transform::from_xyz(4.0, 8.0, 4.0).looking_at(Vec3::ZERO, Vec3::Y),
         ..default()
     });
 

examples/3d/deferred_rendering.rs

@@ -18,10 +18,6 @@ fn main() {
     App::new()
         .insert_resource(Msaa::Off)
         .insert_resource(DefaultOpaqueRendererMethod::deferred())
-        .insert_resource(AmbientLight {
-            color: Color::WHITE,
-            brightness: 1.0 / 5.0f32,
-        })
         .insert_resource(DirectionalLightShadowMap { size: 4096 })
         .add_plugins(DefaultPlugins)
         .insert_resource(Normal(None))
@@ -62,7 +58,7 @@ fn setup(
         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: 150.0,
+            intensity: 250.0,
         },
         DepthPrepass,
         MotionVectorPrepass,
@@ -72,7 +68,7 @@ fn setup(
 
     commands.spawn(DirectionalLightBundle {
         directional_light: DirectionalLight {
-            illuminance: 4000.0,
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },

examples/3d/fog.rs

@@ -17,10 +17,12 @@
 use bevy::{
     pbr::{NotShadowCaster, NotShadowReceiver},
     prelude::*,
+    render::camera::ExposureSettings,
 };
 
 fn main() {
     App::new()
+        .insert_resource(AmbientLight::NONE)
         .add_plugins(DefaultPlugins)
         .add_systems(
             Startup,
@@ -41,6 +43,9 @@ fn setup_camera_fog(mut commands: Commands) {
             },
             ..default()
         },
+        // This is a dark scene,
+        // increasing the exposure makes it easier to see
+        ExposureSettings { ev100: 4.0 },
     ));
 }
 
@@ -114,8 +119,7 @@ fn setup_pyramid_scene(
     commands.spawn(PointLightBundle {
         transform: Transform::from_xyz(0.0, 1.0, 0.0),
         point_light: PointLight {
-            intensity: 300_000.,
-            range: 100.,
+            intensity: 4_000.,
             shadows_enabled: true,
             ..default()
         },

examples/3d/generate_custom_mesh.rs

@@ -57,10 +57,9 @@ fn setup(
     });
 
     // Light up the scene.
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
-            intensity: 100_000.0,
-            range: 100.0,
+    commands.spawn(DirectionalLightBundle {
+        directional_light: DirectionalLight {
+            illuminance: light_consts::lux::OVERCAST_DAY,
             ..default()
         },
         transform: camera_and_light_transform,

examples/3d/lighting.rs

@@ -4,7 +4,7 @@
 use std::f32::consts::PI;
 
 use bevy::{
-    pbr::CascadeShadowConfigBuilder,
+    pbr::{light_consts, CascadeShadowConfigBuilder},
     prelude::*,
     render::camera::{ExposureSettings, PhysicalCameraParameters},
 };
@@ -14,8 +14,8 @@ fn main() {
         .add_plugins(DefaultPlugins)
         .insert_resource(Parameters(PhysicalCameraParameters {
             aperture_f_stops: 1.0,
-            shutter_speed_s: 1.0 / 15.0,
-            sensitivity_iso: 400.0,
+            shutter_speed_s: 1.0 / 100.0,
+            sensitivity_iso: 100.0,
         }))
         .add_systems(Startup, setup)
         .add_systems(Update, (update_exposure, movement, animate_light_direction))
@@ -207,7 +207,7 @@ fn setup(
     // directional 'sun' light
     commands.spawn(DirectionalLightBundle {
         directional_light: DirectionalLight {
-            illuminance: 100.0,
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },

examples/3d/lightmaps.rs

@@ -21,10 +21,10 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
         ..default()
     });
 
-    commands.spawn(Camera3dBundle {
+    commands.spawn((Camera3dBundle {
         transform: Transform::from_xyz(-278.0, 273.0, 800.0),
         ..default()
-    });
+    },));
 }
 
 fn add_lightmaps_to_meshes(

examples/3d/load_gltf.rs

@@ -25,13 +25,13 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
         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: 150.0,
+            intensity: 250.0,
         },
     ));
 
     commands.spawn(DirectionalLightBundle {
         directional_light: DirectionalLight {
-            illuminance: 2000.0,
+            illuminance: light_consts::lux::OVERCAST_DAY,
             shadows_enabled: true,
             ..default()
         },