Add bevy_light::SunDisk (#20434)

# Objective

* Fixes **#20425** (GI probes capture the sun disk while a
`DirectionalLight` also lights the scene, so we need a way to skip the
disk during probe baking).
* ~~**Add `sun_disk_intensity: f32` to `AtmosphereSettings`** so you can
smoothly hide, dim, or over‑brighten the sun disk without affecting the
visible illumination of scene objects, while still allowing the sun’s
radiance to scatter into the atmosphere even when the disk itself is
hidden.~~
* Add a bevy_light::SunDisk component that acts as an add‑on to
DirectionalLight.
#20434 (comment)

## Testing

* Ran the official `atmosphere` example on a MacBook M1 (see showcase
below).
* Toggled bloom on/off and tried intensities 0, 0.01, 1, and 10 — the
sky looks correct and no warnings appear.
* Noticed a small dark “hole” in the center of the sun disk under some
settings; this artifact was present before these changes (often hidden
by bloom) and probably deserves further investigation. (FIXED IN THIS
PR)

I’m new to WGSL/shader code — please point out anything silly! 🙂

---

## Showcase

* Scene brightness changes with intensity only because bloom amplifies
the bright disk; sky illumination stays unchanged.
* With bloom disabled, the disk is the only thing that changes — the
rest of the scene looks identical.
* Raising intensity above 1.0 doesn’t affect the scene without bloom
(the disk is already 100 % white) but boosts the bloom halo when bloom
is enabled.
* Lowering intensity reduces the bloom halo; drop it far enough and the
disk blends into the sky, which is physically plausible for very dim
suns.

<details>
  <summary><strong>1.0</strong> (bloom on) — normal</summary>
<img width="1680" height="1050" alt="default 1 0"
src="https://github.com/user-attachments/assets/89144e52-1159-42c6-9325-f80f986349ec"
/>
</details>

<details>
  <summary><strong>0.0</strong> (bloom on) — no disk</summary>
<img width="1680" height="1050" alt="no sun 0 0"
src="https://github.com/user-attachments/assets/2b3842ae-26ed-45bf-9266-20189bc487a7"
/>
</details>

<details>
<summary><strong>0.01</strong> (bloom on) — low brightness, tiny bloom
effect</summary>
<img width="1680" height="1050" alt="0 21"
src="https://github.com/user-attachments/assets/8c3943df-74b6-4422-8c9b-061e56ee33f8"
/>
</details>

<details>
<summary><strong>0.00001</strong> (bloom on) — disk blends into the
sky</summary>
<img width="1680" height="1050" alt="0 00001"
src="https://github.com/user-attachments/assets/e1228131-41b2-4f30-b50d-ebceebc8cabb"
/>
</details>

<details>
  <summary><strong>10.0</strong> (bloom on) — blinding glare</summary>
<img width="1680" height="1050" alt="10"
src="https://github.com/user-attachments/assets/3527c6d6-27ec-4e6f-9e9f-564a6b246bba"
/>
</details>

<details>
<summary><strong>1.0</strong> (bloom off) — normal sun with no
bloom</summary>
<img width="1680" height="1050" alt="1 no bloom"
src="https://github.com/user-attachments/assets/b62ce660-cb65-46b1-b211-a5d330b08719"
/>
</details>

<details>
<summary><strong>10.0</strong> (bloom off) — indistinguishable from 1.0
when bloom is off</summary>
<img width="1680" height="1050" alt="10 no bloom"
src="https://github.com/user-attachments/assets/17ea20dd-3de7-4bb9-82a1-16f7df9a9994"
/>
</details>

Quick question for reviewers: (not part of this PR) I’ve already
experimented with parameterizing the **sun angular size** and it works
well. It could serve as a cool artistic control or let you match skies
for planets that aren’t Earth. Would folks be interested in a follow‑up
PR?

<details>
  <summary>4× sun size</summary>
<img width="1680" height="1050" alt="4x sun"
src="https://github.com/user-attachments/assets/5c39ef98-0376-48b7-b845-bfad6d87c09b"
/>
</details>

---------

Co-authored-by: Ivan Ivashchenko <[email protected]>
Co-authored-by: Alice Cecile <[email protected]>
Co-authored-by: JMS55 <[email protected]>

Author: 4 people

crates/bevy_light/src/directional_light.rs

@@ -240,3 +240,53 @@ pub fn update_directional_light_frusta(
             .collect();
     }
 }
