Inconsistent segments/resolution naming (#13438)

# Objective

- Fixes #13412

## Solution

- Renamed `segments` in `bevy_gizmos` to `resolution` and adjusted
examples

## Migration Guide

- When working with gizmos, replace all calls to `.segments(...)` with
`.resolution(...)`

crates/bevy_gizmos/src/arcs.rs

@@ -3,7 +3,7 @@
 //! Includes the implementation of [`Gizmos::arc_2d`],
 //! and assorted support items.
 
-use crate::circles::DEFAULT_CIRCLE_SEGMENTS;
+use crate::circles::DEFAULT_CIRCLE_RESOLUTION;
 use crate::prelude::{GizmoConfigGroup, Gizmos};
 use bevy_color::Color;
 use bevy_math::{Quat, Vec2, Vec3};
@@ -42,7 +42,7 @@ where
     ///     // You may want to increase this for larger arcs.
     ///     gizmos
     ///         .arc_2d(Vec2::ZERO, 0., PI / 4., 5., RED)
-    ///         .segments(64);
+    ///         .resolution(64);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -62,7 +62,7 @@ where
             arc_angle,
             radius,
             color: color.into(),
-            segments: None,
+            resolution: None,
         }
     }
 }
@@ -79,17 +79,17 @@ where
     arc_angle: f32,
     radius: f32,
     color: Color,
-    segments: Option<usize>,
+    resolution: Option<usize>,
 }
 
 impl<Config, Clear> Arc2dBuilder<'_, '_, '_, Config, Clear>
 where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,
 {
-    /// Set the number of line-segments for this arc.
-    pub fn segments(mut self, segments: usize) -> Self {
-        self.segments.replace(segments);
+    /// Set the number of lines used to approximate the geometry of this arc.
+    pub fn resolution(mut self, resolution: usize) -> Self {
+        self.resolution.replace(resolution);
         self
     }
 }
@@ -104,12 +104,17 @@ where
             return;
         }
 
-        let segments = self
-            .segments
-            .unwrap_or_else(|| segments_from_angle(self.arc_angle));
+        let resolution = self
+            .resolution
+            .unwrap_or_else(|| resolution_from_angle(self.arc_angle));
 
-        let positions = arc_2d_inner(self.direction_angle, self.arc_angle, self.radius, segments)
-            .map(|vec2| (vec2 + self.position));
+        let positions = arc_2d_inner(
+            self.direction_angle,
+            self.arc_angle,
+            self.radius,
+            resolution,
+        )
+        .map(|vec2| (vec2 + self.position));
         self.gizmos.linestrip_2d(positions, self.color);
     }
 }
@@ -118,12 +123,12 @@ fn arc_2d_inner(
     direction_angle: f32,
     arc_angle: f32,
     radius: f32,
-    segments: usize,
+    resolution: usize,
 ) -> impl Iterator<Item = Vec2> {
-    (0..segments + 1).map(move |i| {
+    (0..resolution + 1).map(move |i| {
         let start = direction_angle - arc_angle / 2.;
 
-        let angle = start + (i as f32 * (arc_angle / segments as f32));
+        let angle = start + (i as f32 * (arc_angle / resolution as f32));
         Vec2::from(angle.sin_cos()) * radius
     })
 }
@@ -155,8 +160,8 @@ where
     /// - `color`: color of the arc
     ///
     /// # Builder methods
-    /// The number of segments of the arc (i.e. the level of detail) can be adjusted with the
-    /// `.segments(...)` method.
+    /// The resolution of the arc (i.e. the level of detail) can be adjusted with the
+    /// `.resolution(...)` method.
     ///
     /// # Example
     /// ```
@@ -177,7 +182,7 @@ where
     ///          rotation,
     ///          ORANGE
     ///          )
-    ///          .segments(100);
+    ///          .resolution(100);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -198,7 +203,7 @@ where
             angle,
             radius,
             color: color.into(),
-            segments: None,
+            resolution: None,
         }
     }
 
@@ -212,8 +217,8 @@ where
     /// - `color`: color of the arc
     ///
     /// # Builder methods
-    /// The number of segments of the arc (i.e. the level of detail) can be adjusted with the
-    /// `.segments(...)` method.
+    /// The resolution of the arc (i.e. the level of detail) can be adjusted with the
+    /// `.resolution(...)` method.
     ///
     /// # Examples
     /// ```
@@ -228,7 +233,7 @@ where
     ///        Vec3::ZERO,
     ///        ORANGE
     ///        )
