bevy_core_pipeline/tonemapping/
mod.rs

1use bevy_app::prelude::*;
2use bevy_asset::{
3    embedded_asset, load_embedded_asset, AssetServer, Assets, Handle, RenderAssetUsages,
4};
5use bevy_camera::Camera;
6use bevy_ecs::prelude::*;
7use bevy_image::{CompressedImageFormats, Image, ImageSampler, ImageType};
8#[cfg(not(feature = "tonemapping_luts"))]
9use bevy_log::error;
10use bevy_reflect::{std_traits::ReflectDefault, Reflect};
11use bevy_render::{
12    extract_component::{ExtractComponent, ExtractComponentPlugin},
13    extract_resource::{ExtractResource, ExtractResourcePlugin},
14    render_asset::RenderAssets,
15    render_resource::{
16        binding_types::{sampler, texture_2d, texture_3d, uniform_buffer},
17        *,
18    },
19    renderer::RenderDevice,
20    texture::{FallbackImage, GpuImage},
21    view::{ExtractedView, ViewTarget, ViewUniform},
22    GpuResourceAppExt, Render, RenderApp, RenderStartup, RenderSystems,
23};
24use bevy_shader::{load_shader_library, Shader, ShaderDefVal};
25use bitflags::bitflags;
26
27mod node;
28
29use bevy_utils::default;
30pub use node::tonemapping;
31
32use crate::FullscreenShader;
33
34/// 3D LUT (look up table) textures used for tonemapping
35#[derive(Resource, Clone, ExtractResource)]
36pub struct TonemappingLuts {
37    pub blender_filmic: Handle<Image>,
38    pub agx: Handle<Image>,
39    pub tony_mc_mapface: Handle<Image>,
40}
41
42pub struct TonemappingPlugin;
43
44impl Plugin for TonemappingPlugin {
45    fn build(&self, app: &mut App) {
46        load_shader_library!(app, "tonemapping_shared.wgsl");
47        load_shader_library!(app, "lut_bindings.wgsl");
48
49        embedded_asset!(app, "tonemapping.wgsl");
50
51        if !app.world().is_resource_added::<TonemappingLuts>() {
52            let mut images = app.world_mut().resource_mut::<Assets<Image>>();
53
54            #[cfg(feature = "tonemapping_luts")]
55            let tonemapping_luts = {
56                TonemappingLuts {
57                    blender_filmic: images.add(setup_tonemapping_lut_image(
58                        include_bytes!("luts/Blender_-11_12.ktx2"),
59                        ImageType::Extension("ktx2"),
60                    )),
61                    agx: images.add(setup_tonemapping_lut_image(
62                        include_bytes!("luts/AgX-default_contrast.ktx2"),
63                        ImageType::Extension("ktx2"),
64                    )),
65                    tony_mc_mapface: images.add(setup_tonemapping_lut_image(
66                        include_bytes!("luts/tony_mc_mapface.ktx2"),
67                        ImageType::Extension("ktx2"),
68                    )),
69                }
70            };
71
72            #[cfg(not(feature = "tonemapping_luts"))]
73            let tonemapping_luts = {
74                let placeholder = images.add(lut_placeholder());
75                TonemappingLuts {
76                    blender_filmic: placeholder.clone(),
77                    agx: placeholder.clone(),
78                    tony_mc_mapface: placeholder,
79                }
80            };
81
82            app.insert_resource(tonemapping_luts);
83        }
84
85        app.add_plugins(ExtractResourcePlugin::<TonemappingLuts>::default());
86
87        app.add_plugins((
88            ExtractComponentPlugin::<Tonemapping>::default(),
89            ExtractComponentPlugin::<DebandDither>::default(),
90        ));
91
92        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
93            return;
94        };
95        render_app
96            .init_gpu_resource::<SpecializedRenderPipelines<TonemappingPipeline>>()
97            .add_systems(RenderStartup, init_tonemapping_pipeline)
98            .add_systems(
99                Render,
100                prepare_view_tonemapping_pipelines.in_set(RenderSystems::Prepare),
101            );
102    }
103}
104
105#[derive(Resource)]
106pub struct TonemappingPipeline {
107    texture_bind_group: BindGroupLayoutDescriptor,
108    sampler: Sampler,
109    fullscreen_shader: FullscreenShader,
110    fragment_shader: Handle<Shader>,
111}
112
113/// Optionally enables a tonemapping shader that attempts to map linear input stimulus into a perceptually uniform image for a given [`Camera`] entity.
114#[derive(
115    Component, Debug, Hash, Clone, Copy, Reflect, Default, ExtractComponent, PartialEq, Eq,
116)]
117#[extract_component_filter(With<Camera>)]
118#[reflect(Component, Debug, Hash, Default, PartialEq)]
119pub enum Tonemapping {
120    /// Bypass tonemapping.
121    None,
122    /// Suffers from lots hue shifting, brights don't desaturate naturally.
123    /// Bright primaries and secondaries don't desaturate at all.
124    Reinhard,
125    /// Suffers from hue shifting. Brights don't desaturate much at all across the spectrum.
126    ReinhardLuminance,
127    /// Same base implementation that Godot 4.0 uses for Tonemap ACES.
128    /// <https://github.com/TheRealMJP/BakingLab/blob/master/BakingLab/ACES.hlsl>
129    /// Not neutral, has a very specific aesthetic, intentional and dramatic hue shifting.
130    /// Bright greens and reds turn orange. Bright blues turn magenta.
131    /// Significantly increased contrast. Brights desaturate across the spectrum.
132    AcesFitted,
133    /// By Troy Sobotka
134    /// <https://github.com/sobotka/AgX>
135    /// Very neutral. Image is somewhat desaturated when compared to other tonemappers.
136    /// Little to no hue shifting. Subtle [Abney shifting](https://en.wikipedia.org/wiki/Abney_effect).
137    /// NOTE: Requires the `tonemapping_luts` cargo feature.
138    AgX,
139    /// By Tomasz Stachowiak
140    /// Has little hue shifting in the darks and mids, but lots in the brights. Brights desaturate across the spectrum.
141    /// Is sort of between Reinhard and `ReinhardLuminance`. Conceptually similar to reinhard-jodie.
142    /// Designed as a compromise if you want e.g. decent skin tones in low light, but can't afford to re-do your
143    /// VFX to look good without hue shifting.
144    SomewhatBoringDisplayTransform,
145    /// Current Bevy default.
146    /// By Tomasz Stachowiak
147    /// <https://github.com/h3r2tic/tony-mc-mapface>
148    /// Very neutral. Subtle but intentional hue shifting. Brights desaturate across the spectrum.
149    /// Comment from author:
150    /// Tony is a display transform intended for real-time applications such as games.
151    /// It is intentionally boring, does not increase contrast or saturation, and stays close to the
152    /// input stimulus where compression isn't necessary.
153    /// Brightness-equivalent luminance of the input stimulus is compressed. The non-linearity resembles Reinhard.
154    /// Color hues are preserved during compression, except for a deliberate [Bezold–Brücke shift](https://en.wikipedia.org/wiki/Bezold%E2%80%93Br%C3%BCcke_shift).
155    /// To avoid posterization, selective desaturation is employed, with care to avoid the [Abney effect](https://en.wikipedia.org/wiki/Abney_effect).
156    /// NOTE: Requires the `tonemapping_luts` cargo feature.
157    #[default]
158    TonyMcMapface,
159    /// Default Filmic Display Transform from blender.
160    /// Somewhat neutral. Suffers from hue shifting. Brights desaturate across the spectrum.
161    /// NOTE: Requires the `tonemapping_luts` cargo feature.
162    BlenderFilmic,
163    /// Despite its name, it is not considered to be neutral.
164    /// Highly saturated colors and tends to produce a very high contrast image.
165    /// Suffers from significant [Abney shifting](https://en.wikipedia.org/wiki/Abney_effect), and tends to crush grays and desaturated colors.
166    /// Designed for e-commerce to faithfully reproduce the colors of brand's logos when used with low brightness grayscale lighting.
167    /// See [the KhronosGroup spec](https://github.com/KhronosGroup/ToneMapping/tree/main/PBR_Neutral) for more information.
168    KhronosPbrNeutral,
169}
170
171impl Tonemapping {
172    pub fn is_enabled(&self) -> bool {
173        *self != Tonemapping::None
174    }
175}
176
177bitflags! {
178    /// Various flags describing what tonemapping needs to do.
179    ///
180    /// This allows the shader to skip unneeded steps.
181    #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
182    pub struct TonemappingPipelineKeyFlags: u8 {
183        /// The hue needs to be changed.
184        const HUE_ROTATE                = 0x01;
185        /// The white balance needs to be adjusted.
186        const WHITE_BALANCE             = 0x02;
187        /// Saturation/contrast/gamma/gain/lift for one or more sections
188        /// (shadows, midtones, highlights) need to be adjusted.
189        const SECTIONAL_COLOR_GRADING   = 0x04;
190    }
191}
192
193#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
194pub struct TonemappingPipelineKey {
195    target_format: TextureFormat,
196    deband_dither: DebandDither,
197    tonemapping: Tonemapping,
198    flags: TonemappingPipelineKeyFlags,
199}
200
201impl SpecializedRenderPipeline for TonemappingPipeline {
202    type Key = TonemappingPipelineKey;
203
204    fn specialize(&self, key: Self::Key) -> RenderPipelineDescriptor {
205        let mut shader_defs = Vec::new();
206
207        shader_defs.push(ShaderDefVal::UInt(
208            "TONEMAPPING_LUT_TEXTURE_BINDING_INDEX".into(),
209            3,
210        ));
211        shader_defs.push(ShaderDefVal::UInt(
212            "TONEMAPPING_LUT_SAMPLER_BINDING_INDEX".into(),
213            4,
214        ));
215
216        if let DebandDither::Enabled = key.deband_dither {
217            shader_defs.push("DEBAND_DITHER".into());
218        }
219
220        // Define shader flags depending on the color grading options in use.
221        if key.flags.contains(TonemappingPipelineKeyFlags::HUE_ROTATE) {
222            shader_defs.push("HUE_ROTATE".into());
223        }
224        if key
225            .flags
226            .contains(TonemappingPipelineKeyFlags::WHITE_BALANCE)
227        {
228            shader_defs.push("WHITE_BALANCE".into());
229        }
230        if key
231            .flags
232            .contains(TonemappingPipelineKeyFlags::SECTIONAL_COLOR_GRADING)
233        {
234            shader_defs.push("SECTIONAL_COLOR_GRADING".into());
235        }
236
237        match key.tonemapping {
238            Tonemapping::None => shader_defs.push("TONEMAP_METHOD_NONE".into()),
239            Tonemapping::Reinhard => shader_defs.push("TONEMAP_METHOD_REINHARD".into()),
240            Tonemapping::ReinhardLuminance => {
241                shader_defs.push("TONEMAP_METHOD_REINHARD_LUMINANCE".into());
242            }
243            Tonemapping::AcesFitted => shader_defs.push("TONEMAP_METHOD_ACES_FITTED".into()),
244            Tonemapping::AgX => {
245                #[cfg(not(feature = "tonemapping_luts"))]
246                error!(
247                    "AgX tonemapping requires the `tonemapping_luts` feature.
248                    Either enable the `tonemapping_luts` feature for bevy in `Cargo.toml` (recommended),
249                    or use a different `Tonemapping` method for your `Camera2d`/`Camera3d`."
250                );
251                shader_defs.push("TONEMAP_METHOD_AGX".into());
252            }
253            Tonemapping::SomewhatBoringDisplayTransform => {
254                shader_defs.push("TONEMAP_METHOD_SOMEWHAT_BORING_DISPLAY_TRANSFORM".into());
255            }
256            Tonemapping::TonyMcMapface => {
257                #[cfg(not(feature = "tonemapping_luts"))]
258                error!(
259                    "TonyMcMapFace tonemapping requires the `tonemapping_luts` feature.
260                    Either enable the `tonemapping_luts` feature for bevy in `Cargo.toml` (recommended),
261                    or use a different `Tonemapping` method for your `Camera2d`/`Camera3d`."
262                );
263                shader_defs.push("TONEMAP_METHOD_TONY_MC_MAPFACE".into());
264            }
265            Tonemapping::BlenderFilmic => {
266                #[cfg(not(feature = "tonemapping_luts"))]
267                error!(
268                    "BlenderFilmic tonemapping requires the `tonemapping_luts` feature.
269                    Either enable the `tonemapping_luts` feature for bevy in `Cargo.toml` (recommended),
270                    or use a different `Tonemapping` method for your `Camera2d`/`Camera3d`."
271                );
272                shader_defs.push("TONEMAP_METHOD_BLENDER_FILMIC".into());
273            }
274            Tonemapping::KhronosPbrNeutral => shader_defs.push("TONEMAP_METHOD_PBR_NEUTRAL".into()),
275        }
276        RenderPipelineDescriptor {
277            label: Some("tonemapping pipeline".into()),
278            layout: vec![self.texture_bind_group.clone()],
279            vertex: self.fullscreen_shader.to_vertex_state(),
280            fragment: Some(FragmentState {
281                shader: self.fragment_shader.clone(),
282                shader_defs,
283                targets: vec![Some(ColorTargetState {
284                    format: key.target_format,
285                    blend: None,
286                    write_mask: ColorWrites::ALL,
287                })],
288                ..default()
289            }),
290            ..default()
291        }
292    }
293}
294
295pub fn init_tonemapping_pipeline(
296    mut commands: Commands,
297    render_device: Res<RenderDevice>,
298    fullscreen_shader: Res<FullscreenShader>,
299    asset_server: Res<AssetServer>,
300) {
301    let mut entries = DynamicBindGroupLayoutEntries::new_with_indices(
302        ShaderStages::FRAGMENT,
303        (
304            (0, uniform_buffer::<ViewUniform>(true)),
305            (
306                1,
307                texture_2d(TextureSampleType::Float { filterable: false }),
308            ),
309            (2, sampler(SamplerBindingType::NonFiltering)),
310        ),
311    );
312    let lut_layout_entries = get_lut_bind_group_layout_entries();
313    entries = entries.extend_with_indices(((3, lut_layout_entries[0]), (4, lut_layout_entries[1])));
314
315    let tonemap_texture_bind_group =
316        BindGroupLayoutDescriptor::new("tonemapping_hdr_texture_bind_group_layout", &entries);
317
318    let sampler = render_device.create_sampler(&SamplerDescriptor::default());
319
320    commands.insert_resource(TonemappingPipeline {
321        texture_bind_group: tonemap_texture_bind_group,
322        sampler,
323        fullscreen_shader: fullscreen_shader.clone(),
324        fragment_shader: load_embedded_asset!(asset_server.as_ref(), "tonemapping.wgsl"),
325    });
326}
327
328#[derive(Component)]
329pub struct ViewTonemappingPipeline(CachedRenderPipelineId);
330
331pub fn prepare_view_tonemapping_pipelines(
332    mut commands: Commands,
333    pipeline_cache: Res<PipelineCache>,
334    mut pipelines: ResMut<SpecializedRenderPipelines<TonemappingPipeline>>,
335    upscaling_pipeline: Res<TonemappingPipeline>,
336    view_targets: Query<
337        (
338            Entity,
339            &ExtractedView,
340            Option<&Tonemapping>,
341            Option<&DebandDither>,
342        ),
343        With<ViewTarget>,
344    >,
345) {
346    for (entity, view, tonemapping, dither) in view_targets.iter() {
347        // As an optimization, we omit parts of the shader that are unneeded.
348        let mut flags = TonemappingPipelineKeyFlags::empty();
349        flags.set(
350            TonemappingPipelineKeyFlags::HUE_ROTATE,
351            view.color_grading.global.hue != 0.0,
352        );
353        flags.set(
354            TonemappingPipelineKeyFlags::WHITE_BALANCE,
355            view.color_grading.global.temperature != 0.0 || view.color_grading.global.tint != 0.0,
356        );
357        flags.set(
358            TonemappingPipelineKeyFlags::SECTIONAL_COLOR_GRADING,
359            view.color_grading
360                .all_sections()
361                .any(|section| *section != default()),
362        );
363
364        let key = TonemappingPipelineKey {
365            target_format: view.target_format,
366            deband_dither: *dither.unwrap_or(&DebandDither::Disabled),
367            tonemapping: *tonemapping.unwrap_or(&Tonemapping::None),
368            flags,
369        };
370        let pipeline = pipelines.specialize(&pipeline_cache, &upscaling_pipeline, key);
371
372        commands
373            .entity(entity)
374            .insert(ViewTonemappingPipeline(pipeline));
375    }
376}
377/// Enables a debanding shader that applies dithering to mitigate color banding in the final image for a given [`Camera`] entity.
378#[derive(
379    Component, Debug, Hash, Clone, Copy, Reflect, Default, ExtractComponent, PartialEq, Eq,
380)]
381#[extract_component_filter(With<Camera>)]
382#[reflect(Component, Debug, Hash, Default, PartialEq)]
383pub enum DebandDither {
384    #[default]
385    Disabled,
386    Enabled,
387}
388
389pub fn get_lut_bindings<'a>(
390    images: &'a RenderAssets<GpuImage>,
391    tonemapping_luts: &'a TonemappingLuts,
392    tonemapping: &Tonemapping,
393    fallback_image: &'a FallbackImage,
394) -> (&'a TextureView, &'a Sampler) {
395    let image = match tonemapping {
396        // AgX lut texture used when tonemapping doesn't need a texture since it's very small (32x32x32)
397        Tonemapping::None
398        | Tonemapping::Reinhard
399        | Tonemapping::ReinhardLuminance
400        | Tonemapping::AcesFitted
401        | Tonemapping::AgX
402        | Tonemapping::KhronosPbrNeutral
403        | Tonemapping::SomewhatBoringDisplayTransform => &tonemapping_luts.agx,
404        Tonemapping::TonyMcMapface => &tonemapping_luts.tony_mc_mapface,
405        Tonemapping::BlenderFilmic => &tonemapping_luts.blender_filmic,
406    };
407    let lut_image = images.get(image).unwrap_or(&fallback_image.d3);
408    (&lut_image.texture_view, &lut_image.sampler)
409}
410
411pub fn get_lut_bind_group_layout_entries() -> [BindGroupLayoutEntryBuilder; 2] {
412    [
413        texture_3d(TextureSampleType::Float { filterable: true }),
414        sampler(SamplerBindingType::Filtering),
415    ]
416}
417
418#[expect(clippy::allow_attributes, reason = "`dead_code` is not always linted.")]
419#[allow(
420    dead_code,
421    reason = "There is unused code when the `tonemapping_luts` feature is disabled."
422)]
423fn setup_tonemapping_lut_image(bytes: &[u8], image_type: ImageType) -> Image {
424    let image_sampler = ImageSampler::Descriptor(bevy_image::ImageSamplerDescriptor {
425        label: Some("Tonemapping LUT sampler".to_string()),
426        address_mode_u: bevy_image::ImageAddressMode::ClampToEdge,
427        address_mode_v: bevy_image::ImageAddressMode::ClampToEdge,
428        address_mode_w: bevy_image::ImageAddressMode::ClampToEdge,
429        mag_filter: bevy_image::ImageFilterMode::Linear,
430        min_filter: bevy_image::ImageFilterMode::Linear,
431        mipmap_filter: bevy_image::ImageFilterMode::Linear,
432        ..default()
433    });
434    Image::from_buffer(
435        bytes,
436        image_type,
437        CompressedImageFormats::NONE,
438        false,
439        image_sampler,
440        // LUT must be kept in main world for render recovery reasons
441        RenderAssetUsages::default(),
442    )
443    .unwrap()
444}
445
446pub fn lut_placeholder() -> Image {
447    let format = TextureFormat::Rgba8Unorm;
448    let data = vec![255, 0, 255, 255];
449    Image {
450        data: Some(data),
451        data_order: TextureDataOrder::default(),
452        texture_descriptor: TextureDescriptor {
453            size: Extent3d::default(),
454            format,
455            dimension: TextureDimension::D3,
456            label: None,
457            mip_level_count: 1,
458            sample_count: 1,
459            usage: TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST,
460            view_formats: &[],
461        },
462        sampler: ImageSampler::Default,
463        texture_view_descriptor: None,
464        asset_usage: RenderAssetUsages::RENDER_WORLD,
465        copy_on_resize: false,
466    }
467}
bevy_core_pipeline/tonemapping/mod.rs

bevy_core_pipeline/tonemapping/
mod.rs
