bevy_camera/visibility/range.rs
1//! Specific distances from the camera in which entities are visible, also known
2//! as *hierarchical levels of detail* or *HLOD*s.
3
4use core::{
5 hash::{Hash, Hasher},
6 ops::Range,
7};
8
9use bevy_app::{App, Plugin, PostUpdate};
10use bevy_ecs::{
11 component::Component,
12 entity::{Entity, EntityHashMap},
13 query::With,
14 reflect::ReflectComponent,
15 resource::Resource,
16 schedule::IntoScheduleConfigs as _,
17 system::{Local, Query, ResMut},
18};
19use bevy_math::FloatOrd;
20use bevy_reflect::Reflect;
21use bevy_transform::components::GlobalTransform;
22use bevy_utils::Parallel;
23
24use super::{check_visibility, VisibilitySystems};
25use crate::{camera::Camera, primitives::Aabb};
26
27/// A plugin that enables [`VisibilityRange`]s, which allow entities to be
28/// hidden or shown based on distance to the camera.
29pub struct VisibilityRangePlugin;
30
31impl Plugin for VisibilityRangePlugin {
32 fn build(&self, app: &mut App) {
33 app.init_resource::<VisibleEntityRanges>().add_systems(
34 PostUpdate,
35 check_visibility_ranges
36 .in_set(VisibilitySystems::CheckVisibility)
37 .before(check_visibility),
38 );
39 }
40}
41
42/// Specifies the range of distances that this entity must be from the camera in
43/// order to be rendered.
44///
45/// This is also known as *hierarchical level of detail* or *HLOD*.
46///
47/// Use this component when you want to render a high-polygon mesh when the
48/// camera is close and a lower-polygon mesh when the camera is far away. This
49/// is a common technique for improving performance, because fine details are
50/// hard to see in a mesh at a distance. To avoid an artifact known as *popping*
51/// between levels, each level has a *margin*, within which the object
52/// transitions gradually from invisible to visible using a dithering effect.
53///
54/// You can also use this feature to replace multiple meshes with a single mesh
55/// when the camera is distant. This is the reason for the term "*hierarchical*
56/// level of detail". Reducing the number of meshes can be useful for reducing
57/// drawcall count. Note that you must place the [`VisibilityRange`] component
58/// on each entity you want to be part of a LOD group, as [`VisibilityRange`]
59/// isn't automatically propagated down to children.
60///
61/// A typical use of this feature might look like this:
62///
63/// | Entity | `start_margin` | `end_margin` |
64/// |-------------------------|----------------|--------------|
65/// | Root | N/A | N/A |
66/// | ├─ High-poly mesh | [0, 0) | [20, 25) |
67/// | ├─ Low-poly mesh | [20, 25) | [70, 75) |
68/// | └─ Billboard *imposter* | [70, 75) | [150, 160) |
69///
70/// With this setup, the user will see a high-poly mesh when the camera is
71/// closer than 20 units. As the camera zooms out, between 20 units to 25 units,
72/// the high-poly mesh will gradually fade to a low-poly mesh. When the camera
73/// is 70 to 75 units away, the low-poly mesh will fade to a single textured
74/// quad. And between 150 and 160 units, the object fades away entirely. Note
75/// that the `end_margin` of a higher LOD is always identical to the
76/// `start_margin` of the next lower LOD; this is important for the crossfade
77/// effect to function properly.
78#[derive(Component, Clone, PartialEq, Default, Reflect)]
79#[reflect(Component, PartialEq, Hash, Clone)]
80pub struct VisibilityRange {
81 /// The range of distances, in world units, between which this entity will
82 /// smoothly fade into view as the camera zooms out.
83 ///
84 /// If the start and end of this range are identical, the transition will be
85 /// abrupt, with no crossfading.
86 ///
87 /// `start_margin.end` must be less than or equal to `end_margin.start`.
88 pub start_margin: Range<f32>,
89
90 /// The range of distances, in world units, between which this entity will
91 /// smoothly fade out of view as the camera zooms out.
92 ///
93 /// If the start and end of this range are identical, the transition will be
94 /// abrupt, with no crossfading.
95 ///
96 /// `end_margin.start` must be greater than or equal to `start_margin.end`.
97 pub end_margin: Range<f32>,
98
99 /// If set to true, Bevy will use the center of the axis-aligned bounding
100 /// box ([`Aabb`]) as the position of the mesh for the purposes of
101 /// visibility range computation.
102 ///
103 /// Otherwise, if this field is set to false, Bevy will use the origin of
104 /// the mesh as the mesh's position.
105 ///
106 /// Usually you will want to leave this set to false, because different LODs
107 /// may have different AABBs, and smooth crossfades between LOD levels
108 /// require that all LODs of a mesh be at *precisely* the same position. If
109 /// you aren't using crossfading, however, and your meshes aren't centered
110 /// around their origins, then this flag may be useful.
111 pub use_aabb: bool,
112}
113
114impl Eq for VisibilityRange {}
115
116impl Hash for VisibilityRange {
117 fn hash<H>(&self, state: &mut H)
118 where
119 H: Hasher,
120 {
121 FloatOrd(self.start_margin.start).hash(state);
122 FloatOrd(self.start_margin.end).hash(state);
123 FloatOrd(self.end_margin.start).hash(state);
124 FloatOrd(self.end_margin.end).hash(state);
125 }
126}
127
128impl VisibilityRange {
129 /// Creates a new *abrupt* visibility range, with no crossfade.
130 ///
131 /// There will be no crossfade; the object will immediately vanish if the
132 /// camera is closer than `start` units or farther than `end` units from the
133 /// model.
134 ///
135 /// The `start` value must be less than or equal to the `end` value.
136 #[inline]
137 pub fn abrupt(start: f32, end: f32) -> Self {
138 Self {
139 start_margin: start..start,
140 end_margin: end..end,
141 use_aabb: false,
142 }
143 }
144
145 /// Returns true if both the start and end transitions for this range are
146 /// abrupt: that is, there is no crossfading.
147 #[inline]
148 pub fn is_abrupt(&self) -> bool {
149 self.start_margin.start == self.start_margin.end
150 && self.end_margin.start == self.end_margin.end
151 }
152
153 /// Returns true if the object will be visible at all, given a camera
154 /// `camera_distance` units away.
155 ///
156 /// Any amount of visibility, even with the heaviest dithering applied, is
157 /// considered visible according to this check.
158 #[inline]
159 pub fn is_visible_at_all(&self, camera_distance: f32) -> bool {
160 camera_distance >= self.start_margin.start && camera_distance < self.end_margin.end
161 }
162
163 /// Returns true if the object is completely invisible, given a camera
164 /// `camera_distance` units away.
165 ///
166 /// This is equivalent to `!VisibilityRange::is_visible_at_all()`.
167 #[inline]
168 pub fn is_culled(&self, camera_distance: f32) -> bool {
169 !self.is_visible_at_all(camera_distance)
170 }
171}
172
173/// Stores which entities are in within the [`VisibilityRange`]s of views.
174///
175/// This doesn't store the results of frustum or occlusion culling; use
176/// [`ViewVisibility`](`super::ViewVisibility`) for that. Thus entities in this list may not
177/// actually be visible.
178///
179/// For efficiency, these tables only store entities that have
180/// [`VisibilityRange`] components. Entities without such a component won't be
181/// in these tables at all.
182///
183/// The table is indexed by entity and stores a 32-bit bitmask with one bit for
184/// each camera, where a 0 bit corresponds to "out of range" and a 1 bit
185/// corresponds to "in range". Hence it's limited to storing information for 32
186/// views.
187#[derive(Resource, Default)]
188pub struct VisibleEntityRanges {
189 /// Stores which bit index each view corresponds to.
190 views: EntityHashMap<u8>,
191
192 /// Stores a bitmask in which each view has a single bit.
193 ///
194 /// A 0 bit for a view corresponds to "out of range"; a 1 bit corresponds to
195 /// "in range".
196 entities: EntityHashMap<u32>,
197}
198
199impl VisibleEntityRanges {
200 /// Clears out the [`VisibleEntityRanges`] in preparation for a new frame.
201 fn clear(&mut self) {
202 self.views.clear();
203 self.entities.clear();
204 }
205
206 /// Returns true if the entity is in range of the given camera.
207 ///
208 /// This only checks [`VisibilityRange`]s and doesn't perform any frustum or
209 /// occlusion culling. Thus the entity might not *actually* be visible.
210 ///
211 /// The entity is assumed to have a [`VisibilityRange`] component. If the
212 /// entity doesn't have that component, this method will return false.
213 #[inline]
214 pub fn entity_is_in_range_of_view(&self, entity: Entity, view: Entity) -> bool {
215 let Some(visibility_bitmask) = self.entities.get(&entity) else {
216 return false;
217 };
218 let Some(view_index) = self.views.get(&view) else {
219 return false;
220 };
221 (visibility_bitmask & (1 << view_index)) != 0
222 }
223
224 /// Returns true if the entity is in range of any view.
225 ///
226 /// This only checks [`VisibilityRange`]s and doesn't perform any frustum or
227 /// occlusion culling. Thus the entity might not *actually* be visible.
228 ///
229 /// The entity is assumed to have a [`VisibilityRange`] component. If the
230 /// entity doesn't have that component, this method will return false.
231 #[inline]
232 pub fn entity_is_in_range_of_any_view(&self, entity: Entity) -> bool {
233 self.entities.contains_key(&entity)
234 }
235}
236
237/// Checks all entities against all views in order to determine which entities
238/// with [`VisibilityRange`]s are potentially visible.
239///
240/// This only checks distance from the camera and doesn't frustum or occlusion
241/// cull.
242pub fn check_visibility_ranges(
243 mut visible_entity_ranges: ResMut<VisibleEntityRanges>,
244 view_query: Query<(Entity, &GlobalTransform), With<Camera>>,
245 mut par_local: Local<Parallel<Vec<(Entity, u32)>>>,
246 entity_query: Query<(Entity, &GlobalTransform, Option<&Aabb>, &VisibilityRange)>,
247) {
248 visible_entity_ranges.clear();
249
250 // Early out if the visibility range feature isn't in use.
251 if entity_query.is_empty() {
252 return;
253 }
254
255 // Assign an index to each view.
256 let mut views = vec![];
257 for (view, view_transform) in view_query.iter().take(32) {
258 let view_index = views.len() as u8;
259 visible_entity_ranges.views.insert(view, view_index);
260 views.push((view, view_transform.translation_vec3a()));
261 }
262
263 // Check each entity/view pair. Only consider entities with
264 // [`VisibilityRange`] components.
265 entity_query.par_iter().for_each(
266 |(entity, entity_transform, maybe_model_aabb, visibility_range)| {
267 let mut visibility = 0;
268 for (view_index, &(_, view_position)) in views.iter().enumerate() {
269 // If instructed to use the AABB and the model has one, use its
270 // center as the model position. Otherwise, use the model's
271 // translation.
272 let model_position = match (visibility_range.use_aabb, maybe_model_aabb) {
273 (true, Some(model_aabb)) => entity_transform
274 .affine()
275 .transform_point3a(model_aabb.center),
276 _ => entity_transform.translation_vec3a(),
277 };
278
279 if visibility_range.is_visible_at_all((view_position - model_position).length()) {
280 visibility |= 1 << view_index;
281 }
282 }
283
284 // Invisible entities have no entry at all in the hash map. This speeds
285 // up checks slightly in this common case.
286 if visibility != 0 {
287 par_local.borrow_local_mut().push((entity, visibility));
288 }
289 },
290 );
291
292 visible_entity_ranges.entities.extend(par_local.drain());
293}