Enum bevy::pbr::prelude::FogFalloff

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

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

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

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

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
§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)
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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::srgba(0.35, 0.48, 0.66, 1.0),
            directional_light_color: Color::srgba(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::srgb(0.35, 0.5, 0.66), // atmospheric extinction color (after light is lost due to absorption by atmospheric particles)
                Color::srgb(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:

Trait Implementations§

§

impl Clone for FogFalloff

§

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
§

impl Debug for FogFalloff

§

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

Formats the value using the given formatter. Read more
§

impl Enum for FogFalloff
where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath + RegisterForReflection, Vec3: FromReflect + TypePath + RegisterForReflection,

§

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

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

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

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
§

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 + RegisterForReflection, Vec3: FromReflect + TypePath + RegisterForReflection,

§

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

impl GetTypeRegistration for FogFalloff
where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath + RegisterForReflection, Vec3: FromReflect + TypePath + RegisterForReflection,

§

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.
§

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type. Read more
§

impl Reflect for FogFalloff
where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath + RegisterForReflection, Vec3: FromReflect + TypePath + RegisterForReflection,

§

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

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

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

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
§

fn try_apply( &mut self, __value_param: &(dyn Reflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value. Read more
§

fn reflect_kind(&self) -> ReflectKind

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

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

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

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

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

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

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

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

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

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

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

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

Applies a reflected value to this value. Read more
§

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

Debug formatter for the value. Read more
§

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

Returns a serializable version of the value. Read more
§

fn is_dynamic(&self) -> bool

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

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

§

fn type_path() -> &'static str

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

fn short_type_path() -> &'static str

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

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

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

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

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

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

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

impl Typed for FogFalloff
where FogFalloff: Any + Send + Sync, f32: FromReflect + TypePath + RegisterForReflection, Vec3: FromReflect + TypePath + RegisterForReflection,

§

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
§

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

§

fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> 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
§

impl<T> Downcast<T> for T

§

fn downcast(&self) -> &T

§

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

§

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

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

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

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

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

§

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

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

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.

§

impl<S> FromSample<S> for S

§

fn from_sample_(s: S) -> S

§

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

§

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
§

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
§

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
§

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
§

impl<T> Instrument for T

§

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

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

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> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<F, T> IntoSample<T> for F
where T: FromSample<F>,

§

fn into_sample(self) -> T

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
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
§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

§

fn to_sample_(self) -> U

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

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

§

fn clone_type_data(&self) -> Box<dyn TypeData>

§

impl<T> Upcast<T> for T

§

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

§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

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
§

fn with_current_subscriber(self) -> WithDispatch<Self>

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

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

§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

§

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

§

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

§

impl<T> WasmNotSendSync for T
where T: WasmNotSend + WasmNotSync,

§

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