Merge pull request #94127 from Mickeon/doc-peeves-transform2d

Overhaul Transform2D documentation

doc/classes/Transform2D.xml

@@ -4,8 +4,10 @@
 		A 2×3 matrix representing a 2D transformation.
 	</brief_description>
 	<description>
-		A 2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of three [Vector2] values: [member x], [member y], and the [member origin].
+		The [Transform2D] built-in [Variant] type is a 2×3 [url=https://en.wikipedia.org/wiki/Matrix_(mathematics)]matrix[/url] representing a transformation in 2D space. It contains three [Vector2] values: [member x], [member y], and [member origin]. Together, they can represent translation, rotation, scale, and skew.
+		The [member x] and [member y] axes form a 2×2 matrix, known as the transform's [b]basis[/b]. The length of each axis ([method Vector2.length]) influences the transform's scale, while the direction of all axes influence the rotation. Usually, both axes are perpendicular to one another. However, when you rotate one axis individually, the transform becomes skewed. Applying a skewed transform to a 2D sprite will make the sprite appear distorted.
 		For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial.
+		[b]Note:[/b] Unlike [Transform3D], there is no 2D equivalent to the [Basis] type. All mentions of "basis" refer to the [member x] and [member y] components of [Transform2D].
 	</description>
 	<tutorials>
 		<link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link>
@@ -17,7 +19,7 @@
 		<constructor name="Transform2D">
 			<return type="Transform2D" />
 			<description>
-				Constructs a default-initialized [Transform2D] set to [constant IDENTITY].
+				Constructs a [Transform2D] identical to [constant IDENTITY].
 			</description>
 		</constructor>
 		<constructor name="Transform2D">
@@ -32,7 +34,7 @@
 			<param index="0" name="rotation" type="float" />
 			<param index="1" name="position" type="Vector2" />
 			<description>
-				Constructs the transform from a given angle (in radians) and position.
+				Constructs a [Transform2D] from a given angle (in radians) and position.
 			</description>
 		</constructor>
 		<constructor name="Transform2D">
@@ -42,7 +44,7 @@
 			<param index="2" name="skew" type="float" />
 			<param index="3" name="position" type="Vector2" />
 			<description>
-				Constructs the transform from a given angle (in radians), scale, skew (in radians) and position.
+				Constructs a [Transform2D] from a given angle (in radians), scale, skew (in radians), and position.
 			</description>
 		</constructor>
 		<constructor name="Transform2D">
@@ -51,7 +53,7 @@
 			<param index="1" name="y_axis" type="Vector2" />
 			<param index="2" name="origin" type="Vector2" />
 			<description>
-				Constructs the transform from 3 [Vector2] values representing [member x], [member y], and the [member origin] (the three column vectors).
+				Constructs a [Transform2D] from 3 [Vector2] values representing [member x], [member y], and the [member origin] (the three matrix columns).
 			</description>
 		</constructor>
 	</constructors>
@@ -59,56 +61,81 @@
 		<method name="affine_inverse" qualifiers="const">
 			<return type="Transform2D" />
 			<description>
-				Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant).
+				Returns the inverted version of this transform. Unlike [method inverse], this method works with almost any basis, including non-uniform ones, but is slower. See also [method inverse].
+				[b]Note:[/b] For this method to return correctly, the transform's basis needs to have a determinant that is not exactly [code]0[/code] (see [method determinant]).
 			</description>
 		</method>
 		<method name="basis_xform" qualifiers="const">
 			<return type="Vector2" />
 			<param index="0" name="v" type="Vector2" />
 			<description>
-				Returns a vector transformed (multiplied) by the basis matrix.
+				Returns a copy of the [param v] vector, transformed (multiplied) by the transform basis's matrix. Unlike the multiplication operator ([code]*[/code]), this method ignores the [member origin].
-				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).
+				Returns a copy of the [param v] vector, transformed (multiplied) by the inverse transform basis's matrix (see [method inverse]). This method ignores the [member origin].
-				This method does not account for translation (the [member origin] vector).
+				[b]Note:[/b] This method assumes that this transform's basis is [i]orthonormal[/i] (see [method orthonormalized]). If the basis is not orthonormal, [code]transform.affine_inverse().basis_xform(vector)[/code] should be used instead (see [method affine_inverse]).
-				[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) [code]transform.affine_inverse().basis_xform(vector)[/code] can be used instead. See [method affine_inverse].
 			</description>
 		</method>
 		<method name="determinant" qualifiers="const">
 			<return type="float" />
 			<description>
