bevy_pbr/fog.rs
1use bevy_camera::Camera;
2use bevy_color::{Color, ColorToComponents, LinearRgba};
3use bevy_ecs::prelude::*;
4use bevy_math::{ops, Vec3};
5use bevy_reflect::{std_traits::ReflectDefault, Reflect};
6use bevy_render::extract_component::ExtractComponent;
7
8use crate::ViewFogUniformOffset;
9
10/// Configures the “classic” computer graphics [distance fog](https://en.wikipedia.org/wiki/Distance_fog) effect,
11/// in which objects appear progressively more covered in atmospheric haze the further away they are from the camera.
12/// Affects meshes rendered via the PBR [`StandardMaterial`](crate::StandardMaterial).
13///
14/// ## Falloff
15///
16/// The rate at which fog intensity increases with distance is controlled by the falloff mode.
17/// Currently, the following fog falloff modes are supported:
18///
19/// - [`FogFalloff::Linear`]
20/// - [`FogFalloff::Exponential`]
21/// - [`FogFalloff::ExponentialSquared`]
22/// - [`FogFalloff::Atmospheric`]
23///
24/// ## Example
25///
26/// ```
27/// # use bevy_ecs::prelude::*;
28/// # use bevy_render::prelude::*;
29/// # use bevy_camera::prelude::*;
30/// # use bevy_pbr::prelude::*;
31/// # use bevy_color::Color;
32/// # fn system(mut commands: Commands) {
33/// commands.spawn((
34/// // Setup your camera as usual
35/// Camera3d::default(),
36/// // Add fog to the same entity
37/// DistanceFog {
38/// color: Color::WHITE,
39/// falloff: FogFalloff::Exponential { density: 1e-3 },
40/// ..Default::default()
41/// },
42/// ));
43/// # }
44/// # bevy_ecs::system::assert_is_system(system);
45/// ```
46///
47/// ## Material Override
48///
49/// Once enabled for a specific camera, the fog effect can also be disabled for individual
50/// [`StandardMaterial`](crate::StandardMaterial) instances via the `fog_enabled` flag.
51#[derive(Debug, Clone, Component, Reflect, ExtractComponent)]
52#[extract_component_filter(With<Camera>)]
53#[extract_component_sync_target((Self, ViewFogUniformOffset))]
54#[reflect(Component, Default, Debug, Clone)]
55pub struct DistanceFog {
56 /// The color of the fog effect.
57 ///
58 /// **Tip:** The alpha channel of the color can be used to “modulate” the fog effect without
59 /// changing the fog falloff mode or parameters.
60 pub color: Color,
61
62 /// Color used to modulate the influence of directional light colors on the
63 /// fog, where the view direction aligns with each directional light direction,
64 /// producing a “glow” or light dispersion effect. (e.g. around the sun)
65 ///
66 /// Use [`Color::NONE`] to disable the effect.
67 pub directional_light_color: Color,
68
69 /// The exponent applied to the directional light alignment calculation.
70 /// A higher value means a more concentrated “glow”.
71 pub directional_light_exponent: f32,
72
73 /// Determines which falloff mode to use, and its parameters.
74 pub falloff: FogFalloff,
75}
76
77/// Allows switching between different fog falloff modes, and configuring their parameters.
78///
79/// ## Convenience Methods
80///
81/// When using non-linear fog modes it can be hard to determine the right parameter values
82/// for a given scene.
83///
84/// For easier artistic control, instead of creating the enum variants directly, you can use the
85/// visibility-based convenience methods:
86///
87/// - For `FogFalloff::Exponential`:
88/// - [`FogFalloff::from_visibility()`]
89/// - [`FogFalloff::from_visibility_contrast()`]
90///
91/// - For `FogFalloff::ExponentialSquared`:
92/// - [`FogFalloff::from_visibility_squared()`]
93/// - [`FogFalloff::from_visibility_contrast_squared()`]
94///
95/// - For `FogFalloff::Atmospheric`:
96/// - [`FogFalloff::from_visibility_color()`]
97/// - [`FogFalloff::from_visibility_colors()`]
98/// - [`FogFalloff::from_visibility_contrast_color()`]
99/// - [`FogFalloff::from_visibility_contrast_colors()`]
100#[derive(Debug, Clone, Reflect)]
101#[reflect(Clone)]
102pub enum FogFalloff {
103 /// A linear fog falloff that grows in intensity between `start` and `end` distances.
104 ///
105 /// This falloff mode is simpler to control than other modes, however it can produce results that look “artificial”, depending on the scene.
106 ///
107 /// ## Formula
108 ///
109 /// The fog intensity for a given point in the scene is determined by the following formula:
110 ///
111 /// ```text
112 /// let fog_intensity = 1.0 - ((end - distance) / (end - start)).clamp(0.0, 1.0);
113 /// ```
114 ///
115 /// <svg width="370" height="212" viewBox="0 0 370 212" fill="none">
116 /// <title>Plot showing how linear fog falloff behaves for start and end values of 0.8 and 2.2, respectively.</title>
117 /// <path d="M331 151H42V49" stroke="currentColor" stroke-width="2"/>
118 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="136" y="173.864">1</tspan></text>
119 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="30" y="53.8636">1</tspan></text>
120 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="42" y="173.864">0</tspan></text>
121 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="232" y="173.864">2</tspan></text>
122 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="332" y="173.864">3</tspan></text>
123 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="161" y="190.864">distance</tspan></text>
124 /// <text font-family="sans-serif" transform="translate(10 132) rotate(-90)" fill="currentColor" style="white-space: pre" font-family="Inter" font-size="12" letter-spacing="0em"><tspan x="0" y="11.8636">fog intensity</tspan></text>
125 /// <path d="M43 150H117.227L263 48H331" stroke="#FF00E5"/>
126 /// <path d="M118 151V49" stroke="#FF00E5" stroke-dasharray="1 4"/>
127 /// <path d="M263 151V49" stroke="#FF00E5" stroke-dasharray="1 4"/>
128 /// <text font-family="sans-serif" fill="#FF00E5" style="white-space: pre" font-family="Inter" font-size="10" letter-spacing="0em"><tspan x="121" y="58.6364">start</tspan></text>
129 /// <text font-family="sans-serif" fill="#FF00E5" style="white-space: pre" font-family="Inter" font-size="10" letter-spacing="0em"><tspan x="267" y="58.6364">end</tspan></text>
130 /// </svg>
131 Linear {
132 /// Distance from the camera where fog is completely transparent, in world units.
133 start: f32,
134
135 /// Distance from the camera where fog is completely opaque, in world units.
136 end: f32,
137 },
138
139 /// An exponential fog falloff with a given `density`.
140 ///
141 /// Initially gains intensity quickly with distance, then more slowly. Typically produces more natural results than [`FogFalloff::Linear`],
142 /// but is a bit harder to control.
143 ///
144 /// To move the fog “further away”, use lower density values. To move it “closer” use higher density values.
145 ///
146 /// ## Tips
147 ///
148 /// - Use the [`FogFalloff::from_visibility()`] convenience method to create an exponential falloff with the proper
149 /// density for a desired visibility distance in world units;
150 /// - It's not _unusual_ to have very large or very small values for the density, depending on the scene
151 /// scale. Typically, for scenes with objects in the scale of thousands of units, you might want density values
152 /// in the ballpark of `0.001`. Conversely, for really small scale scenes you might want really high values of
153 /// density;
154 /// - Combine the `density` parameter with the [`DistanceFog`] `color`'s alpha channel for easier artistic control.
155 ///
156 /// ## Formula
157 ///
158 /// The fog intensity for a given point in the scene is determined by the following formula:
159 ///
160 /// ```text
161 /// let fog_intensity = 1.0 - 1.0 / (distance * density).exp();
162 /// ```
163 ///
164 /// <svg width="370" height="212" viewBox="0 0 370 212" fill="none">
165 /// <title>Plot showing how exponential fog falloff behaves for different density values</title>
166 /// <mask id="mask0_3_31" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="42" y="42" width="286" height="108">
167 /// <rect x="42" y="42" width="286" height="108" fill="#D9D9D9"/>
168 /// </mask>
169 /// <g mask="url(#mask0_3_31)">
170 /// <path d="M42 150C42 150 98.3894 53 254.825 53L662 53" stroke="#FF003D" stroke-width="1"/>
171 /// <path d="M42 150C42 150 139.499 53 409.981 53L1114 53" stroke="#001AFF" stroke-width="1"/>
172 /// <path d="M42 150C42 150 206.348 53 662.281 53L1849 53" stroke="#14FF00" stroke-width="1"/>
173 /// </g>
174 /// <path d="M331 151H42V49" stroke="currentColor" stroke-width="2"/>
175 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="136" y="173.864">1</tspan></text>
176 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="30" y="53.8636">1</tspan></text>
177 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="42" y="173.864">0</tspan></text>
178 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="232" y="173.864">2</tspan></text>
179 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="332" y="173.864">3</tspan></text>
180 /// <text font-family="sans-serif" fill="#FF003D" style="white-space: pre" font-size="10" letter-spacing="0em"><tspan x="77" y="64.6364">density = 2</tspan></text>
181 /// <text font-family="sans-serif" fill="#001AFF" style="white-space: pre" font-size="10" letter-spacing="0em"><tspan x="236" y="76.6364">density = 1</tspan></text>
182 /// <text font-family="sans-serif" fill="#14FF00" style="white-space: pre" font-size="10" letter-spacing="0em"><tspan x="205" y="115.636">density = 0.5</tspan></text>
183 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="161" y="190.864">distance</tspan></text>
184 /// <text font-family="sans-serif" transform="translate(10 132) rotate(-90)" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="0" y="11.8636">fog intensity</tspan></text>
185 /// </svg>
186 Exponential {
187 /// Multiplier applied to the world distance (within the exponential fog falloff calculation).
188 density: f32,
189 },
190
191 /// A squared exponential fog falloff with a given `density`.
192 ///
193 /// Similar to [`FogFalloff::Exponential`], but grows more slowly in intensity for closer distances
194 /// before “catching up”.
195 ///
196 /// To move the fog “further away”, use lower density values. To move it “closer” use higher density values.
197 ///
198 /// ## Tips
199 ///
200 /// - Use the [`FogFalloff::from_visibility_squared()`] convenience method to create an exponential squared falloff
201 /// with the proper density for a desired visibility distance in world units;
202 /// - Combine the `density` parameter with the [`DistanceFog`] `color`'s alpha channel for easier artistic control.
203 ///
204 /// ## Formula
205 ///
206 /// The fog intensity for a given point in the scene is determined by the following formula:
207 ///
208 /// ```text
209 /// let fog_intensity = 1.0 - 1.0 / (distance * density).squared().exp();
210 /// ```
211 ///
212 /// <svg width="370" height="212" viewBox="0 0 370 212" fill="none">
213 /// <title>Plot showing how exponential squared fog falloff behaves for different density values</title>
214 /// <mask id="mask0_1_3" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="42" y="42" width="286" height="108">
215 /// <rect x="42" y="42" width="286" height="108" fill="#D9D9D9"/>
216 /// </mask>
217 /// <g mask="url(#mask0_1_3)">
218 /// <path d="M42 150C75.4552 150 74.9241 53.1724 166.262 53.1724L404 53.1724" stroke="#FF003D" stroke-width="1"/>
219 /// <path d="M42 150C107.986 150 106.939 53.1724 287.091 53.1724L756 53.1724" stroke="#001AFF" stroke-width="1"/>
220 /// <path d="M42 150C166.394 150 164.42 53.1724 504.035 53.1724L1388 53.1724" stroke="#14FF00" stroke-width="1"/>
221 /// </g>
222 /// <path d="M331 151H42V49" stroke="currentColor" stroke-width="2"/>
223 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="136" y="173.864">1</tspan></text>
224 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="30" y="53.8636">1</tspan></text>
225 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="42" y="173.864">0</tspan></text>
226 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="232" y="173.864">2</tspan></text>
227 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="332" y="173.864">3</tspan></text>
228 /// <text font-family="sans-serif" fill="#FF003D" style="white-space: pre" font-size="10" letter-spacing="0em"><tspan x="61" y="54.6364">density = 2</tspan></text>
229 /// <text font-family="sans-serif" fill="#001AFF" style="white-space: pre" font-size="10" letter-spacing="0em"><tspan x="168" y="84.6364">density = 1</tspan></text>
230 /// <text font-family="sans-serif" fill="#14FF00" style="white-space: pre" font-size="10" letter-spacing="0em"><tspan x="174" y="121.636">density = 0.5</tspan></text>
231 /// <text font-family="sans-serif" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="161" y="190.864">distance</tspan></text>
232 /// <text font-family="sans-serif" transform="translate(10 132) rotate(-90)" fill="currentColor" style="white-space: pre" font-size="12" letter-spacing="0em"><tspan x="0" y="11.8636">fog intensity</tspan></text>
233 /// </svg>
234 ExponentialSquared {
235 /// Multiplier applied to the world distance (within the exponential squared fog falloff calculation).
236 density: f32,
237 },
238
239 /// A more general form of the [`FogFalloff::Exponential`] mode. The falloff formula is separated into
240 /// two terms, `extinction` and `inscattering`, for a somewhat simplified atmospheric scattering model.
241 /// Additionally, individual color channels can have their own density values, resulting in a total of
242 /// six different configuration parameters.
243 ///
244 /// ## Tips
245 ///
246 /// - Use the [`FogFalloff::from_visibility_colors()`] or [`FogFalloff::from_visibility_color()`] convenience methods
247 /// to create an atmospheric falloff with the proper densities for a desired visibility distance in world units and
248 /// extinction and inscattering colors;
249 /// - Combine the atmospheric fog parameters with the [`DistanceFog`] `color`'s alpha channel for easier artistic control.
250 ///
251 /// ## Formula
252 ///
253 /// Unlike other modes, atmospheric falloff doesn't use a simple intensity-based blend of fog color with
254 /// object color. Instead, it calculates per-channel extinction and inscattering factors, which are
255 /// then used to calculate the final color.
256 ///
257 /// ```text
258 /// let extinction_factor = 1.0 - 1.0 / (distance * extinction).exp();
259 /// let inscattering_factor = 1.0 - 1.0 / (distance * inscattering).exp();
260 /// let result = input_color * (1.0 - extinction_factor) + fog_color * inscattering_factor;
261 /// ```
262 ///
263 /// ## Equivalence to [`FogFalloff::Exponential`]
264 ///
265 /// For a density value of `D`, the following two falloff modes will produce identical visual results:
266 ///
267 /// ```
268 /// # use bevy_pbr::prelude::*;
269 /// # use bevy_math::prelude::*;
270 /// # const D: f32 = 0.5;
271 /// #
272 /// let exponential = FogFalloff::Exponential {
273 /// density: D,
274 /// };
275 ///
276 /// let atmospheric = FogFalloff::Atmospheric {
277 /// extinction: Vec3::new(D, D, D),
278 /// inscattering: Vec3::new(D, D, D),
279 /// };
280 /// ```
281 ///
282 /// **Note:** While the results are identical, [`FogFalloff::Atmospheric`] is computationally more expensive.
283 Atmospheric {
284 /// Controls how much light is removed due to atmospheric “extinction”, i.e. loss of light due to
285 /// photons being absorbed by atmospheric particles.
286 ///
287 /// Each component can be thought of as an independent per `R`/`G`/`B` channel `density` factor from
288 /// [`FogFalloff::Exponential`]: Multiplier applied to the world distance (within the fog
289 /// falloff calculation) for that specific channel.
290 ///
291 /// **Note:**
292 /// This value is not a `Color`, since it affects the channels exponentially in a non-intuitive way.
293 /// For artistic control, use the [`FogFalloff::from_visibility_colors()`] convenience method.
294 extinction: Vec3,
295
296 /// Controls how much light is added due to light scattering from the sun through the atmosphere.
297 ///
298 /// Each component can be thought of as an independent per `R`/`G`/`B` channel `density` factor from
299 /// [`FogFalloff::Exponential`]: A multiplier applied to the world distance (within the fog
300 /// falloff calculation) for that specific channel.
301 ///
302 /// **Note:**
303 /// This value is not a `Color`, since it affects the channels exponentially in a non-intuitive way.
304 /// For artistic control, use the [`FogFalloff::from_visibility_colors()`] convenience method.
305 inscattering: Vec3,
306 },
307}
308
309impl FogFalloff {
310 /// Creates a [`FogFalloff::Exponential`] value from the given visibility distance in world units,
311 /// using the revised Koschmieder contrast threshold, [`FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD`].
312 pub fn from_visibility(visibility: f32) -> FogFalloff {
313 FogFalloff::from_visibility_contrast(
314 visibility,
315 FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD,
316 )
317 }
318
319 /// Creates a [`FogFalloff::Exponential`] value from the given visibility distance in world units,
320 /// and a given contrast threshold in the range of `0.0` to `1.0`.
321 pub fn from_visibility_contrast(visibility: f32, contrast_threshold: f32) -> FogFalloff {
322 FogFalloff::Exponential {
323 density: FogFalloff::koschmieder(visibility, contrast_threshold),
324 }
325 }
326
327 /// Creates a [`FogFalloff::ExponentialSquared`] value from the given visibility distance in world units,
328 /// using the revised Koschmieder contrast threshold, [`FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD`].
329 pub fn from_visibility_squared(visibility: f32) -> FogFalloff {
330 FogFalloff::from_visibility_contrast_squared(
331 visibility,
332 FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD,
333 )
334 }
335
336 /// Creates a [`FogFalloff::ExponentialSquared`] value from the given visibility distance in world units,
337 /// and a given contrast threshold in the range of `0.0` to `1.0`.
338 pub fn from_visibility_contrast_squared(
339 visibility: f32,
340 contrast_threshold: f32,
341 ) -> FogFalloff {
342 FogFalloff::ExponentialSquared {
343 density: (FogFalloff::koschmieder(visibility, contrast_threshold) / visibility).sqrt(),
344 }
345 }
346
347 /// Creates a [`FogFalloff::Atmospheric`] value from the given visibility distance in world units,
348 /// and a shared color for both extinction and inscattering, using the revised Koschmieder contrast threshold,
349 /// [`FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD`].
350 pub fn from_visibility_color(
351 visibility: f32,
352 extinction_inscattering_color: Color,
353 ) -> FogFalloff {
354 FogFalloff::from_visibility_contrast_colors(
355 visibility,
356 FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD,
357 extinction_inscattering_color,
358 extinction_inscattering_color,
359 )
360 }
361
362 /// Creates a [`FogFalloff::Atmospheric`] value from the given visibility distance in world units,
363 /// extinction and inscattering colors, using the revised Koschmieder contrast threshold,
364 /// [`FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD`].
365 ///
366 /// ## Tips
367 /// - Alpha values of the provided colors can modulate the `extinction` and `inscattering` effects;
368 /// - Using an `extinction_color` of [`Color::WHITE`] or [`Color::NONE`] disables the extinction effect;
369 /// - Using an `inscattering_color` of [`Color::BLACK`] or [`Color::NONE`] disables the inscattering effect.
370 pub fn from_visibility_colors(
371 visibility: f32,
372 extinction_color: Color,
373 inscattering_color: Color,
374 ) -> FogFalloff {
375 FogFalloff::from_visibility_contrast_colors(
376 visibility,
377 FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD,
378 extinction_color,
379 inscattering_color,
380 )
381 }
382
383 /// Creates a [`FogFalloff::Atmospheric`] value from the given visibility distance in world units,
384 /// a contrast threshold in the range of `0.0` to `1.0`, and a shared color for both extinction and inscattering.
385 pub fn from_visibility_contrast_color(
386 visibility: f32,
387 contrast_threshold: f32,
388 extinction_inscattering_color: Color,
389 ) -> FogFalloff {
390 FogFalloff::from_visibility_contrast_colors(
391 visibility,
392 contrast_threshold,
393 extinction_inscattering_color,
394 extinction_inscattering_color,
395 )
396 }
397
398 /// Creates a [`FogFalloff::Atmospheric`] value from the given visibility distance in world units,
399 /// a contrast threshold in the range of `0.0` to `1.0`, extinction and inscattering colors.
400 ///
401 /// ## Tips
402 /// - Alpha values of the provided colors can modulate the `extinction` and `inscattering` effects;
403 /// - Using an `extinction_color` of [`Color::WHITE`] or [`Color::NONE`] disables the extinction effect;
404 /// - Using an `inscattering_color` of [`Color::BLACK`] or [`Color::NONE`] disables the inscattering effect.
405 pub fn from_visibility_contrast_colors(
406 visibility: f32,
407 contrast_threshold: f32,
408 extinction_color: Color,
409 inscattering_color: Color,
410 ) -> FogFalloff {
411 use core::f32::consts::E;
412
413 let [r_e, g_e, b_e, a_e] = LinearRgba::from(extinction_color).to_f32_array();
414 let [r_i, g_i, b_i, a_i] = LinearRgba::from(inscattering_color).to_f32_array();
415
416 FogFalloff::Atmospheric {
417 extinction: Vec3::new(
418 // Values are subtracted from 1.0 here to preserve the intuitive/artistic meaning of
419 // colors, since they're later subtracted. (e.g. by giving a blue extinction color, you
420 // get blue and _not_ yellow results)
421 ops::powf(1.0 - r_e, E),
422 ops::powf(1.0 - g_e, E),
423 ops::powf(1.0 - b_e, E),
424 ) * FogFalloff::koschmieder(visibility, contrast_threshold)
425 * ops::powf(a_e, E),
426
427 inscattering: Vec3::new(ops::powf(r_i, E), ops::powf(g_i, E), ops::powf(b_i, E))
428 * FogFalloff::koschmieder(visibility, contrast_threshold)
429 * ops::powf(a_i, E),
430 }
431 }
432
433 /// A 2% contrast threshold was originally proposed by Koschmieder, being the
434 /// minimum visual contrast at which a human observer could detect an object.
435 /// We use a revised 5% contrast threshold, deemed more realistic for typical human observers.
436 pub const REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD: f32 = 0.05;
437
438 /// Calculates the extinction coefficient β, from V and Cₜ, where:
439 ///
440 /// - Cₜ is the contrast threshold, in the range of `0.0` to `1.0`
441 /// - V is the visibility distance in which a perfectly black object is still identifiable
442 /// against the horizon sky within the contrast threshold
443 ///
444 /// We start with Koschmieder's equation:
445 ///
446 /// ```text
447 /// -ln(Cₜ)
448 /// V = ─────────
449 /// β
450 /// ```
451 ///
452 /// Multiplying both sides by β/V, that gives us:
453 ///
454 /// ```text
455 /// -ln(Cₜ)
456 /// β = ─────────
457 /// V
458 /// ```
459 ///
460 /// See:
461 /// - <https://en.wikipedia.org/wiki/Visibility>
462 /// - <https://www.biral.com/wp-content/uploads/2015/02/Introduction_to_visibility-v2-2.pdf>
463 pub fn koschmieder(v: f32, c_t: f32) -> f32 {
464 -ops::ln(c_t) / v
465 }
466}
467
468impl Default for DistanceFog {
469 fn default() -> Self {
470 DistanceFog {
471 color: Color::WHITE,
472 falloff: FogFalloff::Linear {
473 start: 0.0,
474 end: 100.0,
475 },
476 directional_light_color: Color::NONE,
477 directional_light_exponent: 8.0,
478 }
479 }
480}