Implement XformInv<T> for Transforms.

- Create new trait `XformInv<...>`.
- Implement `XformInv<Rect2/Vector2>` for `Transform2D` and `Transform2D::basis_xform_inv`.
- Implement `XformInv<Aabb/Plane/Vector3>` for `Transform3D` and `XformInv<Vector3>` for `Basis`.
- Document transform/basis operations.

Author: Yarwin

godot-core/src/builtin/basis.rs

@@ -8,7 +8,7 @@
 use godot_ffi as sys;
 use sys::{ffi_methods, GodotFfi};
 
-use crate::builtin::math::{ApproxEq, FloatExt, GlamConv, GlamType};
+use crate::builtin::math::{ApproxEq, FloatExt, GlamConv, GlamType, XformInv};
 use crate::builtin::real_consts::FRAC_PI_2;
 use crate::builtin::{real, EulerOrder, Quaternion, RMat3, RQuat, RVec2, RVec3, Vector3};
 use std::cmp::Ordering;
@@ -629,6 +629,24 @@ impl Mul<Vector3> for Basis {
     }
 }
 
+impl XformInv<Vector3> for Basis {
+    /// Inversely transforms given [`Vector3`] by this basis,
+    /// under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+    ///
+    /// `basis.xform_inv(vector)` is equivalent to `basis.transposed() * vector`. See [`Basis::transposed()`].
+    ///
+    /// For transforming by inverse of a non-orthonormal basis (e.g. with scaling) `basis.inverse() * vector` can be used instead. See [`Basis::inverse()`].
+    ///
+    /// _Godot equivalent: `vector * basis`_
+    fn xform_inv(&self, rhs: Vector3) -> Vector3 {
+        Vector3::new(
+            self.col_a().dot(rhs),
+            self.col_b().dot(rhs),
+            self.col_c().dot(rhs),
+        )
+    }
+}
+
 // SAFETY:
 // This type is represented as `Self` in Godot, so `*mut Self` is sound.
 unsafe impl GodotFfi for Basis {

godot-core/src/builtin/math/mod.rs

@@ -8,10 +8,12 @@
 mod approx_eq;
 mod float;
 mod glam_helpers;
+mod xform;
 
 pub use crate::{assert_eq_approx, assert_ne_approx};
 pub use approx_eq::ApproxEq;
 pub use float::FloatExt;
+pub use xform::XformInv;
 
 // Internal glam re-exports
 pub(crate) use glam_helpers::*;

godot-core/src/builtin/math/xform.rs

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/// Applying inverse transforms.
+///
+/// See also: [`Transform2D`](crate::builtin::Transform2D), [`Transform3D`](crate::builtin::Transform3D), [`Basis`](crate::builtin::Basis).
+///
+/// _Godot equivalent: `rhs * mat`_
+pub trait XformInv<T> {
+    fn xform_inv(&self, rhs: T) -> T;
+}

godot-core/src/builtin/mod.rs

@@ -26,6 +26,7 @@ pub use crate::sys::VariantType;
 pub mod __prelude_reexport {
     use super::*;
 
+    pub use super::math::XformInv;
     pub use aabb::*;
     pub use basis::*;
     pub use callable::*;

godot-core/src/builtin/transform2d.rs

@@ -8,7 +8,7 @@
 use godot_ffi as sys;
 use sys::{ffi_methods, GodotFfi};
 
-use crate::builtin::math::{assert_ne_approx, ApproxEq, FloatExt, GlamConv, GlamType};
+use crate::builtin::math::{assert_ne_approx, ApproxEq, FloatExt, GlamConv, GlamType, XformInv};
 use crate::builtin::real_consts::PI;
 use crate::builtin::{real, RAffine2, RMat2, Rect2, Vector2};
 
@@ -37,6 +37,15 @@ use std::ops::{Mul, MulAssign};
 /// [`Transform3D`]: crate::builtin::Transform3D
 /// [`Projection`]: crate::builtin::Projection
 ///
+/// # Transform operations
+///
+/// | Operation                      | Transform2D                    | Notes                               |
+/// |--------------------------------|--------------------------------|-------------------------------------|
+/// | Apply                          | transform * v                  | Supports [`Rect2`] and [`Vector2`]. |
+/// | Apply inverse                  | transform.xform_inv(v)         | Supports [`Rect2`] and [`Vector2`]. |
+/// | Apply, no translate            | transform.basis_xform(v)       | Supports [`Vector2`].               |
+/// | Apply inverse, no translate    | transform.basis_xform_inv(v)   | Supports [`Vector2`].               |
+///
 /// # Godot docs
 ///
 /// [`Transform2D` (stable)](https://docs.godotengine.org/en/stable/classes/class_transform2d.html)
@@ -349,6 +358,19 @@ impl Mul<Vector2> for Transform2D {
     }
 }
 
+impl XformInv<Vector2> for Transform2D {
+    /// Inversely transforms (multiplies) the given [`Vector2`] by this transformation matrix,
+    /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+    ///
+    /// For transforming by inverse of an affine transformation (e.g. with scaling) `transform.affine_inverse() * vector` can be used instead. See: [`Transform2D::affine_inverse()`].
+    ///
+    /// _Godot equivalent: `vector * transform` or `transform.inverse() * vector`_
+    fn xform_inv(&self, rhs: Vector2) -> Vector2 {
+        let v = rhs - self.origin;
+        self.basis_xform_inv(v)
+    }
+}
+
 impl Mul<real> for Transform2D {
     type Output = Self;
 
@@ -370,9 +392,41 @@ impl Mul<Rect2> for Transform2D {
         let ya = self.b * rhs.position.y;
         let yb = self.b * rhs.end().y;
 
-        let position = Vector2::coord_min(xa, xb) + Vector2::coord_min(ya, yb) + self.origin;
-        let end = Vector2::coord_max(xa, xb) + Vector2::coord_max(ya, yb) + self.origin;
-        Rect2::new(position, end - position)
+        let position = Vector2::coord_min(xa, xb) + Vector2::coord_min(ya, yb);
+        let end = Vector2::coord_max(xa, xb) + Vector2::coord_max(ya, yb);
+        Rect2::new(position + self.origin, end - position)
+    }
+}
+
+impl XformInv<Rect2> for Transform2D {
+    /// Inversely transforms (multiplies) the given [`Rect2`] by this [`Transform2D`] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+    ///
+    /// For transforming by inverse of an affine transformation (e.g. with scaling) `transform.affine_inverse() * vector` can be used instead. See: [`Transform2D::affine_inverse()`].
+    ///
+    /// _Godot equivalent: `rect2 * transform` or `transform.inverse() * rect2`_
+    fn xform_inv(&self, rhs: Rect2) -> Rect2 {
+        // https://web.archive.org/web/20220317024830/https://dev.theomader.com/transform-bounding-boxes/
+        // Same as Godot's `Transform2D::xform_inv` but omits unnecessary `Rect2::expand_to`.
+        // There is probably some more clever way to do that.
+
+        // Use the first point initialize our min/max.
+        let start = self.xform_inv(rhs.position);
+        // `min` is position of our aabb, `max` is the farthest vertex.
+        let (mut min, mut max) = (start, start);
+
+        let vertices = [
+            Vector2::new(rhs.position.x, rhs.position.y + rhs.size.y),
+            rhs.end(),
+            Vector2::new(rhs.position.x + rhs.size.x, rhs.position.y),
+        ];
+
+        for v in vertices {
+            let transformed = self.xform_inv(v);
+            min = Vector2::coord_min(min, transformed);
+            max = Vector2::coord_max(max, transformed);
+        }
+
+        Rect2::new(min, max - min)
     }
 }
 

godot-core/src/builtin/transform3d.rs

@@ -8,7 +8,7 @@
 use godot_ffi as sys;
 use sys::{ffi_methods, GodotFfi};
 
-use crate::builtin::math::{ApproxEq, GlamConv, GlamType};
+use crate::builtin::math::{ApproxEq, GlamConv, GlamType, XformInv};
 use crate::builtin::{real, Aabb, Basis, Plane, Projection, RAffine3, Vector3};
 
 use std::fmt::Display;
@@ -37,6 +37,15 @@ use std::ops::Mul;
 /// [`Transform2D`]: crate::builtin::Transform2D
 /// [`Projection`]: Projection
 ///
+/// # Transform operations
+///
+/// | Operation                      | Transform3D                    | Notes                                      |
+/// |--------------------------------|--------------------------------|--------------------------------------------|
+/// | Apply                          | `transform * v`                | Supports [`Aabb`], [`Plane`], [`Vector3`]. |
+/// | Apply inverse                  | `transform.xform_inv(v)`       | Supports [`Aabb`], [`Plane`], [`Vector3`]. |
+/// | Apply, no translate            | `transform.basis * v`          | Supports [`Vector3`].                      |
+/// | Apply inverse, no translate    | `transform.basis.xform_inv(v)` | Supports [`Vector3`].                      |
+///
 /// # Godot docs
 ///
 /// [`Transform3D` (stable)](https://docs.godotengine.org/en/stable/classes/class_transform3d.html)
@@ -303,6 +312,19 @@ impl Mul<Vector3> for Transform3D {
     }
 }
 
