Ring shape primitive (#21446)

# Objective

This introduces a generalised 2d `Ring` shape for any underlying
primitive (i.e. what an `Annulus` is to a `Circle`). This allows us to
have "hollow" shapes or "outlines". `Ring` is also extrudable. It is
assumed that the inner and outer meshes have the same number of
vertices.

```rs
let capsule_ring = Ring::new(Capsule2d::new(50.0, 100.0), Capsule2d::new(45.0, 100.0));
let hexagon_ring = Ring::new(RegularPolygon::new(50.0, 6), RegularPolygon::new(45.0, 6)); // note vertex count must match
```

## Solution

There is a new generic primitive `Ring`, which takes as input any
`Primitive2d`, with two instances of that shape: the outer and the inner
(or hollow).

The mesh for a `RingMeshBuilder` is constructed by concatenating the
vertices of the outer and inner meshes, then walking the perimeter to
join corresponding vertices like so:

<img width="513" height="509" alt="image"
src="https://github.com/user-attachments/assets/2cecb458-3b59-44fb-858b-1beffecd1e57"
/>

```
# outer vertices, then inner vertices
positions = [
  0  1  2  3  4
  0' 1' 2' 3' 4'
]
# pairs of triangles
indices = [
  0  1  0'    0' 1  1'
  1  2  1'    1' 2  2'
  2  3  2'    2' 3  3'
  3  4  3'    3' 4  4'
  4  0  4'    4' 0  0'
]
```

Examples of generated meshes:

<img width="398" height="351" alt="image"
src="https://github.com/user-attachments/assets/348bbd91-9f4e-4040-bfa5-d508a4308c10"
/>

<img width="472" height="376" alt="image"
src="https://github.com/user-attachments/assets/dbaf894e-6f7f-4b79-af3e-69516da85898"
/>

<img width="388" height="357" alt="image"
src="https://github.com/user-attachments/assets/cb9881e5-4518-4743-b8de-5816b632f36f"
/>

<img width="449" height="402" alt="image"
src="https://github.com/user-attachments/assets/7d2022c9-b8cf-4b4b-bb09-cbe4fe49fb89"
/>

## Testing

I've tested these changes by updating the `2d_shapes`, `3d_shapes` and
`custom_primitives` examples.

It could potentially benefit from unit tests.

---

## Showcase

<img width="1282" height="752" alt="image"
src="https://github.com/user-attachments/assets/edab9dbf-1093-43c7-9804-8e5c8a830573"
/>

_Rings of 2d primitives (bottom row)_

<img width="1282" height="752" alt="image"
src="https://github.com/user-attachments/assets/fbeed7f9-42bb-432c-bce9-cfeca87d70af"
/>

_Extrusions of rings of extrudable primitives (back row)_

---

## Follow-up work

I've only realised this from looking at Extrudable, but because I used
the mesh positions but it does assume the positions are well-ordered
around the perimeter. Extrudable instead uses the notion of a perimeter
(via indices so it doesn't matter what order the mesh positions are in),
a follow-up may be to do something similar for Ring. An alternative idea
may be to compute the perimeter first as directly a list of Vec2
positions (maybe a Perimeter trait), then construct any needed meshes
from that.

This potentially makes `Annulus` redundant as it is equivalent to a
`Ring<Circle>`. One thing of note is that `Extrusion<Annulus>` is
textured differently from `Extrusion<Ring<Circle>>`.

Another idea is to have a way to construct `PrimitiveTopology::LineList`
meshes from Primitive shapes (which may have a similar effect as
creating a Ring).

Author: tigregalis

crates/bevy_math/src/bounding/bounded2d/primitive_impls.rs

@@ -5,7 +5,7 @@ use crate::{
     ops,
     primitives::{
         Annulus, Arc2d, Capsule2d, Circle, CircularSector, CircularSegment, Ellipse, Line2d,
-        Plane2d, Rectangle, RegularPolygon, Rhombus, Segment2d, Triangle2d,
+        Plane2d, Primitive2d, Rectangle, RegularPolygon, Rhombus, Ring, Segment2d, Triangle2d,
     },
     Dir2, Isometry2d, Mat2, Rot2, Vec2,
 };
@@ -428,6 +428,16 @@ impl Bounded2d for Capsule2d {
     }
 }
 
+impl<P: Bounded2d + Primitive2d> Bounded2d for Ring<P> {
+    fn aabb_2d(&self, isometry: impl Into<Isometry2d>) -> Aabb2d {
+        self.outer_shape.aabb_2d(isometry)
+    }
+
+    fn bounding_circle(&self, isometry: impl Into<Isometry2d>) -> BoundingCircle {
+        self.outer_shape.bounding_circle(isometry)
+    }
+}
+
 #[cfg(test)]
 #[expect(clippy::print_stdout, reason = "Allowed in tests.")]
 mod tests {

crates/bevy_math/src/bounding/bounded3d/extrusion.rs

@@ -7,7 +7,7 @@ use crate::{
     ops,
     primitives::{
         Capsule2d, Cuboid, Cylinder, Ellipse, Extrusion, Line2d, Primitive2d, Rectangle,
-        RegularPolygon, Segment2d, Triangle2d,
+        RegularPolygon, Ring, Segment2d, Triangle2d,
     },
     Isometry2d, Isometry3d, Quat, Rot2,
 };
@@ -165,6 +165,21 @@ impl BoundedExtrusion for Capsule2d {
     }
 }
 
+impl<T: BoundedExtrusion> BoundedExtrusion for Ring<T> {
+    fn extrusion_aabb_3d(&self, half_depth: f32, isometry: impl Into<Isometry3d>) -> Aabb3d {
+        self.outer_shape.extrusion_aabb_3d(half_depth, isometry)
+    }
+
+    fn extrusion_bounding_sphere(
+        &self,
+        half_depth: f32,
+        isometry: impl Into<Isometry3d>,
+    ) -> BoundingSphere {
+        self.outer_shape
+            .extrusion_bounding_sphere(half_depth, isometry)
+    }
+}
+
 impl<T: BoundedExtrusion> Bounded3d for Extrusion<T> {
     fn aabb_3d(&self, isometry: impl Into<Isometry3d>) -> Aabb3d {
         self.base_shape.extrusion_aabb_3d(self.half_depth, isometry)

crates/bevy_math/src/primitives/dim2.rs

@@ -6,6 +6,7 @@ use thiserror::Error;
 use super::{Measured2d, Primitive2d, WindingOrder};
 use crate::{
     ops::{self, FloatPow},
+    primitives::Inset,
     Dir2, InvalidDirectionError, Isometry2d, Ray2d, Rot2, Vec2,
 };
 
@@ -468,11 +469,11 @@ impl Measured2d for CircularSegment {
 }
 
 impl CircularSegment {
-    /// Create a new [`CircularSegment`] from a `radius`, and an `angle`
+    /// Create a new [`CircularSegment`] from a `radius`, and a `half_angle` in radians.
     #[inline]
-    pub const fn new(radius: f32, angle: f32) -> Self {
+    pub const fn new(radius: f32, half_angle: f32) -> Self {
         Self {
-            arc: Arc2d::new(radius, angle),
+            arc: Arc2d::new(radius, half_angle),
         }
     }
 
@@ -793,6 +794,9 @@ mod arc_tests {
 }
 
 /// An ellipse primitive, which is like a circle, but the width and height can be different
+///
+/// Ellipse does not implement [`Inset`] as concentric ellipses do not have parallel curves:
+/// if the ellipse is not a circle, the inset shape is not actually an ellipse (although it may look like one) but can also be a lens-like shape.
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(
@@ -2234,6 +2238,71 @@ impl Measured2d for Capsule2d {
     }
 }
 
+/// A 2D shape representing the ring version of a base shape.
+///
+/// The `inner_shape` forms the "hollow" of the `outer_shape`.
+///
+/// The resulting shapes are rings or hollow shapes.
+/// For example, a circle becomes an annulus.
+///
+/// # Warning
+///
+/// The `outer_shape` must contain the `inner_shape` for the generated meshes to be accurate.
+///
+/// If there are vertices in the `inner_shape` that escape the `outer_shape`
+/// (for example, if the `inner_shape` is in fact larger),
+/// it may result in incorrect geometries.
+#[derive(Clone, Copy, Debug, PartialEq)]
+#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
+pub struct Ring<P: Primitive2d> {
+    /// The outer shape
+    pub outer_shape: P,
+    /// The inner shape (the same shape of a different size)
+    pub inner_shape: P,
+}
+
+impl<P: Primitive2d> Ring<P> {
+    /// Create a new `Ring` from a given `outer_shape` and `inner_shape`.
+    ///
+    /// If the primitive implements [`Inset`] and you would like a uniform thickness, consider using [`ToRing::to_ring`]
+    pub const fn new(outer_shape: P, inner_shape: P) -> Self {
+        Self {
+            outer_shape,
+            inner_shape,
+        }
+    }
+}
+
+impl<T: Primitive2d> Primitive2d for Ring<T> {}
+
+impl<P: Primitive2d + Clone + Inset> Ring<P> {
+    /// Generate a `Ring` from a given `primitive` and a `thickness`.
+    pub fn from_primitive_and_thickness(primitive: P, thickness: f32) -> Self {
+        let hollow = primitive.clone().inset(thickness);
+        Ring::new(primitive, hollow)
+    }
+}
+
+/// Provides a convenience method for converting a primitive to a [`Ring`], with a given thickness.
+///
+/// The primitive must implement [`Inset`].
+pub trait ToRing: Primitive2d + Inset
+where
+    Self: Sized,
+{
+    /// Construct a `Ring`
+    fn to_ring(self, thickness: f32) -> Ring<Self>;
+}
+
+impl<P> ToRing for P
+where
+    P: Primitive2d + Clone + Inset,
+{
+    fn to_ring(self, thickness: f32) -> Ring<Self> {
+        Ring::from_primitive_and_thickness(self, thickness)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     // Reference values were computed by hand and/or with external tools

crates/bevy_math/src/primitives/inset.rs

@@ -0,0 +1,98 @@
+use crate::{
+    ops,
+    primitives::{
+        Capsule2d, Circle, CircularSegment, Primitive2d, Rectangle, RegularPolygon, Rhombus,
+        Triangle2d,
+    },
+    Vec2,
+};
+
+/// A primitive that can be resized uniformly.
+///
+/// See documentation on [`Inset::inset`].
+///
+/// See also [`ToRing`](crate::primitives::ToRing).
+pub trait Inset: Primitive2d {
+    /// Create a new version of this primitive that is resized uniformly.
+    /// That is, it resizes the shape inwards such that for the lines between vertices,
+    /// it creates new parallel lines that are `distance` inwards from the original lines.
+    ///
+    /// This is useful for creating smaller shapes or making outlines of `distance` thickness with [`Ring`](crate::primitives::Ring).
+    ///
+    /// See also [`ToRing::to_ring`](crate::primitives::ToRing::to_ring)
+    fn inset(self, distance: f32) -> Self;
+}
+
+impl Inset for Circle {
+    fn inset(mut self, distance: f32) -> Self {
+        self.radius -= distance;
+        self
+    }
+}
+
+impl Inset for Triangle2d {
+    fn inset(self, distance: f32) -> Self {
+        fn find_inset_point(a: Vec2, b: Vec2, c: Vec2, distance: f32) -> Vec2 {
+            let unit_vector_ab = (b - a).normalize();
+            let unit_vector_ac = (c - a).normalize();
+            let half_angle_bac = unit_vector_ab.angle_to(unit_vector_ac) / 2.0;
+            let mean = (unit_vector_ab + unit_vector_ac) / 2.0;
+            let direction = mean.normalize();
+            let magnitude = distance / ops::sin(half_angle_bac);
+            a + direction * magnitude
+        }
+
+        let [a, b, c] = self.vertices;
+
+        let new_a = find_inset_point(a, b, c, distance);
+        let new_b = find_inset_point(b, c, a, distance);
+        let new_c = find_inset_point(c, a, b, distance);
+
+        Self::new(new_a, new_b, new_c)
+    }
+}
+
+impl Inset for Rhombus {
+    fn inset(mut self, distance: f32) -> Self {
+        let [half_width, half_height] = self.half_diagonals.into();
+        let angle = ops::atan(half_height / half_width);
+        let x_offset = distance / ops::sin(angle);
+        let y_offset = distance / ops::cos(angle);
+        self.half_diagonals -= Vec2::new(x_offset, y_offset);
+        self
+    }
+}
+
+impl Inset for Capsule2d {
+    fn inset(mut self, distance: f32) -> Self {
+        self.radius -= distance;
+        self
+    }
+}
+
+impl Inset for Rectangle {
+    fn inset(mut self, distance: f32) -> Self {
+        self.half_size -= Vec2::splat(distance);
+        self
+    }
+}
+
+impl Inset for CircularSegment {
+    fn inset(self, distance: f32) -> Self {
+        let old_arc = self.arc;
+        let radius = old_arc.radius - distance;
+        let apothem = old_arc.apothem() + distance;
+        // https://en.wikipedia.org/wiki/Circular_segment
+        let half_angle = ops::acos(apothem / radius);
+        Self::new(radius, half_angle)
+    }
+}
+
+impl Inset for RegularPolygon {
+    fn inset(mut self, distance: f32) -> Self {
+        let half_angle = self.internal_angle_radians() / 2.0;
+        let offset = distance / ops::sin(half_angle);
+        self.circumcircle.radius -= offset;
+        self
+    }
+}

crates/bevy_math/src/primitives/mod.rs

@@ -6,6 +6,8 @@ mod dim2;
 pub use dim2::*;
 mod dim3;
 pub use dim3::*;
+mod inset;
+pub use inset::*;
 mod polygon;
 
 /// A marker trait for 2D primitives