+
+/// Add to a [`DirectionalLight`] to control rendering of the visible solar disk in the sky.
+/// Affects only the disk’s appearance, not the light’s illuminance or shadows.
+/// Requires a `bevy::pbr::Atmosphere` component on a [`Camera3d`](bevy_camera::Camera3d) to have any effect.
+///
+/// By default, the atmosphere is rendered with [`SunDisk::EARTH`], which approximates the
+/// apparent size and brightness of the Sun as seen from Earth. You can also disable the sun
+/// disk entirely with [`SunDisk::OFF`].
+#[derive(Component, Clone)]
+#[require(DirectionalLight)]
+pub struct SunDisk {
+    /// The angular size (diameter) of the sun disk in radians, as observed from the scene.
+    pub angular_size: f32,
+    /// Multiplier for the brightness of the sun disk.
+    ///
+    /// `0.0` disables the disk entirely (atmospheric scattering still occurs),
+    /// `1.0` is the default physical intensity, and values `>1.0` overexpose it.
+    pub intensity: f32,
+}
+
+impl SunDisk {
+    /// Earth-like parameters for the sun disk.
+    ///
+    /// Uses the mean apparent size (~32 arcminutes) of the Sun at 1 AU distance
+    /// with default intensity.
+    pub const EARTH: SunDisk = SunDisk {
+        angular_size: 0.00930842,
+        intensity: 1.0,
+    };
+
+    /// No visible sun disk.
+    ///
+    /// Keeps scattering and directional light illumination, but hides the disk itself.
+    pub const OFF: SunDisk = SunDisk {
+        angular_size: 0.0,
+        intensity: 0.0,
+    };
+}
+
+impl Default for SunDisk {
+    fn default() -> Self {
+        Self::EARTH
+    }
+}
+
+impl Default for &SunDisk {
+    fn default() -> Self {
+        &SunDisk::EARTH
+    }
+}

crates/bevy_light/src/lib.rs

