Proposed changes by nicopap and mockersf

crates/bevy_render/src/primitives/mod.rs

@@ -6,16 +6,26 @@ 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 local 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.
+/// orthogonal to the local axis.
 ///
-/// 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 is typically used as a component on an entity during "frustum culling",
+/// a process to determine if the entity should be rendered by a [`Camera`]
+/// entity if it intersects with its [`Frustum`].
 ///
-/// It won't be updated automatically if the space occupied by the entity changes.
+/// It will be added automatically by the systems in [`CalculateBounds`] to entities that:
+/// - could be subject to frustum culling, for example with a [`Handle<Mesh>`]
+/// or `Sprite` component,
+/// - don't have the [`NoFrustumCulling`] component.
+///
+/// It won't be updated automatically if the space occupied by the entity changes,
+/// for example if the vertex positions of a [`Mesh`] inside a `Handle<Mesh>` are
+/// updated.
+///
+/// [`Camera`]: crate::camera::Camera
+/// [`NoFrustumCulling`]: crate::view::visibility::NoFrustumCulling
+/// [`CalculateBounds`]: crate::view::visibility::VisibilitySystems::CalculateBounds
+/// [`Mesh`]: crate::mesh::Mesh
+/// [`Handle<Mesh>`]: crate::mesh::Mesh
 #[derive(Component, Clone, Copy, Debug, Default, Reflect)]
 #[reflect(Component)]
 pub struct Aabb {
@@ -99,11 +109,11 @@ impl Sphere {
 ///
 /// 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 signed distance along the normal from the bisecting plane to the origin of 3D space.
 ///
 /// 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.
+/// - the distance along the inverse of the normal from the origin of 3D space to the bisecting plane,
+/// - the opposite of the distance along the normal from the origin of 3D space to the bisecting plane.
 ///
 /// 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,
@@ -114,16 +124,16 @@ impl Sphere {
 /// 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`], and for light computation.
+/// It is used to define a [`Frustum`], and for light computation, for example.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct HalfSpace {
     normal_d: Vec4,
 }
 
 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 signed distance from the plane to the origin along the normal.
+    /// represent the bisecting plane's unit normal, and the last component is
+    /// the signed distance along the normal from the plane to the origin.
     /// The constructor ensures the normal vector is normalized and the distance is appropriately scaled.
     #[inline]
     pub fn new(normal_d: Vec4) -> Self {
@@ -140,38 +150,44 @@ impl HalfSpace {
 
     /// Returns the signed 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 `normal.dot(p) + distance >= 0.`.
     #[inline]
     pub fn d(&self) -> f32 {
         self.normal_d.w
     }
 
-    /// Returns the bisecting plane's unit normal vector and the distance from the origin to the plane.
+    /// Returns the bisecting plane's unit normal vector and the signed distance
+    /// from the plane to the origin.
     #[inline]
     pub fn normal_d(&self) -> Vec4 {
         self.normal_d
     }
 }
 
 /// A frustum defined as the intersection of 6 [`HalfSpace`].
-/// Usually a six sided polyhedron with sides inside the bisecting planes of the half-spaces.
+///
+/// Usually an apex-truncated square pyramid (a pyramid without the top) or a cuboid.
 ///
 /// 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.
+/// A frustum component is used on an entity with a [`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 [`NoFrustumCulling`] component.
+///
+/// The frustum component is typically added from a bundle, either the `Camera2dBundle`
+/// or the `Camera3dBundle`.
+/// It is usually updated automatically by [`update_frusta`] from the
+/// [`CameraProjection`] component and [`GlobalTransform`] of the camera entity.
 ///
-/// 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.
+/// [`Camera`]: crate::camera::Camera
+/// [`NoFrustumCulling`]: crate::view::visibility::NoFrustumCulling
+/// [`update_frusta`]: crate::view::visibility::update_frusta
+/// [`CameraProjection`]: crate::camera::CameraProjection
+/// [`GlobalTransform`]: bevy_transform::components::GlobalTransform
 #[derive(Component, Clone, Copy, Debug, Default, Reflect)]
 #[reflect(Component)]
 pub struct Frustum {

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

@@ -155,6 +155,11 @@ pub struct VisibilityBundle {
 
 /// Use this component to opt-out of built-in frustum culling for entities, see
 /// [`Frustum`].
+///
+/// It can be used for example:
+/// - when a [`Mesh`] is updated but its [`Aabb`] is not, which might happen with animations,
+/// - when using some light effects, like wanting a [`Mesh`] out of the [`Frustum`]
+/// to appear in the reflection of a [`Mesh`] within.
 #[derive(Component, Default, Reflect)]
 #[reflect(Component, Default)]
 pub struct NoFrustumCulling;
@@ -259,10 +264,10 @@ impl Plugin for VisibilityPlugin {
     }
 }
 
-/// System calculating and inserting an [`Aabb`] component to entities with a
+/// Computes and adds an [`Aabb`] component to entities with a
 /// [`Handle<Mesh>`](Mesh) component and without a [`NoFrustumCulling`] component.
 ///
-/// Used in system set [`VisibilitySystems::CalculateBounds`].
+/// This system is used in system set [`VisibilitySystems::CalculateBounds`].
 pub fn calculate_bounds(
     mut commands: Commands,
     meshes: Res<Assets<Mesh>>,
@@ -277,11 +282,9 @@ 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.
+/// Updates [`Frustum`].
 ///
-/// Used in system sets [`VisibilitySystems::UpdateProjectionFrusta`],
+/// This system is used in system sets [`VisibilitySystems::UpdateProjectionFrusta`],
 /// [`VisibilitySystems::UpdatePerspectiveFrusta`], and
 /// [`VisibilitySystems::UpdateOrthographicFrusta`].
 pub fn update_frusta<T: Component + CameraProjection + Send + Sync + 'static>(
@@ -359,9 +362,9 @@ fn propagate_recursive(
     Ok(())
 }
 
-/// System updating the visibility of entities each frame.
+/// Updates the visibility of entities each frame.
 ///
-/// The system is part of the [`VisibilitySystems::CheckVisibility`] set. Each frame, it updates the
+/// This system is part of the [`VisibilitySystems::CheckVisibility`] set. Each frame, it updates the
 /// [`ComputedVisibility`] of all entities, and for each view also compute the [`VisibleEntities`]
 /// for that view.
 pub fn check_visibility(