-    ///        .segments(100);
+    ///        .resolution(100);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -259,8 +264,8 @@ where
     /// - `color`: color of the arc
     ///
     /// # Builder methods
-    /// The number of segments of the arc (i.e. the level of detail) can be adjusted with the
-    /// `.segments(...)` method.
+    /// The resolution of the arc (i.e. the level of detail) can be adjusted with the
+    /// `.resolution(...)` method.
     ///
     /// # Examples
     /// ```
@@ -275,7 +280,7 @@ where
     ///        Vec3::ZERO,
     ///        ORANGE
     ///        )
-    ///        .segments(100);
+    ///        .resolution(100);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -334,7 +339,7 @@ where
             angle,
             radius,
             color: color.into(),
-            segments: None,
+            resolution: None,
         }
     }
 }
@@ -361,17 +366,17 @@ where
     angle: f32,
     radius: f32,
     color: Color,
-    segments: Option<usize>,
+    resolution: Option<usize>,
 }
 
 impl<Config, Clear> Arc3dBuilder<'_, '_, '_, Config, Clear>
 where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,
 {
-    /// Set the number of line-segments for this arc.
-    pub fn segments(mut self, segments: usize) -> Self {
-        self.segments.replace(segments);
+    /// Set the number of lines for this arc.
+    pub fn resolution(mut self, resolution: usize) -> Self {
+        self.resolution.replace(resolution);
         self
     }
 }
@@ -386,17 +391,17 @@ where
             return;
         }
 
-        let segments = self
-            .segments
-            .unwrap_or_else(|| segments_from_angle(self.angle));
+        let resolution = self
+            .resolution
+            .unwrap_or_else(|| resolution_from_angle(self.angle));
 
         let positions = arc_3d_inner(
             self.start_vertex,
             self.center,
             self.rotation,
             self.angle,
             self.radius,
-            segments,
+            resolution,
         );
         self.gizmos.linestrip(positions, self.color);
     }
@@ -408,20 +413,20 @@ fn arc_3d_inner(
     rotation: Quat,
     angle: f32,
     radius: f32,
-    segments: usize,
+    resolution: usize,
 ) -> impl Iterator<Item = Vec3> {
     // drawing arcs bigger than TAU degrees or smaller than -TAU degrees makes no sense since
-    // we won't see the overlap and we would just decrease the level of details since the segments
+    // we won't see the overlap and we would just decrease the level of details since the resolution
     // would be larger
     let angle = angle.clamp(-TAU, TAU);
-    (0..=segments)
-        .map(move |frac| frac as f32 / segments as f32)
+    (0..=resolution)
+        .map(move |frac| frac as f32 / resolution as f32)
         .map(move |percentage| angle * percentage)
         .map(move |frac_angle| Quat::from_axis_angle(Vec3::Y, frac_angle) * start_vertex)
         .map(move |p| rotation * (p * radius) + center)
 }
 
