bevy_post_process/auto_exposure/
settings.rs

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

bevy_post_process/auto_exposure/
settings.rs
