[Merged by Bors] - Initial tonemapping options

Cargo.toml

@@ -50,6 +50,7 @@ default = [
   "x11",
   "filesystem_watcher",
   "android_shared_stdcxx",
+  "tonemapping_luts"
 ]
 
 # Force dynamic linking, which improves iterative compile times
@@ -132,6 +133,9 @@ android_shared_stdcxx = ["bevy_internal/android_shared_stdcxx"]
 # These trace events are expensive even when off, thus they require compile time opt-in.
 detailed_trace = ["bevy_internal/detailed_trace"]
 
+# Include tonemapping LUT KTX2 files.
+tonemapping_luts = ["bevy_internal/tonemapping_luts"]
+
 [dependencies]
 bevy_dylib = { path = "crates/bevy_dylib", version = "0.9.0", default-features = false, optional = true }
 bevy_internal = { path = "crates/bevy_internal", version = "0.9.0", default-features = false }
@@ -396,7 +400,7 @@ path = "examples/3d/tonemapping.rs"
 required-features = ["ktx2", "zstd"]
 
 [package.metadata.example.tonemapping]
-name = "tonemapping"
+name = "Tonemapping"
 description = "Compares tonemapping options"
 category = "3D Rendering"
 wasm = true

assets/shaders/tonemapping_test_patterns.wgsl

@@ -12,9 +12,12 @@ struct FragmentInput {
     #import bevy_pbr::mesh_vertex_output
 };
 
+// Sweep across hues on y axis with value from 0.0 to +15EV across x axis 
+// quantized into 24 steps for both axis.
 fn color_sweep(uv: vec2<f32>) -> vec3<f32> {
+    var uv = uv;
     let steps = 24.0;
-    let uv = uv * (1.0 + 1.0 / steps);
+    uv.y = uv.y * (1.0 + 1.0 / steps);
     let ratio = 2.0;
 
     let h = PI * 2.0 * floor(1.0 + steps * uv.y) / steps;
@@ -38,6 +41,7 @@ fn hsv_to_srgb(c: vec3<f32>) -> vec3<f32> {
     return c.z * mix(K.xxx, clamp(p - K.xxx, vec3(0.0), vec3(1.0)), c.y);
 }
 
+// Generates a continuous sRGB sweep.
 fn continuous_hue(uv: vec2<f32>) -> vec3<f32> {
     return hsv_to_srgb(vec3(uv.x, 1.0, 1.0)) * max(0.0, exp2(uv.y * 9.0) - 1.0);
 }

crates/bevy_core_pipeline/Cargo.toml

@@ -15,6 +15,7 @@ keywords = ["bevy"]
 [features]
 trace = []
 webgl = []
+tonemapping_luts = []
 
 [dependencies]
 # bevy

crates/bevy_core_pipeline/src/core_2d/camera_2d.rs

@@ -1,6 +1,6 @@
 use crate::{
     clear_color::ClearColorConfig,
-    tonemapping::{Dither, Tonemapping},
+    tonemapping::{DebandDither, Tonemapping},
 };
 use bevy_ecs::prelude::*;
 use bevy_reflect::Reflect;
@@ -30,7 +30,7 @@ pub struct Camera2dBundle {
     pub global_transform: GlobalTransform,
     pub camera_2d: Camera2d,
     pub tonemapping: Tonemapping,
-    pub dither: Dither,
+    pub deband_dither: DebandDither,
 }
 
 impl Default for Camera2dBundle {
@@ -72,7 +72,7 @@ impl Camera2dBundle {
             camera: Camera::default(),
             camera_2d: Camera2d::default(),
             tonemapping: Tonemapping::None,
-            dither: Dither::Disabled,
+            deband_dither: DebandDither::Disabled,
         }
     }
 }

crates/bevy_core_pipeline/src/core_3d/camera_3d.rs

@@ -1,6 +1,6 @@
 use crate::{
     clear_color::ClearColorConfig,
-    tonemapping::{Dither, Tonemapping},
+    tonemapping::{DebandDither, Tonemapping},
 };
 use bevy_ecs::prelude::*;
 use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize};
@@ -62,7 +62,7 @@ pub struct Camera3dBundle {
     pub global_transform: GlobalTransform,
     pub camera_3d: Camera3d,
     pub tonemapping: Tonemapping,
-    pub dither: Dither,
+    pub dither: DebandDither,
     pub color_grading: ColorGrading,
 }
 
@@ -79,7 +79,7 @@ impl Default for Camera3dBundle {
             global_transform: Default::default(),
             camera_3d: Default::default(),
             tonemapping: Tonemapping::ReinhardLuminance,
-            dither: Dither::Enabled,
+            dither: DebandDither::Enabled,
             color_grading: ColorGrading::default(),
         }
     }

