From 0387331c12f6335501bc487342a06cd911e79949 Mon Sep 17 00:00:00 2001 From: Doonv <58695417+doonv@users.noreply.github.com> Date: Sat, 20 Jan 2024 23:52:09 +0200 Subject: [PATCH] Direction: Rename `from_normalized` to `new_unchecked` (#11425) # Objective `Direction2d::from_normalized` & `Direction3d::from_normalized` don't emphasize that importance of the vector being normalized enough. ## Solution Rename `from_normalized` to `new_unchecked` and add more documentation. --- `Direction2d` and `Direction3d` were added somewhat recently in https://github.com/bevyengine/bevy/pull/10466 (after 0.12), so I don't think documenting the changelog and migration guide is necessary (Since there is no major previous version to migrate from). But here it is anyway in case it's needed: ## Changelog - Renamed `Direction2d::from_normalized` and `Direction3d::from_normalized` to `new_unchecked`. ## Migration Guide - Renamed `Direction2d::from_normalized` and `Direction3d::from_normalized` to `new_unchecked`. --------- Co-authored-by: Tristan Guichaoua <33934311+tguichaoua@users.noreply.github.com> Co-authored-by: Joona Aalto --- .../src/bounding/bounded3d/primitive_impls.rs | 3 ++- crates/bevy_math/src/primitives/dim2.rs | 25 ++++++++++++------- crates/bevy_math/src/primitives/dim3.rs | 25 ++++++++++++------- 3 files changed, 34 insertions(+), 19 deletions(-) diff --git a/crates/bevy_math/src/bounding/bounded3d/primitive_impls.rs b/crates/bevy_math/src/bounding/bounded3d/primitive_impls.rs index 8125aae218..b992fb517e 100644 --- a/crates/bevy_math/src/bounding/bounded3d/primitive_impls.rs +++ b/crates/bevy_math/src/bounding/bounded3d/primitive_impls.rs @@ -150,7 +150,8 @@ impl Bounded3d for Capsule { fn aabb_3d(&self, translation: Vec3, rotation: Quat) -> Aabb3d { // Get the line segment between the hemispheres of the rotated capsule let segment = Segment3d { - direction: Direction3d::from_normalized(rotation * Vec3::Y), + // Multiplying a normalized vector (Vec3::Y) with a rotation returns a normalized vector. + direction: Direction3d::new_unchecked(rotation * Vec3::Y), half_length: self.half_length, }; let (a, b) = (segment.point1(), segment.point2()); diff --git a/crates/bevy_math/src/primitives/dim2.rs b/crates/bevy_math/src/primitives/dim2.rs index cb832f9f61..39d6b740ce 100644 --- a/crates/bevy_math/src/primitives/dim2.rs +++ b/crates/bevy_math/src/primitives/dim2.rs @@ -24,6 +24,17 @@ impl Direction2d { Self::new_and_length(value).map(|(dir, _)| dir) } + /// Create a [`Direction2d`] from a [`Vec2`] that is already normalized. + /// + /// # Warning + /// + /// `value` must be normalized, i.e it's length must be `1.0`. + pub fn new_unchecked(value: Vec2) -> Self { + debug_assert!(value.is_normalized()); + + Self(value) + } + /// Create a direction from a finite, nonzero [`Vec2`], also returning its original length. /// /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length @@ -34,7 +45,7 @@ impl Direction2d { direction .map(|dir| (Self(dir), length)) - .map_or(Err(InvalidDirectionError::from_length(length)), Ok) + .ok_or(InvalidDirectionError::from_length(length)) } /// Create a direction from its `x` and `y` components. @@ -44,12 +55,6 @@ impl Direction2d { pub fn from_xy(x: f32, y: f32) -> Result { Self::new(Vec2::new(x, y)) } - - /// Create a direction from a [`Vec2`] that is already normalized. - pub fn from_normalized(value: Vec2) -> Self { - debug_assert!(value.is_normalized()); - Self(value) - } } impl TryFrom for Direction2d { @@ -187,8 +192,10 @@ impl Segment2d { pub fn from_points(point1: Vec2, point2: Vec2) -> (Self, Vec2) { let diff = point2 - point1; let length = diff.length(); + ( - Self::new(Direction2d::from_normalized(diff / length), length), + // We are dividing by the length here, so the vector is normalized. + Self::new(Direction2d::new_unchecked(diff / length), length), (point1 + point2) / 2., ) } @@ -477,7 +484,7 @@ mod tests { ); assert_eq!( Direction2d::new_and_length(Vec2::X * 6.5), - Ok((Direction2d::from_normalized(Vec2::X), 6.5)) + Ok((Direction2d::X, 6.5)) ); } diff --git a/crates/bevy_math/src/primitives/dim3.rs b/crates/bevy_math/src/primitives/dim3.rs index 192b9074a9..3809271c32 100644 --- a/crates/bevy_math/src/primitives/dim3.rs +++ b/crates/bevy_math/src/primitives/dim3.rs @@ -28,6 +28,17 @@ impl Direction3d { Self::new_and_length(value).map(|(dir, _)| dir) } + /// Create a [`Direction3d`] from a [`Vec3`] that is already normalized. + /// + /// # Warning + /// + /// `value` must be normalized, i.e it's length must be `1.0`. + pub fn new_unchecked(value: Vec3) -> Self { + debug_assert!(value.is_normalized()); + + Self(value) + } + /// Create a direction from a finite, nonzero [`Vec3`], also returning its original length. /// /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length @@ -38,7 +49,7 @@ impl Direction3d { direction .map(|dir| (Self(dir), length)) - .map_or(Err(InvalidDirectionError::from_length(length)), Ok) + .ok_or(InvalidDirectionError::from_length(length)) } /// Create a direction from its `x`, `y`, and `z` components. @@ -48,12 +59,6 @@ impl Direction3d { pub fn from_xyz(x: f32, y: f32, z: f32) -> Result { Self::new(Vec3::new(x, y, z)) } - - /// Create a direction from a [`Vec3`] that is already normalized. - pub fn from_normalized(value: Vec3) -> Self { - debug_assert!(value.is_normalized()); - Self(value) - } } impl TryFrom for Direction3d { @@ -146,8 +151,10 @@ impl Segment3d { pub fn from_points(point1: Vec3, point2: Vec3) -> (Self, Vec3) { let diff = point2 - point1; let length = diff.length(); + ( - Self::new(Direction3d::from_normalized(diff / length), length), + // We are dividing by the length here, so the vector is normalized. + Self::new(Direction3d::new_unchecked(diff / length), length), (point1 + point2) / 2., ) } @@ -423,7 +430,7 @@ mod test { ); assert_eq!( Direction3d::new_and_length(Vec3::X * 6.5), - Ok((Direction3d::from_normalized(Vec3::X), 6.5)) + Ok((Direction3d::X, 6.5)) ); } }