2017-09-12 20:42:36 +00:00
<?xml version="1.0" encoding="UTF-8" ?>
2022-02-14 13:18:53 +00:00
<class name= "Quaternion" version= "4.0" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation= "../class.xsd" >
2017-09-12 20:42:36 +00:00
<brief_description >
Quaternion.
</brief_description>
<description >
2020-07-21 18:07:00 +00:00
A unit quaternion used for representing 3D rotations. Quaternions need to be normalized to be used for rotation.
2021-01-20 07:02:02 +00:00
It is similar to Basis, which implements matrix representation of rotations, and can be parametrized using both an axis-angle pair or Euler angles. Basis stores rotation, scale, and shearing, while Quaternion only stores rotation.
2020-07-21 18:07:00 +00:00
Due to its compactness and the way it is stored in memory, certain operations (obtaining axis-angle and performing SLERP, in particular) are more efficient and robust against floating-point errors.
2017-09-12 20:42:36 +00:00
</description>
<tutorials >
2021-11-15 09:43:07 +00:00
<link title= "Using 3D transforms" > $DOCS_URL/tutorials/3d/using_transforms.html#interpolating-with-quaternions</link>
2020-10-01 08:34:47 +00:00
<link title= "Third Person Shooter Demo" > https://godotengine.org/asset-library/asset/678</link>
2017-09-12 20:42:36 +00:00
</tutorials>
2021-09-21 02:49:02 +00:00
<constructors >
<constructor name= "Quaternion" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
2020-11-09 16:46:03 +00:00
<description >
Constructs a default-initialized quaternion with all components set to [code]0[/code].
</description>
2021-09-21 02:49:02 +00:00
</constructor>
<constructor name= "Quaternion" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "from" type= "Quaternion" />
2020-11-09 16:46:03 +00:00
<description >
2021-01-20 07:02:02 +00:00
Constructs a [Quaternion] as a copy of the given [Quaternion].
2020-11-09 16:46:03 +00:00
</description>
2021-09-21 02:49:02 +00:00
</constructor>
<constructor name= "Quaternion" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "arc_from" type= "Vector3" />
<argument index= "1" name= "arc_to" type= "Vector3" />
2017-09-12 20:42:36 +00:00
<description >
</description>
2021-09-21 02:49:02 +00:00
</constructor>
<constructor name= "Quaternion" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "axis" type= "Vector3" />
<argument index= "1" name= "angle" type= "float" />
2017-09-12 20:42:36 +00:00
<description >
2020-11-04 14:38:26 +00:00
Constructs a quaternion that will rotate around the given axis by the specified angle. The axis must be a normalized vector.
2017-09-12 20:42:36 +00:00
</description>
2021-09-21 02:49:02 +00:00
</constructor>
<constructor name= "Quaternion" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
2021-10-21 16:38:20 +00:00
<argument index= "0" name= "euler_yxz" type= "Vector3" />
2018-05-12 00:14:39 +00:00
<description >
</description>
2021-09-21 02:49:02 +00:00
</constructor>
<constructor name= "Quaternion" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "from" type= "Basis" />
2017-09-12 20:42:36 +00:00
<description >
2020-11-04 14:38:26 +00:00
Constructs a quaternion from the given [Basis].
2017-09-12 20:42:36 +00:00
</description>
2021-09-21 02:49:02 +00:00
</constructor>
<constructor name= "Quaternion" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "x" type= "float" />
<argument index= "1" name= "y" type= "float" />
<argument index= "2" name= "z" type= "float" />
<argument index= "3" name= "w" type= "float" />
2020-11-09 16:46:03 +00:00
<description >
Constructs a quaternion defined by the given values.
</description>
2021-09-21 02:49:02 +00:00
</constructor>
</constructors>
<methods >
2020-12-07 06:40:46 +00:00
<method name= "angle_to" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "float" />
<argument index= "0" name= "to" type= "Quaternion" />
2020-12-07 06:40:46 +00:00
<description >
Returns the angle between this quaternion and [code]to[/code]. This is the magnitude of the angle you would need to rotate by to get from one to the other.
[b]Note:[/b] This method has an abnormally high amount of floating-point error, so methods such as [code]is_zero_approx[/code] will not work reliably.
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "dot" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "float" />
<argument index= "0" name= "with" type= "Quaternion" />
2017-09-12 20:42:36 +00:00
<description >
Returns the dot product of two quaternions.
</description>
</method>
2022-03-15 16:35:25 +00:00
<method name= "exp" qualifiers= "const" >
<return type= "Quaternion" />
<description >
</description>
</method>
2021-10-20 23:42:22 +00:00
<method name= "get_angle" qualifiers= "const" >
<return type= "float" />
<description >
</description>
</method>
<method name= "get_axis" qualifiers= "const" >
<return type= "Vector3" />
<description >
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "get_euler" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "Vector3" />
2018-05-12 00:14:39 +00:00
<description >
2020-07-21 18:07:00 +00:00
Returns Euler angles (in the YXZ convention: when decomposing, first Z, then X, and Y last) corresponding to the rotation represented by the unit quaternion. Returned vector contains the rotation angles in the format (X angle, Y angle, Z angle).
2018-05-12 00:14:39 +00:00
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "inverse" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
2017-09-12 20:42:36 +00:00
<description >
Returns the inverse of the quaternion.
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "is_equal_approx" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "bool" />
<argument index= "0" name= "to" type= "Quaternion" />
2019-11-08 07:33:48 +00:00
<description >
2021-03-18 11:04:28 +00:00
Returns [code]true[/code] if this quaternion and [code]quat[/code] are approximately equal, by running [method @GlobalScope.is_equal_approx] on each component.
2019-11-08 07:33:48 +00:00
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "is_normalized" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "bool" />
2017-09-12 20:42:36 +00:00
<description >
Returns whether the quaternion is normalized or not.
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "length" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "float" />
2017-09-12 20:42:36 +00:00
<description >
Returns the length of the quaternion.
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "length_squared" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "float" />
2017-09-12 20:42:36 +00:00
<description >
Returns the length of the quaternion, squared.
</description>
</method>
2022-03-15 16:35:25 +00:00
<method name= "log" qualifiers= "const" >
<return type= "Quaternion" />
<description >
</description>
</method>
2021-03-18 13:44:42 +00:00
<method name= "normalized" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
2017-09-12 20:42:36 +00:00
<description >
Returns a copy of the quaternion, normalized to unit length.
</description>
2020-11-10 13:16:20 +00:00
</method>
2021-09-21 02:49:02 +00:00
<method name= "slerp" qualifiers= "const" >
<return type= "Quaternion" />
<argument index= "0" name= "to" type= "Quaternion" />
<argument index= "1" name= "weight" type= "float" />
2021-09-17 15:22:48 +00:00
<description >
2021-09-21 02:49:02 +00:00
Returns the result of the spherical linear interpolation between this quaternion and [code]to[/code] by amount [code]weight[/code].
[b]Note:[/b] Both quaternions must be normalized.
2021-09-17 15:22:48 +00:00
</description>
</method>
2021-09-21 02:49:02 +00:00
<method name= "slerpni" qualifiers= "const" >
<return type= "Quaternion" />
<argument index= "0" name= "to" type= "Quaternion" />
<argument index= "1" name= "weight" type= "float" />
2020-11-10 13:16:20 +00:00
<description >
2021-09-21 02:49:02 +00:00
Returns the result of the spherical linear interpolation between this quaternion and [code]to[/code] by amount [code]weight[/code], but without checking if the rotation path is not bigger than 90 degrees.
2020-11-10 13:16:20 +00:00
</description>
</method>
2022-07-27 12:27:51 +00:00
<method name= "spherical_cubic_interpolate" qualifiers= "const" >
<return type= "Quaternion" />
<argument index= "0" name= "b" type= "Quaternion" />
<argument index= "1" name= "pre_a" type= "Quaternion" />
<argument index= "2" name= "post_b" type= "Quaternion" />
<argument index= "3" name= "weight" type= "float" />
<description >
Performs a spherical cubic interpolation between quaternions [code]pre_a[/code], this vector, [code]b[/code], and [code]post_b[/code], by the given amount [code]weight[/code].
</description>
</method>
2021-09-21 02:49:02 +00:00
</methods>
<members >
<member name= "w" type= "float" setter= "" getter= "" default= "1.0" >
W component of the quaternion (real part).
Quaternion components should usually not be manipulated directly.
</member>
<member name= "x" type= "float" setter= "" getter= "" default= "0.0" >
X component of the quaternion (imaginary [code]i[/code] axis part).
Quaternion components should usually not be manipulated directly.
</member>
<member name= "y" type= "float" setter= "" getter= "" default= "0.0" >
Y component of the quaternion (imaginary [code]j[/code] axis part).
Quaternion components should usually not be manipulated directly.
</member>
<member name= "z" type= "float" setter= "" getter= "" default= "0.0" >
Z component of the quaternion (imaginary [code]k[/code] axis part).
Quaternion components should usually not be manipulated directly.
</member>
</members>
<constants >
<constant name= "IDENTITY" value= "Quaternion(0, 0, 0, 1)" >
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.
</constant>
</constants>
<operators >
<operator name= "operator !=" >
<return type= "bool" />
<argument index= "0" name= "right" type= "Quaternion" />
<description >
2021-11-04 15:58:20 +00:00
Returns [code]true[/code] if the quaternions are not equal.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
2021-09-21 02:49:02 +00:00
</description>
</operator>
<operator name= "operator *" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "right" type= "Quaternion" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
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).
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator *" >
<return type= "Vector3" />
<argument index= "0" name= "right" type= "Vector3" />
<description >
2021-11-04 15:58:20 +00:00
Rotates (multiplies) the [Vector3] by the given [Quaternion].
2021-09-21 02:49:02 +00:00
</description>
</operator>
<operator name= "operator *" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "right" type= "float" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
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.
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator *" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "right" type= "int" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
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.
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator +" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "right" type= "Quaternion" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
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.
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator -" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "right" type= "Quaternion" />
2020-12-04 14:54:48 +00:00
<description >
2021-11-04 15:58:20 +00:00
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.
2020-12-04 14:54:48 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator /" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "right" type= "float" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
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.
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator /" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
<argument index= "0" name= "right" type= "int" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
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.
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator ==" >
2021-07-30 13:28:05 +00:00
<return type= "bool" />
<argument index= "0" name= "right" type= "Quaternion" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
Returns [code]true[/code] if the quaternions are exactly equal.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator []" >
2021-07-30 13:28:05 +00:00
<return type= "float" />
<argument index= "0" name= "index" type= "int" />
2020-11-10 13:16:20 +00:00
<description >
2021-11-04 15:58:20 +00:00
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].
2020-11-10 13:16:20 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator unary+" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
2017-09-12 20:42:36 +00:00
<description >
2021-11-04 15:58:20 +00:00
Returns the same value as if the [code]+[/code] was not there. Unary [code]+[/code] does nothing, but sometimes it can make your code more readable.
2017-09-12 20:42:36 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
<operator name= "operator unary-" >
2021-07-30 13:28:05 +00:00
<return type= "Quaternion" />
2017-09-12 20:42:36 +00:00
<description >
2021-11-04 15:58:20 +00:00
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.
2017-09-12 20:42:36 +00:00
</description>
2021-09-21 02:49:02 +00:00
</operator>
</operators>
2017-09-12 20:42:36 +00:00
</class>