introduction of ConvexPolygon and ConvexPolygonMeshBuilder (#15544)

# Objective

- As discussed on
[Discord](https://discord.com/channels/691052431525675048/1203087353850364004/1285300659746246849),
implement a `ConvexPolygon` 2D math primitive and associated mesh
builder.
- The original goal was to have a mesh builder for the simplest (i.e.
convex) polygons.

## Solution

- The `ConvexPolygon` is created from its vertices.
- The convexity of the polygon is checked when created via `new()` by
verifying that the winding order of all the triangles formed with
adjacent vertices is the same.
- The `ConvexPolygonMeshBuilder` uses an anchor vertex and goes through
every adjacent pair of vertices in the polygon to form triangles that
fill up the polygon.

## Testing

- Tested locally with my own simple `ConvexPolygonMeshBuilder` usage.

crates/bevy_math/src/primitives/dim2.rs

@@ -1,4 +1,5 @@
 use core::f32::consts::{FRAC_1_SQRT_2, FRAC_PI_2, FRAC_PI_3, PI};
+use thiserror::Error;
 
 use super::{Measured2d, Primitive2d, WindingOrder};
 use crate::{
@@ -1603,6 +1604,67 @@ impl<const N: usize> Polygon<N> {
     }
 }
 
+/// A convex polygon with `N` vertices.
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "bevy_reflect", derive(Reflect), reflect(Debug, PartialEq))]
+#[cfg_attr(
+    all(feature = "serialize", feature = "bevy_reflect"),
+    reflect(Serialize, Deserialize)
+)]
+pub struct ConvexPolygon<const N: usize> {
+    /// The vertices of the [`ConvexPolygon`].
+    #[cfg_attr(feature = "serialize", serde(with = "super::serde::array"))]
+    pub vertices: [Vec2; N],
+}
+impl<const N: usize> Primitive2d for ConvexPolygon<N> {}
+
+/// An error that happens when creating a [`ConvexPolygon`].
+#[derive(Error, Debug, Clone)]
+pub enum ConvexPolygonError {
+    /// The created polygon is not convex.
+    #[error("The created polygon is not convex")]
+    Concave,
+}
+
+impl<const N: usize> ConvexPolygon<N> {
+    fn triangle_winding_order(
+        &self,
+        a_index: usize,
+        b_index: usize,
+        c_index: usize,
+    ) -> WindingOrder {
+        let a = self.vertices[a_index];
+        let b = self.vertices[b_index];
+        let c = self.vertices[c_index];
+        Triangle2d::new(a, b, c).winding_order()
+    }
+
+    /// Create a [`ConvexPolygon`] from its `vertices`.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ConvexPolygonError::Concave`] if the `vertices` do not form a convex polygon.
+    pub fn new(vertices: [Vec2; N]) -> Result<Self, ConvexPolygonError> {
+        let polygon = Self::new_unchecked(vertices);
+        let ref_winding_order = polygon.triangle_winding_order(N - 1, 0, 1);
+        for i in 1..N {
+            let winding_order = polygon.triangle_winding_order(i - 1, i, (i + 1) % N);
+            if winding_order != ref_winding_order {
+                return Err(ConvexPolygonError::Concave);
+            }
+        }
+        Ok(polygon)
+    }
+
+    /// Create a [`ConvexPolygon`] from its `vertices`, without checks.
+    /// Use this version only if you know that the `vertices` make up a convex polygon.
+    #[inline(always)]
+    pub fn new_unchecked(vertices: [Vec2; N]) -> Self {
+        Self { vertices }
+    }
+}
+
 /// A polygon with a variable number of vertices, allocated on the heap
 /// in a `Box<[Vec2]>`.
 ///

crates/bevy_mesh/src/primitives/dim2.rs

@@ -7,8 +7,8 @@ use super::{Extrudable, MeshBuilder, Meshable};
 use bevy_math::{
     ops,
     primitives::{
-        Annulus, Capsule2d, Circle, CircularSector, CircularSegment, Ellipse, Rectangle,
-        RegularPolygon, Rhombus, Triangle2d, Triangle3d, WindingOrder,
+        Annulus, Capsule2d, Circle, CircularSector, CircularSegment, ConvexPolygon, Ellipse,
+        Rectangle, RegularPolygon, Rhombus, Triangle2d, Triangle3d, WindingOrder,
     },
     FloatExt, Vec2,
 };
@@ -398,6 +398,55 @@ impl From<CircularSegment> for Mesh {
     }
 }
 
+/// A builder used for creating a [`Mesh`] with a [`ConvexPolygon`] shape.
+pub struct ConvexPolygonMeshBuilder<const N: usize> {
+    pub vertices: [Vec2; N],
+}
+
+impl<const N: usize> Meshable for ConvexPolygon<N> {
+    type Output = ConvexPolygonMeshBuilder<N>;
+
+    fn mesh(&self) -> Self::Output {
+        Self::Output {
+            vertices: self.vertices,
+        }
+    }
+}
+
+impl<const N: usize> MeshBuilder for ConvexPolygonMeshBuilder<N> {
+    fn build(&self) -> Mesh {
+        let mut indices = Vec::with_capacity((N - 2) * 3);
+        let mut positions = Vec::with_capacity(N);
+
+        for vertex in self.vertices {
+            positions.push([vertex.x, vertex.y, 0.0]);
+        }
+        for i in 2..N as u32 {
+            indices.extend_from_slice(&[0, i - 1, i]);
+        }
+        Mesh::new(
+            PrimitiveTopology::TriangleList,
+            RenderAssetUsages::default(),
+        )
+        .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
+        .with_inserted_indices(Indices::U32(indices))
+    }
+}
+
+impl<const N: usize> Extrudable for ConvexPolygonMeshBuilder<N> {
+    fn perimeter(&self) -> Vec<PerimeterSegment> {
+        vec![PerimeterSegment::Flat {
+            indices: (0..N as u32).chain([0]).collect(),
+        }]
+    }
+}
+
+impl<const N: usize> From<ConvexPolygon<N>> for Mesh {
+    fn from(polygon: ConvexPolygon<N>) -> Self {
+        polygon.mesh().build()
+    }
+}
+
 /// A builder used for creating a [`Mesh`] with a [`RegularPolygon`] shape.
 pub struct RegularPolygonMeshBuilder {
     circumradius: f32,

crates/bevy_mesh/src/primitives/extrusion.rs

@@ -67,7 +67,7 @@ impl PerimeterSegment {
     }
 }
 
-/// A trait for required for implementing `Meshable` for `Extrusion<T>`.
+/// A trait required for implementing `Meshable` for `Extrusion<T>`.
 ///
 /// ## Warning
 ///