More gizmos builders (#13261)

# Objective

- Add GizmoBuilders for some primitives as discussed in #13233

## Solution

- `gizmos.primitive_2d(CIRCLE)` and `gizmos.primitive_2d(ELLIPSE)` now
return `Ellipse2dBuilder` aswell.
- `gizmos.primitive_3d(SPHERE)` and `gizmos.sphere()` now return the
same `SphereBuilder`.
- the `.circle_segments` method on the `SphereBuilder` that used to be
returned by `.sphere()` is now called `.segments`
  - the sphere primitive gizmo now matches the `gizmos.sphere` gizmo
- `gizmos.primitive_2d(ANNULUS)` now returns a `Annulus2dBuilder`
allowing the configuration of the `segments`
- gizmos cylinders and capsules now have only 1 line per axis, similar
to `gizmos.sphere`

## Migration Guide

- Some `gizmos.primitive_nd` methods now return some or different
builders. You may need to adjust types and match statements
- Replace any calls to `circle_segments()` with `.segments()`

---------

Co-authored-by: Raphael Büttgenbach <[email protected]>

Author: lynn-lumen

crates/bevy_gizmos/src/circles.rs

@@ -178,6 +178,45 @@ where
             resolution: DEFAULT_CIRCLE_RESOLUTION,
         }
     }
+
+    /// Draw a wireframe sphere in 3D made out of 3 circles around the axes.
+    ///
+    /// This should be called for each frame the sphere needs to be rendered.
+    ///
+    /// # Example
+    /// ```
+    /// # use bevy_gizmos::prelude::*;
+    /// # use bevy_render::prelude::*;
+    /// # use bevy_math::prelude::*;
+    /// # use bevy_color::Color;
+    /// fn system(mut gizmos: Gizmos) {
+    ///     gizmos.sphere(Vec3::ZERO, Quat::IDENTITY, 1., Color::BLACK);
+    ///
+    ///     // Each circle has 32 line-segments by default.
+    ///     // You may want to increase this for larger spheres.
+    ///     gizmos
+    ///         .sphere(Vec3::ZERO, Quat::IDENTITY, 5., Color::BLACK)
+    ///         .resolution(64);
+    /// }
+    /// # bevy_ecs::system::assert_is_system(system);
+    /// ```
+    #[inline]
+    pub fn sphere(
+        &mut self,
+        position: Vec3,
+        rotation: Quat,
+        radius: f32,
+        color: impl Into<Color>,
+    ) -> SphereBuilder<'_, 'w, 's, Config, Clear> {
+        SphereBuilder {
+            gizmos: self,
+            radius,
+            position,
+            rotation,
+            color: color.into(),
+            resolution: DEFAULT_CIRCLE_RESOLUTION,
+        }
+    }
 }
 
 /// A builder returned by [`Gizmos::ellipse`].
@@ -266,3 +305,66 @@ where
         self.gizmos.linestrip_2d(positions, self.color);
     }
 }
+
+/// Builder for configuring the drawing options of [`Sphere`].
+pub struct SphereBuilder<'a, 'w, 's, Config, Clear>
+where
+    Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
+{
+    gizmos: &'a mut Gizmos<'w, 's, Config, Clear>,
+
+    // Radius of the sphere
+    radius: f32,
+
+    // Rotation of the sphere around the origin in 3D space
+    rotation: Quat,
+    // Center position of the sphere in 3D space
+    position: Vec3,
+    // Color of the sphere
+    color: Color,
+
+    // Number of line-segments used to approximate the sphere geometry
+    resolution: usize,
+}
+
+impl<Config, Clear> SphereBuilder<'_, '_, '_, Config, Clear>
+where
+    Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
+{
+    /// Set the number of line-segments used to approximate the sphere geometry.
+    pub fn resolution(mut self, resolution: usize) -> Self {
+        self.resolution = resolution;
+        self
+    }
+}
+
+impl<Config, Clear> Drop for SphereBuilder<'_, '_, '_, Config, Clear>
+where
+    Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
+{
+    fn drop(&mut self) {
+        if !self.gizmos.enabled {
+            return;
+        }
+
+        let SphereBuilder {
+            radius,
+            position: center,
+            rotation,
+            color,
+            resolution,
+            ..
+        } = self;
+
+        // draws one great circle around each of the local axes
+        Vec3::AXES.into_iter().for_each(|axis| {
+            let normal = *rotation * axis;
+            self.gizmos
+                .circle(*center, Dir3::new_unchecked(normal), *radius, *color)
+                .resolution(*resolution);
+        });
+    }
+}