+impl XformInv<Vector3> for Transform3D {
+    /// Inversely transforms given [`Vector3`] by this transformation matrix,
+    /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+    ///
+    /// For transforming by inverse of an affine transformation (e.g. with scaling) `transform.affine_inverse() * vector` can be used instead. See [`Transform3D::affine_inverse()`].
+    ///
+    /// _Godot equivalent: `aabb * transform`_
+    fn xform_inv(&self, rhs: Vector3) -> Vector3 {
+        let v = rhs - self.origin;
+        self.basis.xform_inv(v)
+    }
+}
+
 impl Mul<real> for Transform3D {
     type Output = Self;
 
@@ -342,6 +364,55 @@ impl Mul<Aabb> for Transform3D {
     }
 }
 
+impl XformInv<Aabb> for Transform3D {
+    /// Inversely transforms each vertex in given [`Aabb`] individually by this transformation matrix,
+    /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not),
+    /// and then creates an `Aabb` encompassing all of them.
+    ///
+    /// For transforming by inverse of an affine transformation (e.g. with scaling) `transform.affine_inverse() * aabb` can be used instead. See [`Transform3D::affine_inverse()`].
+    ///
+    /// _Godot equivalent: `aabb * transform`_
+    fn xform_inv(&self, rhs: Aabb) -> Aabb {
+        // Same as Godot's `Transform3D::xform_inv` but omits unnecessary `Aabb::expand_to`.
+        // There is probably some more clever way to do that.
+
+        // Use the first vertex initialize our min/max.
+        let end = self.xform_inv(rhs.end());
+        // `min` is the "lowest" vertex of our Aabb, `max` is the farthest vertex.
+        let (mut min, mut max) = (end, end);
+
+        let vertices = [
+            Vector3::new(
+                rhs.position.x + rhs.size.x,
+                rhs.position.y + rhs.size.y,
+                rhs.position.z,
+            ),
+            Vector3::new(
+                rhs.position.x + rhs.size.x,
+                rhs.position.y,
+                rhs.position.z + rhs.size.z,
+            ),
+            Vector3::new(rhs.position.x + rhs.size.x, rhs.position.y, rhs.position.z),
+            Vector3::new(
+                rhs.position.x,
+                rhs.position.y + rhs.size.y,
+                rhs.position.z + rhs.size.z,
+            ),
+            Vector3::new(rhs.position.x, rhs.position.y + rhs.size.y, rhs.position.z),
+            Vector3::new(rhs.position.x, rhs.position.y, rhs.position.z + rhs.size.z),
+            rhs.position,
+        ];
+
+        for v in vertices {
+            let transformed = self.xform_inv(v);
+            min = Vector3::coord_min(min, transformed);
+            max = Vector3::coord_max(max, transformed);
+        }
+
+        Aabb::new(min, max - min)
+    }
+}
+
 impl Mul<Plane> for Transform3D {
     type Output = Plane;
 
@@ -354,6 +425,17 @@ impl Mul<Plane> for Transform3D {
     }
 }
 
