Inconsistent segments/resolution naming (bevyengine#13438)

# Objective

- Fixes bevyengine#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);