bevy_post_process/auto_exposure/
settings.rs

1use core::ops::RangeInclusive;
2
3use super::compensation_curve::AutoExposureCompensationCurve;
4use bevy_asset::Handle;
5use bevy_camera::Hdr;
6use bevy_ecs::{prelude::Component, reflect::ReflectComponent};
7use bevy_image::Image;
8use bevy_reflect::{std_traits::ReflectDefault, Reflect};
9use bevy_render::extract_component::ExtractComponent;
10use bevy_utils::default;
11
12/// Component that enables auto exposure for an HDR-enabled 2d or 3d camera.
13///
14/// Auto exposure adjusts the exposure of the camera automatically to
15/// simulate the human eye's ability to adapt to different lighting conditions.
16///
17/// Bevy's implementation builds a 64 bin histogram of the scene's luminance,
18/// and then adjusts the exposure so that the average brightness of the final
19/// render will be middle gray. Because it's using a histogram, some details can
20/// be selectively ignored or emphasized. Outliers like shadows and specular
21/// highlights can be ignored, and certain areas can be given more (or less)
22/// weight based on a mask.
23///
24/// # Usage Notes
25///
26/// **Auto Exposure requires compute shaders and is not compatible with WebGL2.**
27#[derive(Component, Clone, Reflect, ExtractComponent)]
28#[reflect(Component, Default, Clone)]
29#[require(Hdr)]
30pub struct AutoExposure {
31    /// The range of exposure values for the histogram.
32    ///
33    /// Pixel values below this range will be ignored, and pixel values above this range will be
34    /// clamped in the sense that they will count towards the highest bin in the histogram.
35    /// The default value is `-8.0..=8.0`.
36    pub range: RangeInclusive<f32>,
37
38    /// The portion of the histogram to consider when metering.
39    ///
40    /// By default, the darkest 10% and the brightest 10% of samples are ignored,
41    /// so the default value is `0.10..=0.90`.
42    pub filter: RangeInclusive<f32>,
43
44    /// The speed at which the exposure adapts from dark to bright scenes, in F-stops per second.
45    pub speed_brighten: f32,
46
47    /// The speed at which the exposure adapts from bright to dark scenes, in F-stops per second.
48    pub speed_darken: f32,
49
50    /// The distance in F-stops from the target exposure from where to transition from animating
51    /// in linear fashion to animating exponentially. This helps against jittering when the
52    /// target exposure keeps on changing slightly from frame to frame, while still maintaining
53    /// a relatively slow animation for big changes in scene brightness.
54    ///
55    /// ```text
56    /// ev
57    ///                       ➔●┐
58    /// |              ⬈         ├ exponential section
59    /// │        ⬈               ┘
60    /// │    ⬈                   ┐
61    /// │  ⬈                     ├ linear section
62    /// │⬈                       ┘
63    /// ●───────────────────────── time
64    /// ```
65    ///
66    /// The default value is 1.5.
67    pub exponential_transition_distance: f32,
68
69    /// The mask to apply when metering. The mask will cover the entire screen, where:
70    /// * `(0.0, 0.0)` is the top-left corner,
71    /// * `(1.0, 1.0)` is the bottom-right corner.
72    ///
73    /// Only the red channel of the texture is used.
74    /// The sample at the current screen position will be used to weight the contribution
75    /// of each pixel to the histogram:
76    /// * 0.0 means the pixel will not contribute to the histogram,
77    /// * 1.0 means the pixel will contribute fully to the histogram.
78    ///
79    /// The default value is a white image, so all pixels contribute equally.
80    ///
81    /// # Usage Notes
82    ///
83    /// The mask is quantized to 16 discrete levels because of limitations in the compute shader
84    /// implementation.
85    pub metering_mask: Handle<Image>,
86
87    /// Exposure compensation curve to apply after metering.
88    /// The default value is a flat line at 0.0.
89    /// For more information, see [`AutoExposureCompensationCurve`].
90    pub compensation_curve: Handle<AutoExposureCompensationCurve>,
91}
92
93impl Default for AutoExposure {
94    fn default() -> Self {
95        Self {
96            range: -8.0..=8.0,
97            filter: 0.10..=0.90,
98            speed_brighten: 3.0,
99            speed_darken: 1.0,
100            exponential_transition_distance: 1.5,
101            metering_mask: default(),
102            compensation_curve: default(),
103        }
104    }
105}
bevy_post_process/auto_exposure/settings.rs

bevy_post_process/auto_exposure/
settings.rs
