Enum bevy::pbr::FogFalloff

pub enum FogFalloff {
    Linear {
        start: f32,
        end: f32,
    },
    Exponential {
        density: f32,
    },
    ExponentialSquared {
        density: f32,
    },
    Atmospheric {
        extinction: Vec3,
        inscattering: Vec3,
    },
}

Allows switching between different fog falloff modes, and configuring their parameters.

Convenience Methods

When using non-linear fog modes it can be hard to determine the right parameter values for a given scene.

For easier artistic control, instead of creating the enum variants directly, you can use the visibility-based convenience methods:

• For FogFalloff::Exponential:

  • FogFalloff::from_visibility()
  • FogFalloff::from_visibility_contrast()

• For FogFalloff::ExponentialSquared:

  • FogFalloff::from_visibility_squared()
  • FogFalloff::from_visibility_contrast_squared()

• For FogFalloff::Atmospheric:

  • FogFalloff::from_visibility_color()
  • FogFalloff::from_visibility_colors()
  • FogFalloff::from_visibility_contrast_color()
  • FogFalloff::from_visibility_contrast_colors()

Variants

Linear

Fields

start: f32

Distance from the camera where fog is completely transparent, in world units.

end: f32

Distance from the camera where fog is completely opaque, in world units.

A linear fog falloff that grows in intensity between start and end distances.

This falloff mode is simpler to control than other modes, however it can produce results that look “artificial”, depending on the scene.

Formula

The fog intensity for a given point in the scene is determined by the following formula:

let fog_intensity = 1.0 - ((end - distance) / (end - start)).clamp(0.0, 1.0);

Exponential

Fields

density: f32

Multiplier applied to the world distance (within the exponential fog falloff calculation).

An exponential fog falloff with a given density.

Initially gains intensity quickly with distance, then more slowly. Typically produces more natural results than FogFalloff::Linear, but is a bit harder to control.

To move the fog “further away”, use lower density values. To move it “closer” use higher density values.

Tips

• Use the FogFalloff::from_visibility() convenience method to create an exponential falloff with the proper density for a desired visibility distance in world units;
• It’s not unusual to have very large or very small values for the density, depending on the scene scale. Typically, for scenes with objects in the scale of thousands of units, you might want density values in the ballpark of 0.001. Conversely, for really small scale scenes you might want really high values of density;
• Combine the density parameter with the FogSettings color’s alpha channel for easier artistic control.

Formula

The fog intensity for a given point in the scene is determined by the following formula:

let fog_intensity = 1.0 - 1.0 / (distance * density).exp();

ExponentialSquared

Fields

density: f32

Multiplier applied to the world distance (within the exponential squared fog falloff calculation).

A squared exponential fog falloff with a given density.

Similar to FogFalloff::Exponential, but grows more slowly in intensity for closer distances before “catching up”.

To move the fog “further away”, use lower density values. To move it “closer” use higher density values.

Tips

• Use the FogFalloff::from_visibility_squared() convenience method to create an exponential squared falloff with the proper density for a desired visibility distance in world units;
• Combine the density parameter with the FogSettings color’s alpha channel for easier artistic control.

Formula

The fog intensity for a given point in the scene is determined by the following formula:

let fog_intensity = 1.0 - 1.0 / (distance * density).powi(2).exp();

Atmospheric

Fields

extinction: Vec3

Controls how much light is removed due to atmospheric “extinction”, i.e. loss of light due to photons being absorbed by atmospheric particles.

Each component can be thought of as an independent per R/G/B channel density factor from FogFalloff::Exponential: Multiplier applied to the world distance (within the fog falloff calculation) for that specific channel.

Note: This value is not a Color, since it affects the channels exponentially in a non-intuitive way. For artistic control, use the FogFalloff::from_visibility_colors() convenience method.

inscattering: Vec3

Controls how much light is added due to light scattering from the sun through the atmosphere.

Each component can be thought of as an independent per R/G/B channel density factor from FogFalloff::Exponential: A multiplier applied to the world distance (within the fog falloff calculation) for that specific channel.

Note: This value is not a Color, since it affects the channels exponentially in a non-intuitive way. For artistic control, use the FogFalloff::from_visibility_colors() convenience method.

