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

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);

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.

Exponential

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();

Fields

density: f32

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

ExponentialSquared

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();

Fields

density: f32

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

Atmospheric

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.

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.

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.

Examples found in repository

examples/3d/atmospheric_fog.rs (lines 37-41)

fn setup_camera_fog(mut commands: Commands) {
    commands.spawn((
        Camera3dBundle {
            transform: Transform::from_xyz(-1.0, 0.1, 1.0)
                .looking_at(Vec3::new(0.0, 0.0, 0.0), Vec3::Y),
            ..default()
        },
        FogSettings {
            color: Color::rgba(0.35, 0.48, 0.66, 1.0),
            directional_light_color: Color::rgba(1.0, 0.95, 0.85, 0.5),
            directional_light_exponent: 30.0,
            falloff: FogFalloff::from_visibility_colors(
                15.0, // distance in world units up to which objects retain visibility (>= 5% contrast)
                Color::rgb(0.35, 0.5, 0.66), // atmospheric extinction color (after light is lost due to absorption by atmospheric particles)
                Color::rgb(0.8, 0.844, 1.0), // atmospheric inscattering color (light gained due to scattering from the sun)
            ),
        },
    ));
}

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 FogFalloff

where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath, Vec3: FromReflect + TypePath,

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 FromReflect for FogFalloff

where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath, Vec3: FromReflect + TypePath,

fn from_reflect(__param0: &(dyn Reflect + 'static)) -> Option<FogFalloff>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn Reflect> ) -> Result<Self, Box<dyn Reflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetTypeRegistration for FogFalloff

where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath, Vec3: FromReflect + TypePath,

fn get_type_registration() -> TypeRegistration

impl Reflect for FogFalloff

where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath, Vec3: FromReflect + TypePath,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn into_any(self: Box<FogFalloff>) -> Box<dyn Any>

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>) -> Box<dyn Reflect>

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>

Clones the value as a Reflect trait object.

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

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_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

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

Returns an immutable 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>) -> 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.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl TypePath for FogFalloff

where FogFalloff: Any + Send + Sync,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for FogFalloff

where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath, Vec3: FromReflect + TypePath,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.