crates/bevy_core_pipeline/src/tonemapping/luts/info.txt

@@ -0,0 +1,25 @@
+--- Process for recreating AgX-default_contrast.ktx2 ---
+Download: 
+https://github.com/MrLixm/AgXc/blob/898198e0490b0551ed81412a0c22e0b72fffb7cd/obs/obs-script/AgX-default_contrast.lut.png
+Convert to vertical strip exr with: 
+https://gist.github.com/DGriffin91/fc8e0cfd55aaa175ac10199403bc19b8
+Convert exr to 3D ktx2 with:
+https://gist.github.com/DGriffin91/49401c43378b58bce32059291097d4ca
+
+--- Process for recreating tony_mc_mapface.ktx2 ---
+Download: 
+https://github.com/h3r2tic/tony-mc-mapface/blob/909e51c8a74251fd828770248476cb084081e08c/tony_mc_mapface.dds
+Convert dds to 3D ktx2 with:
+https://gist.github.com/DGriffin91/49401c43378b58bce32059291097d4ca
+
+--- Process for recreating Blender_-11_12.ktx2 ---
+Create LUT stimulus with:
+https://gist.github.com/DGriffin91/e119bf32b520e219f6e102a6eba4a0cf
+Open LUT image in Blender's image editor and make sure color space is set to linear.
+Export from Blender as 32bit EXR, override color space to Filmic sRGB.
+Import EXR back into blender set color space to sRGB, then export as 32bit EXR override color space to linear.
+Convert exr to 3D ktx2 with:
+https://gist.github.com/DGriffin91/49401c43378b58bce32059291097d4ca
+
+
+

crates/bevy_core_pipeline/src/tonemapping/mod.rs

@@ -5,9 +5,10 @@ use bevy_ecs::prelude::*;
 use bevy_reflect::{FromReflect, Reflect, TypeUuid};
 use bevy_render::camera::Camera;
 use bevy_render::extract_component::{ExtractComponent, ExtractComponentPlugin};
+use bevy_render::extract_resource::{ExtractResource, ExtractResourcePlugin};
 use bevy_render::render_asset::RenderAssets;
 use bevy_render::renderer::RenderDevice;
-use bevy_render::texture::{CompressedImageFormats, Image, ImageType};
+use bevy_render::texture::{CompressedImageFormats, Image, ImageSampler, ImageType};
 use bevy_render::view::{ViewTarget, ViewUniform};
 use bevy_render::{render_resource::*, RenderApp, RenderSet};
 
@@ -22,7 +23,8 @@ const TONEMAPPING_SHADER_HANDLE: HandleUntyped =
 const TONEMAPPING_SHARED_SHADER_HANDLE: HandleUntyped =
     HandleUntyped::weak_from_u64(Shader::TYPE_UUID, 2499430578245347910);
 
