Rename rendering components for improved consistency and clarity (bev…

…yengine#15035)

# Objective

The names of numerous rendering components in Bevy are inconsistent and
a bit confusing. Relevant names include:

- `AutoExposureSettings`
- `AutoExposureSettingsUniform`
- `BloomSettings`
- `BloomUniform` (no `Settings`)
- `BloomPrefilterSettings`
- `ChromaticAberration` (no `Settings`)
- `ContrastAdaptiveSharpeningSettings`
- `DepthOfFieldSettings`
- `DepthOfFieldUniform` (no `Settings`)
- `FogSettings`
- `SmaaSettings`, `Fxaa`, `TemporalAntiAliasSettings` (really
inconsistent??)
- `ScreenSpaceAmbientOcclusionSettings`
- `ScreenSpaceReflectionsSettings`
- `VolumetricFogSettings`

Firstly, there's a lot of inconsistency between `Foo`/`FooSettings` and
`FooUniform`/`FooSettingsUniform` and whether names are abbreviated or
not.

Secondly, the `Settings` post-fix seems unnecessary and a bit confusing
semantically, since it makes it seem like the component is mostly just
auxiliary configuration instead of the core *thing* that actually
enables the feature. This will be an even bigger problem once bundles
like `TemporalAntiAliasBundle` are deprecated in favor of required
components, as users will expect a component named `TemporalAntiAlias`
(or similar), not `TemporalAntiAliasSettings`.

## Solution

Drop the `Settings` post-fix from the component names, and change some
names to be more consistent.

- `AutoExposure`
- `AutoExposureUniform`
- `Bloom`
- `BloomUniform`
- `BloomPrefilter`
- `ChromaticAberration`
- `ContrastAdaptiveSharpening`
- `DepthOfField`
- `DepthOfFieldUniform`
- `DistanceFog`
- `Smaa`, `Fxaa`, `TemporalAntiAliasing` (note: we might want to change
to `Taa`, see "Discussion")
- `ScreenSpaceAmbientOcclusion`
- `ScreenSpaceReflections`
- `VolumetricFog`

I kept the old names as deprecated type aliases to make migration a bit
less painful for users. We should remove them after the next release.
(And let me know if I should just... not add them at all)

I also added some very basic docs for a few types where they were
missing, like on `Fxaa` and `DepthOfField`.

## Discussion

- `TemporalAntiAliasing` is still inconsistent with `Smaa` and `Fxaa`.
Consensus [on
Discord](https://discord.com/channels/691052431525675048/743663924229963868/1280601167209955431)
seemed to be that renaming to `Taa` would probably be fine, but I think
it's a bit more controversial, and it would've required renaming a lot
of related types like `TemporalAntiAliasNode`,
`TemporalAntiAliasBundle`, and `TemporalAntiAliasPlugin`, so I think
it's better to leave to a follow-up.
- I think `Fog` should probably have a more specific name like
`DistanceFog` considering it seems to be distinct from `VolumetricFog`.
~~This should probably be done in a follow-up though, so I just removed
the `Settings` post-fix for now.~~ (done)

---

## Migration Guide

Many rendering components have been renamed for improved consistency and
clarity.

- `AutoExposureSettings` → `AutoExposure`
- `BloomSettings` → `Bloom`
- `BloomPrefilterSettings` → `BloomPrefilter`
- `ContrastAdaptiveSharpeningSettings` → `ContrastAdaptiveSharpening`
- `DepthOfFieldSettings` → `DepthOfField`
- `FogSettings` → `DistanceFog`
- `SmaaSettings` → `Smaa`
- `TemporalAntiAliasSettings` → `TemporalAntiAliasing`
- `ScreenSpaceAmbientOcclusionSettings` → `ScreenSpaceAmbientOcclusion`
- `ScreenSpaceReflectionsSettings` → `ScreenSpaceReflections`
- `VolumetricFogSettings` → `VolumetricFog`

---------

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

crates/bevy_core_pipeline/src/auto_exposure/buffers.rs

@@ -6,8 +6,8 @@ use bevy_render::{
 };
 use bevy_utils::{Entry, HashMap};
 
-use super::pipeline::AutoExposureSettingsUniform;
-use super::AutoExposureSettings;
+use super::pipeline::AutoExposureUniform;
+use super::AutoExposure;
 
 #[derive(Resource, Default)]
 pub(super) struct AutoExposureBuffers {
@@ -16,19 +16,19 @@ pub(super) struct AutoExposureBuffers {
 
 pub(super) struct AutoExposureBuffer {
     pub(super) state: StorageBuffer<f32>,
-    pub(super) settings: UniformBuffer<AutoExposureSettingsUniform>,
+    pub(super) settings: UniformBuffer<AutoExposureUniform>,
 }
 
 #[derive(Resource)]
 pub(super) struct ExtractedStateBuffers {
-    changed: Vec<(Entity, AutoExposureSettings)>,
+    changed: Vec<(Entity, AutoExposure)>,
     removed: Vec<Entity>,
 }
 
 pub(super) fn extract_buffers(
     mut commands: Commands,
-    changed: Extract<Query<(Entity, &AutoExposureSettings), Changed<AutoExposureSettings>>>,
-    mut removed: Extract<RemovedComponents<AutoExposureSettings>>,
+    changed: Extract<Query<(Entity, &AutoExposure), Changed<AutoExposure>>>,
+    mut removed: Extract<RemovedComponents<AutoExposure>>,
 ) {
     commands.insert_resource(ExtractedStateBuffers {
         changed: changed
@@ -50,7 +50,7 @@ pub(super) fn prepare_buffers(
         let (low_percent, high_percent) = settings.filter.into_inner();
         let initial_state = 0.0f32.clamp(min_log_lum, max_log_lum);
 
-        let settings = AutoExposureSettingsUniform {
+        let settings = AutoExposureUniform {
             min_log_lum,
             inv_log_lum_range: 1.0 / (max_log_lum - min_log_lum),
             log_lum_range: max_log_lum - min_log_lum,

crates/bevy_core_pipeline/src/auto_exposure/mod.rs

@@ -26,14 +26,15 @@ use node::AutoExposureNode;
 use pipeline::{
     AutoExposurePass, AutoExposurePipeline, ViewAutoExposurePipeline, METERING_SHADER_HANDLE,
 };
-pub use settings::AutoExposureSettings;
+#[allow(deprecated)]
+pub use settings::{AutoExposure, AutoExposureSettings};
 
 use crate::auto_exposure::compensation_curve::GpuAutoExposureCompensationCurve;
 use crate::core_3d::graph::{Core3d, Node3d};
 
 /// Plugin for the auto exposure feature.
 ///
-/// See [`AutoExposureSettings`] for more details.
+/// See [`AutoExposure`] for more details.
 pub struct AutoExposurePlugin;
 
 #[derive(Resource)]
@@ -58,8 +59,8 @@ impl Plugin for AutoExposurePlugin {
             .resource_mut::<Assets<AutoExposureCompensationCurve>>()
             .insert(&Handle::default(), AutoExposureCompensationCurve::default());
 
-        app.register_type::<AutoExposureSettings>();
-        app.add_plugins(ExtractComponentPlugin::<AutoExposureSettings>::default());
+        app.register_type::<AutoExposure>();
+        app.add_plugins(ExtractComponentPlugin::<AutoExposure>::default());
 
         let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
             return;
@@ -113,9 +114,9 @@ fn queue_view_auto_exposure_pipelines(
     pipeline_cache: Res<PipelineCache>,
     mut compute_pipelines: ResMut<SpecializedComputePipelines<AutoExposurePipeline>>,
     pipeline: Res<AutoExposurePipeline>,
-    view_targets: Query<(Entity, &AutoExposureSettings)>,
+    view_targets: Query<(Entity, &AutoExposure)>,
 ) {
-    for (entity, settings) in view_targets.iter() {
+    for (entity, auto_exposure) in view_targets.iter() {
         let histogram_pipeline =
             compute_pipelines.specialize(&pipeline_cache, &pipeline, AutoExposurePass::Histogram);
         let average_pipeline =
@@ -124,8 +125,8 @@ fn queue_view_auto_exposure_pipelines(
         commands.entity(entity).insert(ViewAutoExposurePipeline {
             histogram_pipeline,
             mean_luminance_pipeline: average_pipeline,
-            compensation_curve: settings.compensation_curve.clone(),
-            metering_mask: settings.metering_mask.clone(),
+            compensation_curve: auto_exposure.compensation_curve.clone(),
+            metering_mask: auto_exposure.metering_mask.clone(),
         });
     }
 }

crates/bevy_core_pipeline/src/auto_exposure/pipeline.rs

@@ -27,7 +27,7 @@ pub struct ViewAutoExposurePipeline {
 }
 
 #[derive(ShaderType, Clone, Copy)]
-pub struct AutoExposureSettingsUniform {
+pub struct AutoExposureUniform {
     pub(super) min_log_lum: f32,
     pub(super) inv_log_lum_range: f32,
     pub(super) log_lum_range: f32,
@@ -59,7 +59,7 @@ impl FromWorld for AutoExposurePipeline {
                     ShaderStages::COMPUTE,
                     (
                         uniform_buffer::<GlobalsUniform>(false),
-                        uniform_buffer::<AutoExposureSettingsUniform>(false),
+                        uniform_buffer::<AutoExposureUniform>(false),
                         texture_2d(TextureSampleType::Float { filterable: false }),
                         texture_2d(TextureSampleType::Float { filterable: false }),
                         texture_1d(TextureSampleType::Float { filterable: false }),

crates/bevy_core_pipeline/src/auto_exposure/settings.rs

@@ -25,7 +25,7 @@ use bevy_utils::default;
 ///
 #[derive(Component, Clone, Reflect, ExtractComponent)]
 #[reflect(Component)]
-pub struct AutoExposureSettings {
+pub struct AutoExposure {
     /// The range of exposure values for the histogram.
     ///
     /// Pixel values below this range will be ignored, and pixel values above this range will be
@@ -88,7 +88,10 @@ pub struct AutoExposureSettings {
     pub compensation_curve: Handle<AutoExposureCompensationCurve>,
 }
 
-impl Default for AutoExposureSettings {
+#[deprecated(since = "0.15.0", note = "Renamed to `AutoExposure`")]
+pub type AutoExposureSettings = AutoExposure;
+
+impl Default for AutoExposure {
     fn default() -> Self {
         Self {
             range: -8.0..=8.0,

crates/bevy_core_pipeline/src/bloom/downsampling_pipeline.rs

@@ -1,4 +1,4 @@
-use super::{BloomSettings, BLOOM_SHADER_HANDLE, BLOOM_TEXTURE_FORMAT};
+use super::{Bloom, BLOOM_SHADER_HANDLE, BLOOM_TEXTURE_FORMAT};
 use crate::fullscreen_vertex_shader::fullscreen_shader_vertex_state;
 use bevy_ecs::{
     prelude::{Component, Entity},
@@ -33,7 +33,7 @@ pub struct BloomDownsamplingPipelineKeys {
     first_downsample: bool,
 }
 
-/// The uniform struct extracted from [`BloomSettings`] attached to a Camera.
+/// The uniform struct extracted from [`Bloom`] attached to a Camera.
 /// Will be available for use in the Bloom shader.
 #[derive(Component, ShaderType, Clone)]
 pub struct BloomUniforms {
@@ -136,10 +136,10 @@ pub fn prepare_downsampling_pipeline(
     pipeline_cache: Res<PipelineCache>,
     mut pipelines: ResMut<SpecializedRenderPipelines<BloomDownsamplingPipeline>>,
     pipeline: Res<BloomDownsamplingPipeline>,
-    views: Query<(Entity, &BloomSettings)>,
+    views: Query<(Entity, &Bloom)>,
 ) {
-    for (entity, settings) in &views {
-        let prefilter = settings.prefilter_settings.threshold > 0.0;
+    for (entity, bloom) in &views {
+        let prefilter = bloom.prefilter.threshold > 0.0;
 
         let pipeline_id = pipelines.specialize(
             &pipeline_cache,

crates/bevy_core_pipeline/src/bloom/mod.rs

@@ -3,7 +3,10 @@ mod settings;
 mod upsampling_pipeline;
 
 use bevy_color::{Gray, LinearRgba};
-pub use settings::{BloomCompositeMode, BloomPrefilterSettings, BloomSettings};
+#[allow(deprecated)]
+pub use settings::{
+    Bloom, BloomCompositeMode, BloomPrefilter, BloomPrefilterSettings, BloomSettings,
+};
 
 use crate::{
     core_2d::graph::{Core2d, Node2d},
@@ -44,11 +47,11 @@ impl Plugin for BloomPlugin {
     fn build(&self, app: &mut App) {
         load_internal_asset!(app, BLOOM_SHADER_HANDLE, "bloom.wgsl", Shader::from_wgsl);
 
-        app.register_type::<BloomSettings>();
-        app.register_type::<BloomPrefilterSettings>();
+        app.register_type::<Bloom>();
+        app.register_type::<BloomPrefilter>();
         app.register_type::<BloomCompositeMode>();
         app.add_plugins((
-            ExtractComponentPlugin::<BloomSettings>::default(),
+            ExtractComponentPlugin::<Bloom>::default(),
             UniformComponentPlugin::<BloomUniforms>::default(),
         ));
 
@@ -100,7 +103,7 @@ impl ViewNode for BloomNode {
         &'static BloomTexture,
         &'static BloomBindGroups,
         &'static DynamicUniformIndex<BloomUniforms>,
-        &'static BloomSettings,
+        &'static Bloom,
         &'static UpsamplingPipelineIds,
         &'static BloomDownsamplingPipelineIds,
     );
@@ -324,18 +327,18 @@ fn prepare_bloom_textures(
     mut commands: Commands,
     mut texture_cache: ResMut<TextureCache>,
     render_device: Res<RenderDevice>,
-    views: Query<(Entity, &ExtractedCamera, &BloomSettings)>,
+    views: Query<(Entity, &ExtractedCamera, &Bloom)>,
 ) {
-    for (entity, camera, settings) in &views {
+    for (entity, camera, bloom) in &views {
         if let Some(UVec2 {
             x: width,
             y: height,
         }) = camera.physical_viewport_size
         {
             // How many times we can halve the resolution minus one so we don't go unnecessarily low
-            let mip_count = settings.max_mip_dimension.ilog2().max(2) - 1;
+            let mip_count = bloom.max_mip_dimension.ilog2().max(2) - 1;
             let mip_height_ratio = if height != 0 {
-                settings.max_mip_dimension as f32 / height as f32
+                bloom.max_mip_dimension as f32 / height as f32
             } else {
                 0.
             };
@@ -457,19 +460,18 @@ fn prepare_bloom_bind_groups(
 /// * `max_mip` - the index of the lowest frequency pyramid level.
 ///
 /// This function can be visually previewed for all values of *mip* (normalized) with tweakable
-/// [`BloomSettings`] parameters on [Desmos graphing calculator](https://www.desmos.com/calculator/ncc8xbhzzl).
-fn compute_blend_factor(bloom_settings: &BloomSettings, mip: f32, max_mip: f32) -> f32 {
+/// [`Bloom`] parameters on [Desmos graphing calculator](https://www.desmos.com/calculator/ncc8xbhzzl).
+fn compute_blend_factor(bloom: &Bloom, mip: f32, max_mip: f32) -> f32 {
     let mut lf_boost = (1.0
-        - (1.0 - (mip / max_mip)).powf(1.0 / (1.0 - bloom_settings.low_frequency_boost_curvature)))
-        * bloom_settings.low_frequency_boost;
+        - (1.0 - (mip / max_mip)).powf(1.0 / (1.0 - bloom.low_frequency_boost_curvature)))
+        * bloom.low_frequency_boost;
     let high_pass_lq = 1.0
-        - (((mip / max_mip) - bloom_settings.high_pass_frequency)
-            / bloom_settings.high_pass_frequency)
+        - (((mip / max_mip) - bloom.high_pass_frequency) / bloom.high_pass_frequency)
             .clamp(0.0, 1.0);
-    lf_boost *= match bloom_settings.composite_mode {
-        BloomCompositeMode::EnergyConserving => 1.0 - bloom_settings.intensity,
+    lf_boost *= match bloom.composite_mode {
+        BloomCompositeMode::EnergyConserving => 1.0 - bloom.intensity,
         BloomCompositeMode::Additive => 1.0,
     };
 
-    (bloom_settings.intensity + lf_boost) * high_pass_lq
+    (bloom.intensity + lf_boost) * high_pass_lq
 }

crates/bevy_core_pipeline/src/bloom/settings.rs

@@ -26,7 +26,7 @@ use bevy_render::{extract_component::ExtractComponent, prelude::Camera};
 /// used in Bevy as well as a visualization of the curve's respective scattering profile.
 #[derive(Component, Reflect, Clone)]
 #[reflect(Component, Default)]
-pub struct BloomSettings {
+pub struct Bloom {
     /// Controls the baseline of how much the image is scattered (default: 0.15).
     ///
     /// This parameter should be used only to control the strength of the bloom
@@ -90,15 +90,21 @@ pub struct BloomSettings {
     /// * 1.0 - maximum scattering angle is 90 degrees
     pub high_pass_frequency: f32,
 
-    pub prefilter_settings: BloomPrefilterSettings,
+    /// Controls the threshold filter used for extracting the brightest regions from the input image
+    /// before blurring them and compositing back onto the original image.
+    ///
+    /// Changing these settings creates a physically inaccurate image and makes it easy to make
+    /// the final result look worse. However, they can be useful when emulating the 1990s-2000s game look.
+    /// See [`BloomPrefilter`] for more information.
+    pub prefilter: BloomPrefilter,
 
     /// Controls whether bloom textures
     /// are blended between or added to each other. Useful
     /// if image brightening is desired and a must-change
-    /// if `prefilter_settings` are used.
+    /// if `prefilter` is used.
     ///
     /// # Recommendation
-    /// Set to [`BloomCompositeMode::Additive`] if `prefilter_settings` are
+    /// Set to [`BloomCompositeMode::Additive`] if `prefilter` is
     /// configured in a non-energy-conserving way,
     /// otherwise set to [`BloomCompositeMode::EnergyConserving`].
     pub composite_mode: BloomCompositeMode,
@@ -112,7 +118,10 @@ pub struct BloomSettings {
     pub uv_offset: f32,
 }
 
-impl BloomSettings {
+#[deprecated(since = "0.15.0", note = "Renamed to `Bloom`")]
+pub type BloomSettings = Bloom;
+
+impl Bloom {
     const DEFAULT_MAX_MIP_DIMENSION: u32 = 512;
     const DEFAULT_UV_OFFSET: f32 = 0.004;
 
@@ -124,7 +133,7 @@ impl BloomSettings {
         low_frequency_boost: 0.7,
         low_frequency_boost_curvature: 0.95,
         high_pass_frequency: 1.0,
-        prefilter_settings: BloomPrefilterSettings {
+        prefilter: BloomPrefilter {
             threshold: 0.0,
             threshold_softness: 0.0,
         },
@@ -139,7 +148,7 @@ impl BloomSettings {
         low_frequency_boost: 0.7,
         low_frequency_boost_curvature: 0.95,
         high_pass_frequency: 1.0,
-        prefilter_settings: BloomPrefilterSettings {
+        prefilter: BloomPrefilter {
             threshold: 0.6,
             threshold_softness: 0.2,
         },
@@ -154,7 +163,7 @@ impl BloomSettings {
         low_frequency_boost: 0.0,
         low_frequency_boost_curvature: 0.0,
         high_pass_frequency: 1.0 / 3.0,
-        prefilter_settings: BloomPrefilterSettings {
+        prefilter: BloomPrefilter {
             threshold: 0.0,
             threshold_softness: 0.0,
         },
@@ -164,7 +173,7 @@ impl BloomSettings {
     };
 }
 
-impl Default for BloomSettings {
+impl Default for Bloom {
     fn default() -> Self {
         Self::NATURAL
     }
@@ -179,7 +188,7 @@ impl Default for BloomSettings {
 /// * Changing these settings makes it easy to make the final result look worse
 /// * Non-default prefilter settings should be used in conjunction with [`BloomCompositeMode::Additive`]
 #[derive(Default, Clone, Reflect)]
-pub struct BloomPrefilterSettings {
+pub struct BloomPrefilter {
     /// Baseline of the quadratic threshold curve (default: 0.0).
     ///
     /// RGB values under the threshold curve will not contribute to the effect.
@@ -194,19 +203,22 @@ pub struct BloomPrefilterSettings {
     pub threshold_softness: f32,
 }
 
+#[deprecated(since = "0.15.0", note = "Renamed to `BloomPrefilter`")]
+pub type BloomPrefilterSettings = BloomPrefilter;
+
 #[derive(Debug, Clone, Reflect, PartialEq, Eq, Hash, Copy)]
 pub enum BloomCompositeMode {
     EnergyConserving,
     Additive,
 }
 
-impl ExtractComponent for BloomSettings {
+impl ExtractComponent for Bloom {
     type QueryData = (&'static Self, &'static Camera);
 
     type QueryFilter = ();
     type Out = (Self, BloomUniforms);
 
-    fn extract_component((settings, camera): QueryItem<'_, Self::QueryData>) -> Option<Self::Out> {
+    fn extract_component((bloom, camera): QueryItem<'_, Self::QueryData>) -> Option<Self::Out> {
         match (
             camera.physical_viewport_rect(),
             camera.physical_viewport_size(),
@@ -215,8 +227,8 @@ impl ExtractComponent for BloomSettings {
             camera.hdr,
         ) {
             (Some(URect { min: origin, .. }), Some(size), Some(target_size), true, true) => {
-                let threshold = settings.prefilter_settings.threshold;
-                let threshold_softness = settings.prefilter_settings.threshold_softness;
+                let threshold = bloom.prefilter.threshold;
+                let threshold_softness = bloom.prefilter.threshold_softness;
                 let knee = threshold * threshold_softness.clamp(0.0, 1.0);
 
                 let uniform = BloomUniforms {
@@ -232,10 +244,10 @@ impl ExtractComponent for BloomSettings {
                     aspect: AspectRatio::try_from_pixels(size.x, size.y)
                         .expect("Valid screen size values for Bloom settings")
                         .ratio(),
-                    uv_offset: settings.uv_offset,
+                    uv_offset: bloom.uv_offset,
                 };
 
-                Some((settings.clone(), uniform))
+                Some((bloom.clone(), uniform))
             }
             _ => None,
         }