From bc352561c9814112dbcf5925a4476f135d758c65 Mon Sep 17 00:00:00 2001 From: Joona Aalto Date: Wed, 9 Oct 2024 02:59:27 +0300 Subject: [PATCH] Migrate reflection probes to required components (#15737) # Objective Getting closer to the end! Another part of the required components migration: reflection probes. ## Solution As per the [proposal added by Cart](https://hackmd.io/@bevy/required_components/%2FNmpIh0tGSiayGlswbfcEzw) (Proposal 2), make `LightProbe` require `Transform` and `Visibility`, and deprecate `ReflectionProbeBundle`. Note that this proposal wasn't officially blessed yet, but it is the only existing one that really works, so I implemented it here for consideration. ## Testing I ran the reflection probe example, and it appears to work. --- ## Migration Guide `ReflectionProbeBundle` has been deprecated in favor of inserting the `LightProbe` and `EnvironmentMapLight` components directly. Inserting them will now automatically insert `Transform` and `Visibility` components. --------- Co-authored-by: Tim Blackbird Co-authored-by: Alice Cecile --- .../bevy_pbr/src/light_probe/environment_map.rs | 10 +++++++--- crates/bevy_pbr/src/light_probe/mod.rs | 12 ++++++------ crates/bevy_pbr/src/ssr/mod.rs | 4 ++-- examples/3d/reflection_probes.rs | 15 ++++++--------- 4 files changed, 21 insertions(+), 20 deletions(-) diff --git a/crates/bevy_pbr/src/light_probe/environment_map.rs b/crates/bevy_pbr/src/light_probe/environment_map.rs index c366d02b59bb6..4fff505427642 100644 --- a/crates/bevy_pbr/src/light_probe/environment_map.rs +++ b/crates/bevy_pbr/src/light_probe/environment_map.rs @@ -11,15 +11,13 @@ //! 1. If attached to a view, they represent the objects located a very far //! distance from the view, in a similar manner to a skybox. Essentially, these //! *view environment maps* represent a higher-quality replacement for -//! [`crate::AmbientLight`] for outdoor scenes. The indirect light from such +//! [`AmbientLight`](crate::AmbientLight) for outdoor scenes. The indirect light from such //! environment maps are added to every point of the scene, including //! interior enclosed areas. //! //! 2. If attached to a [`LightProbe`], environment maps represent the immediate //! surroundings of a specific location in the scene. These types of //! environment maps are known as *reflection probes*. -//! [`ReflectionProbeBundle`] is available as a mechanism to conveniently add -//! these to a scene. //! //! Typically, environment maps are static (i.e. "baked", calculated ahead of //! time) and so only reflect fixed static geometry. The environment maps must @@ -46,6 +44,8 @@ //! //! [several pre-filtered environment maps]: https://github.com/KhronosGroup/glTF-Sample-Environments +#![expect(deprecated)] + use bevy_asset::{AssetId, Handle}; use bevy_ecs::{ bundle::Bundle, component::Component, query::QueryItem, reflect::ReflectComponent, @@ -137,6 +137,10 @@ pub struct EnvironmentMapIds { /// surrounding a region in space. For more information, see /// [`crate::environment_map`]. #[derive(Bundle, Clone)] +#[deprecated( + since = "0.15.0", + note = "Use the `LightProbe` and `EnvironmentMapLight` components instead. Inserting them will now also insert the other components required by them automatically." +)] pub struct ReflectionProbeBundle { /// Contains a transform that specifies the position of this reflection probe in space. pub spatial: SpatialBundle, diff --git a/crates/bevy_pbr/src/light_probe/mod.rs b/crates/bevy_pbr/src/light_probe/mod.rs index 68a401c60ad27..dca5d7209e9b5 100644 --- a/crates/bevy_pbr/src/light_probe/mod.rs +++ b/crates/bevy_pbr/src/light_probe/mod.rs @@ -23,7 +23,7 @@ use bevy_render::{ settings::WgpuFeatures, sync_world::RenderEntity, texture::{FallbackImage, GpuImage, Image}, - view::ExtractedView, + view::{ExtractedView, Visibility}, Extract, ExtractSchedule, Render, RenderApp, RenderSet, }; use bevy_transform::{components::Transform, prelude::GlobalTransform}; @@ -65,15 +65,14 @@ pub struct LightProbePlugin; /// A marker component for a light probe, which is a cuboid region that provides /// global illumination to all fragments inside it. /// -/// The light probe range is conceptually a unit cube (1×1×1) centered on the -/// origin. The [`bevy_transform::prelude::Transform`] applied to this entity -/// can scale, rotate, or translate that cube so that it contains all fragments -/// that should take this light probe into account. -/// /// Note that a light probe will have no effect unless the entity contains some /// kind of illumination, which can either be an [`EnvironmentMapLight`] or an /// [`IrradianceVolume`]. /// +/// The light probe range is conceptually a unit cube (1×1×1) centered on the +/// origin. The [`Transform`] applied to this entity can scale, rotate, or translate +/// that cube so that it contains all fragments that should take this light probe into account. +/// /// When multiple sources of indirect illumination can be applied to a fragment, /// the highest-quality one is chosen. Diffuse and specular illumination are /// considered separately, so, for example, Bevy may decide to sample the @@ -104,6 +103,7 @@ pub struct LightProbePlugin; /// with other engines should be aware of this terminology difference. #[derive(Component, Debug, Clone, Copy, Default, Reflect)] #[reflect(Component, Default, Debug)] +#[require(Transform, Visibility)] pub struct LightProbe; /// A GPU type that stores information about a light probe. diff --git a/crates/bevy_pbr/src/ssr/mod.rs b/crates/bevy_pbr/src/ssr/mod.rs index eef6d9857ec2d..5852315f58d84 100644 --- a/crates/bevy_pbr/src/ssr/mod.rs +++ b/crates/bevy_pbr/src/ssr/mod.rs @@ -86,8 +86,8 @@ pub struct ScreenSpaceReflectionsBundle { /// /// As with all screen-space techniques, SSR can only reflect objects on screen. /// When objects leave the camera, they will disappear from reflections. -/// Alternatives that don't suffer from this problem include -/// [`crate::environment_map::ReflectionProbeBundle`]s. The advantage of SSR is +/// An alternative that doesn't suffer from this problem is the combination of +/// a [`LightProbe`](crate::LightProbe) and [`EnvironmentMapLight`]. The advantage of SSR is /// that it can reflect all objects, not just static ones. /// /// SSR is an approximation technique and produces artifacts in some situations. diff --git a/examples/3d/reflection_probes.rs b/examples/3d/reflection_probes.rs index 17c76576e7aa6..f33559236dee5 100644 --- a/examples/3d/reflection_probes.rs +++ b/examples/3d/reflection_probes.rs @@ -136,20 +136,17 @@ fn spawn_sphere( // Spawns the reflection probe. fn spawn_reflection_probe(commands: &mut Commands, cubemaps: &Cubemaps) { - commands.spawn(ReflectionProbeBundle { - spatial: SpatialBundle { - // 2.0 because the sphere's radius is 1.0 and we want to fully enclose it. - transform: Transform::from_scale(Vec3::splat(2.0)), - ..SpatialBundle::default() - }, - light_probe: LightProbe, - environment_map: EnvironmentMapLight { + commands.spawn(( + LightProbe, + EnvironmentMapLight { diffuse_map: cubemaps.diffuse.clone(), specular_map: cubemaps.specular_reflection_probe.clone(), intensity: 5000.0, ..default() }, - }); + // 2.0 because the sphere's radius is 1.0 and we want to fully enclose it. + Transform::from_scale(Vec3::splat(2.0)), + )); } // Spawns the help text.