Rename Transform::mul_vec3 to transform_point and improve docs (bevyengine#6132)

The docs ended up quite verbose :v

Also added a missing `#[inline]` to `GlobalTransform::mul_transform`.

I'd say this resolves bevyengine#5500

# Migration Guide
`Transform::mul_vec3` has been renamed to `transform_point`.

Co-authored-by: devil-ira <justthecooldude@gmail.com>

Author: tim-blackbird

crates/bevy_sprite/src/render/mod.rs

@@ -568,7 +568,9 @@ pub fn queue_sprites(
                 let positions = QUAD_VERTEX_POSITIONS.map(|quad_pos| {
                     extracted_sprite
                         .transform
-                        .mul_vec3(((quad_pos - extracted_sprite.anchor) * quad_size).extend(0.))
+                        .transform_point(
+                            ((quad_pos - extracted_sprite.anchor) * quad_size).extend(0.),
+                        )
                         .into()
                 });
 

crates/bevy_transform/src/components/global_transform.rs

@@ -142,14 +142,17 @@ impl GlobalTransform {
         (self.0.matrix3 * extents).length()
     }
 
-    /// Returns a [`Vec3`] of this [`Transform`] applied to `value`.
+    /// Transforms the given `point`, applying shear, scale, rotation and translation.
+    ///
+    /// This moves `point` into the local space of this [`GlobalTransform`].
     #[inline]
-    pub fn mul_vec3(&self, v: Vec3) -> Vec3 {
-        self.0.transform_point3(v)
+    pub fn transform_point(&self, point: Vec3) -> Vec3 {
+        self.0.transform_point3(point)
     }
 
     /// Multiplies `self` with `transform` component by component, returning the
     /// resulting [`GlobalTransform`]
+    #[inline]
     pub fn mul_transform(&self, transform: Transform) -> Self {
         Self(self.0 * transform.compute_affine())
     }
@@ -202,6 +205,6 @@ impl Mul<Vec3> for GlobalTransform {
 
     #[inline]
     fn mul(self, value: Vec3) -> Self::Output {
-        self.mul_vec3(value)
+        self.transform_point(value)
     }
 }

crates/bevy_transform/src/components/transform.rs

@@ -328,7 +328,7 @@ impl Transform {
     #[inline]
     #[must_use]
     pub fn mul_transform(&self, transform: Transform) -> Self {
-        let translation = self.mul_vec3(transform.translation);
+        let translation = self.transform_point(transform.translation);
         let rotation = self.rotation * transform.rotation;
         let scale = self.scale * transform.scale;
         Transform {
@@ -338,13 +338,22 @@ impl Transform {
         }
     }
 
-    /// Returns a [`Vec3`] of this [`Transform`] applied to `value`.
+    /// Transforms the given `point`, applying scale, rotation and translation.
+    ///
+    /// If this [`Transform`] has a parent, this will transform a `point` that is
+    /// relative to the parent's [`Transform`] into one relative to this [`Transform`].
+    ///
+    /// If this [`Transform`] does not have a parent, this will transform a `point`
+    /// that is in global space into one relative to this [`Transform`].
+    ///
+    /// If you want to transform a `point` in global space to the local space of this [`Transform`],
+    /// consider using [`GlobalTransform::transform_point()`] instead.
     #[inline]
-    pub fn mul_vec3(&self, mut value: Vec3) -> Vec3 {
-        value = self.scale * value;
-        value = self.rotation * value;
-        value += self.translation;
-        value
+    pub fn transform_point(&self, mut point: Vec3) -> Vec3 {
+        point = self.scale * point;
+        point = self.rotation * point;
+        point += self.translation;
+        point
     }
 
     /// Changes the `scale` of this [`Transform`], multiplying the current `scale` by
@@ -381,6 +390,6 @@ impl Mul<Vec3> for Transform {
     type Output = Vec3;
 
     fn mul(self, value: Vec3) -> Self::Output {
-        self.mul_vec3(value)
+        self.transform_point(value)
     }
 }

examples/tools/scene_viewer.rs

@@ -226,7 +226,7 @@ fn setup_scene_after_load(
             // correct bounds. However, it could very well be rotated and so we first convert to
             // a Sphere, and then back to an Aabb to find the conservative min and max points.
             let sphere = Sphere {
-                center: Vec3A::from(transform.mul_vec3(Vec3::from(aabb.center))),
+                center: Vec3A::from(transform.transform_point(Vec3::from(aabb.center))),
                 radius: transform.radius_vec3a(aabb.half_extents),
             };
             let aabb = Aabb::from(sphere);