crates/bevy_gizmos/src/gizmos.rs

@@ -2,14 +2,13 @@
 
 use std::{iter, marker::PhantomData, mem};
 
-use crate::circles::DEFAULT_CIRCLE_RESOLUTION;
 use bevy_color::{Color, LinearRgba};
 use bevy_ecs::{
     component::Tick,
     system::{Deferred, ReadOnlySystemParam, Res, Resource, SystemBuffer, SystemMeta, SystemParam},
     world::{unsafe_world_cell::UnsafeWorldCell, World},
 };
-use bevy_math::{Dir3, Quat, Rotation2d, Vec2, Vec3};
+use bevy_math::{Quat, Rotation2d, Vec2, Vec3};
 use bevy_transform::TransformPoint;
 use bevy_utils::default;
 
@@ -459,45 +458,6 @@ where
         strip_colors.push(LinearRgba::NAN);
     }
 
-    /// Draw a wireframe sphere in 3D made out of 3 circles around the axes.
-    ///
-    /// This should be called for each frame the sphere needs to be rendered.
-    ///
-    /// # Example
-    /// ```
-    /// # use bevy_gizmos::prelude::*;
-    /// # use bevy_render::prelude::*;
-    /// # use bevy_math::prelude::*;
-    /// # use bevy_color::Color;
-    /// fn system(mut gizmos: Gizmos) {
-    ///     gizmos.sphere(Vec3::ZERO, Quat::IDENTITY, 1., Color::BLACK);
-    ///
-    ///     // Each circle has 32 line-segments by default.
-    ///     // You may want to increase this for larger spheres.
-    ///     gizmos
-    ///         .sphere(Vec3::ZERO, Quat::IDENTITY, 5., Color::BLACK)
-    ///         .resolution(64);
-    /// }
-    /// # bevy_ecs::system::assert_is_system(system);
-    /// ```
-    #[inline]
-    pub fn sphere(
-        &mut self,
-        position: Vec3,
-        rotation: Quat,
-        radius: f32,
-        color: impl Into<Color>,
-    ) -> SphereBuilder<'_, 'w, 's, Config, Clear> {
-        SphereBuilder {
-            gizmos: self,
-            position,
-            rotation: rotation.normalize(),
-            radius,
-            color: color.into(),
-            resolution: DEFAULT_CIRCLE_RESOLUTION,
-        }
-    }
-
     /// Draw a wireframe rectangle in 3D.
     ///
     /// This should be called for each frame the rectangle needs to be rendered.
@@ -790,49 +750,6 @@ where
     }
 }
 
-/// A builder returned by [`Gizmos::sphere`].
-pub struct SphereBuilder<'a, 'w, 's, Config, Clear = ()>
-where
-    Config: GizmoConfigGroup,
-    Clear: 'static + Send + Sync,
-{
-    gizmos: &'a mut Gizmos<'w, 's, Config, Clear>,
-    position: Vec3,
-    rotation: Quat,
-    radius: f32,
-    color: Color,
-    resolution: usize,
-}
-
-impl<Config, Clear> SphereBuilder<'_, '_, '_, Config, Clear>
-where
-    Config: GizmoConfigGroup,
-    Clear: 'static + Send + Sync,
-{
-    /// Set the number of line-segments per circle for this sphere.
-    pub fn resolution(mut self, resolution: usize) -> Self {
-        self.resolution = resolution;
-        self
-    }
-}
-
-impl<Config, Clear> Drop for SphereBuilder<'_, '_, '_, Config, Clear>
-where
-    Config: GizmoConfigGroup,
-    Clear: 'static + Send + Sync,
-{
-    fn drop(&mut self) {
-        if !self.gizmos.enabled {
-            return;
-        }
-        for axis in Dir3::AXES {
-            self.gizmos
-                .circle(self.position, self.rotation * axis, self.radius, self.color)
-                .resolution(self.resolution);
-        }
-    }
-}
-
 fn rect_inner(size: Vec2) -> [Vec2; 4] {
     let half_size = size / 2.;
     let tl = Vec2::new(-half_size.x, half_size.y);

crates/bevy_gizmos/src/primitives/dim2.rs

@@ -102,7 +102,7 @@ where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,
 {
-    type Output<'a> = () where Self: 'a;
+    type Output<'a> = crate::circles::Ellipse2dBuilder<'a, 'w, 's, Config, Clear> where Self: 'a;
 
     fn primitive_2d(
         &mut self,
@@ -111,11 +111,7 @@ where
         _angle: f32,
         color: impl Into<Color>,
     ) -> Self::Output<'_> {
-        if !self.enabled {
-            return;
-        }
-
-        self.circle_2d(position, primitive.radius, color);
+        self.circle_2d(position, primitive.radius, color)
     }
 }
 
