Merge pull request #83514 from kleonc/docs-multiplication-operators-d…

…oing-xform_inv-csharp

Clarify C# docs for operators performing `xform_inv`

doc/classes/Transform2D.xml

@@ -67,17 +67,17 @@
 			<param index="0" name="v" type="Vector2" />
 			<description>
 				Returns a vector transformed (multiplied) by the basis matrix.
-				This method does not account for translation (the origin vector).
+				This method does not account for translation (the [member origin] vector).
 			</description>
 		</method>
 		<method name="basis_xform_inv" qualifiers="const">
 			<return type="Vector2" />
 			<param index="0" name="v" type="Vector2" />
 			<description>
 				Returns a vector transformed (multiplied) by the inverse basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
-				This method does not account for translation (the origin vector).
+				This method does not account for translation (the [member origin] vector).
 				[code]transform.basis_xform_inv(vector)[/code] is equivalent to [code]transform.inverse().basis_xform(vector)[/code]. See [method inverse].
-				For non-orthonormal transforms (e.g. with scaling) use [code]transform.affine_inverse().basis_xform(vector)[/code] instead. See [method affine_inverse].
+				For non-orthonormal transforms (e.g. with scaling) [code]transform.affine_inverse().basis_xform(vector)[/code] can be used instead. See [method affine_inverse].
 			</description>
 		</method>
 		<method name="determinant" qualifiers="const">
@@ -276,14 +276,14 @@
 			<return type="Transform2D" />
 			<param index="0" name="right" type="float" />
 			<description>
-				This operator multiplies all components of the [Transform2D], including the origin vector, which scales it uniformly.
+				This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly.
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Transform2D" />
 			<param index="0" name="right" type="int" />
 			<description>
-				This operator multiplies all components of the [Transform2D], including the origin vector, which scales it uniformly.
+				This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly.
 			</description>
 		</operator>
 		<operator name="operator ==">

doc/classes/Transform3D.xml

@@ -235,14 +235,14 @@
 			<return type="Transform3D" />
 			<param index="0" name="right" type="float" />
 			<description>
-				This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly.
+				This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly.
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Transform3D" />
 			<param index="0" name="right" type="int" />
 			<description>
-				This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly.
+				This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly.
 			</description>
 		</operator>
 		<operator name="operator ==">

doc/classes/Vector3.xml

@@ -444,7 +444,7 @@
 			<description>
 				Inversely transforms (multiplies) the [Vector3] by the given [Basis] matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
 				[code]vector * basis[/code] is equivalent to [code]basis.transposed() * vector[/code]. See [method Basis.transposed].
-				For transforming by inverse of a non-orthonormal basis [code]basis.inverse() * vector[/code] can be used instead. See [method Basis.inverse].
+				For transforming by inverse of a non-orthonormal basis (e.g. with scaling) [code]basis.inverse() * vector[/code] can be used instead. See [method Basis.inverse].
 			</description>
 		</operator>
 		<operator name="operator *">

modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs

@@ -1037,10 +1037,11 @@ public static Basis FromScale(Vector3 scale)
         }
 
         /// <summary>
-        /// Returns a Vector3 transformed (multiplied) by the transposed basis matrix.
-        ///
-        /// Note: This results in a multiplication by the inverse of the
-        /// basis matrix only if it represents a rotation-reflection.
+        /// Returns a Vector3 transformed (multiplied) by the inverse basis matrix,
+        /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
+        /// <c>vector * basis</c> is equivalent to <c>basis.Transposed() * vector</c>. See <see cref="Transposed"/>.
+        /// For transforming by inverse of a non-orthonormal basis (e.g. with scaling) <c>basis.Inverse() * vector</c> can be used instead. See <see cref="Inverse"/>.
         /// </summary>
         /// <param name="vector">A Vector3 to inversely transform.</param>
         /// <param name="basis">The basis matrix transformation to apply.</param>

modules/mono/glue/GodotSharp/GodotSharp/Core/Projection.cs

@@ -905,7 +905,8 @@ public Projection(Transform3D transform)
         }
 
         /// <summary>
-        /// Returns a Vector4 transformed (multiplied) by the inverse projection.
+        /// Returns a Vector4 transformed (multiplied) by the transpose of the projection.
+        /// For transforming by inverse of a projection [code]projection.Inverse() * vector[/code] can be used instead. See <see cref="Inverse"/>.
         /// </summary>
         /// <param name="proj">The projection to apply.</param>
         /// <param name="vector">A Vector4 to transform.</param>

