From 38cd13c51a4772d21a38d4048cec6be43b965efd Mon Sep 17 00:00:00 2001 From: Micky Date: Sun, 14 Jan 2024 18:50:06 +0100 Subject: [PATCH] Overhaul Quaternion documentation --- doc/classes/Quaternion.xml | 99 ++++++++++++++++++++++---------------- 1 file changed, 58 insertions(+), 41 deletions(-) diff --git a/doc/classes/Quaternion.xml b/doc/classes/Quaternion.xml index 61bc4f472041..283e25dcb116 100644 --- a/doc/classes/Quaternion.xml +++ b/doc/classes/Quaternion.xml @@ -4,19 +4,24 @@ A unit quaternion used for representing 3D rotations. - Quaternions are similar to [Basis], which implements the matrix representation of rotations. Unlike [Basis], which stores rotation, scale, and shearing, quaternions only store rotation. - Quaternions can be parametrized using both an axis-angle pair or Euler angles. Due to their compactness and the way they are stored in memory, certain operations (obtaining axis-angle and performing SLERP, in particular) are more efficient and robust against floating-point errors. - [b]Note:[/b] Quaternions need to be normalized before being used for rotation. + The [Quaternion] built-in [Variant] type is a 4D data structure that represents rotation in the form of a [url=https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation]Hamilton convention quaternion[/url]. Compared to the [Basis] type which can store both rotation and scale, quaternions can [i]only[/i] store rotation. + A [Quaternion] is composed by 4 floating-point components: [member w], [member x], [member y], and [member z]. These components are very compact in memory, and because of this some operations are more efficient and less likely to cause floating-point errors. Methods such as [method get_angle], [method get_axis], and [method slerp] are faster than their [Basis] counterparts. + For a great introduction to quaternions, see [url=https://www.youtube.com/watch?v=d4EgbgTm0Bg]this video by 3Blue1Brown[/url]. You do not need to know the math behind quaternions, as Godot provides several helper methods that handle it for you. These include [method slerp] and [method spherical_cubic_interpolate], as well as the [code]*[/code] operator. + [b]Note:[/b] Quaternions must be normalized before being used for rotation (see [method normalized]). + [b]Note:[/b] Similarly to [Vector2] and [Vector3], the components of a quaternion use 32-bit precision by default, unlike [float] which is always 64-bit. If double precision is needed, compile the engine with the option [code]precision=double[/code]. + https://www.youtube.com/watch?v=d4EgbgTm0Bg + https://quaternions.online/ $DOCS_URL/tutorials/3d/using_transforms.html#interpolating-with-quaternions https://godotengine.org/asset-library/asset/678 + https://iwatake2222.github.io/rotation_master/rotation_master.html - Constructs a default-initialized quaternion with all components set to [code]0[/code]. + Constructs a [Quaternion] identical to the [constant IDENTITY]. @@ -31,7 +36,7 @@ - Constructs a quaternion representing the shortest arc between two points on the surface of a sphere with a radius of [code]1.0[/code]. + Constructs a [Quaternion] representing the shortest arc between [param arc_from] and [param arc_to]. These can be imagined as two points intersecting a sphere's surface, with a radius of [code]1.0[/code]. @@ -39,14 +44,15 @@ - Constructs a quaternion that will rotate around the given axis by the specified angle. The axis must be a normalized vector. + Constructs a [Quaternion] representing rotation around the [param axis] by the given [param angle], in radians. The axis must be a normalized vector. - Constructs a quaternion from the given [Basis]. + Constructs a [Quaternion] from the given rotation [Basis]. + This constructor is faster than [method Basis.get_rotation_quaternion], but the given basis must be [i]orthonormalized[/i] (see [method Basis.orthonormalized]). Otherwise, the constructor fails and returns [constant IDENTITY]. @@ -56,7 +62,8 @@ - Constructs a quaternion defined by the given values. + Constructs a [Quaternion] defined by the given values. + [b]Note:[/b] Only normalized quaternions represent rotation; if these values are not normalized, the new [Quaternion] will not be a valid rotation. @@ -73,7 +80,8 @@ - Returns the dot product of two quaternions. + Returns the dot product between this quaternion and [param with]. + This is equivalent to [code](quat.x * with.x) + (quat.y * with.y) + (quat.z * with.z) + (quat.w * with.w)[/code]. @@ -86,7 +94,7 @@ - Constructs a Quaternion from Euler angles in YXZ rotation order. + Constructs a new [Quaternion] from the given [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians. This method always uses the YXZ convention ([constant EULER_ORDER_YXZ]). @@ -106,13 +114,14 @@ - Returns the quaternion's rotation in the form of Euler angles. The Euler order depends on the [param order] parameter, for example using the YXZ convention: since this method decomposes, first Z, then X, and Y last. See the [enum EulerOrder] enum for possible values. The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle). + Returns this quaternion's rotation as a [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians. + The order of each consecutive rotation can be changed with [param order] (see [enum EulerOrder] constants). By default, the YXZ convention is used ([constant EULER_ORDER_YXZ]): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method [method from_euler], this order is reversed. - Returns the inverse of the quaternion. + Returns the inverse version of this quaternion, inverting the sign of every component except [member w]. @@ -131,31 +140,32 @@ - Returns whether the quaternion is normalized or not. + Returns [code]true[/code] if this quaternion is normalized. See also [method normalized]. - Returns the length of the quaternion. + Returns this quaternion's length, also called magnitude. - Returns the length of the quaternion, squared. + Returns this quaternion's length, squared. + [b]Note:[/b] This method is faster than [method length], so prefer it if you only need to compare quaternion lengths. - Returns the logarithm of this quaternion. The vector part of the result is the rotation axis of this quaternion multiplied by its rotation angle, the real part of the result is zero. + Returns the logarithm of this quaternion. Multiplies this quaternion's rotation axis by its rotation angle, and stores the result in the returned quaternion's vector part ([member x], [member y], and [member z]). The returned quaternion's real part ([member w]) is always [code]0.0[/code]. - Returns a copy of the quaternion, normalized to unit length. + Returns a copy of this quaternion, normalized so that its length is [code]1.0[/code]. See also [method is_normalized]. @@ -163,8 +173,7 @@ - Returns the result of the spherical linear interpolation between this quaternion and [param to] by amount [param weight]. - [b]Note:[/b] Both quaternions must be normalized. + Performs a spherical-linear interpolation with the [param to] quaternion, given a [param weight] and returns the result. Both this quaternion and [param to] must be normalized. @@ -172,7 +181,7 @@ - Returns the result of the spherical linear interpolation between this quaternion and [param to] by amount [param weight], but without checking if the rotation path is not bigger than 90 degrees. + Performs a spherical-linear interpolation with the [param to] quaternion, given a [param weight] and returns the result. Unlike [method slerp], this method does not check if the rotation path is smaller than 90 degrees. Both this quaternion and [param to] must be normalized. @@ -202,25 +211,26 @@ - W component of the quaternion (real part). - Quaternion components should usually not be manipulated directly. + W component of the quaternion. This is the "real" part. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. - X component of the quaternion (imaginary [code]i[/code] axis part). - Quaternion components should usually not be manipulated directly. + X component of the quaternion. This is the value along the "imaginary" [code]i[/code] axis. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. - Y component of the quaternion (imaginary [code]j[/code] axis part). - Quaternion components should usually not be manipulated directly. + Y component of the quaternion. This is the value along the "imaginary" [code]j[/code] axis. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. - Z component of the quaternion (imaginary [code]k[/code] axis part). - Quaternion components should usually not be manipulated directly. + Z component of the quaternion. This is the value along the "imaginary" [code]k[/code] axis. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. - The identity quaternion, representing no rotation. Equivalent to an identity [Basis] matrix. If a vector is transformed by an identity quaternion, it will not change. + The identity quaternion, representing no rotation. This has the same rotation as [constant Basis.IDENTITY]. + If a [Vector3] is rotated (multiplied) by this quaternion, it does not change. @@ -228,7 +238,7 @@ - Returns [code]true[/code] if the quaternions are not equal. + Returns [code]true[/code] if the components of both quaternions are not exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. @@ -236,63 +246,69 @@ - Composes these two quaternions by multiplying them together. This has the effect of rotating the second quaternion (the child) by the first quaternion (the parent). + Composes (multiplies) two quaternions. This rotates the [param right] quaternion (the child) by this quaternion (the parent). - Rotates (multiplies) the [Vector3] by the given [Quaternion]. + Rotates (multiplies) the [param right] vector by this quaternion, returning a [Vector3]. - Multiplies each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Multiplies each component of the [Quaternion] by the right [float] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. - Multiplies each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Multiplies each component of the [Quaternion] by the right [int] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. - Adds each component of the left [Quaternion] to the right [Quaternion]. This operation is not meaningful on its own, but it can be used as a part of a larger expression, such as approximating an intermediate rotation between two nearby rotations. + Adds each component of the left [Quaternion] to the right [Quaternion]. + This operation is not meaningful on its own, but it can be used as a part of a larger expression, such as approximating an intermediate rotation between two nearby rotations. - Subtracts each component of the left [Quaternion] by the right [Quaternion]. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Subtracts each component of the left [Quaternion] by the right [Quaternion]. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. - Divides each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Divides each component of the [Quaternion] by the right [float] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. - Divides each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Divides each component of the [Quaternion] by the right [int] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. - Returns [code]true[/code] if the quaternions are exactly equal. + Returns [code]true[/code] if the components of both quaternions are exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. @@ -300,7 +316,8 @@ - Access quaternion components using their index. [code]q[0][/code] is equivalent to [code]q.x[/code], [code]q[1][/code] is equivalent to [code]q.y[/code], [code]q[2][/code] is equivalent to [code]q.z[/code], and [code]q[3][/code] is equivalent to [code]q.w[/code]. + Accesses each component of this quaternion by their index. + Index [code]0[/code] is the same as [member x], index [code]1[/code] is the same as [member y], index [code]2[/code] is the same as [member z], and index [code]3[/code] is the same as [member w]. @@ -312,7 +329,7 @@ - Returns the negative value of the [Quaternion]. This is the same as writing [code]Quaternion(-q.x, -q.y, -q.z, -q.w)[/code]. This operation results in a quaternion that represents the same rotation. + Returns the negative value of the [Quaternion]. This is the same as multiplying all components by [code]-1[/code]. This operation results in a quaternion that represents the same rotation.