Improve documentation relating to Frustum and HalfSpace

crates/bevy_render/src/camera/projection.rs

@@ -53,6 +53,9 @@ impl<T: CameraProjection + Component + GetTypeRegistration> Plugin for CameraPro
 /// to recompute the camera projection matrix of the [`Camera`] component attached to
 /// the same entity as the component implementing this trait.
 ///
+/// Components implementing this trait include: [`Projection`], [`PerspectiveProjection`]
+/// and [`OrthographicProjection`].
+///
 /// [`Camera`]: crate::camera::Camera
 pub trait CameraProjection {
     fn get_projection_matrix(&self) -> Mat4;

crates/bevy_render/src/primitives/mod.rs

@@ -4,6 +4,18 @@ use bevy_reflect::Reflect;
 use bevy_utils::HashMap;
 
 /// An axis-aligned bounding box.
+///
+/// It represents a box covering the local space occupied by the entity, with faces
+/// orthogonal to the axis. It is used as a component on an entity to determine
+/// if it should be rendered by a [`Camera`](crate::camera::Camera) entity if it
+/// intersects with its [`Frustum`], in a process called frustum culling.
+///
+/// It will be added automatically to entities that could be subject to frustum
+/// culling, and don't have the [`NoFrustumCulling`](crate::view::visibility::NoFrustumCulling)
+/// component, using the systems in
+/// [`CalculateBounds`](crate::view::visibility::VisibilitySystems::CalculateBounds).
+///
+/// It won't be updated automatically if the space occupied by the entity changes.
 #[derive(Component, Clone, Copy, Debug, Default, Reflect)]
 #[reflect(Component)]
 pub struct Aabb {
@@ -81,11 +93,29 @@ impl Sphere {
     }
 }
 
-/// A bisecting plane that partitions 3D space into two regions.
+/// A region of 3D space, specifically a closed set whose border is a bisecting 2D plane.
+/// This bisecting plane partitions 3D space into two infinite regions,
+/// the half-space is one of those regions and includes the bisecting plane.
+///
+/// Each instance of this type is characterized by:
+/// - the bisecting plane's unit normal, normalized and pointing "inside" the half-space,
+/// - the signed distance from the bisecting plane to the origin of 3D space along the normal
+///
+/// The distance can also be seen as:
+/// - the distance from the origin of 3D space to the bisecting plane along the inverse of the normal,
+/// - the opposite of the distance from the origin of 3D space to the bisecting plane along the normal.
+///
+/// Any point `p` is considered to be within the `HalfSpace` when the length of the projection
+/// of p on the normal is greater or equal than the opposite of the distance,
+/// meaning: if the equation `n.p + d >= 0` is satisfied,
+/// where `n` is the normal, `d` the distance, and `n.p` is a dot product.
 ///
-/// Each instance of this type is characterized by the bisecting plane's unit normal and distance from the origin along the normal.
-/// Any point `p` is considered to be within the `HalfSpace` when the distance is positive,
-/// meaning: if the equation `n.p + d > 0` is satisfied.
+/// For example, the half-space containing all the points with a z-coordinate lesser
+/// or equal than `8.0` would be defined by: `HalfSpace::new(Vec3::NEG_Z.extend(-8.0))`.
+/// It includes all the points from the bisecting plane towards `NEG_Z`, and the distance
+/// from the plane to the origin is `-8.0` along `NEG_Z`.
+///
+/// It is used to define a [`Frustum`].
 #[derive(Clone, Copy, Debug, Default)]
 pub struct HalfSpace {
     normal_d: Vec4,
@@ -94,7 +124,7 @@ pub struct HalfSpace {
 impl HalfSpace {
     /// Constructs a `HalfSpace` from a 4D vector whose first 3 components
     /// represent the bisecting plane's unit normal, and the last component signifies
-    /// the distance from the origin to the plane along the normal.
+    /// the signed distance from the plane to the origin along the normal.
     /// The constructor ensures the normal vector is normalized and the distance is appropriately scaled.
     #[inline]
     pub fn new(normal_d: Vec4) -> Self {
@@ -109,8 +139,9 @@ impl HalfSpace {
         Vec3A::from(self.normal_d)
     }
 
-    /// Returns the distance from the origin to the bisecting plane along the plane's unit normal vector.
-    /// This distance helps determine the position of a point `p` on the bisecting plane, as per the equation `n.p + d = 0`.
+    /// Returns the distance from the bisecting plane to the origin along the plane's unit normal vector.
+    /// This distance helps determine the position of a point `p` relative to the
+    /// bisecting plane, as per the equation `n.p + d >= 0`.
     #[inline]
     pub fn d(&self) -> f32 {
         self.normal_d.w
@@ -123,9 +154,24 @@ impl HalfSpace {
     }
 }
 
-/// A frustum made up of the 6 defining half spaces.
-/// Half spaces are ordered left, right, top, bottom, near, far.
-/// The normal vectors of the half spaces point towards the interior of the frustum.
+/// A frustum defined as the intersection of 6 [`HalfSpace`].
+/// Usually a six sided polyhedron with sides inside the bisecting planes of the half-spaces.
+///
+/// Half spaces are ordered left, right, top, bottom, near, far. The normal vectors
+/// of the half-spaces point towards the interior of the frustum.
+///
+/// A frustum component is used on an entity with a [`Camera`](crate::camera::Camera)
+/// component to determine which entities will be considered for rendering
+/// by this camera, all entities with an [`Aabb`] component that does not intersect
+/// with the frustum will not be rendered, and not be used in rendering computations.
+///
+/// This process is called frustum culling, and entities can opt out of it using
+/// the [`NoFrustumCulling`](crate::view::visibility::NoFrustumCulling) component.
+///
+/// The frustum component is typically added by adding a bundle, either the `Camera2dBundle`
+/// or the `Camera3dBundle`, and is typically updated automatically by
+/// [`update_frusta`](crate::view::visibility::update_frusta) from the
+/// [`CameraProjection`](crate::camera::CameraProjection) component of the camera entity.
 #[derive(Component, Clone, Copy, Debug, Default, Reflect)]
 #[reflect(Component)]
 pub struct Frustum {

crates/bevy_render/src/view/visibility/mod.rs

@@ -153,23 +153,21 @@ pub struct VisibilityBundle {
     pub computed: ComputedVisibility,
 }
 
-/// Use this component to opt-out of built-in frustum culling for Mesh entities
+/// Use this component to opt-out of built-in frustum culling for entities, see
+/// [`Frustum`].
 #[derive(Component, Default, Reflect)]
 #[reflect(Component, Default)]
 pub struct NoFrustumCulling;
 
 /// Collection of entities visible from the current view.
 ///
 /// This component contains all entities which are visible from the currently
-/// rendered view. The collection is updated automatically by the [`check_visibility()`]
-/// system, and renderers can use it to optimize rendering of a particular view, to
+/// rendered view. The collection is updated automatically by the [`VisibilitySystems::CheckVisibility`]
+/// system set, and renderers can use it to optimize rendering of a particular view, to
 /// prevent drawing items not visible from that view.
 ///
 /// This component is intended to be attached to the same entity as the [`Camera`] and
 /// the [`Frustum`] defining the view.
-///
-/// Currently this component is ignored by the sprite renderer, so sprite rendering
-/// is not optimized per view.
 #[derive(Clone, Component, Default, Debug, Reflect)]
 #[reflect(Component)]
 pub struct VisibleEntities {
@@ -193,13 +191,21 @@ impl VisibleEntities {
 
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
 pub enum VisibilitySystems {
+    /// Label for the [`calculate_bounds`] and `calculate_bounds_2d` systems,
+    /// calculating and inserting an [`Aabb`] to relevant entities.
     CalculateBounds,
+    /// Label for the [`apply_deferred`] call after [`VisibilitySystems::CalculateBounds`]
     CalculateBoundsFlush,
+    /// Label for the [`update_frusta<OrthographicProjection>`] system.
     UpdateOrthographicFrusta,
+    /// Label for the [`update_frusta<PerspectiveProjection>`] system.
     UpdatePerspectiveFrusta,
+    /// Label for the [`update_frusta<Projection>`] system.
     UpdateProjectionFrusta,
+    /// Label for the system propagating the [`ComputedVisibility`] in a
+    /// [`hierarchy`](bevy_hierarchy).
     VisibilityPropagate,
-    /// Label for the [`check_visibility()`] system updating each frame the [`ComputedVisibility`]
+    /// Label for the [`check_visibility`] system updating [`ComputedVisibility`]
     /// of each entity and the [`VisibleEntities`] of each view.
     CheckVisibility,
 }
@@ -253,6 +259,10 @@ impl Plugin for VisibilityPlugin {
     }
 }
 
+/// System calculating and inserting an [`Aabb`] component to entities with a
+/// [`Handle<Mesh>`](Mesh) component and without a [`NoFrustumCulling`] component.
+///
+/// Used in system set [`VisibilitySystems::CalculateBounds`].
 pub fn calculate_bounds(
     mut commands: Commands,
     meshes: Res<Assets<Mesh>>,
@@ -267,6 +277,13 @@ pub fn calculate_bounds(
     }
 }
 
+/// System updating the [`Frustum`] component of an entity, typically a [`Camera`],
+/// using its [`GlobalTransform`] and the projection matrix from its [`CameraProjection`]
+/// component.
+///
+/// Used in system sets [`VisibilitySystems::UpdateProjectionFrusta`],
+/// [`VisibilitySystems::UpdatePerspectiveFrusta`], and
+/// [`VisibilitySystems::UpdateOrthographicFrusta`].
 pub fn update_frusta<T: Component + CameraProjection + Send + Sync + 'static>(
     mut views: Query<(&GlobalTransform, &T, &mut Frustum)>,
 ) {

crates/bevy_sprite/src/lib.rs

@@ -105,6 +105,13 @@ impl Plugin for SpritePlugin {
     }
 }
 
+/// System calculating and inserting an [`Aabb`] component to entities with either:
+/// - a `Mesh2dHandle` component,
+/// - a `Sprite` and `Handle<Image>` components,
+/// - a `TextureAtlasSprite` and `Handle<TextureAtlas>` components,
+/// and without a [`NoFrustumCulling`] component.
+///
+/// Used in system set [`VisibilitySystems::CalculateBounds`].
 pub fn calculate_bounds_2d(
     mut commands: Commands,
     meshes: Res<Assets<Mesh>>,