+impl XformInv<Plane> for Transform3D {
+    /// Inversely transforms (multiplies) the Plane by the given Transform3D transformation matrix.
+    ///
+    /// `transform.xform_inv(plane)` is equivalent to `transform.affine_inverse() * plane`. See [`Transform3D::affine_inverse()`].
+    ///
+    /// _Godot equivalent: `plane * transform`_
+    fn xform_inv(&self, rhs: Plane) -> Plane {
+        self.affine_inverse() * rhs
+    }
+}
+
 impl ApproxEq for Transform3D {
     /// Returns if the two transforms are approximately equal, by comparing `basis` and `origin` separately.
     fn approx_eq(&self, other: &Self) -> bool {

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

@@ -8,7 +8,7 @@
 use crate::framework::itest;
 
 use godot::builtin::inner::InnerTransform2D;
-use godot::builtin::{real, RealConv, Rect2, Transform2D, VariantOperator, Vector2};
+use godot::builtin::{real, RealConv, Rect2, Transform2D, VariantOperator, Vector2, XformInv};
 use godot::meta::ToGodot;
 use godot::private::class_macros::assert_eq_approx;
 
@@ -18,6 +18,12 @@ const TEST_TRANSFORM: Transform2D = Transform2D::from_cols(
     Vector2::new(5.0, 6.0),
 );
 
+const TEST_TRANSFORM_ORTHONORMAL: Transform2D = Transform2D::from_cols(
+    Vector2::new(1.0, 0.0),
+    Vector2::new(0.0, 1.0),
+    Vector2::new(5.0, 6.0),
+);
+
 #[itest]
 fn transform2d_equiv() {
     let inner = InnerTransform2D::from_outer(&TEST_TRANSFORM);
@@ -106,3 +112,48 @@ fn transform2d_xform_equiv() {
         "operator: Transform2D * Rect2 (2)"
     );
 }
+
+#[itest]
+fn transform2d_xform_inv_equiv() {
+    let vec = Vector2::new(1.0, 2.0);
+
+    assert_eq_approx!(
+        TEST_TRANSFORM_ORTHONORMAL.xform_inv(vec),
+        vec.to_variant()
+            .evaluate(
+                &TEST_TRANSFORM_ORTHONORMAL.to_variant(),
+                VariantOperator::MULTIPLY
+            )
+            .unwrap()
+            .to::<Vector2>(),
+        "operator: Transform2D * Vector2"
+    );
+
+    let rect_2 = Rect2::new(Vector2::new(1.0, 2.0), Vector2::new(3.0, 4.0));
+
+    assert_eq_approx!(
+        TEST_TRANSFORM_ORTHONORMAL.xform_inv(rect_2),
+        rect_2
+            .to_variant()
+            .evaluate(
+                &TEST_TRANSFORM_ORTHONORMAL.to_variant(),
+                VariantOperator::MULTIPLY
+            )
+            .unwrap()
+            .to::<Rect2>(),
+        "operator: Transform2D * Rect2 (1)"
+    );
+
+    assert_eq_approx!(
+        TEST_TRANSFORM_ORTHONORMAL.rotated(0.8).xform_inv(rect_2),
+        rect_2
+            .to_variant()
+            .evaluate(
+                &TEST_TRANSFORM_ORTHONORMAL.rotated(0.8).to_variant(),
+                VariantOperator::MULTIPLY
+            )
+            .unwrap()
+            .to::<Rect2>(),
+        "operator: Transform2D * Rect2 (2)"
+    );
+}