From 185cfee96ffe692ff17af19129b318d116e99b42 Mon Sep 17 00:00:00 2001 From: Micky Date: Mon, 15 Jan 2024 12:10:52 +0100 Subject: [PATCH] Overhaul Transform3D documentation (cherry picked from commit 64ba22a9a7d4c4f8540acb8b489c37f5e6d8380b) --- doc/classes/Transform3D.xml | 76 +++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 32 deletions(-) diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index 4134d1335f8..2ab41a8d4f8 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -4,8 +4,9 @@ A 3×4 matrix representing a 3D transformation. - A 3×4 matrix (3 rows, 4 columns) used for 3D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of a [member basis] (first 3 columns) and a [Vector3] for the [member origin] (last column). - For more information, read the "Matrices and transforms" documentation article. + The [Transform3D] built-in [Variant] type is a 3×4 matrix representing a transformation in 3D space. It contains a [Basis], which on its own can represent rotation, scale, and shear. Additionally, combined with its own [member origin], the transform can also represent a translation. + For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial. + [b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions]Importing 3D Scenes[/url] tutorial. $DOCS_URL/tutorials/math/index.html @@ -19,7 +20,7 @@ - Constructs a default-initialized [Transform3D] set to [constant IDENTITY]. + Constructs a [Transform3D] identical to the [constant IDENTITY]. @@ -34,14 +35,14 @@ - Constructs a Transform3D from a [Basis] and [Vector3]. + Constructs a [Transform3D] from a [Basis] and [Vector3]. - Constructs a Transform3D from a [Projection] by trimming the last row of the projection matrix ([code]from.x.w[/code], [code]from.y.w[/code], [code]from.z.w[/code], and [code]from.w.w[/code] are not copied over). + Constructs a [Transform3D] from a [Projection]. Because [Transform3D] is a 3×4 matrix and [Projection] is a 4×4 matrix, this operation trims the last row of the projection matrix ([code]from.x.w[/code], [code]from.y.w[/code], [code]from.z.w[/code], and [code]from.w.w[/code] are not included in the new transform). @@ -51,7 +52,8 @@ - Constructs a Transform3D from four [Vector3] values (matrix columns). Each axis corresponds to local basis vectors (some of which may be scaled). + Constructs a [Transform3D] from four [Vector3] values (also called matrix columns). + The first three arguments are the [member basis]'s axes ([member Basis.x], [member Basis.y], and [member Basis.z]). @@ -59,7 +61,8 @@ - Returns the inverse of the transform, under the assumption that the transformation is composed of rotation, scaling and translation. + Returns the inverted version of this transform. Unlike [method inverse], this method works with almost any [member basis], including non-uniform ones, but is slower. See also [method Basis.inverse]. + [b]Note:[/b] For this method to return correctly, the transform's [member basis] needs to not have a determinant of exactly [code]0[/code] (see [method Basis.determinant]). @@ -67,13 +70,15 @@ - 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. - Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use [method affine_inverse] for transforms with scaling). + Returns the inverted version of this transform. See also [method Basis.inverse]. + [b]Note:[/b] For this method to return correctly, the transform's [member basis] needs to be [i]orthonormal[/i] (see [method Basis.orthonormalized]). That means, the basis should only represent a rotation. If it does not, use [method affine_inverse] instead. @@ -95,7 +100,7 @@ - Returns a copy of the transform rotated such that the forward axis (-Z) points towards the [param target] position. + Returns a copy of this transform rotated so that the forward axis (-Z) points towards the [param target] position. The up axis (+Y) points as close to the [param up] vector as possible while staying perpendicular to the forward axis. The resulting transform is orthonormalized. The existing rotation, scale, and skew information from the original transform is discarded. The [param target] and [param up] vectors cannot be zero, cannot be parallel to each other, and are defined in global/parent space. If [param use_model_front] is [code]true[/code], the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the [param target] position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right). @@ -103,7 +108,7 @@ - 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 [member 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. See also [method Basis.orthonormalized]. @@ -111,7 +116,7 @@ - Returns a copy of the transform rotated around the given [param axis] by the given [param angle] (in radians). + Returns a copy of this transform rotated around the given [param axis] by the given [param angle] (in radians). The [param axis] 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. @@ -122,7 +127,7 @@ - Returns a copy of the transform rotated around the given [param axis] by the given [param angle] (in radians). + Returns a copy of this transform rotated around the given [param axis] by the given [param angle] (in radians). The [param axis] 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. @@ -132,7 +137,7 @@ - Returns a copy of the transform scaled by the given [param scale] factor. + Returns a copy of this transform scaled by the given [param scale] 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. @@ -141,7 +146,7 @@ - Returns a copy of the transform scaled by the given [param scale] factor. + Returns a copy of this transform scaled by the given [param scale] 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. @@ -150,7 +155,7 @@ - Returns a copy of the transform translated by the given [param offset]. + Returns a copy of this transform translated by the given [param offset]. 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. @@ -159,7 +164,7 @@ - Returns a copy of the transform translated by the given [param offset]. + Returns a copy of this transform translated by the given [param offset]. 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. @@ -167,24 +172,25 @@ - The basis is a matrix containing 3 [Vector3] as its columns: X axis, Y axis, and Z axis. These vectors can be interpreted as the basis vectors of local coordinate system traveling with the object. + The [Basis] of this transform. It is composed by 3 axes ([member Basis.x], [member Basis.y], and [member Basis.z]). Together, these represent the transform's rotation, scale, and shearing. - The translation offset of the transform (column 3, the fourth column). Equivalent to array index [code]3[/code]. + The translation offset of this transform. In 3D space, this can be seen as the position. - [Transform3D] with no translation, rotation or scaling applied. When applied to other data structures, [constant IDENTITY] performs no transformation. + A transform with no translation, no rotation, and its scale being [code]1[/code]. Its [member basis] is equal to [constant Basis.IDENTITY]. + When multiplied by another [Variant] such as [AABB] or another [Transform3D], no transformation occurs. - [Transform3D] with mirroring applied perpendicular to the YZ plane. + [Transform3D] with mirroring applied perpendicular to the YZ plane. Its [member basis] is equal to [constant Basis.FLIP_X]. - [Transform3D] with mirroring applied perpendicular to the XZ plane. + [Transform3D] with mirroring applied perpendicular to the XZ plane. Its [member basis] is equal to [constant Basis.FLIP_Y]. - [Transform3D] with mirroring applied perpendicular to the XY plane. + [Transform3D] with mirroring applied perpendicular to the XY plane. Its [member basis] is equal to [constant Basis.FLIP_Z]. @@ -192,7 +198,7 @@ - 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. @@ -200,56 +206,62 @@ - Transforms (multiplies) the [AABB] by the given [Transform3D] matrix. + Transforms (multiplies) the [AABB] by this transformation matrix. - Transforms (multiplies) each element of the [Vector3] array by the given [Transform3D] matrix. + Transforms (multiplies) every [Vector3] element of the given [PackedVector3Array] by this transformation matrix. + On larger arrays, this operation is much faster than transforming each [Vector3] individually. - Transforms (multiplies) the [Plane] by the given [Transform3D] transformation matrix. + Transforms (multiplies) the [Plane] by this transformation matrix. - 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 [Node3D]s. + [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]. - Transforms (multiplies) the [Vector3] by the given [Transform3D] matrix. + Transforms (multiplies) the [Vector3] by this transformation matrix. - This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly. + Multiplies all components of the [Transform3D] by the given [float], including the [member origin]. This affects the transform's scale uniformly, also resizing the [member basis]. - This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly. + Multiplies all components of the [Transform3D] by the given [int], including the [member origin]. This affects the transform's scale uniformly, also resizing the [member basis]. - 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.