modules/mono/glue/GodotSharp/GodotSharp/Core/Quaternion.cs

@@ -644,6 +644,7 @@ public static Quaternion FromEuler(Vector3 eulerYXZ)
 
         /// <summary>
         /// Returns a Vector3 rotated (multiplied) by the inverse quaternion.
+        /// <c>vector * quaternion</c> is equivalent to <c>quaternion.Inverse() * vector</c>. See <see cref="Inverse"/>.
         /// </summary>
         /// <param name="vector">A Vector3 to inversely rotate.</param>
         /// <param name="quaternion">The quaternion to rotate by.</param>

modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs

@@ -126,7 +126,7 @@ readonly get
 
         /// <summary>
         /// Returns the inverse of the transform, under the assumption that
-        /// the transformation is composed of rotation, scaling, and translation.
+        /// the basis is invertible (must have non-zero determinant).
         /// </summary>
         /// <seealso cref="Inverse"/>
         /// <returns>The inverse transformation matrix.</returns>
@@ -180,11 +180,12 @@ public readonly Vector2 BasisXform(Vector2 v)
         }
 
         /// <summary>
-        /// Returns a vector transformed (multiplied) by the inverse basis matrix.
+        /// Returns a vector transformed (multiplied) by the inverse basis matrix,
+        /// under the assumption that the basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
         /// This method does not account for translation (the <see cref="Origin"/> vector).
-        ///
-        /// Note: This results in a multiplication by the inverse of the
-        /// basis matrix only if it represents a rotation-reflection.
+        /// <c>transform.BasisXformInv(vector)</c> is equivalent to <c>transform.Inverse().BasisXform(vector)</c>. See <see cref="Inverse"/>.
+        /// For non-orthonormal transforms (e.g. with scaling) <c>transform.AffineInverse().BasisXform(vector)</c> can be used instead. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <seealso cref="BasisXform(Vector2)"/>
         /// <param name="v">A vector to inversely transform.</param>
@@ -213,8 +214,9 @@ public readonly Transform2D InterpolateWith(Transform2D transform, real_t weight
 
         /// <summary>
         /// Returns the inverse of the transform, under the assumption that
-        /// the transformation is composed of rotation and translation
-        /// (no scaling, use <see cref="AffineInverse"/> for transforms with scaling).
+        /// the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not). Use <see cref="AffineInverse"/> for
+        /// non-orthonormal transforms (e.g. with scaling).
         /// </summary>
         /// <returns>The inverse matrix.</returns>
         public readonly Transform2D Inverse()
@@ -480,7 +482,11 @@ public Transform2D(real_t rotation, Vector2 scale, real_t skew, Vector2 origin)
         }
 
         /// <summary>
-        /// Returns a Vector2 transformed (multiplied) by the inverse transformation matrix.
+        /// Returns a Vector2 transformed (multiplied) by the inverse transformation matrix,
+        /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
+        /// <c>vector * transform</c> is equivalent to <c>transform.Inverse() * vector</c>. See <see cref="Inverse"/>.
+        /// For transforming by inverse of an affine transformation (e.g. with scaling) <c>transform.AffineInverse() * vector</c> can be used instead. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <param name="vector">A Vector2 to inversely transform.</param>
         /// <param name="transform">The transformation to apply.</param>
@@ -507,7 +513,11 @@ public Transform2D(real_t rotation, Vector2 scale, real_t skew, Vector2 origin)
         }
 
         /// <summary>
-        /// Returns a Rect2 transformed (multiplied) by the inverse transformation matrix.
+        /// Returns a Rect2 transformed (multiplied) by the inverse transformation matrix,
+        /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
+        /// <c>rect * transform</c> is equivalent to <c>transform.Inverse() * rect</c>. See <see cref="Inverse"/>.
+        /// For transforming by inverse of an affine transformation (e.g. with scaling) <c>transform.AffineInverse() * rect</c> can be used instead. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <param name="rect">A Rect2 to inversely transform.</param>
         /// <param name="transform">The transformation to apply.</param>
@@ -541,7 +551,11 @@ public Transform2D(real_t rotation, Vector2 scale, real_t skew, Vector2 origin)
         }
 
         /// <summary>