@@ -205,46 +201,114 @@ where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,
 {
-    type Output<'a> = () where Self: 'a;
+    type Output<'a> = crate::circles::Ellipse2dBuilder<'a, 'w, 's, Config, Clear> where Self: 'a;
 
-    fn primitive_2d(
+    fn primitive_2d<'a>(
         &mut self,
         primitive: &Ellipse,
         position: Vec2,
         angle: f32,
         color: impl Into<Color>,
     ) -> Self::Output<'_> {
-        if !self.enabled {
-            return;
-        }
-
-        self.ellipse_2d(position, angle, primitive.half_size, color);
+        self.ellipse_2d(position, angle, primitive.half_size, color)
     }
 }
 
 // annulus 2d
 
+/// Builder for configuring the drawing options of [`Annulus`].
+pub struct Annulus2dBuilder<'a, 'w, 's, Config, Clear>
+where
+    Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
+{
+    gizmos: &'a mut Gizmos<'w, 's, Config, Clear>,
+    position: Vec2,
+    inner_radius: f32,
+    outer_radius: f32,
+    color: Color,
+    inner_resolution: usize,
+    outer_resolution: usize,
+}
+
+impl<Config, Clear> Annulus2dBuilder<'_, '_, '_, Config, Clear>
+where
+    Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
+{
+    /// Set the number of line-segments for each circle of the annulus.
+    pub fn resolution(mut self, resolution: usize) -> Self {
+        self.outer_resolution = resolution;
+        self.inner_resolution = resolution;
+        self
+    }
+
+    /// Set the number of line-segments for the outer circle of the annulus.
+    pub fn outer_resolution(mut self, resolution: usize) -> Self {
+        self.outer_resolution = resolution;
+        self
+    }
+
+    /// Set the number of line-segments for the inner circle of the annulus.
+    pub fn inner_resolution(mut self, resolution: usize) -> Self {
+        self.inner_resolution = resolution;
+        self
+    }
+}
+
 impl<'w, 's, Config, Clear> GizmoPrimitive2d<Annulus> for Gizmos<'w, 's, Config, Clear>
 where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,
 {
-    type Output<'a> = () where Self: 'a;
+    type Output<'a> = Annulus2dBuilder<'a, 'w, 's, Config, Clear> where Self: 'a;
 
     fn primitive_2d(
         &mut self,
         primitive: &Annulus,
         position: Vec2,
-        angle: f32,
+        _angle: f32,
         color: impl Into<Color>,
     ) -> Self::Output<'_> {
-        if !self.enabled {
+        Annulus2dBuilder {
+            gizmos: self,
+            position,
+            inner_radius: primitive.inner_circle.radius,
+            outer_radius: primitive.outer_circle.radius,
+            color: color.into(),
+            inner_resolution: crate::circles::DEFAULT_CIRCLE_RESOLUTION,
+            outer_resolution: crate::circles::DEFAULT_CIRCLE_RESOLUTION,
+        }
+    }
+}
+
+impl<Config, Clear> Drop for Annulus2dBuilder<'_, '_, '_, Config, Clear>
+where
+    Config: GizmoConfigGroup,
+    Clear: 'static + Send + Sync,
+{
+    fn drop(&mut self) {
+        if !self.gizmos.enabled {
             return;
         }
 
-        let color = color.into();
-        self.primitive_2d(&primitive.inner_circle, position, angle, color);
-        self.primitive_2d(&primitive.outer_circle, position, angle, color);
+        let Annulus2dBuilder {
+            gizmos,
+            position,
+            inner_radius,
+            outer_radius,
+            inner_resolution,
+            outer_resolution,
+            color,
+            ..
+        } = self;
+
+        gizmos
+            .circle_2d(*position, *outer_radius, *color)
+            .resolution(*outer_resolution);
+        gizmos
+            .circle_2d(*position, *inner_radius, *color)
+            .resolution(*inner_resolution);
     }
 }
 
@@ -266,8 +330,7 @@ where
     ) -> Self::Output<'_> {
         if !self.enabled {
             return;
-        }
-
+        };
         let [a, b, c, d] =
             [(1.0, 0.0), (0.0, 1.0), (-1.0, 0.0), (0.0, -1.0)].map(|(sign_x, sign_y)| {
                 Vec2::new(