-#[derive(Resource)]
+/// 3D LUT (look up table) textures used for tonemapping
+#[derive(Resource, Clone, ExtractResource)]
 pub struct TonemappingLuts {
     blender_filmic: Handle<Image>,
     agx: Handle<Image>,
@@ -46,32 +48,50 @@ impl Plugin for TonemappingPlugin {
             Shader::from_wgsl
         );
 
-        let mut images = app.world.resource_mut::<Assets<Image>>();
-
-        let tonemapping_luts = TonemappingLuts {
-            blender_filmic: images.add(setup_tonemapping_lut_image(
-                include_bytes!("luts/Blender_-11_12.ktx2"),
-                ImageType::Extension("ktx2"),
-            )),
-            agx: images.add(setup_tonemapping_lut_image(
-                include_bytes!("luts/AgX-default_contrast.ktx2"),
-                ImageType::Extension("ktx2"),
-            )),
-            tony_mc_mapface: images.add(setup_tonemapping_lut_image(
-                include_bytes!("luts/TonyMcMapface.ktx2"),
-                ImageType::Extension("ktx2"),
-            )),
-        };
+        if !app.world.is_resource_added::<TonemappingLuts>() {
+            let mut images = app.world.resource_mut::<Assets<Image>>();
+
+            #[cfg(feature = "tonemapping_luts")]
+            let tonemapping_luts = {
+                TonemappingLuts {
+                    blender_filmic: images.add(setup_tonemapping_lut_image(
+                        include_bytes!("luts/Blender_-11_12.ktx2"),
+                        ImageType::Extension("ktx2"),
+                    )),
+                    agx: images.add(setup_tonemapping_lut_image(
+                        include_bytes!("luts/AgX-default_contrast.ktx2"),
+                        ImageType::Extension("ktx2"),
+                    )),
+                    tony_mc_mapface: images.add(setup_tonemapping_lut_image(
+                        include_bytes!("luts/tony_mc_mapface.ktx2"),
+                        ImageType::Extension("ktx2"),
+                    )),
+                }
+            };
+
+            #[cfg(not(feature = "tonemapping_luts"))]
+            let tonemapping_luts = {
+                let placeholder = images.add(lut_placeholder());
+                TonemappingLuts {
+                    blender_filmic: placeholder.clone(),
+                    agx: placeholder.clone(),
+                    tony_mc_mapface: placeholder,
+                }
+            };
+
+            app.insert_resource(tonemapping_luts);
+        }
+
+        app.add_plugin(ExtractResourcePlugin::<TonemappingLuts>::default());
 
         app.register_type::<Tonemapping>();
-        app.register_type::<Dither>();
+        app.register_type::<DebandDither>();
 
         app.add_plugin(ExtractComponentPlugin::<Tonemapping>::default());
-        app.add_plugin(ExtractComponentPlugin::<Dither>::default());
+        app.add_plugin(ExtractComponentPlugin::<DebandDither>::default());
 
         if let Ok(render_app) = app.get_sub_app_mut(RenderApp) {
             render_app
-                .insert_resource(tonemapping_luts)
                 .init_resource::<TonemappingPipeline>()
                 .init_resource::<SpecializedRenderPipelines<TonemappingPipeline>>()
                 .add_system(queue_view_tonemapping_pipelines.in_set(RenderSet::Queue));
@@ -84,6 +104,7 @@ pub struct TonemappingPipeline {
     texture_bind_group: BindGroupLayout,
 }
 
+/// Optionally enables a tonemapping shader that attempts to map linear input stimulus into a perceptually uniform image for a given [`Camera`] entity.
 #[derive(
     Component,
     Debug,
@@ -100,21 +121,45 @@ pub struct TonemappingPipeline {
 #[extract_component_filter(With<Camera>)]
 #[reflect(Component)]
 pub enum Tonemapping {
+    /// Bypass tonemapping.
     None,
     /// Suffers from lots hue shifting, brights don't desaturate naturally.
+    /// Bright primaries and secondaries don't desaturate at all.
     Reinhard,
-    /// Old bevy default. Suffers from hue shifting, brights don't desaturate much at all.
+    /// Current bevy default. Likely to change in the future.
+    /// Suffers from hue shifting. Brights don't desaturate much at all across the spectrum.
+    #[default]
     ReinhardLuminance,
-    /// Bad
-    Aces,
-    /// Very Good
+    /// Same base implementation that Godot 4.0 uses for Tonemap ACES.
+    /// <https://github.com/TheRealMJP/BakingLab/blob/master/BakingLab/ACES.hlsl>
+    /// Not neutral, has a very specific aesthetic, intentional and dramatic hue shifting.
+    /// Bright greens and reds turn orange. Bright blues turn magenta.
+    /// Significantly increased contrast. Brights desaturate across the spectrum.
+    AcesFitted,
+    /// By Troy Sobotka
+    /// <https://github.com/sobotka/AgX>
+    /// Very neutral. Image is somewhat desaturated when compared to other tonemappers.
+    /// Little to no hue shifting. Subtle abney shifting.
     AgX,
-    /// Also good
+    /// By Tomasz Stachowiak
+    /// Has little hue shifting in the darks and mids, but lots in the brights. Brights desaturate across the spectrum.
+    /// Is sort of between Reinhard and ReinhardLuminance. Conceptually similar to reinhard-jodie.
+    /// Designed as a compromise if you want e.g. decent skin tones in low light, but can't afford to re-do your
+    /// VFX to look good without hue shifting.
     SomewhatBoringDisplayTransform,
-    /// Very Good
+    /// By Tomasz Stachowiak
+    /// <https://github.com/h3r2tic/tony-mc-mapface>
+    /// Very neutral. Subtle but intentional hue shifting. Brights desaturate across the spectrum.
+    /// Comment from author:
+    /// Tony is a display transform intended for real-time applications such as games.
+    /// It is intentionally boring, does not increase contrast or saturation, and stays close to the
+    /// input stimulus where compression isn't necessary.
+    /// Brightness-equivalent luminance of the input stimulus is compressed. The non-linearity resembles Reinhard.
+    /// Color hues are preserved during compression, except for a deliberate Bezold–Brücke shift.
+    /// To avoid posterization, selective desaturation is employed, with care to avoid the Abney effect.
     TonyMcMapface,
-    /// Also good
-    #[default]
+    /// Default Filmic Display Transform from blender.
+    /// Somewhat neutral. Suffers from hue shifting. Brights desaturate across the spectrum.
     BlenderFilmic,
 }
 
@@ -125,7 +170,7 @@ impl Tonemapping {
 }
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct TonemappingPipelineKey {
-    deband_dither: Dither,
+    deband_dither: DebandDither,
     tonemapping: Tonemapping,
 }
 
@@ -134,7 +179,7 @@ impl SpecializedRenderPipeline for TonemappingPipeline {
 
     fn specialize(&self, key: Self::Key) -> RenderPipelineDescriptor {
         let mut shader_defs = Vec::new();
-        if let Dither::Enabled = key.deband_dither {
+        if let DebandDither::Enabled = key.deband_dither {
             shader_defs.push("DEBAND_DITHER".into());
         }
         match key.tonemapping {
@@ -143,7 +188,7 @@ impl SpecializedRenderPipeline for TonemappingPipeline {
             Tonemapping::ReinhardLuminance => {
                 shader_defs.push("TONEMAP_METHOD_REINHARD_LUMINANCE".into());
             }
-            Tonemapping::Aces => shader_defs.push("TONEMAP_METHOD_ACES".into()),
+            Tonemapping::AcesFitted => shader_defs.push("TONEMAP_METHOD_ACES_FITTED".into()),
             Tonemapping::AgX => shader_defs.push("TONEMAP_METHOD_AGX".into()),
             Tonemapping::SomewhatBoringDisplayTransform => {
                 shader_defs.push("TONEMAP_METHOD_SOMEWHAT_BORING_DISPLAY_TRANSFORM".into());
@@ -227,11 +272,11 @@ pub fn queue_view_tonemapping_pipelines(
     pipeline_cache: Res<PipelineCache>,
     mut pipelines: ResMut<SpecializedRenderPipelines<TonemappingPipeline>>,
     upscaling_pipeline: Res<TonemappingPipeline>,
-    view_targets: Query<(Entity, Option<&Tonemapping>, Option<&Dither>), With<ViewTarget>>,
+    view_targets: Query<(Entity, Option<&Tonemapping>, Option<&DebandDither>), With<ViewTarget>>,
 ) {
     for (entity, tonemapping, dither) in view_targets.iter() {
         let key = TonemappingPipelineKey {
-            deband_dither: *dither.unwrap_or(&Dither::Disabled),
+            deband_dither: *dither.unwrap_or(&DebandDither::Disabled),
             tonemapping: *tonemapping.unwrap_or(&Tonemapping::None),
         };
         let pipeline = pipelines.specialize(&pipeline_cache, &upscaling_pipeline, key);
@@ -241,7 +286,7 @@ pub fn queue_view_tonemapping_pipelines(
             .insert(ViewTonemappingPipeline(pipeline));
     }
 }
-
+/// Enables a debanding shader that applies dithering to mitigate color banding in the final image for a given [`Camera`] entity.
 #[derive(
     Component,
     Debug,
@@ -257,7 +302,7 @@ pub fn queue_view_tonemapping_pipelines(
 )]
 #[extract_component_filter(With<Camera>)]
 #[reflect(Component)]
-pub enum Dither {
+pub enum DebandDither {
     #[default]
     Disabled,
     Enabled,
@@ -274,7 +319,7 @@ pub fn get_lut_bindings<'a>(
         Tonemapping::None
         | Tonemapping::Reinhard
         | Tonemapping::ReinhardLuminance
-        | Tonemapping::Aces
+        | Tonemapping::AcesFitted
         | Tonemapping::AgX
         | Tonemapping::SomewhatBoringDisplayTransform => &tonemapping_luts.agx,
         Tonemapping::TonyMcMapface => &tonemapping_luts.tony_mc_mapface,
@@ -314,6 +359,8 @@ pub fn get_lut_bind_group_layout_entries(bindings: [u32; 2]) -> [BindGroupLayout
     ]
 }
 
+// allow(dead_code) so it doesn't complain when the tonemapping_luts feature is disabled
+#[allow(dead_code)]
 fn setup_tonemapping_lut_image(bytes: &[u8], image_type: ImageType) -> Image {
     let mut image =
         Image::from_buffer(bytes, image_type, CompressedImageFormats::NONE, false).unwrap();
@@ -331,3 +378,27 @@ fn setup_tonemapping_lut_image(bytes: &[u8], image_type: ImageType) -> Image {
 
     image
 }
+
+pub fn lut_placeholder() -> Image {
+    let format = TextureFormat::Rgba8Unorm;
+    let data = vec![255, 0, 255, 255];
+    Image {
+        data,
+        texture_descriptor: TextureDescriptor {
+            size: Extent3d {
+                width: 1,
+                height: 1,
+                depth_or_array_layers: 1,
+            },
+            format,
+            dimension: TextureDimension::D3,
+            label: None,
+            mip_level_count: 1,
+            sample_count: 1,
+            usage: TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST,
+            view_formats: &[],
+        },
+        sampler_descriptor: ImageSampler::Default,
+        texture_view_descriptor: None,
+    }
+}