-// helper function for getting a default value for the segments parameter
-fn segments_from_angle(angle: f32) -> usize {
-    ((angle.abs() / TAU) * DEFAULT_CIRCLE_SEGMENTS as f32).ceil() as usize
+// helper function for getting a default value for the resolution parameter
+fn resolution_from_angle(angle: f32) -> usize {
+    ((angle.abs() / TAU) * DEFAULT_CIRCLE_RESOLUTION as f32).ceil() as usize
 }

crates/bevy_gizmos/src/circles.rs

@@ -9,11 +9,11 @@ use bevy_math::Mat2;
 use bevy_math::{Dir3, Quat, Vec2, Vec3};
 use std::f32::consts::TAU;
 
-pub(crate) const DEFAULT_CIRCLE_SEGMENTS: usize = 32;
+pub(crate) const DEFAULT_CIRCLE_RESOLUTION: usize = 32;
 
-fn ellipse_inner(half_size: Vec2, segments: usize) -> impl Iterator<Item = Vec2> {
-    (0..segments + 1).map(move |i| {
-        let angle = i as f32 * TAU / segments as f32;
+fn ellipse_inner(half_size: Vec2, resolution: usize) -> impl Iterator<Item = Vec2> {
+    (0..resolution + 1).map(move |i| {
+        let angle = i as f32 * TAU / resolution as f32;
         let (x, y) = angle.sin_cos();
         Vec2::new(x, y) * half_size
     })
@@ -41,7 +41,7 @@ where
     ///     // You may want to increase this for larger ellipses.
     ///     gizmos
     ///         .ellipse(Vec3::ZERO, Quat::IDENTITY, Vec2::new(5., 1.), RED)
-    ///         .segments(64);
+    ///         .resolution(64);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -59,7 +59,7 @@ where
             rotation,
             half_size,
             color: color.into(),
-            segments: DEFAULT_CIRCLE_SEGMENTS,
+            resolution: DEFAULT_CIRCLE_RESOLUTION,
         }
     }
 
@@ -80,7 +80,7 @@ where
     ///     // You may want to increase this for larger ellipses.
     ///     gizmos
     ///         .ellipse_2d(Vec2::ZERO, 180.0_f32.to_radians(), Vec2::new(5., 1.), RED)
-    ///         .segments(64);
+    ///         .resolution(64);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -98,7 +98,7 @@ where
             rotation: Mat2::from_angle(angle),
             half_size,
             color: color.into(),
-            segments: DEFAULT_CIRCLE_SEGMENTS,
+            resolution: DEFAULT_CIRCLE_RESOLUTION,
         }
     }
 
@@ -119,7 +119,7 @@ where
     ///     // You may want to increase this for larger circles.
     ///     gizmos
     ///         .circle(Vec3::ZERO, Dir3::Z, 5., RED)
-    ///         .segments(64);
+    ///         .resolution(64);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -137,7 +137,7 @@ where
             rotation: Quat::from_rotation_arc(Vec3::Z, *normal),
             half_size: Vec2::splat(radius),
             color: color.into(),
-            segments: DEFAULT_CIRCLE_SEGMENTS,
+            resolution: DEFAULT_CIRCLE_RESOLUTION,
         }
     }
 
@@ -158,7 +158,7 @@ where
     ///     // You may want to increase this for larger circles.
     ///     gizmos
     ///         .circle_2d(Vec2::ZERO, 5., RED)
-    ///         .segments(64);
+    ///         .resolution(64);
     /// }
     /// # bevy_ecs::system::assert_is_system(system);
     /// ```
@@ -175,7 +175,7 @@ where
             rotation: Mat2::IDENTITY,
             half_size: Vec2::splat(radius),
             color: color.into(),
-            segments: DEFAULT_CIRCLE_SEGMENTS,
+            resolution: DEFAULT_CIRCLE_RESOLUTION,
         }
     }
 }
@@ -191,17 +191,17 @@ where
     rotation: Quat,
     half_size: Vec2,
     color: Color,
-    segments: usize,
+    resolution: usize,
 }
 
 impl<Config, Clear> EllipseBuilder<'_, '_, '_, Config, Clear>
 where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,
 {
-    /// Set the number of line-segments for this ellipse.
-    pub fn segments(mut self, segments: usize) -> Self {
-        self.segments = segments;
+    /// Set the number of lines used to approximate the geometry of this ellipse.
+    pub fn resolution(mut self, resolution: usize) -> Self {
+        self.resolution = resolution;
         self
     }
 }
@@ -216,7 +216,7 @@ where
             return;
         }
 
-        let positions = ellipse_inner(self.half_size, self.segments)
+        let positions = ellipse_inner(self.half_size, self.resolution)
             .map(|vec2| self.rotation * vec2.extend(0.))
             .map(|vec3| vec3 + self.position);
         self.gizmos.linestrip(positions, self.color);
@@ -234,17 +234,17 @@ where
     rotation: Mat2,
     half_size: Vec2,
     color: Color,
-    segments: usize,
+    resolution: usize,
 }
 
 impl<Config, Clear> Ellipse2dBuilder<'_, '_, '_, Config, Clear>
 where
     Config: GizmoConfigGroup,
     Clear: 'static + Send + Sync,
 {
-    /// Set the number of line-segments for this ellipse.
-    pub fn segments(mut self, segments: usize) -> Self {
-        self.segments = segments;
+    /// Set the number of line-segments used to approximate the geometry of this ellipse.
+    pub fn resolution(mut self, resolution: usize) -> Self {
+        self.resolution = resolution;
         self
     }
 }
@@ -260,7 +260,7 @@ where
             return;
         };
 
-        let positions = ellipse_inner(self.half_size, self.segments)
+        let positions = ellipse_inner(self.half_size, self.resolution)
             .map(|vec2| self.rotation * vec2)
             .map(|vec2| vec2 + self.position);
         self.gizmos.linestrip_2d(positions, self.color);