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};
8use bevy_reflect::{std_traits::ReflectDefault, Reflect};
9use bevy_render::{
10    extract_component::{ExtractComponent, ExtractComponentPlugin},
11    extract_resource::{ExtractResource, ExtractResourcePlugin},
12    render_asset::RenderAssets,
13    render_resource::{
14        binding_types::{sampler, texture_2d, texture_3d, uniform_buffer},
15        *,
16    },
17    renderer::RenderDevice,
18    texture::{FallbackImage, GpuImage},
19    view::{ExtractedView, ViewTarget, ViewUniform},
20    Render, RenderApp, RenderStartup, RenderSystems,
21};
22use bevy_shader::{load_shader_library, Shader, ShaderDefVal};
23use bitflags::bitflags;
24#[cfg(not(feature = "tonemapping_luts"))]
25use tracing::error;
26
27mod node;
28
29use bevy_utils::default;
30pub use node::TonemappingNode;
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_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: BindGroupLayout,
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}
164
165impl Tonemapping {
166    pub fn is_enabled(&self) -> bool {
167        *self != Tonemapping::None
168    }
169}
170
171bitflags! {
172    /// Various flags describing what tonemapping needs to do.
173    ///
174    /// This allows the shader to skip unneeded steps.
175    #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
176    pub struct TonemappingPipelineKeyFlags: u8 {
177        /// The hue needs to be changed.
178        const HUE_ROTATE                = 0x01;
179        /// The white balance needs to be adjusted.
180        const WHITE_BALANCE             = 0x02;
181        /// Saturation/contrast/gamma/gain/lift for one or more sections
182        /// (shadows, midtones, highlights) need to be adjusted.
183        const SECTIONAL_COLOR_GRADING   = 0x04;
184    }
185}
186
187#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
188pub struct TonemappingPipelineKey {
189    deband_dither: DebandDither,
190    tonemapping: Tonemapping,
191    flags: TonemappingPipelineKeyFlags,
192}
193
194impl SpecializedRenderPipeline for TonemappingPipeline {
195    type Key = TonemappingPipelineKey;
196
197    fn specialize(&self, key: Self::Key) -> RenderPipelineDescriptor {
198        let mut shader_defs = Vec::new();
199
200        shader_defs.push(ShaderDefVal::UInt(
201            "TONEMAPPING_LUT_TEXTURE_BINDING_INDEX".into(),
202            3,
203        ));
204        shader_defs.push(ShaderDefVal::UInt(
205            "TONEMAPPING_LUT_SAMPLER_BINDING_INDEX".into(),
206            4,
207        ));
208
209        if let DebandDither::Enabled = key.deband_dither {
210            shader_defs.push("DEBAND_DITHER".into());
211        }
212
213        // Define shader flags depending on the color grading options in use.
214        if key.flags.contains(TonemappingPipelineKeyFlags::HUE_ROTATE) {
215            shader_defs.push("HUE_ROTATE".into());
216        }
217        if key
218            .flags
219            .contains(TonemappingPipelineKeyFlags::WHITE_BALANCE)
220        {
221            shader_defs.push("WHITE_BALANCE".into());
222        }
223        if key
224            .flags
225            .contains(TonemappingPipelineKeyFlags::SECTIONAL_COLOR_GRADING)
226        {
227            shader_defs.push("SECTIONAL_COLOR_GRADING".into());
228        }
229
230        match key.tonemapping {
231            Tonemapping::None => shader_defs.push("TONEMAP_METHOD_NONE".into()),
232            Tonemapping::Reinhard => shader_defs.push("TONEMAP_METHOD_REINHARD".into()),
233            Tonemapping::ReinhardLuminance => {
234                shader_defs.push("TONEMAP_METHOD_REINHARD_LUMINANCE".into());
235            }
236            Tonemapping::AcesFitted => shader_defs.push("TONEMAP_METHOD_ACES_FITTED".into()),
237            Tonemapping::AgX => {
238                #[cfg(not(feature = "tonemapping_luts"))]
239                error!(
240                    "AgX tonemapping requires the `tonemapping_luts` feature.
241                    Either enable the `tonemapping_luts` feature for bevy in `Cargo.toml` (recommended),
242                    or use a different `Tonemapping` method for your `Camera2d`/`Camera3d`."
243                );
244                shader_defs.push("TONEMAP_METHOD_AGX".into());
245            }
246            Tonemapping::SomewhatBoringDisplayTransform => {
247                shader_defs.push("TONEMAP_METHOD_SOMEWHAT_BORING_DISPLAY_TRANSFORM".into());
248            }
249            Tonemapping::TonyMcMapface => {
250                #[cfg(not(feature = "tonemapping_luts"))]
251                error!(
252                    "TonyMcMapFace tonemapping requires the `tonemapping_luts` feature.
253                    Either enable the `tonemapping_luts` feature for bevy in `Cargo.toml` (recommended),
254                    or use a different `Tonemapping` method for your `Camera2d`/`Camera3d`."
255                );
256                shader_defs.push("TONEMAP_METHOD_TONY_MC_MAPFACE".into());
257            }
258            Tonemapping::BlenderFilmic => {
259                #[cfg(not(feature = "tonemapping_luts"))]
260                error!(
261                    "BlenderFilmic tonemapping requires the `tonemapping_luts` feature.
262                    Either enable the `tonemapping_luts` feature for bevy in `Cargo.toml` (recommended),
263                    or use a different `Tonemapping` method for your `Camera2d`/`Camera3d`."
264                );
265                shader_defs.push("TONEMAP_METHOD_BLENDER_FILMIC".into());
266            }
267        }
268        RenderPipelineDescriptor {
269            label: Some("tonemapping pipeline".into()),
270            layout: vec![self.texture_bind_group.clone()],
271            vertex: self.fullscreen_shader.to_vertex_state(),
272            fragment: Some(FragmentState {
273                shader: self.fragment_shader.clone(),
274                shader_defs,
275                targets: vec![Some(ColorTargetState {
276                    format: ViewTarget::TEXTURE_FORMAT_HDR,
277                    blend: None,
278                    write_mask: ColorWrites::ALL,
279                })],
280                ..default()
281            }),
282            ..default()
283        }
284    }
285}
286
287pub fn init_tonemapping_pipeline(
288    mut commands: Commands,
289    render_device: Res<RenderDevice>,
290    fullscreen_shader: Res<FullscreenShader>,
291    asset_server: Res<AssetServer>,
292) {
293    let mut entries = DynamicBindGroupLayoutEntries::new_with_indices(
294        ShaderStages::FRAGMENT,
295        (
296            (0, uniform_buffer::<ViewUniform>(true)),
297            (
298                1,
299                texture_2d(TextureSampleType::Float { filterable: false }),
300            ),
301            (2, sampler(SamplerBindingType::NonFiltering)),
302        ),
303    );
304    let lut_layout_entries = get_lut_bind_group_layout_entries();
305    entries = entries.extend_with_indices(((3, lut_layout_entries[0]), (4, lut_layout_entries[1])));
306
307    let tonemap_texture_bind_group = render_device
308        .create_bind_group_layout("tonemapping_hdr_texture_bind_group_layout", &entries);
309
310    let sampler = render_device.create_sampler(&SamplerDescriptor::default());
311
312    commands.insert_resource(TonemappingPipeline {
313        texture_bind_group: tonemap_texture_bind_group,
314        sampler,
315        fullscreen_shader: fullscreen_shader.clone(),
316        fragment_shader: load_embedded_asset!(asset_server.as_ref(), "tonemapping.wgsl"),
317    });
318}
319
320#[derive(Component)]
321pub struct ViewTonemappingPipeline(CachedRenderPipelineId);
322
323pub fn prepare_view_tonemapping_pipelines(
324    mut commands: Commands,
325    pipeline_cache: Res<PipelineCache>,
326    mut pipelines: ResMut<SpecializedRenderPipelines<TonemappingPipeline>>,
327    upscaling_pipeline: Res<TonemappingPipeline>,
328    view_targets: Query<
329        (
330            Entity,
331            &ExtractedView,
332            Option<&Tonemapping>,
333            Option<&DebandDither>,
334        ),
335        With<ViewTarget>,
336    >,
337) {
338    for (entity, view, tonemapping, dither) in view_targets.iter() {
339        // As an optimization, we omit parts of the shader that are unneeded.
340        let mut flags = TonemappingPipelineKeyFlags::empty();
341        flags.set(
342            TonemappingPipelineKeyFlags::HUE_ROTATE,
343            view.color_grading.global.hue != 0.0,
344        );
345        flags.set(
346            TonemappingPipelineKeyFlags::WHITE_BALANCE,
347            view.color_grading.global.temperature != 0.0 || view.color_grading.global.tint != 0.0,
348        );
349        flags.set(
350            TonemappingPipelineKeyFlags::SECTIONAL_COLOR_GRADING,
351            view.color_grading
352                .all_sections()
353                .any(|section| *section != default()),
354        );
355
356        let key = TonemappingPipelineKey {
357            deband_dither: *dither.unwrap_or(&DebandDither::Disabled),
358            tonemapping: *tonemapping.unwrap_or(&Tonemapping::None),
359            flags,
360        };
361        let pipeline = pipelines.specialize(&pipeline_cache, &upscaling_pipeline, key);
362
363        commands
364            .entity(entity)
365            .insert(ViewTonemappingPipeline(pipeline));
366    }
367}
368/// Enables a debanding shader that applies dithering to mitigate color banding in the final image for a given [`Camera`] entity.
369#[derive(
370    Component, Debug, Hash, Clone, Copy, Reflect, Default, ExtractComponent, PartialEq, Eq,
371)]
372#[extract_component_filter(With<Camera>)]
373#[reflect(Component, Debug, Hash, Default, PartialEq)]
374pub enum DebandDither {
375    #[default]
376    Disabled,
377    Enabled,
378}
379
380pub fn get_lut_bindings<'a>(
381    images: &'a RenderAssets<GpuImage>,
382    tonemapping_luts: &'a TonemappingLuts,
383    tonemapping: &Tonemapping,
384    fallback_image: &'a FallbackImage,
385) -> (&'a TextureView, &'a Sampler) {
386    let image = match tonemapping {
387        // AgX lut texture used when tonemapping doesn't need a texture since it's very small (32x32x32)
388        Tonemapping::None
389        | Tonemapping::Reinhard
390        | Tonemapping::ReinhardLuminance
391        | Tonemapping::AcesFitted
392        | Tonemapping::AgX
393        | Tonemapping::SomewhatBoringDisplayTransform => &tonemapping_luts.agx,
394        Tonemapping::TonyMcMapface => &tonemapping_luts.tony_mc_mapface,
395        Tonemapping::BlenderFilmic => &tonemapping_luts.blender_filmic,
396    };
397    let lut_image = images.get(image).unwrap_or(&fallback_image.d3);
398    (&lut_image.texture_view, &lut_image.sampler)
399}
400
401pub fn get_lut_bind_group_layout_entries() -> [BindGroupLayoutEntryBuilder; 2] {
402    [
403        texture_3d(TextureSampleType::Float { filterable: true }),
404        sampler(SamplerBindingType::Filtering),
405    ]
406}
407
408#[expect(clippy::allow_attributes, reason = "`dead_code` is not always linted.")]
409#[allow(
410    dead_code,
411    reason = "There is unused code when the `tonemapping_luts` feature is disabled."
412)]
413fn setup_tonemapping_lut_image(bytes: &[u8], image_type: ImageType) -> Image {
414    let image_sampler = ImageSampler::Descriptor(bevy_image::ImageSamplerDescriptor {
415        label: Some("Tonemapping LUT sampler".to_string()),
416        address_mode_u: bevy_image::ImageAddressMode::ClampToEdge,
417        address_mode_v: bevy_image::ImageAddressMode::ClampToEdge,
418        address_mode_w: bevy_image::ImageAddressMode::ClampToEdge,
419        mag_filter: bevy_image::ImageFilterMode::Linear,
420        min_filter: bevy_image::ImageFilterMode::Linear,
421        mipmap_filter: bevy_image::ImageFilterMode::Linear,
422        ..default()
423    });
424    Image::from_buffer(
425        bytes,
426        image_type,
427        CompressedImageFormats::NONE,
428        false,
429        image_sampler,
430        RenderAssetUsages::RENDER_WORLD,
431    )
432    .unwrap()
433}
434
435pub fn lut_placeholder() -> Image {
436    let format = TextureFormat::Rgba8Unorm;
437    let data = vec![255, 0, 255, 255];
438    Image {
439        data: Some(data),
440        data_order: TextureDataOrder::default(),
441        texture_descriptor: TextureDescriptor {
442            size: Extent3d::default(),
443            format,
444            dimension: TextureDimension::D3,
445            label: None,
446            mip_level_count: 1,
447            sample_count: 1,
448            usage: TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST,
449            view_formats: &[],
450        },
451        sampler: ImageSampler::Default,
452        texture_view_descriptor: None,
453        asset_usage: RenderAssetUsages::RENDER_WORLD,
454        copy_on_resize: false,
455    }
456}
bevy_core_pipeline/tonemapping/mod.rs

bevy_core_pipeline/tonemapping/
mod.rs
