Struct VisibilityRange

pub struct VisibilityRange {
    pub start_margin: Range<f32>,
    pub end_margin: Range<f32>,
}

Specifies the range of distances that this entity must be from the camera in order to be rendered.

This is also known as hierarchical level of detail or HLOD.

Use this component when you want to render a high-polygon mesh when the camera is close and a lower-polygon mesh when the camera is far away. This is a common technique for improving performance, because fine details are hard to see in a mesh at a distance. To avoid an artifact known as popping between levels, each level has a margin, within which the object transitions gradually from invisible to visible using a dithering effect.

You can also use this feature to replace multiple meshes with a single mesh when the camera is distant. This is the reason for the term “hierarchical level of detail”. Reducing the number of meshes can be useful for reducing drawcall count. Note that you must place the VisibilityRange component on each entity you want to be part of a LOD group, as VisibilityRange isn’t automatically propagated down to children.

A typical use of this feature might look like this:

Entity	start_margin	end_margin
Root	N/A	N/A
├─ High-poly mesh	[0, 0)	[20, 25)
├─ Low-poly mesh	[20, 25)	[70, 75)
└─ Billboard imposter	[70, 75)	[150, 160)

With this setup, the user will see a high-poly mesh when the camera is closer than 20 units. As the camera zooms out, between 20 units to 25 units, the high-poly mesh will gradually fade to a low-poly mesh. When the camera is 70 to 75 units away, the low-poly mesh will fade to a single textured quad. And between 150 and 160 units, the object fades away entirely. Note that the end_margin of a higher LOD is always identical to the start_margin of the next lower LOD; this is important for the crossfade effect to function properly.

Fields

start_margin: Range<f32>

The range of distances, in world units, between which this entity will smoothly fade into view as the camera zooms out.

If the start and end of this range are identical, the transition will be abrupt, with no crossfading.

start_margin.end must be less than or equal to end_margin.start.

end_margin: Range<f32>

The range of distances, in world units, between which this entity will smoothly fade out of view as the camera zooms out.

If the start and end of this range are identical, the transition will be abrupt, with no crossfading.

end_margin.start must be greater than or equal to start_margin.end.

Implementations

impl VisibilityRange

pub fn abrupt(start: f32, end: f32) -> Self

Creates a new abrupt visibility range, with no crossfade.

There will be no crossfade; the object will immediately vanish if the camera is closer than start units or farther than end units from the model.

The start value must be less than or equal to the end value.

pub fn is_abrupt(&self) -> bool

Returns true if both the start and end transitions for this range are abrupt: that is, there is no crossfading.

pub fn is_visible_at_all(&self, camera_distance: f32) -> bool

Returns true if the object will be visible at all, given a camera camera_distance units away.

Any amount of visibility, even with the heaviest dithering applied, is considered visible according to this check.

pub fn is_culled(&self, camera_distance: f32) -> bool

Returns true if the object is completely invisible, given a camera camera_distance units away.

This is equivalent to !VisibilityRange::is_visible_at_all().

Trait Implementations

impl Clone for VisibilityRange

fn clone(&self) -> VisibilityRange

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Component for VisibilityRange

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

fn register_component_hooks(_hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

impl FromReflect for VisibilityRange

where Self: Any + Send + Sync, Range<f32>: FromReflect + TypePath + RegisterForReflection,

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

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 VisibilityRange

where Self: Any + Send + Sync, Range<f32>: 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.

impl Hash for VisibilityRange

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for VisibilityRange

fn eq(&self, other: &VisibilityRange) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Reflect for VisibilityRange

where Self: Any + Send + Sync, Range<f32>: FromReflect + TypePath + RegisterForReflection,

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

Returns the TypeInfo of the type represented by this value.

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

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

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

Returns the value as a &mut dyn Any.

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

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a reflected value.

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

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: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

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

fn try_apply(&mut self, value: &dyn Reflect) -> Result<(), ApplyError>

Tries to apply 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<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

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

Returns a “partial equality” comparison result.

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

Applies a reflected value to this value.

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

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

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 Struct for VisibilityRange

where Self: Any + Send + Sync, Range<f32>: FromReflect + TypePath + RegisterForReflection,

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

Returns a reference to the value of the field named name as a &dyn Reflect.

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

Returns a mutable reference to the value of the field named name as a &mut dyn Reflect.

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

Returns a reference to the value of the field with index index as a &dyn Reflect.

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

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

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

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

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

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

impl TypePath for VisibilityRange

where Self: 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 VisibilityRange

where Self: Any + Send + Sync, Range<f32>: FromReflect + TypePath + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl Eq for VisibilityRange

impl StructuralPartialEq for VisibilityRange