Enum bevy_pbr::FogFalloff

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

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:

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);
Plot showing how linear fog falloff behaves for start and end values of 0.8 and 2.2, respectively. 1 1 0 2 3 distance fog intensity start end
§

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();
Plot showing how exponential fog falloff behaves for different density values 1 1 0 2 3 density = 2 density = 1 density = 0.5 distance fog intensity
§

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();
Plot showing how exponential squared fog falloff behaves for different density values 1 1 0 2 3 density = 2 density = 1 density = 0.5 distance fog intensity
§

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
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§

source§

impl FogFalloff

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.
source

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.

source

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.
source

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.

source

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:

Trait Implementations§

source§

impl Clone for FogFalloff

source§

fn clone(&self) -> FogFalloff

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for FogFalloff

source§

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

Formats the value using the given formatter. Read more
source§

impl Enum for FogFalloff

source§

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

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

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

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

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

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

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

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

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

Returns the index of the field (in the current variant) with the given name. Read more
source§

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

Returns the name of the field (in the current variant) with the given index. Read more
source§

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

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

fn field_len(&self) -> usize

Returns the number of fields in the current variant.
source§

fn variant_name(&self) -> &str

The name of the current variant.
source§

fn variant_index(&self) -> usize

The index of the current variant.
source§

fn variant_type(&self) -> VariantType

The type of the current variant.
source§

fn clone_dynamic(&self) -> DynamicEnum

source§

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

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

fn variant_path(&self) -> String

Returns the full path to the current variant.
source§

impl FromReflect for FogFalloff

source§

fn from_reflect(__param0: &dyn Reflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.
source§

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. Read more
source§

impl GetTypeRegistration for FogFalloff

source§

impl Reflect for FogFalloff

source§

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

Returns the TypeInfo of the type represented by this value. Read more
source§

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

Returns the value as a Box<dyn Any>.
source§

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.
source§

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.
source§

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed reflected value.
source§

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a reflected value.
source§

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable reflected value.
source§

fn clone_value(&self) -> Box<dyn Reflect>

Clones the value as a Reflect trait object. Read more
source§

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. Read more
source§

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

Applies a reflected value to this value. Read more
source§

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type. Read more
source§

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

Returns an immutable enumeration of “kinds” of type. Read more
source§

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

Returns a mutable enumeration of “kinds” of type. Read more
source§

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type. Read more
source§

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

Returns a hash of the value (which includes the type). Read more
source§

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

Returns a “partial equality” comparison result. Read more
source§

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

Debug formatter for the value. Read more
source§

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

Returns a serializable version of the value. Read more
source§

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type. Read more
source§

impl TypePath for FogFalloff
where Self: Any + Send + Sync,

source§

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type. Read more
source§

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type. Read more
source§

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

Returns the name of the type, or None if it is anonymous. Read more
source§

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

Returns the name of the crate the type is in, or None if it is anonymous. Read more
source§

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

Returns the path to the module the type is in, or None if it is anonymous. Read more
source§

impl Typed for FogFalloff

source§

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T, U> AsBindGroupShaderType<U> for T
where U: ShaderType, &'a T: for<'a> Into<U>,

source§

fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Downcast<T> for T

source§

fn downcast(&self) -> &T

source§

impl<T> Downcast for T
where T: Any,

source§

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

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
source§

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

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
source§

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

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> DynamicTypePath for T
where T: TypePath,

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> GetPath for T
where T: Reflect + ?Sized,

source§

fn reflect_path<'p>( &self, path: impl ReflectPath<'p> ) -> Result<&(dyn Reflect + 'static), ReflectPathError<'p>>

Returns a reference to the value specified by path. Read more
source§

fn reflect_path_mut<'p>( &mut self, path: impl ReflectPath<'p> ) -> Result<&mut (dyn Reflect + 'static), ReflectPathError<'p>>

Returns a mutable reference to the value specified by path. Read more
source§

fn path<'p, T>( &self, path: impl ReflectPath<'p> ) -> Result<&T, ReflectPathError<'p>>
where T: Reflect,

Returns a statically typed reference to the value specified by path. Read more
source§

fn path_mut<'p, T>( &mut self, path: impl ReflectPath<'p> ) -> Result<&mut T, ReflectPathError<'p>>
where T: Reflect,

Returns a statically typed mutable reference to the value specified by path. Read more
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> TypeData for T
where T: 'static + Send + Sync + Clone,

source§

impl<T> Upcast<T> for T

source§

fn upcast(&self) -> Option<&T>

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> Settings for T
where T: 'static + Send + Sync,

source§

impl<T> WasmNotSend for T
where T: Send,

source§

impl<T> WasmNotSendSync for T

source§

impl<T> WasmNotSync for T
where T: Sync,