Struct Quaternion
- Namespace
- Godot
- Assembly
- GodotSharp.dll
A unit quaternion used for representing 3D rotations. Quaternions need to be normalized to be used for rotation.
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.
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.
public struct Quaternion : IEquatable<Quaternion>- Implements
- Inherited Members
Constructors
Quaternion(Basis)
Constructs a Quaternion from the given Basis.
public Quaternion(Basis basis)Parameters
Quaternion(Vector3, Vector3)
public Quaternion(Vector3 arcFrom, Vector3 arcTo)Parameters
Quaternion(Vector3, float)
Constructs a Quaternion that will rotate around the given axis by the specified angle. The axis must be a normalized vector.
public Quaternion(Vector3 axis, float angle)Parameters
axisVector3The axis to rotate around. Must be normalized.
anglefloatThe angle to rotate, in radians.
Quaternion(float, float, float, float)
Constructs a Quaternion defined by the given values.
public Quaternion(float x, float y, float z, float w)Parameters
xfloatX component of the quaternion (imaginary
iaxis part).yfloatY component of the quaternion (imaginary
jaxis part).zfloatZ component of the quaternion (imaginary
kaxis part).wfloatW component of the quaternion (real part).
Fields
W
W component of the quaternion (real part). Quaternion components should usually not be manipulated directly.
public float WField Value
X
X component of the quaternion (imaginary i axis part).
Quaternion components should usually not be manipulated directly.
public float XField Value
Y
Y component of the quaternion (imaginary j axis part).
Quaternion components should usually not be manipulated directly.
public float YField Value
Z
Z component of the quaternion (imaginary k axis part).
Quaternion components should usually not be manipulated directly.
public float ZField Value
Properties
Identity
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.
public static Quaternion Identity { get; }Property Value
- Quaternion
Equivalent to
new Quaternion(0, 0, 0, 1).
this[int]
Access quaternion components using their index.
public float this[int index] { readonly get; set; }Parameters
indexint
Property Value
- float
[0]is equivalent to X,[1]is equivalent to Y,[2]is equivalent to Z,[3]is equivalent to W.
Exceptions
- ArgumentOutOfRangeException
indexis not 0, 1, 2 or 3.
Methods
AngleTo(Quaternion)
Returns the angle between this quaternion and to.
This is the magnitude of the angle you would need to rotate
by to get from one to the other.
Note: This method has an abnormally high amount of floating-point error, so methods such as IsZeroApprox(float) will not work reliably.
public readonly float AngleTo(Quaternion to)Parameters
toQuaternionThe other quaternion.
Returns
- float
The angle between the quaternions.
Dot(Quaternion)
Returns the dot product of two quaternions.
public readonly float Dot(Quaternion b)Parameters
bQuaternionThe other quaternion.
Returns
- float
The dot product.
Equals(Quaternion)
Returns true if this quaternion and other are equal.
public readonly bool Equals(Quaternion other)Parameters
otherQuaternionThe other quaternion to compare.
Returns
- bool
Whether or not the quaternions are exactly equal.
Equals(object)
Returns true if this quaternion and obj are equal.
public override readonly bool Equals(object obj)Parameters
objobjectThe other object to compare.
Returns
- bool
Whether or not the quaternion and the other object are exactly equal.
Exp()
public readonly Quaternion Exp()Returns
FromEuler(Vector3)
Constructs a Quaternion that will perform a rotation specified by Euler angles (in the YXZ convention: when decomposing, first Z, then X, and Y last), given in the vector format as (X angle, Y angle, Z angle).
public static Quaternion FromEuler(Vector3 eulerYXZ)Parameters
eulerYXZVector3Euler angles that the quaternion will be rotated by.
Returns
GetAngle()
public readonly float GetAngle()Returns
GetAxis()
public readonly Vector3 GetAxis()Returns
GetEuler(EulerOrder)
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).
public readonly Vector3 GetEuler(EulerOrder order = EulerOrder.Yxz)Parameters
orderEulerOrder
Returns
- Vector3
The Euler angle representation of this quaternion.
GetHashCode()
Serves as the hash function for Quaternion.
public override readonly int GetHashCode()Returns
- int
A hash code for this quaternion.
Inverse()
Returns the inverse of the quaternion.
public readonly Quaternion Inverse()Returns
- Quaternion
The inverse quaternion.
IsEqualApprox(Quaternion)
Returns true if this quaternion and other are approximately equal,
by running IsEqualApprox(float, float) on each component.
public readonly bool IsEqualApprox(Quaternion other)Parameters
otherQuaternionThe other quaternion to compare.
Returns
- bool
Whether or not the quaternions are approximately equal.
IsFinite()
Returns true if this quaternion is finite, by calling IsFinite(float) on each component.
public readonly bool IsFinite()Returns
- bool
Whether this vector is finite or not.
IsNormalized()
Returns whether the quaternion is normalized or not.
public readonly bool IsNormalized()Returns
Length()
Returns the length (magnitude) of the quaternion.
public readonly float Length()Returns
- float
Equivalent to
Mathf.Sqrt(LengthSquared).
- See Also
LengthSquared()
Returns the squared length (squared magnitude) of the quaternion. This method runs faster than Length(), so prefer it if you need to compare quaternions or need the squared length for some formula.
public readonly float LengthSquared()Returns
- float
Equivalent to
Dot(this).
Log()
public readonly Quaternion Log()Returns
Normalized()
Returns a copy of the quaternion, normalized to unit length.
public readonly Quaternion Normalized()Returns
- Quaternion
The normalized quaternion.
Slerp(Quaternion, float)
Returns the result of the spherical linear interpolation between
this quaternion and to by amount weight.
Note: Both quaternions must be normalized.
public readonly Quaternion Slerp(Quaternion to, float weight)Parameters
toQuaternionThe destination quaternion for interpolation. Must be normalized.
weightfloatA value on the range of 0.0 to 1.0, representing the amount of interpolation.
Returns
- Quaternion
The resulting quaternion of the interpolation.
Slerpni(Quaternion, float)
Returns the result of the spherical linear interpolation between
this quaternion and to by amount weight, but without
checking if the rotation path is not bigger than 90 degrees.
public readonly Quaternion Slerpni(Quaternion to, float weight)Parameters
toQuaternionThe destination quaternion for interpolation. Must be normalized.
weightfloatA value on the range of 0.0 to 1.0, representing the amount of interpolation.
Returns
- Quaternion
The resulting quaternion of the interpolation.
SphericalCubicInterpolate(Quaternion, Quaternion, Quaternion, float)
Performs a spherical cubic interpolation between quaternions preA, this quaternion,
b, and postB, by the given amount weight.
public readonly Quaternion SphericalCubicInterpolate(Quaternion b, Quaternion preA, Quaternion postB, float weight)Parameters
bQuaternionThe destination quaternion.
preAQuaternionA quaternion before this quaternion.
postBQuaternionA quaternion after
b.weightfloatA value on the range of 0.0 to 1.0, representing the amount of interpolation.
Returns
- Quaternion
The interpolated quaternion.
SphericalCubicInterpolateInTime(Quaternion, Quaternion, Quaternion, float, float, float, float)
Performs a spherical cubic interpolation between quaternions preA, this quaternion,
b, and postB, by the given amount weight.
It can perform smoother interpolation than SphericalCubicInterpolate(Quaternion, Quaternion, Quaternion, float)
by the time values.
public readonly Quaternion SphericalCubicInterpolateInTime(Quaternion b, Quaternion preA, Quaternion postB, float weight, float bT, float preAT, float postBT)Parameters
bQuaternionThe destination quaternion.
preAQuaternionA quaternion before this quaternion.
postBQuaternionA quaternion after
b.weightfloatA value on the range of 0.0 to 1.0, representing the amount of interpolation.
bTfloatpreATfloatpostBTfloat
Returns
- Quaternion
The interpolated quaternion.
ToString()
Converts this Quaternion to a string.
public override readonly string ToString()Returns
- string
A string representation of this quaternion.
ToString(string)
Converts this Quaternion to a string with the given format.
public readonly string ToString(string format)Parameters
formatstring
Returns
- string
A string representation of this quaternion.
Operators
operator +(Quaternion, Quaternion)
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.
public static Quaternion operator +(Quaternion left, Quaternion right)Parameters
leftQuaternionThe left quaternion to add.
rightQuaternionThe right quaternion to add.
Returns
- Quaternion
The added quaternion.
operator /(Quaternion, float)
Divides each component of the Quaternion by the given float. This operation is not meaningful on its own, but it can be used as a part of a larger expression.
public static Quaternion operator /(Quaternion left, float right)Parameters
leftQuaternionThe quaternion to divide.
rightfloatThe value to divide by.
Returns
- Quaternion
The divided quaternion.
operator ==(Quaternion, Quaternion)
Returns true if the quaternions are exactly equal. Note: Due to floating-point precision errors, consider using IsEqualApprox(Quaternion) instead, which is more reliable.
public static bool operator ==(Quaternion left, Quaternion right)Parameters
leftQuaternionThe left quaternion.
rightQuaternionThe right quaternion.
Returns
- bool
Whether or not the quaternions are exactly equal.
operator !=(Quaternion, Quaternion)
Returns true if the quaternions are not equal. Note: Due to floating-point precision errors, consider using IsEqualApprox(Quaternion) instead, which is more reliable.
public static bool operator !=(Quaternion left, Quaternion right)Parameters
leftQuaternionThe left quaternion.
rightQuaternionThe right quaternion.
Returns
- bool
Whether or not the quaternions are not equal.
operator *(Quaternion, Quaternion)
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).
public static Quaternion operator *(Quaternion left, Quaternion right)Parameters
leftQuaternionThe parent quaternion.
rightQuaternionThe child quaternion.
Returns
- Quaternion
The composed quaternion.
operator *(Quaternion, Vector3)
Returns a Vector3 rotated (multiplied) by the quaternion.
public static Vector3 operator *(Quaternion quaternion, Vector3 vector)Parameters
quaternionQuaternionThe quaternion to rotate by.
vectorVector3A Vector3 to transform.
Returns
- Vector3
The rotated Vector3.
operator *(Quaternion, float)
Multiplies each component of the Quaternion by the given float. This operation is not meaningful on its own, but it can be used as a part of a larger expression.
public static Quaternion operator *(Quaternion left, float right)Parameters
leftQuaternionThe quaternion to multiply.
rightfloatThe value to multiply by.
Returns
- Quaternion
The multiplied quaternion.
operator *(Vector3, Quaternion)
Returns a Vector3 rotated (multiplied) by the inverse quaternion.
vector * quaternion is equivalent to quaternion.Inverse() * vector. See Inverse().
public static Vector3 operator *(Vector3 vector, Quaternion quaternion)Parameters
vectorVector3A Vector3 to inversely rotate.
quaternionQuaternionThe quaternion to rotate by.
Returns
- Vector3
The inversely rotated Vector3.
operator *(float, Quaternion)
Multiplies each component of the Quaternion by the given float. This operation is not meaningful on its own, but it can be used as a part of a larger expression.
public static Quaternion operator *(float left, Quaternion right)Parameters
leftfloatThe value to multiply by.
rightQuaternionThe quaternion to multiply.
Returns
- Quaternion
The multiplied quaternion.
operator -(Quaternion, Quaternion)
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.
public static Quaternion operator -(Quaternion left, Quaternion right)Parameters
leftQuaternionThe left quaternion to subtract.
rightQuaternionThe right quaternion to subtract.
Returns
- Quaternion
The subtracted quaternion.
operator -(Quaternion)
Returns the negative value of the Quaternion.
This is the same as writing
new Quaternion(-q.X, -q.Y, -q.Z, -q.W). This operation
results in a quaternion that represents the same rotation.
public static Quaternion operator -(Quaternion quat)Parameters
quatQuaternionThe quaternion to negate.
Returns
- Quaternion
The negated quaternion.