Merge pull request #55923 from bluenote10/feature/consistent_transform_operations

Fix consistency of translated/scaled/rotated in Transform2D and Transform3D

2 files changed, 87 insertions, 8 deletions

diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml
index 924b4cd8e4..9979a73527 100644
--- a/doc/classes/Transform2D.xml
+++ b/doc/classes/Transform2D.xml
@@ -141,14 +141,40 @@
 			<return type="Transform2D" />
 			<argument index="0" name="angle" type="float" />
 			<description>
-				Returns a copy of the transform rotated by the given [code]angle[/code] (in radians), using matrix multiplication.
+				Returns a copy of the transform rotated by the given [code]angle[/code] (in radians).
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding rotation transform [code]R[/code] from the left, i.e., [code]R * X[/code].
+				This can be seen as transforming with respect to the global/parent frame.
+			</description>
+		</method>
+		<method name="rotated_local" qualifiers="const">
+			<return type="Transform2D" />
+			<argument index="0" name="angle" type="float" />
+			<description>
+				Returns a copy of the transform rotated by the given [code]angle[/code] (in radians).
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding rotation transform [code]R[/code] from the right, i.e., [code]X * R[/code].
+				This can be seen as transforming with respect to the local frame.
 			</description>
 		</method>
 		<method name="scaled" qualifiers="const">
 			<return type="Transform2D" />
 			<argument index="0" name="scale" type="Vector2" />
 			<description>
-				Returns a copy of the transform scaled by the given [code]scale[/code] factor, using matrix multiplication.
+				Returns a copy of the transform scaled by the given [code]scale[/code] factor.
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding scaling transform [code]S[/code] from the left, i.e., [code]S * X[/code].
+				This can be seen as transforming with respect to the global/parent frame.
+			</description>
+		</method>
+		<method name="scaled_local" qualifiers="const">
+			<return type="Transform2D" />
+			<argument index="0" name="scale" type="Vector2" />
+			<description>
+				Returns a copy of the transform scaled by the given [code]scale[/code] factor.
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding scaling transform [code]S[/code] from the right, i.e., [code]X * S[/code].
+				This can be seen as transforming with respect to the local frame.
 			</description>
 		</method>
 		<method name="set_rotation">
@@ -173,12 +199,24 @@
 				Sets the transform's skew (in radians).
 			</description>
 		</method>
+		<method name="translated" qualifiers="const">
+			<return type="Transform2D" />
+			<argument index="0" name="offset" type="Vector2" />
+			<description>
+				Returns a copy of the transform translated by the given [code]offset[/code].
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding translation transform [code]T[/code] from the left, i.e., [code]T * X[/code].
+				This can be seen as transforming with respect to the global/parent frame.
+			</description>
+		</method>
 		<method name="translated_local" qualifiers="const">
 			<return type="Transform2D" />
 			<argument index="0" name="offset" type="Vector2" />
 			<description>
-				Returns a copy of the transform translated by the given [code]offset[/code], relative to the transform's basis vectors.
-				Unlike [method rotated] and [method scaled], this does not use matrix multiplication.
+				Returns a copy of the transform translated by the given [code]offset[/code].
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding translation transform [code]T[/code] from the right, i.e., [code]X * T[/code].
+				This can be seen as transforming with respect to the local frame.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml
index de1db718c2..9b673701ae 100644
--- a/doc/classes/Transform3D.xml
+++ b/doc/classes/Transform3D.xml
@@ -102,14 +102,43 @@
 			<argument index="0" name="axis" type="Vector3" />
 			<argument index="1" name="angle" type="float" />
 			<description>
-				Returns a copy of the transform rotated around the given [code]axis[/code] by the given [code]angle[/code] (in radians), using matrix multiplication. The [code]axis[/code] must be a normalized vector.
+				Returns a copy of the transform rotated around the given [code]axis[/code] by the given [code]angle[/code] (in radians).
+				The [code]axis[/code] must be a normalized vector.
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding rotation transform [code]R[/code] from the left, i.e., [code]R * X[/code].
+				This can be seen as transforming with respect to the global/parent frame.
+			</description>
+		</method>
+		<method name="rotated_local" qualifiers="const">
+			<return type="Transform3D" />
+			<argument index="0" name="axis" type="Vector3" />
+			<argument index="1" name="angle" type="float" />
+			<description>
+				Returns a copy of the transform rotated around the given [code]axis[/code] by the given [code]angle[/code] (in radians).
+				The [code]axis[/code] must be a normalized vector.
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding rotation transform [code]R[/code] from the right, i.e., [code]X * R[/code].
+				This can be seen as transforming with respect to the local frame.
 			</description>
 		</method>
 		<method name="scaled" qualifiers="const">
 			<return type="Transform3D" />
 			<argument index="0" name="scale" type="Vector3" />
 			<description>
-				Returns a copy of the transform with its basis and origin scaled by the given [code]scale[/code] factor, using matrix multiplication.
+				Returns a copy of the transform scaled by the given [code]scale[/code] factor.
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding scaling transform [code]S[/code] from the left, i.e., [code]S * X[/code].
+				This can be seen as transforming with respect to the global/parent frame.
+			</description>
+		</method>
+		<method name="scaled_local" qualifiers="const">
+			<return type="Transform3D" />
+			<argument index="0" name="scale" type="Vector3" />
+			<description>
+				Returns a copy of the transform scaled by the given [code]scale[/code] factor.
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding scaling transform [code]S[/code] from the right, i.e., [code]X * S[/code].
+				This can be seen as transforming with respect to the local frame.
 			</description>
 		</method>
 		<method name="spherical_interpolate_with" qualifiers="const">
@@ -120,12 +149,24 @@
 				Returns a transform spherically interpolated between this transform and another by a given [code]weight[/code] (on the range of 0.0 to 1.0).
 			</description>
 		</method>
+		<method name="translated" qualifiers="const">
+			<return type="Transform3D" />
+			<argument index="0" name="offset" type="Vector3" />
+			<description>
+				Returns a copy of the transform translated by the given [code]offset[/code].
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding translation transform [code]T[/code] from the left, i.e., [code]T * X[/code].
+				This can be seen as transforming with respect to the global/parent frame.
+			</description>
+		</method>
 		<method name="translated_local" qualifiers="const">
 			<return type="Transform3D" />
 			<argument index="0" name="offset" type="Vector3" />
 			<description>
-				Returns a copy of the transform translated by the given [code]offset[/code], relative to the transform's basis vectors.
-				Unlike [method rotated] and [method scaled], this does not use matrix multiplication.
+				Returns a copy of the transform translated by the given [code]offset[/code].
+				This method is an optimized version of multiplying the given transform [code]X[/code]
+				with a corresponding translation transform [code]T[/code] from the right, i.e., [code]X * T[/code].
+				This can be seen as transforming with respect to the local frame.
 			</description>
 		</method>
 	</methods>