Merge pull request #1035 from godot-rust/qol/basis-method-names

Rename `Basis` + `Quaternion` methods, closer to Godot

Author: Bromeon

godot-core/src/builtin/basis.rs

@@ -124,10 +124,15 @@ impl Basis {
     /// Create a `Basis` from a `Quaternion`.
     ///
     /// _Godot equivalent: `Basis(Quaternion from)`_
-    pub fn from_quat(quat: Quaternion) -> Self {
+    pub fn from_quaternion(quat: Quaternion) -> Self {
         RMat3::from_quat(quat.to_glam()).to_front()
     }
 
+    #[deprecated = "Renamed to `from_quaternion()`"]
+    pub fn from_quat(quat: Quaternion) -> Self {
+        Self::from_quaternion(quat)
+    }
+
     /// Create a `Basis` from three angles `a`, `b`, and `c` interpreted
     /// as Euler angles according to the given `EulerOrder`.
     ///
@@ -162,23 +167,20 @@ impl Basis {
     /// (implies +X is right).
     ///
     /// _Godot equivalent: `Basis.looking_at()`_
-    pub fn new_looking_at(target: Vector3, up: Vector3, use_model_front: bool) -> Self {
+    pub fn looking_at(target: Vector3, up: Vector3, use_model_front: bool) -> Self {
         super::inner::InnerBasis::looking_at(target, up, use_model_front)
     }
 
+    #[deprecated = "Renamed to `looking_at()`"]
+    pub fn new_looking_at(target: Vector3, up: Vector3, use_model_front: bool) -> Self {
+        Self::looking_at(target, up, use_model_front)
+    }
+
     /// Creates a `[Vector3; 3]` with the columns of the `Basis`.
     pub fn to_cols(&self) -> [Vector3; 3] {
         self.transposed().rows
     }
 
-    /// Creates a [`Quaternion`] representing the same rotation as this basis.
-    ///
-    /// _Godot equivalent: `Basis.get_rotation_quaternion()`_
-    #[doc(alias = "get_rotation_quaternion")]
-    pub fn to_quat(&self) -> Quaternion {
-        RQuat::from_mat3(&self.orthonormalized().to_glam()).to_front()
-    }
-
     const fn to_rows_array(self) -> [real; 9] {
         let [Vector3 {
             x: ax,
@@ -196,11 +198,24 @@ impl Basis {
         [ax, bx, cx, ay, by, cy, az, bz, cz]
     }
 
+    /// Creates a [`Quaternion`] representing the same rotation as this basis.
+    ///
+    /// _Godot equivalent: `Basis.get_rotation_quaternion()`_
+    #[doc(alias = "get_rotation_quaternion")]
+    pub fn get_quaternion(&self) -> Quaternion {
+        RQuat::from_mat3(&self.orthonormalized().to_glam()).to_front()
+    }
+
+    #[deprecated = "Renamed to `get_quaternion()`"]
+    pub fn to_quat(&self) -> Quaternion {
+        self.get_quaternion()
+    }
+
     /// Returns the scale of the matrix.
     ///
     /// _Godot equivalent: `Basis.get_scale()`_
     #[must_use]
-    pub fn scale(&self) -> Vector3 {
+    pub fn get_scale(&self) -> Vector3 {
         let det = self.determinant();
         let det_sign = if det < 0.0 { -1.0 } else { 1.0 };
 
@@ -211,12 +226,24 @@ impl Basis {
         ) * det_sign
     }
 
+    #[deprecated = "Renamed to `get_scale()`"]
+    pub fn scale(&self) -> Vector3 {
+        self.get_scale()
+    }
+
+    /// Returns the rotation of the matrix in euler angles, with the order `YXZ`.
+    ///
+    /// See [`get_euler_with()`](Self::get_euler_with) for custom angle orders.
+    pub fn get_euler(&self) -> Vector3 {
+        self.get_euler_with(EulerOrder::YXZ)
+    }
+
     /// Returns the rotation of the matrix in euler angles.
     ///
-    /// The order of the angles are given by `order`.
+    /// The order of the angles are given by `order`. To use the default order `YXZ`, see [`get_euler()`](Self::get_euler).
     ///
     /// _Godot equivalent: `Basis.get_euler()`_
-    pub fn to_euler(&self, order: EulerOrder) -> Vector3 {
+    pub fn get_euler_with(&self, order: EulerOrder) -> Vector3 {
         use glam::swizzles::Vec3Swizzles as _;
 
         let col_a = self.col_a().to_glam();
@@ -276,6 +303,11 @@ impl Basis {
         .to_front()
     }
 
+    #[deprecated = "Renamed to `get_euler()` + `get_euler_with()`"]
+    pub fn to_euler(&self, order: EulerOrder) -> Vector3 {
+        self.get_euler_with(order)
+    }
+
     fn is_between_neg1_1(f: real) -> Ordering {
         if f >= (1.0 - real::CMP_EPSILON) {
             Ordering::Greater
@@ -416,10 +448,10 @@ impl Basis {
     /// _Godot equivalent: `Basis.slerp()`_
     #[must_use]
     pub fn slerp(&self, other: &Self, weight: real) -> Self {
-        let from = self.to_quat();
-        let to = other.to_quat();
+        let from = self.get_quaternion();
+        let to = other.get_quaternion();
 
-        let mut result = Self::from_quat(from.slerp(to, weight));
+        let mut result = Self::from_quaternion(from.slerp(to, weight));
 
         for i in 0..3 {
             result.rows[i] *= self.rows[i].length().lerp(other.rows[i].length(), weight);
@@ -649,7 +681,7 @@ mod test {
         let to_rotation: Basis = Basis::from_euler(rot_order, original_euler);
 
         // Euler from rotation
-        let euler_from_rotation: Vector3 = to_rotation.to_euler(rot_order);
+        let euler_from_rotation: Vector3 = to_rotation.get_euler_with(rot_order);
         let rotation_from_computed_euler: Basis = Basis::from_euler(rot_order, euler_from_rotation);
 
         let res: Basis = to_rotation.inverse() * rotation_from_computed_euler;
@@ -670,7 +702,7 @@ mod test {
         );
 
         // Double check `to_rotation` decomposing with XYZ rotation order.
-        let euler_xyz_from_rotation: Vector3 = to_rotation.to_euler(EulerOrder::XYZ);
+        let euler_xyz_from_rotation: Vector3 = to_rotation.get_euler_with(EulerOrder::XYZ);
         let rotation_from_xyz_computed_euler: Basis =
             Basis::from_euler(EulerOrder::XYZ, euler_xyz_from_rotation);
 

godot-core/src/builtin/mod.rs

@@ -52,7 +52,7 @@
 //!    ways to achieve the same has downsides: users wonder if a subtle difference exists, or if all options are in fact identical.
 //!    It's unclear which one is the "preferred" option. Recognizing other people's code becomes harder, because there tend to be dialects.
 //! 2. It's often a purely stylistic choice, without functional benefits. Someone may want to write `(1, 2).into()` instead of
-//!    `Vector2::new(1, 2)`. This is not strong enough of a reason -- if brevity is of concern, a function `vec2(1, 2)` does the job better.
+//!    `Vector2i::new(1, 2)`. This is not strong enough of a reason -- if brevity is of concern, a function `vec2i(1, 2)` does the job better.
 //! 3. `From` is less explicit than a named conversion function. If you see `string.to_variant()` or `color.to_hsv()`, you immediately
 //!    know the target type. `string.into()` and `color.into()` lose that aspect. Even with `(1, 2).into()`, you'd first have to check whether
 //!    `From` is only converting the tuple, or if it _also_ provides an `i32`-to-`f32` cast, thus resulting in `Vector2` instead of `Vector2i`.
@@ -62,8 +62,8 @@
 //!    Temporarily commenting out such non-local code breaks the declaration line, too. To make matters worse, turbofish `.into::<Type>()` isn't
 //!    possible either.
 //! 5. Rust itself [requires](https://doc.rust-lang.org/std/convert/trait.From.html#when-to-implement-from) that `From` conversions are
-//!    infallible, lossless, value-preserving and obvious. This rules out a lot of scenarios such as `Basis::to_quaternion()` (which only maintains
-//!    the rotation part, not scale) or `Color::try_to_hsv()` (which is fallible and lossy).
+//!    infallible, lossless, value-preserving and obvious. This rules out a lot of scenarios such as `DynGd::to_gd()` (which only maintains
+//!    the class part, not trait) or `Color::try_to_hsv()` (which is fallible and lossy).
 //!
 //! One main reason to support `From` is to allow generic programming, in particular `impl Into<T>` parameters. This is also the reason
 //! why the string types have historically implemented the trait. But this became less relevant with the advent of

godot-core/src/builtin/quaternion.rs

@@ -107,7 +107,7 @@ impl Quaternion {
         }
     }
 
-    #[deprecated = "Moved to `Quaternion::exp()`"]
+    #[deprecated = "Renamed to `Quaternion::exp()`"]
     pub fn to_exp(self) -> Self {
         self.exp()
     }
@@ -147,9 +147,25 @@ impl Quaternion {
         }
     }
 
-    #[doc(alias = "get_euler")]
+    /// Returns the rotation of the matrix in euler angles, with the order `YXZ`.
+    ///
+    /// See [`get_euler_with()`](Self::get_euler_with) for custom angle orders.
+    pub fn get_euler(self) -> Vector3 {
+        self.get_euler_with(EulerOrder::YXZ)
+    }
+
+    /// Returns the rotation of the matrix in euler angles.
+    ///
+    /// The order of the angles are given by `order`. To use the default order `YXZ`, see [`get_euler()`](Self::get_euler).
+    ///
+    /// _Godot equivalent: `Quaternion.get_euler()`_
+    pub fn get_euler_with(self, order: EulerOrder) -> Vector3 {
+        Basis::from_quaternion(self).get_euler_with(order)
+    }
+
+    #[deprecated = "Renamed to `get_euler()` + `get_euler_with()`"]
     pub fn to_euler(self, order: EulerOrder) -> Vector3 {
-        Basis::from_quat(self).to_euler(order)
+        self.get_euler_with(order)
     }
 
     pub fn inverse(self) -> Self {

godot-core/src/builtin/transform3d.rs

@@ -137,16 +137,16 @@ impl Transform3D {
     /// a given weight (on the range of 0.0 to 1.0).
     #[must_use]
     pub fn interpolate_with(&self, other: &Self, weight: real) -> Self {
-        let src_scale = self.basis.scale();
-        let src_rot = self.basis.to_quat().normalized();
+        let src_scale = self.basis.get_scale();
+        let src_rot = self.basis.get_quaternion().normalized();
         let src_loc = self.origin;
 
-        let dst_scale = other.basis.scale();
-        let dst_rot = other.basis.to_quat().normalized();
+        let dst_scale = other.basis.get_scale();
+        let dst_rot = other.basis.get_quaternion().normalized();
         let dst_loc = other.origin;
 
         let mut basis = Basis::from_scale(src_scale.lerp(dst_scale, weight));
-        basis = Basis::from_quat(src_rot.slerp(dst_rot, weight)) * basis;
+        basis = Basis::from_quaternion(src_rot.slerp(dst_rot, weight)) * basis;
 
         Self {
             basis,
@@ -163,7 +163,7 @@ impl Transform3D {
     #[must_use]
     pub fn looking_at(&self, target: Vector3, up: Vector3, use_model_front: bool) -> Self {
         Self {
-            basis: Basis::new_looking_at(target - self.origin, up, use_model_front),
+            basis: Basis::looking_at(target - self.origin, up, use_model_front),
             origin: self.origin,
         }
     }

godot-core/src/obj/guards.rs

@@ -105,6 +105,7 @@ pub struct DynGdRef<'a, D: ?Sized> {
 }
 
 impl<'a, D: ?Sized> DynGdRef<'a, D> {
+    #[doc(hidden)]
     pub fn from_guard<T: AsDyn<D>>(guard: GdRef<'a, T>) -> Self {
         let obj = &*guard;
         let dyn_obj = obj.dyn_upcast();
@@ -147,6 +148,7 @@ pub struct DynGdMut<'a, D: ?Sized> {
 }
 
 impl<'a, D: ?Sized> DynGdMut<'a, D> {
+    #[doc(hidden)]
     pub fn from_guard<T: AsDyn<D>>(mut guard: GdMut<'a, T>) -> Self {
         let obj = &mut *guard;
         let dyn_obj = obj.dyn_upcast_mut();

itest/rust/src/builtin_tests/geometry/basis_test.rs

@@ -144,15 +144,19 @@ fn basis_equiv() {
         assert_eq_approx!(real::from_f64(inner), outer, "function: {name}\n");
     }
 
-    assert_eq_approx!(inner.get_scale(), outer.scale(), "function: get_scale\n");
+    assert_eq_approx!(
+        inner.get_scale(),
+        outer.get_scale(),
+        "function: get_scale\n"
+    );
     assert_eq_approx!(
         inner.get_euler(EulerOrder::XYZ as i64),
-        outer.to_euler(EulerOrder::XYZ),
+        outer.get_euler_with(EulerOrder::XYZ),
         "function: get_euler\n"
     );
     assert_eq_approx!(
         inner.get_rotation_quaternion(),
-        outer.to_quat(),
+        outer.get_quaternion(),
         "function: get_rotation_quaternion\n"
     )
 }