From ce3db843bc077e76730bc1d886ebbae959163458 Mon Sep 17 00:00:00 2001
From: Kevin Reid <kpreid@switchb.org>
Date: Fri, 13 Jun 2025 10:09:31 -0700
Subject: [PATCH] Make `IrradianceVolume` require `LightProbe` (and document
 this). (#19621)

## Objective

Make it easier to use `IrradianceVolume` with fewer ways to silently
fail. Fix #19614.

## Solution

* Add `#[require(LightProbe)]` to `struct IrradianceVolume`.
* Document this fact.
* Also document the volume being centered on the origin by default (this
was the other thing that was unclear when getting started).

I also looked at the other implementor of `LightProbeComponent`,
`EnvironmentMapLight`, but it has a use which is *not* as a light probe,
so it should not require `LightProbe`.

## Testing

* Confirmed that `examples/3d/irradiance_volumes.rs` still works after
removing `LightProbe`.
* Reviewed generated documentation.
---
 .../src/light_probe/irradiance_volume.rs        | 17 +++++++++++------
 examples/3d/irradiance_volumes.rs               |  1 -
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/crates/bevy_pbr/src/light_probe/irradiance_volume.rs b/crates/bevy_pbr/src/light_probe/irradiance_volume.rs
index 431d1245a2..e2dea463f2 100644
--- a/crates/bevy_pbr/src/light_probe/irradiance_volume.rs
+++ b/crates/bevy_pbr/src/light_probe/irradiance_volume.rs
@@ -17,11 +17,12 @@
 //! documentation in the `bevy-baked-gi` project for more details on this
 //! workflow.
 //!
-//! Like all light probes in Bevy, irradiance volumes are 1×1×1 cubes that can
-//! be arbitrarily scaled, rotated, and positioned in a scene with the
-//! [`bevy_transform::components::Transform`] component. The 3D voxel grid will
-//! be stretched to fill the interior of the cube, and the illumination from the
-//! irradiance volume will apply to all fragments within that bounding region.
+//! Like all light probes in Bevy, irradiance volumes are 1×1×1 cubes, centered
+//! on the origin, that can be arbitrarily scaled, rotated, and positioned in a
+//! scene with the [`bevy_transform::components::Transform`] component. The 3D
+//! voxel grid will be stretched to fill the interior of the cube, with linear
+//! interpolation, and the illumination from the irradiance volume will apply to
+//! all fragments within that bounding region.
 //!
 //! Bevy's irradiance volumes are based on Valve's [*ambient cubes*] as used in
 //! *Half-Life 2* ([Mitchell 2006, slide 27]). These encode a single color of
@@ -154,7 +155,7 @@ use crate::{
     MAX_VIEW_LIGHT_PROBES,
 };
 
-use super::LightProbeComponent;
+use super::{LightProbe, LightProbeComponent};
 
 /// On WebGL and WebGPU, we must disable irradiance volumes, as otherwise we can
 /// overflow the number of texture bindings when deferred rendering is in use
@@ -164,8 +165,12 @@ pub(crate) const IRRADIANCE_VOLUMES_ARE_USABLE: bool = cfg!(not(target_arch = "w
 /// The component that defines an irradiance volume.
 ///
 /// See [`crate::irradiance_volume`] for detailed information.
+///
+/// This component requires the [`LightProbe`] component, and is typically used with
+/// [`bevy_transform::components::Transform`] to place the volume appropriately.
 #[derive(Clone, Reflect, Component, Debug)]
 #[reflect(Component, Default, Debug, Clone)]
+#[require(LightProbe)]
 pub struct IrradianceVolume {
     /// The 3D texture that represents the ambient cubes, encoded in the format
     /// described in [`crate::irradiance_volume`].
diff --git a/examples/3d/irradiance_volumes.rs b/examples/3d/irradiance_volumes.rs
index 31529c4219..80373512db 100644
--- a/examples/3d/irradiance_volumes.rs
+++ b/examples/3d/irradiance_volumes.rs
@@ -251,7 +251,6 @@ fn spawn_irradiance_volume(commands: &mut Commands, assets: &ExampleAssets) {
             intensity: IRRADIANCE_VOLUME_INTENSITY,
             ..default()
         },
-        LightProbe,
     ));
 }