A more general form of the FogFalloff::Exponential mode. The falloff formula is separated into two terms, extinction and inscattering, for a somewhat simplified atmospheric scattering model. Additionally, individual color channels can have their own density values, resulting in a total of six different configuration parameters.

Tips

• Use the FogFalloff::from_visibility_colors() or FogFalloff::from_visibility_color() convenience methods to create an atmospheric falloff with the proper densities for a desired visibility distance in world units and extinction and inscattering colors;
• Combine the atmospheric fog parameters with the FogSettings color’s alpha channel for easier artistic control.

Formula

Unlike other modes, atmospheric falloff doesn’t use a simple intensity-based blend of fog color with object color. Instead, it calculates per-channel extinction and inscattering factors, which are then used to calculate the final color.

let extinction_factor = 1.0 - 1.0 / (distance * extinction).exp();
let inscattering_factor = 1.0 - 1.0 / (distance * inscattering).exp();
let result = input_color * (1.0 - extinction_factor) + fog_color * inscattering_factor;

Equivalence to FogFalloff::Exponential

For a density value of D, the following two falloff modes will produce identical visual results:

let exponential = FogFalloff::Exponential {
    density: D,
};

let atmospheric = FogFalloff::Atmospheric {
    extinction: Vec3::new(D, D, D),
    inscattering: Vec3::new(D, D, D),
};

Note: While the results are identical, FogFalloff::Atmospheric is computationally more expensive.

Implementations

impl FogFalloff

pub fn from_visibility(visibility: f32) -> FogFalloff

Creates a FogFalloff::Exponential value from the given visibility distance in world units, using the revised Koschmieder contrast threshold, FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD.

pub fn from_visibility_contrast( visibility: f32, contrast_threshold: f32 ) -> FogFalloff

Creates a FogFalloff::Exponential value from the given visibility distance in world units, and a given contrast threshold in the range of 0.0 to 1.0.

pub fn from_visibility_squared(visibility: f32) -> FogFalloff

Creates a FogFalloff::ExponentialSquared value from the given visibility distance in world units, using the revised Koschmieder contrast threshold, FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD.

pub fn from_visibility_contrast_squared( visibility: f32, contrast_threshold: f32 ) -> FogFalloff

Creates a FogFalloff::ExponentialSquared value from the given visibility distance in world units, and a given contrast threshold in the range of 0.0 to 1.0.

pub fn from_visibility_color( visibility: f32, extinction_inscattering_color: Color ) -> FogFalloff

Creates a FogFalloff::Atmospheric value from the given visibility distance in world units, and a shared color for both extinction and inscattering, using the revised Koschmieder contrast threshold, FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD.

pub fn from_visibility_colors( visibility: f32, extinction_color: Color, inscattering_color: Color ) -> FogFalloff

Creates a FogFalloff::Atmospheric value from the given visibility distance in world units, extinction and inscattering colors, using the revised Koschmieder contrast threshold, FogFalloff::REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD.

Tips

• Alpha values of the provided colors can modulate the extinction and inscattering effects;
• Using an extinction_color of Color::WHITE or Color::NONE disables the extinction effect;
• Using an inscattering_color of Color::BLACK or Color::NONE disables the inscattering effect.

pub fn from_visibility_contrast_color( visibility: f32, contrast_threshold: f32, extinction_inscattering_color: Color ) -> FogFalloff

Creates a FogFalloff::Atmospheric value from the given visibility distance in world units, a contrast threshold in the range of 0.0 to 1.0, and a shared color for both extinction and inscattering.

pub fn from_visibility_contrast_colors( visibility: f32, contrast_threshold: f32, extinction_color: Color, inscattering_color: Color ) -> FogFalloff

Creates a FogFalloff::Atmospheric value from the given visibility distance in world units, a contrast threshold in the range of 0.0 to 1.0, extinction and inscattering colors.

Tips

• Alpha values of the provided colors can modulate the extinction and inscattering effects;
• Using an extinction_color of Color::WHITE or Color::NONE disables the extinction effect;
• Using an inscattering_color of Color::BLACK or Color::NONE disables the inscattering effect.

