From 6c4f8aa19967b475a1048d1a61ef293998a93027 Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Thu, 1 Jun 2023 17:38:49 -0400
Subject: [PATCH 01/13] Refactor Plane struct

---
 crates/bevy_pbr/src/light.rs             | 22 ++++----
 crates/bevy_render/src/primitives/mod.rs | 66 ++++++++++++------------
 2 files changed, 46 insertions(+), 42 deletions(-)

diff --git a/crates/bevy_pbr/src/light.rs b/crates/bevy_pbr/src/light.rs
index 05bab2296551c..fd2782a6d0a9b 100644
--- a/crates/bevy_pbr/src/light.rs
+++ b/crates/bevy_pbr/src/light.rs
@@ -8,7 +8,7 @@ use bevy_render::{
     color::Color,
     extract_resource::ExtractResource,
     prelude::Projection,
-    primitives::{Aabb, CascadesFrusta, CubemapFrusta, Frustum, Plane, Sphere},
+    primitives::{Aabb, CascadesFrusta, CubemapFrusta, Frustum, HalfSpace, Sphere},
     render_resource::BufferBindingType,
     renderer::RenderDevice,
     view::{ComputedVisibility, RenderLayers, VisibleEntities},
@@ -1457,7 +1457,7 @@ pub(crate) fn assign_lights_to_clusters(
                 let view_x = clip_to_view(inverse_projection, Vec4::new(x_pos, 0.0, 1.0, 1.0)).x;
                 let normal = Vec3::X;
                 let d = view_x * normal.x;
-                x_planes.push(Plane::new(normal.extend(d)));
+                x_planes.push(HalfSpace::new(normal.extend(d)));
             }
 
             let y_slices = clusters.dimensions.y as f32;
@@ -1467,7 +1467,7 @@ pub(crate) fn assign_lights_to_clusters(
                 let view_y = clip_to_view(inverse_projection, Vec4::new(0.0, y_pos, 1.0, 1.0)).y;
                 let normal = Vec3::Y;
                 let d = view_y * normal.y;
-                y_planes.push(Plane::new(normal.extend(d)));
+                y_planes.push(HalfSpace::new(normal.extend(d)));
             }
         } else {
             let x_slices = clusters.dimensions.x as f32;
@@ -1478,7 +1478,7 @@ pub(crate) fn assign_lights_to_clusters(
                 let nt = clip_to_view(inverse_projection, Vec4::new(x_pos, 1.0, 1.0, 1.0)).xyz();
                 let normal = nb.cross(nt);
                 let d = nb.dot(normal);
-                x_planes.push(Plane::new(normal.extend(d)));
+                x_planes.push(HalfSpace::new(normal.extend(d)));
             }
 
             let y_slices = clusters.dimensions.y as f32;
@@ -1489,7 +1489,7 @@ pub(crate) fn assign_lights_to_clusters(
                 let nr = clip_to_view(inverse_projection, Vec4::new(1.0, y_pos, 1.0, 1.0)).xyz();
                 let normal = nr.cross(nl);
                 let d = nr.dot(normal);
-                y_planes.push(Plane::new(normal.extend(d)));
+                y_planes.push(HalfSpace::new(normal.extend(d)));
             }
         }
 