-        /// Returns a copy of the given Vector2[] transformed (multiplied) by the inverse transformation matrix.
+        /// Returns a copy of the given Vector2[] transformed (multiplied) by the inverse transformation matrix,
+        /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
+        /// <c>array * transform</c> is equivalent to <c>transform.Inverse() * array</c>. See <see cref="Inverse"/>.
+        /// For transforming by inverse of an affine transformation (e.g. with scaling) <c>transform.AffineInverse() * array</c> can be used instead. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <param name="array">A Vector2[] to inversely transform.</param>
         /// <param name="transform">The transformation to apply.</param>

modules/mono/glue/GodotSharp/GodotSharp/Core/Transform3D.cs

@@ -105,7 +105,7 @@ readonly get
 
         /// <summary>
         /// Returns the inverse of the transform, under the assumption that
-        /// the transformation is composed of rotation, scaling, and translation.
+        /// the basis is invertible (must have non-zero determinant).
         /// </summary>
         /// <seealso cref="Inverse"/>
         /// <returns>The inverse transformation matrix.</returns>
@@ -144,8 +144,9 @@ public readonly Transform3D InterpolateWith(Transform3D transform, real_t weight
 
         /// <summary>
         /// Returns the inverse of the transform, under the assumption that
-        /// the transformation is composed of rotation and translation
-        /// (no scaling, use <see cref="AffineInverse"/> for transforms with scaling).
+        /// the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not). Use <see cref="AffineInverse"/> for
+        /// non-orthonormal transforms (e.g. with scaling).
         /// </summary>
         /// <returns>The inverse matrix.</returns>
         public readonly Transform3D Inverse()
@@ -426,10 +427,11 @@ public Transform3D(Projection projection)
         }
 
         /// <summary>
-        /// Returns a Vector3 transformed (multiplied) by the transposed transformation matrix.
-        ///
-        /// Note: This results in a multiplication by the inverse of the
-        /// transformation matrix only if it represents a rotation-reflection.
+        /// Returns a Vector3 transformed (multiplied) by the inverse transformation matrix,
+        /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
+        /// <c>vector * transform</c> is equivalent to <c>transform.Inverse() * vector</c>. See <see cref="Inverse"/>.
+        /// For transforming by inverse of an affine transformation (e.g. with scaling) <c>transform.AffineInverse() * vector</c> can be used instead. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <param name="vector">A Vector3 to inversely transform.</param>
         /// <param name="transform">The transformation to apply.</param>
@@ -482,7 +484,11 @@ public Transform3D(Projection projection)
         }
 
         /// <summary>
-        /// Returns an AABB transformed (multiplied) by the inverse transformation matrix.
+        /// Returns an AABB transformed (multiplied) by the inverse transformation matrix,
+        /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
+        /// <c>aabb * transform</c> is equivalent to <c>transform.Inverse() * aabb</c>. See <see cref="Inverse"/>.
+        /// For transforming by inverse of an affine transformation (e.g. with scaling) <c>transform.AffineInverse() * aabb</c> can be used instead. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <param name="aabb">An AABB to inversely transform.</param>
         /// <param name="transform">The transformation to apply.</param>
@@ -523,6 +529,7 @@ public Transform3D(Projection projection)
 
         /// <summary>
         /// Returns a Plane transformed (multiplied) by the inverse transformation matrix.
+        /// <c>plane * transform</c> is equivalent to <c>transform.AffineInverse() * plane</c>. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <param name="plane">A Plane to inversely transform.</param>
         /// <param name="transform">The transformation to apply.</param>
@@ -568,7 +575,11 @@ public Transform3D(Projection projection)
         }
 
         /// <summary>
-        /// Returns a copy of the given Vector3[] transformed (multiplied) by the inverse transformation matrix.
+        /// Returns a copy of the given Vector3[] transformed (multiplied) by the inverse transformation matrix,
+        /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection
+        /// is fine, scaling/skew is not).
+        /// <c>array * transform</c> is equivalent to <c>transform.Inverse() * array</c>. See <see cref="Inverse"/>.
+        /// For transforming by inverse of an affine transformation (e.g. with scaling) <c>transform.AffineInverse() * array</c> can be used instead. See <see cref="AffineInverse"/>.
         /// </summary>
         /// <param name="array">A Vector3[] to inversely transform.</param>
         /// <param name="transform">The transformation to apply.</param>