-				Returns the determinant of the basis matrix. If the basis is uniformly scaled, then its determinant equals the square of the scale factor.
+				Returns the [url=https://en.wikipedia.org/wiki/Determinant]determinant[/url] of this transform basis's matrix. For advanced math, this number can be used to determine a few attributes:
-				A negative determinant means the basis was flipped, so one part of the scale is negative. A zero determinant means the basis isn't invertible, and is usually considered invalid.
+				- If the determinant is exactly [code]0[/code], the basis is not invertible (see [method inverse]).
+				- If the determinant is a negative number, the basis represents a negative scale.
+				[b]Note:[/b] If the basis's scale is the same for every axis, its determinant is always that scale by the power of 2.
 			</description>
 		</method>
 		<method name="get_origin" qualifiers="const">
 			<return type="Vector2" />
 			<description>
-				Returns the transform's origin (translation).
+				Returns this transform's translation. Equivalent to [member origin].
 			</description>
 		</method>
 		<method name="get_rotation" qualifiers="const">
 			<return type="float" />
 			<description>
-				Returns the transform's rotation (in radians).
+				Returns this transform's rotation (in radians). This is equivalent to [member x]'s angle (see [method Vector2.angle]).
 			</description>
 		</method>
 		<method name="get_scale" qualifiers="const">
 			<return type="Vector2" />
 			<description>
-				Returns the scale.
+				Returns the length of both [member x] and [member y], as a [Vector2]. If this transform's basis is not skewed, this value is the scaling factor. It is not affected by rotation.
+				[codeblocks]
+				[gdscript]
+				var my_transform = Transform2D(
+				    Vector2(2, 0),
+				    Vector2(0, 4),
+				    Vector2(0, 0)
+				)
+				# Rotating the Transform2D in any way preserves its scale.
+				my_transform = my_transform.rotated(TAU / 2)
+
+				print(my_transform.get_scale()) # Prints (2, 4).
+				[/gdscript]
+				[csharp]
+				var myTransform = new Transform2D(
+				    Vector3(2.0f, 0.0f),
+				    Vector3(0.0f, 4.0f),
+				    Vector3(0.0f, 0.0f)
+				);
+				// Rotating the Transform2D in any way preserves its scale.
+				myTransform = myTransform.Rotated(Mathf.Tau / 2.0f);
+
+				GD.Print(myTransform.GetScale()); // Prints (2, 4, 8).
+				[/csharp]
+				[/codeblocks]
+				[b]Note:[/b] If the value returned by [method determinant] is negative, the scale is also negative.
 			</description>
 		</method>
 		<method name="get_skew" qualifiers="const">
 			<return type="float" />
 			<description>
-				Returns the transform's skew (in radians).
+				Returns this transform's skew (in radians).
 			</description>
 		</method>
 		<method name="interpolate_with" qualifiers="const">
@@ -116,19 +143,21 @@
 			<param index="0" name="xform" type="Transform2D" />
 			<param index="1" name="weight" type="float" />
 			<description>
-				Returns a transform interpolated between this transform and another by a given [param weight] (on the range of 0.0 to 1.0).
+				Returns the result of the linear interpolation between this transform and [param xform] by the given [param weight].
+				The [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). Values outside this range are allowed and can be used to perform [i]extrapolation[/i] instead.
 			</description>
 		</method>
 		<method name="inverse" qualifiers="const">
 			<return type="Transform2D" />
 			<description>
-				Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use [method affine_inverse] for non-orthonormal transforms (e.g. with scaling).
+				Returns the [url=https://en.wikipedia.org/wiki/Invertible_matrix]inverted version of this transform[/url].
+				[b]Note:[/b] For this method to return correctly, the transform's basis needs to be [i]orthonormal[/i] (see [method orthonormalized]). That means, the basis should only represent a rotation. If it does not, use [method affine_inverse] instead.
 			</description>
 		</method>
 		<method name="is_conformal" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if the transform's basis is conformal, meaning it preserves angles and distance ratios, and may only be composed of rotation and uniform scale. Returns [code]false[/code] if the transform's basis has non-uniform scale or shear/skew. This can be used to validate if the transform is non-distorted, which is important for physics and other use cases.
+				Returns [code]true[/code] if this transform's basis is conformal. A conformal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]uniform[/i] (the axes share the same length). This method can be especially useful during physics calculations.
 			</description>
 		</method>
 		<method name="is_equal_approx" qualifiers="const">
@@ -148,14 +177,13 @@
 			<return type="Transform2D" />
 			<param index="0" name="target" type="Vector2" default="Vector2(0, 0)" />
 			<description>
-				Returns a copy of the transform rotated such that the rotated X-axis points towards the [param target] position.
+				Returns a copy of the transform rotated such that the rotated X-axis points towards the [param target] position, in global space.
-				Operations take place in global space.
 			</description>
 		</method>
 		<method name="orthonormalized" qualifiers="const">
 			<return type="Transform2D" />
 			<description>
-				Returns the transform with the basis orthogonal (90 degrees), and normalized axis vectors (scale of 1 or -1).
+				Returns a copy of this transform with its basis orthonormalized. An orthonormal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]normalized[/i] (the axes have a length of [code]1[/code]), which also means it can only represent rotation.
 			</description>
 		</method>
 		<method name="rotated" qualifiers="const">
@@ -215,24 +243,41 @@
 	</methods>
 	<members>
 		<member name="origin" type="Vector2" setter="" getter="" default="Vector2(0, 0)">
-			The origin vector (column 2, the third column). Equivalent to array index [code]2[/code]. The origin vector represents translation.
+			The translation offset of this transform, and the column [code]2[/code] of the matrix. In 2D space, this can be seen as the position.
 		</member>
 		<member name="x" type="Vector2" setter="" getter="" default="Vector2(1, 0)">
-			The basis matrix's X vector (column 0). Equivalent to array index [code]0[/code].
+			The transform basis's X axis, and the column [code]0[/code] of the matrix. Combined with [member y], this represents the transform's rotation, scale, and skew.
+			On the identity transform, this vector points right ([constant Vector2.RIGHT]).
 		</member>
 		<member name="y" type="Vector2" setter="" getter="" default="Vector2(0, 1)">
-			The basis matrix's Y vector (column 1). Equivalent to array index [code]1[/code].
+			The transform basis's Y axis, and the column [code]1[/code] of the matrix. Combined with [member x], this represents the transform's rotation, scale, and skew.
+			On the identity transform, this vector points up ([constant Vector2.UP]).
 		</member>
 	</members>
 	<constants>
 		<constant name="IDENTITY" value="Transform2D(1, 0, 0, 1, 0, 0)">
-			The identity [Transform2D] with no translation, rotation or scaling applied. When applied to other data structures, [constant IDENTITY] performs no transformation.
+			The identity [Transform2D]. A transform with no translation, no rotation, and its scale being [code]1[/code]. When multiplied by another [Variant] such as [Rect2] or another [Transform2D], no transformation occurs. This means that:
+			- The [member x] points right ([constant Vector2.RIGHT]);
+			- The [member y] points up ([constant Vector2.UP]).
+			[codeblock]
+			var transform = Transform2D.IDENTITY
+			print("| X | Y | Origin")
+			print("| %s | %s | %s" % [transform.x.x, transform.y.x, transform.origin.x])
+			print("| %s | %s | %s" % [transform.x.y, transform.y.y, transform.origin.y])
+			# Prints:
+			# | X | Y | Origin
+			# | 1 | 0 | 0
+			# | 0 | 1 | 0
+			[/codeblock]
+			This is identical to creating [constructor Transform2D] without any parameters. This constant can be used to make your code clearer, and for consistency with C#.
 		</constant>
 		<constant name="FLIP_X" value="Transform2D(-1, 0, 0, 1, 0, 0)">
-			The [Transform2D] that will flip something along the X axis.
+			When any transform is multiplied by [constant FLIP_X], it negates all components of the [member x] axis (the X column).
+			When [constant FLIP_X] is multiplied by any basis, it negates the [member Vector2.x] component of all axes (the X row).
 		</constant>
 		<constant name="FLIP_Y" value="Transform2D(1, 0, 0, -1, 0, 0)">
-			The [Transform2D] that will flip something along the Y axis.
+			When any transform is multiplied by [constant FLIP_Y], it negates all components of the [member y] axis (the Y column).
+			When [constant FLIP_Y] is multiplied by any basis, it negates the [member Vector2.y] component of all axes (the Y row).
 		</constant>
 	</constants>
 	<operators>
@@ -240,7 +285,7 @@
 			<return type="bool" />
 			<param index="0" name="right" type="Transform2D" />
 			<description>
-				Returns [code]true[/code] if the transforms are not equal.
+				Returns [code]true[/code] if the components of both transforms are not equal.
 				[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
 			</description>
 		</operator>
@@ -248,63 +293,69 @@
 			<return type="PackedVector2Array" />
 			<param index="0" name="right" type="PackedVector2Array" />
 			<description>
-				Transforms (multiplies) each element of the [Vector2] array by the given [Transform2D] matrix.
+				Transforms (multiplies) every [Vector2] element of the given [PackedVector2Array] by this transformation matrix.
+				On larger arrays, this operation is much faster than transforming each [Vector2] individually.
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Rect2" />
 			<param index="0" name="right" type="Rect2" />
 			<description>
-				Transforms (multiplies) the [Rect2] by the given [Transform2D] matrix.
+				Transforms (multiplies) the [Rect2] by this transformation matrix.
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Transform2D" />
 			<param index="0" name="right" type="Transform2D" />
 			<description>
-				Composes these two transformation matrices by multiplying them together. This has the effect of transforming the second transform (the child) by the first transform (the parent).
+				Transforms (multiplies) this transform by the [param right] transform.
+				This is the operation performed between parent and child [CanvasItem] nodes.
+				[b]Note:[/b] If you need to only modify one attribute of this transform, consider using one of the following methods, instead:
+				- For translation, see [method translated] or [method translated_local].
+				- For rotation, see [method rotated] or [method rotated_local].
+				- For scale, see [method scaled] or [method scaled_local].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Vector2" />
 			<param index="0" name="right" type="Vector2" />
 			<description>
-				Transforms (multiplies) the [Vector2] by the given [Transform2D] matrix.
+				Transforms (multiplies) the [Vector2] by this transformation matrix.
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Transform2D" />
 			<param index="0" name="right" type="float" />
 			<description>
-				This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly.
+				Multiplies all components of the [Transform2D] by the given [float], including the [member origin]. This affects the transform's scale 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 [member origin] vector, which scales it uniformly.
+				Multiplies all components of the [Transform2D] by the given [int], including the [member origin]. This affects the transform's scale uniformly.
 			</description>
 		</operator>
 		<operator name="operator /">
 			<return type="Transform2D" />
 			<param index="0" name="right" type="float" />
 			<description>
-				This operator divides all components of the [Transform2D], including the [member origin] vector, which inversely scales it uniformly.
+				Divides all components of the [Transform2D] by the given [float], including the [member origin]. This affects the transform's scale uniformly.
 			</description>
 		</operator>
 		<operator name="operator /">
 			<return type="Transform2D" />
 			<param index="0" name="right" type="int" />
 			<description>
-				This operator divides all components of the [Transform2D], including the [member origin] vector, which inversely scales it uniformly.
+				Divides all components of the [Transform2D] by the given [int], including the [member origin]. This affects the transform's scale uniformly.
 			</description>
 		</operator>
 		<operator name="operator ==">
 			<return type="bool" />
 			<param index="0" name="right" type="Transform2D" />
 			<description>
-				Returns [code]true[/code] if the transforms are exactly equal.
+				Returns [code]true[/code] if the components of both transforms are exactly equal.
 				[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
 			</description>
 		</operator>
@@ -312,7 +363,7 @@
 			<return type="Vector2" />
 			<param index="0" name="index" type="int" />
 			<description>
-				Access transform components using their index. [code]t[0][/code] is equivalent to [code]t.x[/code], [code]t[1][/code] is equivalent to [code]t.y[/code], and [code]t[2][/code] is equivalent to [code]t.origin[/code].
+				Accesses each axis (column) of this transform by their index. Index [code]0[/code] is the same as [member x], index [code]1[/code] is the same as [member y], and index [code]2[/code] is the same as [member origin].
 			</description>
 		</operator>
 	</operators>