@@ -48,7 +48,7 @@ pub use spot_light::{
 mod directional_light;
 pub use directional_light::{
     update_directional_light_frusta, DirectionalLight, DirectionalLightShadowMap,
-    DirectionalLightTexture,
+    DirectionalLightTexture, SunDisk,
 };
 
 /// The light prelude.

crates/bevy_pbr/src/atmosphere/functions.wgsl

@@ -36,7 +36,6 @@
 
 
 // CONSTANTS
-
 const FRAC_PI: f32 = 0.3183098862; // 1 / π
 const FRAC_2_PI: f32 = 0.15915494309;  // 1 / (2π)
 const FRAC_3_16_PI: f32 = 0.0596831036594607509; // 3 / (16π)
@@ -275,8 +274,6 @@ fn sample_local_inscattering(local_atmosphere: AtmosphereSample, ray_dir: vec3<f
     return inscattering;
 }
 
-const SUN_ANGULAR_SIZE: f32 = 0.0174533; // angular diameter of sun in radians
-
 fn sample_sun_radiance(ray_dir_ws: vec3<f32>) -> vec3<f32> {
     let r = view_radius();
     let mu_view = ray_dir_ws.y;
@@ -285,11 +282,15 @@ fn sample_sun_radiance(ray_dir_ws: vec3<f32>) -> vec3<f32> {
     for (var light_i: u32 = 0u; light_i < lights.n_directional_lights; light_i++) {
         let light = &lights.directional_lights[light_i];
         let neg_LdotV = dot((*light).direction_to_light, ray_dir_ws);
-        let angle_to_sun = fast_acos(neg_LdotV);
-        let pixel_size = fwidth(angle_to_sun);
-        let factor = smoothstep(0.0, -pixel_size * ROOT_2, angle_to_sun - SUN_ANGULAR_SIZE * 0.5);
-        let sun_solid_angle = (SUN_ANGULAR_SIZE * SUN_ANGULAR_SIZE) * 4.0 * FRAC_PI;
-        sun_radiance += ((*light).color.rgb / sun_solid_angle) * factor * shadow_factor;
+        let angle_to_sun = fast_acos(clamp(neg_LdotV, -1.0, 1.0));
+        let w = max(0.5 * fwidth(angle_to_sun), 1e-6);
+        let sun_angular_size = (*light).sun_disk_angular_size;
+        let sun_intensity = (*light).sun_disk_intensity;
+        if sun_angular_size > 0.0 && sun_intensity > 0.0 {
+            let factor = 1 - smoothstep(sun_angular_size * 0.5 - w, sun_angular_size * 0.5 + w, angle_to_sun);
+            let sun_solid_angle = (sun_angular_size * sun_angular_size) * 0.25 * PI;
+            sun_radiance += ((*light).color.rgb / sun_solid_angle) * sun_intensity * factor * shadow_factor;
+        }
     }
     return sun_radiance;
 }

crates/bevy_pbr/src/render/light.rs

@@ -22,6 +22,7 @@ use bevy_ecs::{
 use bevy_light::cascade::Cascade;
 use bevy_light::cluster::assign::{calculate_cluster_factors, ClusterableObjectType};
 use bevy_light::cluster::GlobalVisibleClusterableObjects;
+use bevy_light::SunDisk;
 use bevy_light::{
     spot_light_clip_from_view, spot_light_world_from_view, AmbientLight, CascadeShadowConfig,
     Cascades, DirectionalLight, DirectionalLightShadowMap, NotShadowCaster, PointLight,
@@ -103,6 +104,8 @@ pub struct ExtractedDirectionalLight {
     pub soft_shadow_size: Option<f32>,
     /// True if this light is using two-phase occlusion culling.
     pub occlusion_culling: bool,
+    pub sun_disk_angular_size: f32,
+    pub sun_disk_intensity: f32,
 }
 
 // NOTE: These must match the bit flags in bevy_pbr/src/render/mesh_view_types.wgsl!
@@ -138,6 +141,8 @@ pub struct GpuDirectionalLight {
     cascades_overlap_proportion: f32,
     depth_texture_base_index: u32,
     decal_index: u32,
+    sun_disk_angular_size: f32,
+    sun_disk_intensity: f32,
 }
 
 // NOTE: These must match the bit flags in bevy_pbr/src/render/mesh_view_types.wgsl!
@@ -327,6 +332,7 @@ pub fn extract_lights(
                 Option<&RenderLayers>,
                 Option<&VolumetricLight>,
                 Has<OcclusionCulling>,
+                Option<&SunDisk>,
             ),
             Without<SpotLight>,
         >,
@@ -508,6 +514,7 @@ pub fn extract_lights(
         maybe_layers,
         volumetric_light,
         occlusion_culling,
+        sun_disk,
     ) in &directional_lights
     {
         if !view_visibility.get() {
@@ -574,6 +581,8 @@ pub fn extract_lights(
                     frusta: extracted_frusta,
                     render_layers: maybe_layers.unwrap_or_default().clone(),
                     occlusion_culling,
+                    sun_disk_angular_size: sun_disk.unwrap_or_default().angular_size,
+                    sun_disk_intensity: sun_disk.unwrap_or_default().intensity,
                 },
                 RenderCascadesVisibleEntities {
                     entities: cascade_visible_entities,
@@ -1200,6 +1209,8 @@ pub fn prepare_lights(
                 num_cascades: num_cascades as u32,
                 cascades_overlap_proportion: light.cascade_shadow_config.overlap_proportion,
                 depth_texture_base_index: num_directional_cascades_enabled_for_this_view as u32,
+                sun_disk_angular_size: light.sun_disk_angular_size,
+                sun_disk_intensity: light.sun_disk_intensity,
                 decal_index: decals
                     .as_ref()
                     .and_then(|decals| decals.get(*light_entity))

crates/bevy_pbr/src/render/mesh_view_types.wgsl

@@ -41,6 +41,8 @@ struct DirectionalLight {
     cascades_overlap_proportion: f32,
     depth_texture_base_index: u32,
     decal_index: u32,
+    sun_disk_angular_size: f32,
+    sun_disk_intensity: f32,
 };
 
 const DIRECTIONAL_LIGHT_FLAGS_SHADOWS_ENABLED_BIT: u32                  = 1u << 0u;

crates/bevy_solari/src/scene/binder.rs

@@ -23,10 +23,6 @@ use core::{f32::consts::TAU, hash::Hash, num::NonZeroU32, ops::Deref};
 const MAX_MESH_SLAB_COUNT: NonZeroU32 = NonZeroU32::new(500).unwrap();
 const MAX_TEXTURE_COUNT: NonZeroU32 = NonZeroU32::new(5_000).unwrap();
 
-/// Average angular diameter of the sun as seen from earth.
-/// <https://en.wikipedia.org/wiki/Angular_diameter#Use_in_astronomy>
-const SUN_ANGULAR_DIAMETER_RADIANS: f32 = 0.00930842;
-
 const TEXTURE_MAP_NONE: u32 = u32::MAX;
 const LIGHT_NOT_PRESENT_THIS_FRAME: u32 = u32::MAX;
 
@@ -407,7 +403,7 @@ struct GpuDirectionalLight {
 
 impl GpuDirectionalLight {
     fn new(directional_light: &ExtractedDirectionalLight) -> Self {
-        let cos_theta_max = cos(SUN_ANGULAR_DIAMETER_RADIANS / 2.0);
+        let cos_theta_max = cos(directional_light.sun_disk_angular_size / 2.0);
         let solid_angle = TAU * (1.0 - cos_theta_max);
         let luminance =
             (directional_light.color.to_vec3() * directional_light.illuminance) / solid_angle;