@@ -1498,7 +1498,7 @@ pub(crate) fn assign_lights_to_clusters(
             let view_z = z_slice_to_view_z(first_slice_depth, far_z, z_slices, z, is_orthographic);
             let normal = -Vec3::Z;
             let d = view_z * normal.z;
-            z_planes.push(Plane::new(normal.extend(d)));
+            z_planes.push(HalfSpace::new(normal.extend(d)));
         }
 
         let mut update_from_light_intersections = |visible_lights: &mut Vec<Entity>| {
@@ -1737,7 +1737,7 @@ pub(crate) fn assign_lights_to_clusters(
 }
 
 // NOTE: This exploits the fact that a x-plane normal has only x and z components
-fn get_distance_x(plane: Plane, point: Vec3A, is_orthographic: bool) -> f32 {
+fn get_distance_x(plane: HalfSpace, point: Vec3A, is_orthographic: bool) -> f32 {
     if is_orthographic {
         point.x - plane.d()
     } else {
@@ -1750,7 +1750,7 @@ fn get_distance_x(plane: Plane, point: Vec3A, is_orthographic: bool) -> f32 {
 }
 
 // NOTE: This exploits the fact that a z-plane normal has only a z component
-fn project_to_plane_z(z_light: Sphere, z_plane: Plane) -> Option<Sphere> {
+fn project_to_plane_z(z_light: Sphere, z_plane: HalfSpace) -> Option<Sphere> {
     // p = sphere center
     // n = plane normal
     // d = n.p if p is in the plane
@@ -1772,7 +1772,11 @@ fn project_to_plane_z(z_light: Sphere, z_plane: Plane) -> Option<Sphere> {
 }
 
 // NOTE: This exploits the fact that a y-plane normal has only y and z components
-fn project_to_plane_y(y_light: Sphere, y_plane: Plane, is_orthographic: bool) -> Option<Sphere> {
+fn project_to_plane_y(
+    y_light: Sphere,
+    y_plane: HalfSpace,
+    is_orthographic: bool,
+) -> Option<Sphere> {
     let distance_to_plane = if is_orthographic {
         y_plane.d() - y_light.center.y
     } else {
diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 4bf88cda080ce..7b5283f7e2e9c 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -81,17 +81,17 @@ impl Sphere {
     }
 }
 
-/// A plane defined by a unit normal and distance from the origin along the normal
-/// Any point `p` is in the plane if `n.p + d = 0`
-/// For planes defining half-spaces such as for frusta, if `n.p + d > 0` then `p` is on
+/// A half-space defined by a unit normal and distance from the origin along the normal
+/// Any point `p` is in the half-space if `n.p + d = 0`
+/// When defining half-spaces such as for frusta, if `n.p + d > 0` then `p` is on
 /// the positive side (inside) of the plane.
 #[derive(Clone, Copy, Debug, Default)]
-pub struct Plane {
+pub struct HalfSpace {
     normal_d: Vec4,
 }
 
-impl Plane {
-    /// Constructs a `Plane` from a 4D vector whose first 3 components
+impl HalfSpace {
+    /// Constructs a `HalfSpace` from a 4D vector whose first 3 components
     /// are the normal and whose last component is the distance along the normal
     /// from the origin.
     /// This constructor ensures that the normal is normalized and the distance is
@@ -103,21 +103,21 @@ impl Plane {
         }
     }
 
-    /// `Plane` unit normal
+    /// `HalfSpace` unit normal
     #[inline]
     pub fn normal(&self) -> Vec3A {
         Vec3A::from(self.normal_d)
     }
 
     /// Signed distance from the origin along the unit normal such that n.p + d = 0 for point p in
-    /// the `Plane`
+    /// the `HalfSpace`
     #[inline]
     pub fn d(&self) -> f32 {
         self.normal_d.w
     }
 
-    /// `Plane` unit normal and signed distance from the origin such that n.p + d = 0 for point p
-    /// in the `Plane`
+    /// `HalfSpace` unit normal and signed distance from the origin such that n.p + d = 0 for point p
+    /// in the `HalfSpace`
     #[inline]
     pub fn normal_d(&self) -> Vec4 {
         self.normal_d
@@ -131,7 +131,7 @@ impl Plane {
 #[reflect(Component)]
 pub struct Frustum {
     #[reflect(ignore)]
-    pub planes: [Plane; 6],
+    pub planes: [HalfSpace; 6],
 }
 
 impl Frustum {
@@ -139,7 +139,7 @@ impl Frustum {
     #[inline]
     pub fn from_view_projection(view_projection: &Mat4) -> Self {
         let mut frustum = Frustum::from_view_projection_no_far(view_projection);
-        frustum.planes[5] = Plane::new(view_projection.row(2));
+        frustum.planes[5] = HalfSpace::new(view_projection.row(2));
         frustum
     }
 
@@ -154,7 +154,7 @@ impl Frustum {
     ) -> Self {
         let mut frustum = Frustum::from_view_projection_no_far(view_projection);
         let far_center = *view_translation - far * *view_backward;
-        frustum.planes[5] = Plane::new(view_backward.extend(-view_backward.dot(far_center)));
+        frustum.planes[5] = HalfSpace::new(view_backward.extend(-view_backward.dot(far_center)));
         frustum
     }
 
@@ -163,10 +163,10 @@ impl Frustum {
     // Rendering by Lengyel.
     fn from_view_projection_no_far(view_projection: &Mat4) -> Self {
         let row3 = view_projection.row(3);
-        let mut planes = [Plane::default(); 6];
+        let mut planes = [HalfSpace::default(); 6];
         for (i, plane) in planes.iter_mut().enumerate().take(5) {
             let row = view_projection.row(i / 2);
-            *plane = Plane::new(if (i & 1) == 0 && i != 4 {
+            *plane = HalfSpace::new(if (i & 1) == 0 && i != 4 {
                 row3 + row
             } else {
                 row3 - row
@@ -250,12 +250,12 @@ mod tests {
     fn big_frustum() -> Frustum {
         Frustum {
             planes: [
-                Plane::new(Vec4::new(-0.9701, -0.2425, -0.0000, 7.7611)),
-                Plane::new(Vec4::new(-0.0000, 1.0000, -0.0000, 4.0000)),
-                Plane::new(Vec4::new(-0.0000, -0.2425, -0.9701, 2.9104)),
-                Plane::new(Vec4::new(-0.0000, -1.0000, -0.0000, 4.0000)),
-                Plane::new(Vec4::new(-0.0000, -0.2425, 0.9701, 2.9104)),
-                Plane::new(Vec4::new(0.9701, -0.2425, -0.0000, -1.9403)),
+                HalfSpace::new(Vec4::new(-0.9701, -0.2425, -0.0000, 7.7611)),
+                HalfSpace::new(Vec4::new(-0.0000, 1.0000, -0.0000, 4.0000)),
+                HalfSpace::new(Vec4::new(-0.0000, -0.2425, -0.9701, 2.9104)),
+                HalfSpace::new(Vec4::new(-0.0000, -1.0000, -0.0000, 4.0000)),
+                HalfSpace::new(Vec4::new(-0.0000, -0.2425, 0.9701, 2.9104)),
+                HalfSpace::new(Vec4::new(0.9701, -0.2425, -0.0000, -1.9403)),
             ],
         }
     }
@@ -286,12 +286,12 @@ mod tests {
     fn frustum() -> Frustum {
         Frustum {
             planes: [
-                Plane::new(Vec4::new(-0.9701, -0.2425, -0.0000, 0.7276)),
-                Plane::new(Vec4::new(-0.0000, 1.0000, -0.0000, 1.0000)),
-                Plane::new(Vec4::new(-0.0000, -0.2425, -0.9701, 0.7276)),
-                Plane::new(Vec4::new(-0.0000, -1.0000, -0.0000, 1.0000)),
-                Plane::new(Vec4::new(-0.0000, -0.2425, 0.9701, 0.7276)),
-                Plane::new(Vec4::new(0.9701, -0.2425, -0.0000, 0.7276)),
+                HalfSpace::new(Vec4::new(-0.9701, -0.2425, -0.0000, 0.7276)),
+                HalfSpace::new(Vec4::new(-0.0000, 1.0000, -0.0000, 1.0000)),
+                HalfSpace::new(Vec4::new(-0.0000, -0.2425, -0.9701, 0.7276)),
+                HalfSpace::new(Vec4::new(-0.0000, -1.0000, -0.0000, 1.0000)),
+                HalfSpace::new(Vec4::new(-0.0000, -0.2425, 0.9701, 0.7276)),
+                HalfSpace::new(Vec4::new(0.9701, -0.2425, -0.0000, 0.7276)),
             ],
         }
     }
@@ -366,12 +366,12 @@ mod tests {
     fn long_frustum() -> Frustum {
         Frustum {
             planes: [
-                Plane::new(Vec4::new(-0.9998, -0.0222, -0.0000, -1.9543)),
-                Plane::new(Vec4::new(-0.0000, 1.0000, -0.0000, 45.1249)),
-                Plane::new(Vec4::new(-0.0000, -0.0168, -0.9999, 2.2718)),
-                Plane::new(Vec4::new(-0.0000, -1.0000, -0.0000, 45.1249)),
-                Plane::new(Vec4::new(-0.0000, -0.0168, 0.9999, 2.2718)),
-                Plane::new(Vec4::new(0.9998, -0.0222, -0.0000, 7.9528)),
+                HalfSpace::new(Vec4::new(-0.9998, -0.0222, -0.0000, -1.9543)),
+                HalfSpace::new(Vec4::new(-0.0000, 1.0000, -0.0000, 45.1249)),
+                HalfSpace::new(Vec4::new(-0.0000, -0.0168, -0.9999, 2.2718)),
+                HalfSpace::new(Vec4::new(-0.0000, -1.0000, -0.0000, 45.1249)),
+                HalfSpace::new(Vec4::new(-0.0000, -0.0168, 0.9999, 2.2718)),
+                HalfSpace::new(Vec4::new(0.9998, -0.0222, -0.0000, 7.9528)),
             ],
         }
     }

From 4958bc84e28a9e01d480294871fbc53a50ffeef4 Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Fri, 2 Jun 2023 11:58:55 -0400
Subject: [PATCH 02/13] Adjust HalfSpace documentation

---
 crates/bevy_render/src/primitives/mod.rs | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 7b5283f7e2e9c..34934d46463fe 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -82,9 +82,8 @@ impl Sphere {
 }
 
 /// A half-space defined by a unit normal and distance from the origin along the normal
-/// Any point `p` is in the half-space if `n.p + d = 0`
-/// When defining half-spaces such as for frusta, if `n.p + d > 0` then `p` is on
-/// the positive side (inside) of the plane.
+/// Any point `p` is considered to be within the half-space,
+/// or on the positive side (inside) of the plane, if the equation n.p + d > 0 is satisfied.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct HalfSpace {
     normal_d: Vec4,

From ddde5ace08b6c9d075b9ecda00203d5b20050b17 Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Fri, 2 Jun 2023 12:00:51 -0400
Subject: [PATCH 03/13] fmt

---
 crates/bevy_render/src/primitives/mod.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 34934d46463fe..409b1f17473a1 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -83,7 +83,7 @@ impl Sphere {
 
 /// A half-space defined by a unit normal and distance from the origin along the normal
 /// Any point `p` is considered to be within the half-space,
-/// or on the positive side (inside) of the plane, if the equation n.p + d > 0 is satisfied.
+/// or on the positive side (inside) of the plane, if the equation `n.p + d > 0` is satisfied.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct HalfSpace {
     normal_d: Vec4,

From 5e12dffe306f8e9ad93204d22c5e08c5681f15ab Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Mon, 5 Jun 2023 18:57:20 -0400
Subject: [PATCH 04/13] Reword HalfSpace documentation

---
 crates/bevy_render/src/primitives/mod.rs | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 409b1f17473a1..ba56adbb46659 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -81,9 +81,10 @@ impl Sphere {
     }
 }
 
-/// A half-space defined by a unit normal and distance from the origin along the normal
-/// Any point `p` is considered to be within the half-space,
-/// or on the positive side (inside) of the plane, if the equation `n.p + d > 0` is satisfied.
+/// A HalfSpace, characterized by the bisecting plane's unit normal and distance from the origin along the normal.
+/// This bisecting plane partitions the 3D space into two regions.
+/// 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.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct HalfSpace {
     normal_d: Vec4,
@@ -91,10 +92,9 @@ pub struct HalfSpace {
 
 impl HalfSpace {
     /// Constructs a `HalfSpace` from a 4D vector whose first 3 components
-    /// are the normal and whose last component is the distance along the normal
-    /// from the origin.
-    /// This constructor ensures that the normal is normalized and the distance is
-    /// scaled accordingly so it represents the signed distance from the origin.
+    /// represent the bisecting plane's unit normal, and the last component signifies
+    /// the distance from the origin to the plane 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 {
         Self {
@@ -102,21 +102,21 @@ impl HalfSpace {
         }
     }
 
-    /// `HalfSpace` unit normal
+    /// Returns the unit normal vector of the bisecting plane that characterizes the `HalfSpace`.
     #[inline]
     pub fn normal(&self) -> Vec3A {
         Vec3A::from(self.normal_d)
     }
 
-    /// Signed distance from the origin along the unit normal such that n.p + d = 0 for point p in
-    /// the `HalfSpace`
+    /// 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`.
     #[inline]
     pub fn d(&self) -> f32 {
         self.normal_d.w
     }
 
-    /// `HalfSpace` unit normal and signed distance from the origin such that n.p + d = 0 for point p
-    /// in the `HalfSpace`
+    /// Returns the bisecting plane's unit normal vector and the distance from the origin to the plane.
+    /// The returned 4D vector embodies the key properties of the bisecting plane that characterizes the `HalfSpace`.
     #[inline]
     pub fn normal_d(&self) -> Vec4 {
         self.normal_d

From 9b1b92f992d999553ab077d56d648b87784dd211 Mon Sep 17 00:00:00 2001
From: lelo <15314665+hate@users.noreply.github.com>
Date: Mon, 5 Jun 2023 20:12:08 -0400
Subject: [PATCH 05/13] Update crates/bevy_render/src/primitives/mod.rs

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
---
 crates/bevy_render/src/primitives/mod.rs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index ba56adbb46659..f50732cee7858 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -81,8 +81,9 @@ impl Sphere {
     }
 }
 
-/// A HalfSpace, characterized by the bisecting plane's unit normal and distance from the origin along the normal.
-/// This bisecting plane partitions the 3D space into two regions.
+/// A bisecting plane that partitions 3D space into two regions.
+///
+/// Mathematically, 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.
 #[derive(Clone, Copy, Debug, Default)]

From 997a5bb1e34a3928f56cbf152c803feb3b4857be Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Tue, 6 Jun 2023 15:32:21 -0400
Subject: [PATCH 06/13] Add backticks

---
 crates/bevy_render/src/primitives/mod.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index f50732cee7858..1cc59f5fa03e3 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -84,7 +84,7 @@ impl Sphere {
 /// A bisecting plane that partitions 3D space into two regions.
 ///
 /// Mathematically, 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,
+/// 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.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct HalfSpace {

From 576ac98ce0f5628e1753a9acc1bd4f3082e35e51 Mon Sep 17 00:00:00 2001
From: lelo <15314665+hate@users.noreply.github.com>
Date: Wed, 7 Jun 2023 11:17:46 -0400
Subject: [PATCH 07/13] Update crates/bevy_render/src/primitives/mod.rs

Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
---
 crates/bevy_render/src/primitives/mod.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 1cc59f5fa03e3..4cdb04d28f697 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -83,7 +83,7 @@ impl Sphere {
 
 /// A bisecting plane that partitions 3D space into two regions.
 ///
-/// Mathematically, each instance of this type is characterized by the bisecting plane's unit normal and distance from the origin along the normal.
+/// 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.
 #[derive(Clone, Copy, Debug, Default)]

From dfc862bc7c60cc5d3bc4ab46371e8dc8543a1784 Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Wed, 7 Jun 2023 11:41:34 -0400
Subject: [PATCH 08/13] remove line

---
 crates/bevy_render/src/primitives/mod.rs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 4cdb04d28f697..33703d3c80013 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -117,7 +117,6 @@ impl HalfSpace {
     }
 
     /// Returns the bisecting plane's unit normal vector and the distance from the origin to the plane.
-    /// The returned 4D vector embodies the key properties of the bisecting plane that characterizes the `HalfSpace`.
     #[inline]
     pub fn normal_d(&self) -> Vec4 {
         self.normal_d

From d9469e77b70a00637a4fe46c7af9f4743b843cd1 Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Wed, 7 Jun 2023 12:56:55 -0400
Subject: [PATCH 09/13] Adjust Frustum documentation

---
 crates/bevy_render/src/primitives/mod.rs | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 33703d3c80013..ee8d470719869 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -123,9 +123,9 @@ impl HalfSpace {
     }
 }
 
-/// A frustum defined by the 6 containing planes
-/// Planes are ordered left, right, top, bottom, near, far
-/// Normals point into the contained volume
+/// A frustum defined by 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.
 #[derive(Component, Clone, Copy, Debug, Default, Reflect)]
 #[reflect(Component)]
 pub struct Frustum {
@@ -142,8 +142,8 @@ impl Frustum {
         frustum
     }
 
-    /// Returns a frustum derived from `view_projection`, but with a custom
-    /// far plane.
+    /// Returns a frustum derived from `view_projection`,
+    /// but with a custom far plane.
     #[inline]
     pub fn from_view_projection_custom_far(
         view_projection: &Mat4,
@@ -157,7 +157,7 @@ impl Frustum {
         frustum
     }
 
-    // NOTE: This approach of extracting the frustum planes from the view
+    // NOTE: This approach of extracting the frustum HalfSpaces from the view
     // projection matrix is from Foundations of Game Engine Development 2
     // Rendering by Lengyel.
     fn from_view_projection_no_far(view_projection: &Mat4) -> Self {
@@ -174,6 +174,7 @@ impl Frustum {
         Self { planes }
     }
 
+    /// Checks if a sphere intersects the frustum.
     #[inline]
     pub fn intersects_sphere(&self, sphere: &Sphere, intersect_far: bool) -> bool {
         let sphere_center = sphere.center.extend(1.0);
@@ -186,6 +187,7 @@ impl Frustum {
         true
     }
 
+    /// Checks if an Oriented Bounding Box (obb) intersects the frustum.
     #[inline]
     pub fn intersects_obb(
         &self,

From cdbb26cf7a32e96a53839511d8cef43727e75740 Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Wed, 7 Jun 2023 12:58:51 -0400
Subject: [PATCH 10/13] Grammar

---
 crates/bevy_render/src/primitives/mod.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index ee8d470719869..c0d294eba9158 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -123,7 +123,7 @@ impl HalfSpace {
     }
 }
 
-/// A frustum defined by the 6 defining half spaces.
+/// 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.
 #[derive(Component, Clone, Copy, Debug, Default, Reflect)]

From 45b78e79c56073513f06f3970c02a4a9b7651a1b Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Wed, 7 Jun 2023 13:11:43 -0400
Subject: [PATCH 11/13] Rename planes member to half_spaces

---
 crates/bevy_render/src/primitives/mod.rs | 31 ++++++++++++------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index c0d294eba9158..3d79b04b4ac40 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -130,7 +130,7 @@ impl HalfSpace {
 #[reflect(Component)]
 pub struct Frustum {
     #[reflect(ignore)]
-    pub planes: [HalfSpace; 6],
+    pub half_spaces: [HalfSpace; 6],
 }
 
 impl Frustum {
@@ -138,7 +138,7 @@ impl Frustum {
     #[inline]
     pub fn from_view_projection(view_projection: &Mat4) -> Self {
         let mut frustum = Frustum::from_view_projection_no_far(view_projection);
-        frustum.planes[5] = HalfSpace::new(view_projection.row(2));
+        frustum.half_spaces[5] = HalfSpace::new(view_projection.row(2));
         frustum
     }
 
@@ -153,7 +153,8 @@ impl Frustum {
     ) -> Self {
         let mut frustum = Frustum::from_view_projection_no_far(view_projection);
         let far_center = *view_translation - far * *view_backward;
-        frustum.planes[5] = HalfSpace::new(view_backward.extend(-view_backward.dot(far_center)));
+        frustum.half_spaces[5] =
+            HalfSpace::new(view_backward.extend(-view_backward.dot(far_center)));
         frustum
     }
 
@@ -162,16 +163,16 @@ impl Frustum {
     // Rendering by Lengyel.
     fn from_view_projection_no_far(view_projection: &Mat4) -> Self {
         let row3 = view_projection.row(3);
-        let mut planes = [HalfSpace::default(); 6];
-        for (i, plane) in planes.iter_mut().enumerate().take(5) {
+        let mut half_spaces = [HalfSpace::default(); 6];
+        for (i, half_space) in half_spaces.iter_mut().enumerate().take(5) {
             let row = view_projection.row(i / 2);
-            *plane = HalfSpace::new(if (i & 1) == 0 && i != 4 {
+            *half_space = HalfSpace::new(if (i & 1) == 0 && i != 4 {
                 row3 + row
             } else {
                 row3 - row
             });
         }
-        Self { planes }
+        Self { half_spaces }
     }
 
     /// Checks if a sphere intersects the frustum.
@@ -179,8 +180,8 @@ impl Frustum {
     pub fn intersects_sphere(&self, sphere: &Sphere, intersect_far: bool) -> bool {
         let sphere_center = sphere.center.extend(1.0);
         let max = if intersect_far { 6 } else { 5 };
-        for plane in &self.planes[..max] {
-            if plane.normal_d().dot(sphere_center) + sphere.radius <= 0.0 {
+        for half_space in &self.half_spaces[..max] {
+            if half_space.normal_d().dot(sphere_center) + sphere.radius <= 0.0 {
                 return false;
             }
         }
@@ -203,16 +204,16 @@ impl Frustum {
             Vec3A::from(model_to_world.z_axis),
         ];
 
-        for (idx, plane) in self.planes.into_iter().enumerate() {
+        for (idx, half_space) in self.half_spaces.into_iter().enumerate() {
             if idx == 4 && !intersect_near {
                 continue;
             }
             if idx == 5 && !intersect_far {
                 continue;
             }
-            let p_normal = plane.normal();
+            let p_normal = half_space.normal();
             let relative_radius = aabb.relative_radius(&p_normal, &axes);
-            if plane.normal_d().dot(aabb_center_world) + relative_radius <= 0.0 {
+            if half_space.normal_d().dot(aabb_center_world) + relative_radius <= 0.0 {
                 return false;
             }
         }
@@ -250,7 +251,7 @@ mod tests {
     // A big, offset frustum
     fn big_frustum() -> Frustum {
         Frustum {
-            planes: [
+            half_spaces: [
                 HalfSpace::new(Vec4::new(-0.9701, -0.2425, -0.0000, 7.7611)),
                 HalfSpace::new(Vec4::new(-0.0000, 1.0000, -0.0000, 4.0000)),
                 HalfSpace::new(Vec4::new(-0.0000, -0.2425, -0.9701, 2.9104)),
@@ -286,7 +287,7 @@ mod tests {
     // A frustum
     fn frustum() -> Frustum {
         Frustum {
-            planes: [
+            half_spaces: [
                 HalfSpace::new(Vec4::new(-0.9701, -0.2425, -0.0000, 0.7276)),
                 HalfSpace::new(Vec4::new(-0.0000, 1.0000, -0.0000, 1.0000)),
                 HalfSpace::new(Vec4::new(-0.0000, -0.2425, -0.9701, 0.7276)),
@@ -366,7 +367,7 @@ mod tests {
     // A long frustum.
     fn long_frustum() -> Frustum {
         Frustum {
-            planes: [
+            half_spaces: [
                 HalfSpace::new(Vec4::new(-0.9998, -0.0222, -0.0000, -1.9543)),
                 HalfSpace::new(Vec4::new(-0.0000, 1.0000, -0.0000, 45.1249)),
                 HalfSpace::new(Vec4::new(-0.0000, -0.0168, -0.9999, 2.2718)),

From d13eea9e065ac28594f99e5b5a035bf8c67da321 Mon Sep 17 00:00:00 2001
From: lelo <15314665+hate@users.noreply.github.com>
Date: Thu, 8 Jun 2023 01:30:44 -0400
Subject: [PATCH 12/13] Update crates/bevy_render/src/primitives/mod.rs

Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
---
 crates/bevy_render/src/primitives/mod.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 3d79b04b4ac40..983ab945aacf0 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -158,7 +158,7 @@ impl Frustum {
         frustum
     }
 
-    // NOTE: This approach of extracting the frustum HalfSpaces from the view
+    // NOTE: This approach of extracting the frustum half-space from the view
     // projection matrix is from Foundations of Game Engine Development 2
     // Rendering by Lengyel.
     fn from_view_projection_no_far(view_projection: &Mat4) -> Self {

From 478cbad3a39705bd0ac63703df8237a2ff08caa6 Mon Sep 17 00:00:00 2001
From: hate <15314665+hate@users.noreply.github.com>
Date: Thu, 8 Jun 2023 01:36:34 -0400
Subject: [PATCH 13/13] add missing documentation

---
 crates/bevy_render/src/primitives/mod.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/crates/bevy_render/src/primitives/mod.rs b/crates/bevy_render/src/primitives/mod.rs
index 983ab945aacf0..5beee4936d3cd 100644
--- a/crates/bevy_render/src/primitives/mod.rs
+++ b/crates/bevy_render/src/primitives/mod.rs
@@ -161,6 +161,8 @@ impl Frustum {
     // NOTE: This approach of extracting the frustum half-space from the view
     // projection matrix is from Foundations of Game Engine Development 2
     // Rendering by Lengyel.
+    /// Returns a frustum derived from `view_projection`,
+    /// without a far plane.
     fn from_view_projection_no_far(view_projection: &Mat4) -> Self {
         let row3 = view_projection.row(3);
         let mut half_spaces = [HalfSpace::default(); 6];