bevy/examples/3d/auto_exposure.rs
Joona Aalto afbbbd7335
Rename rendering components for improved consistency and clarity (#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>
2024-09-10 01:11:46 +00:00

228 lines
6.8 KiB
Rust

//! This example showcases auto exposure,
//! which automatically (but not instantly) adjusts the brightness of the scene in a way that mimics the function of the human eye.
//! Auto exposure requires compute shader capabilities, so it's not available on WebGL.
//!
//! ## Controls
//!
//! | Key Binding | Action |
//! |:-------------------|:---------------------------------------|
//! | `Left` / `Right` | Rotate Camera |
//! | `C` | Toggle Compensation Curve |
//! | `M` | Toggle Metering Mask |
//! | `V` | Visualize Metering Mask |
use bevy::{
core_pipeline::{
auto_exposure::{AutoExposure, AutoExposureCompensationCurve, AutoExposurePlugin},
Skybox,
},
math::{cubic_splines::LinearSpline, primitives::Plane3d, vec2},
prelude::*,
};
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(AutoExposurePlugin)
.add_systems(Startup, setup)
.add_systems(Update, example_control_system)
.run();
}
fn setup(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<StandardMaterial>>,
mut compensation_curves: ResMut<Assets<AutoExposureCompensationCurve>>,
asset_server: Res<AssetServer>,
) {
let metering_mask = asset_server.load("textures/basic_metering_mask.png");
commands.spawn((
Camera3dBundle {
camera: Camera {
hdr: true,
..default()
},
transform: Transform::from_xyz(1.0, 0.0, 0.0).looking_at(Vec3::ZERO, Vec3::Y),
..default()
},
AutoExposure {
metering_mask: metering_mask.clone(),
..default()
},
Skybox {
image: asset_server.load("environment_maps/pisa_specular_rgb9e5_zstd.ktx2"),
brightness: light_consts::lux::DIRECT_SUNLIGHT,
..default()
},
));
commands.insert_resource(ExampleResources {
basic_compensation_curve: compensation_curves.add(
AutoExposureCompensationCurve::from_curve(LinearSpline::new([
vec2(-4.0, -2.0),
vec2(0.0, 0.0),
vec2(2.0, 0.0),
vec2(4.0, 2.0),
]))
.unwrap(),
),
basic_metering_mask: metering_mask.clone(),
});
let plane = meshes.add(Mesh::from(
Plane3d {
normal: -Dir3::Z,
half_size: Vec2::new(2.0, 0.5),
}
.mesh(),
));
// Build a dimly lit box around the camera, with a slot to see the bright skybox.
for level in -1..=1 {
for side in [-Vec3::X, Vec3::X, -Vec3::Z, Vec3::Z] {
if level == 0 && Vec3::Z == side {
continue;
}
let height = Vec3::Y * level as f32;
commands.spawn(PbrBundle {
mesh: plane.clone(),
material: materials.add(StandardMaterial {
base_color: Color::srgb(
0.5 + side.x * 0.5,
0.75 - level as f32 * 0.25,
0.5 + side.z * 0.5,
),
..default()
}),
transform: Transform::from_translation(side * 2.0 + height)
.looking_at(height, Vec3::Y),
..default()
});
}
}
commands.insert_resource(AmbientLight {
color: Color::WHITE,
brightness: 0.0,
});
commands.spawn(PointLightBundle {
point_light: PointLight {
intensity: 2000.0,
..default()
},
transform: Transform::from_xyz(0.0, 0.0, 0.0),
..default()
});
commands.spawn(ImageBundle {
image: UiImage {
texture: metering_mask,
..default()
},
style: Style {
width: Val::Percent(100.0),
height: Val::Percent(100.0),
..default()
},
..default()
});
let text_style = TextStyle::default();
commands.spawn(
TextBundle::from_section(
"Left / Right - Rotate Camera\nC - Toggle Compensation Curve\nM - Toggle Metering Mask\nV - Visualize Metering Mask",
text_style.clone(),
)
.with_style(Style {
position_type: PositionType::Absolute,
top: Val::Px(12.0),
left: Val::Px(12.0),
..default()
}),
);
commands.spawn((
TextBundle::from_section("", text_style).with_style(Style {
position_type: PositionType::Absolute,
top: Val::Px(12.0),
right: Val::Px(12.0),
..default()
}),
ExampleDisplay,
));
}
#[derive(Component)]
struct ExampleDisplay;
#[derive(Resource)]
struct ExampleResources {
basic_compensation_curve: Handle<AutoExposureCompensationCurve>,
basic_metering_mask: Handle<Image>,
}
fn example_control_system(
mut camera: Query<(&mut Transform, &mut AutoExposure), With<Camera3d>>,
mut display: Query<&mut Text, With<ExampleDisplay>>,
mut mask_image: Query<&mut Style, With<UiImage>>,
time: Res<Time>,
input: Res<ButtonInput<KeyCode>>,
resources: Res<ExampleResources>,
) {
let (mut camera_transform, mut auto_exposure) = camera.single_mut();
let rotation = if input.pressed(KeyCode::ArrowLeft) {
time.delta_seconds()
} else if input.pressed(KeyCode::ArrowRight) {
-time.delta_seconds()
} else {
0.0
};
camera_transform.rotate_around(Vec3::ZERO, Quat::from_rotation_y(rotation));
if input.just_pressed(KeyCode::KeyC) {
auto_exposure.compensation_curve =
if auto_exposure.compensation_curve == resources.basic_compensation_curve {
Handle::default()
} else {
resources.basic_compensation_curve.clone()
};
}
if input.just_pressed(KeyCode::KeyM) {
auto_exposure.metering_mask =
if auto_exposure.metering_mask == resources.basic_metering_mask {
Handle::default()
} else {
resources.basic_metering_mask.clone()
};
}
mask_image.single_mut().display = if input.pressed(KeyCode::KeyV) {
Display::Flex
} else {
Display::None
};
let mut display = display.single_mut();
display.sections[0].value = format!(
"Compensation Curve: {}\nMetering Mask: {}",
if auto_exposure.compensation_curve == resources.basic_compensation_curve {
"Enabled"
} else {
"Disabled"
},
if auto_exposure.metering_mask == resources.basic_metering_mask {
"Enabled"
} else {
"Disabled"
},
);
}