pub const REVISED_KOSCHMIEDER_CONTRAST_THRESHOLD: f32 = 0.0500000007f32

A 2% contrast threshold was originally proposed by Koschmieder, being the minimum visual contrast at which a human observer could detect an object. We use a revised 5% contrast threshold, deemed more realistic for typical human observers.

pub fn koschmieder(v: f32, c_t: f32) -> f32

Calculates the extinction coefficient β, from V and Cₜ, where:

• Cₜ is the contrast threshold, in the range of 0.0 to 1.0
• V is the visibility distance in which a perfectly black object is still identifiable against the horizon sky within the contrast threshold

We start with Koschmieder’s equation:

      -ln(Cₜ)
 V = ─────────
         β

Multiplying both sides by β/V, that gives us:

      -ln(Cₜ)
 β = ─────────
         V

See:

• https://en.wikipedia.org/wiki/Visibility
• https://www.biral.com/wp-content/uploads/2015/02/Introduction_to_visibility-v2-2.pdf

Trait Implementations

impl Clone for FogFalloff

fn clone(&self) -> FogFalloff

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FogFalloff

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Enum for FogFalloffwhere f32: FromReflect, Vec3: FromReflect,

fn field(&self, __name_param: &str) -> Option<&(dyn Reflect + 'static)>

Returns a reference to the value of the field (in the current variant) with the given name.

fn field_at(&self, __index_param: usize) -> Option<&(dyn Reflect + 'static)>

Returns a reference to the value of the field (in the current variant) at the given index.

fn field_mut( &mut self, __name_param: &str ) -> Option<&mut (dyn Reflect + 'static)>

Returns a mutable reference to the value of the field (in the current variant) with the given name.

fn field_at_mut( &mut self, __index_param: usize ) -> Option<&mut (dyn Reflect + 'static)>

Returns a mutable reference to the value of the field (in the current variant) at the given index.

fn index_of(&self, __name_param: &str) -> Option<usize>

Returns the index of the field (in the current variant) with the given name.

fn name_at(&self, __index_param: usize) -> Option<&str>

Returns the name of the field (in the current variant) with the given index.

fn iter_fields(&self) -> VariantFieldIter<'_>

Returns an iterator over the values of the current variant’s fields.

fn field_len(&self) -> usize

Returns the number of fields in the current variant.

fn variant_name(&self) -> &str

The name of the current variant.

fn variant_index(&self) -> usize

The index of the current variant.

fn variant_type(&self) -> VariantType

The type of the current variant.

fn clone_dynamic(&self) -> DynamicEnum

fn is_variant(&self, variant_type: VariantType) -> bool

Returns true if the current variant’s type matches the given one.

fn variant_path(&self) -> String

Returns the full path to the current variant.

impl GetTypeRegistration for FogFalloffwhere f32: FromReflect, Vec3: FromReflect,

fn get_type_registration() -> TypeRegistration

impl Reflect for FogFalloffwhere f32: FromReflect, Vec3: FromReflect,

fn type_name(&self) -> &str

Returns the type name of the underlying type.

fn get_type_info(&self) -> &'static TypeInfo

Returns the TypeInfo of the underlying type.

fn into_any(self: Box<FogFalloff, Global>) -> Box<dyn Any + 'static, Global>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect( self: Box<FogFalloff, Global> ) -> Box<dyn Reflect + 'static, Global>

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable reflected value.

fn clone_value(&self) -> Box<dyn Reflect + 'static, Global>

Clones the value as a Reflect trait object.

fn set( &mut self, __value_param: Box<dyn Reflect + 'static, Global> ) -> Result<(), Box<dyn Reflect + 'static, Global>>

Performs a type-checked assignment of a reflected value to this value.

fn apply(&mut self, __value_param: &(dyn Reflect + 'static))

Applies a reflected value to this value.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<FogFalloff, Global>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq(&self, value: &(dyn Reflect + 'static)) -> Option<bool>

Returns a “partial equality” comparison result.

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

impl Typed for FogFalloffwhere f32: FromReflect, Vec3: FromReflect,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.