Jolt Physics
A multi core friendly Game Physics Engine
Loading...
Searching...
No Matches
Quat Class Reference

#include <Quat.h>

Public Member Functions

JPH_INLINE void GetAxisAngle (Vec3 &outAxis, float &outAngle) const
 Get axis and angle that represents this quaternion, outAngle will always be in the range \([0, \pi]\). More...
 
Vec3 GetEulerAngles () const
 Conversion to Euler angles. Rotation order is X then Y then Z (RotZ * RotY * RotX). Angles in radians. More...
 
JPH_INLINE Vec3 operator* (Vec3Arg inValue) const
 Rotate a vector by this quaternion. More...
 
JPH_INLINE Vec3 InverseRotate (Vec3Arg inValue) const
 Rotate a vector by the inverse of this quaternion. More...
 
JPH_INLINE Vec3 RotateAxisX () const
 Rotate a the vector (1, 0, 0) with this quaternion. More...
 
JPH_INLINE Vec3 RotateAxisY () const
 Rotate a the vector (0, 1, 0) with this quaternion. More...
 
JPH_INLINE Vec3 RotateAxisZ () const
 Rotate a the vector (0, 0, 1) with this quaternion. More...
 
JPH_INLINE float Dot (QuatArg inRHS) const
 Dot product. More...
 
JPH_INLINE Quat Conjugated () const
 The conjugate [w, -x, -y, -z] is the same as the inverse for unit quaternions. More...
 
JPH_INLINE Quat Inversed () const
 Get inverse quaternion. More...
 
JPH_INLINE Quat EnsureWPositive () const
 Ensures that the W component is positive by negating the entire quaternion if it is not. This is useful when you want to store a quaternion as a 3 vector by discarding W and reconstructing it as sqrt(1 - x^2 - y^2 - z^2). More...
 
JPH_INLINE Quat GetPerpendicular () const
 Get a quaternion that is perpendicular to this quaternion. More...
 
JPH_INLINE float GetRotationAngle (Vec3Arg inAxis) const
 Get rotation angle around inAxis (uses Swing Twist Decomposition to get the twist quaternion and uses q(axis, angle) = [cos(angle / 2), axis * sin(angle / 2)]) More...
 
JPH_INLINE Quat GetTwist (Vec3Arg inAxis) const
 
JPH_INLINE void GetSwingTwist (Quat &outSwing, Quat &outTwist) const
 
JPH_INLINE Quat LERP (QuatArg inDestination, float inFraction) const
 
JPH_INLINE Quat SLERP (QuatArg inDestination, float inFraction) const
 
JPH_INLINE void StoreFloat3 (Float3 *outV) const
 Store 3 as floats to memory (X, Y and Z component) More...
 
Constructors
 Quat ()=default
 Intentionally not initialized for performance reasons. More...
 
 Quat (const Quat &inRHS)=default
 
Quatoperator= (const Quat &inRHS)=default
 
 Quat (float inX, float inY, float inZ, float inW)
 
 Quat (Vec4Arg inV)
 
Tests
bool operator== (QuatArg inRHS) const
 Check if two quaternions are exactly equal. More...
 
bool operator!= (QuatArg inRHS) const
 Check if two quaternions are different. More...
 
bool IsClose (QuatArg inRHS, float inMaxDistSq=1.0e-12f) const
 If this quaternion is close to inRHS. Note that q and -q represent the same rotation, this is not checked here. More...
 
bool IsNormalized (float inTolerance=1.0e-5f) const
 If the length of this quaternion is 1 +/- inTolerance. More...
 
bool IsNaN () const
 If any component of this quaternion is a NaN (not a number) More...
 
Get components
JPH_INLINE float GetX () const
 Get X component (imaginary part i) More...
 
JPH_INLINE float GetY () const
 Get Y component (imaginary part j) More...
 
JPH_INLINE float GetZ () const
 Get Z component (imaginary part k) More...
 
JPH_INLINE float GetW () const
 Get W component (real part) More...
 
JPH_INLINE Vec3 GetXYZ () const
 Get the imaginary part of the quaternion. More...
 
JPH_INLINE Vec4 GetXYZW () const
 Get the quaternion as a Vec4. More...
 
JPH_INLINE void SetX (float inX)
 Set individual components. More...
 
JPH_INLINE void SetY (float inY)
 
JPH_INLINE void SetZ (float inZ)
 
JPH_INLINE void SetW (float inW)
 
JPH_INLINE void Set (float inX, float inY, float inZ, float inW)
 Set all components. More...
 
Length / normalization operations
JPH_INLINE float LengthSq () const
 
JPH_INLINE float Length () const
 
JPH_INLINE Quat Normalized () const
 Normalize the quaternion (make it length 1) More...
 

Static Public Member Functions

static JPH_INLINE Quat sRotation (Vec3Arg inAxis, float inAngle)
 Rotation from axis and angle. More...
 
static JPH_INLINE Quat sFromTo (Vec3Arg inFrom, Vec3Arg inTo)
 
template<class Random >
static Quat sRandom (Random &inRandom)
 Random unit quaternion. More...
 
static Quat sEulerAngles (Vec3Arg inAngles)
 Conversion from Euler angles. Rotation order is X then Y then Z (RotZ * RotY * RotX). Angles in radians. More...
 
static JPH_INLINE Quat sLoadFloat3Unsafe (const Float3 &inV)
 Load 3 floats from memory (X, Y and Z component and then calculates W) reads 32 bits extra which it doesn't use. More...
 
Default quaternions
static JPH_INLINE Quat sZero ()
 
static JPH_INLINE Quat sIdentity ()
 

Public Attributes

Vec4 mValue
 4 vector that stores [x, y, z, w] parts of the quaternion More...
 

Friends

ostream & operator<< (ostream &inStream, QuatArg inQ)
 To String. More...
 

Additions / multiplications

JPH_INLINE void operator+= (QuatArg inRHS)
 
JPH_INLINE void operator-= (QuatArg inRHS)
 
JPH_INLINE void operator*= (float inValue)
 
JPH_INLINE void operator/= (float inValue)
 
JPH_INLINE Quat operator- () const
 
JPH_INLINE Quat operator+ (QuatArg inRHS) const
 
JPH_INLINE Quat operator- (QuatArg inRHS) const
 
JPH_INLINE Quat operator* (QuatArg inRHS) const
 
JPH_INLINE Quat operator* (float inValue) const
 
JPH_INLINE Quat operator/ (float inValue) const
 
Quat operator* (float inValue, QuatArg inRHS)
 

Detailed Description

Quaternion class, quaternions are 4 dimensional vectors which can describe rotations in 3 dimensional space if their length is 1.

They are written as:

\(q = w + x \: i + y \: j + z \: k\)

or in vector notation:

\(q = [w, v] = [w, x, y, z]\)

Where:

w = the real part v = the imaginary part, (x, y, z)

Note that we store the quaternion in a Vec4 as [x, y, z, w] because that makes it easy to extract the rotation axis of the quaternion:

q = [cos(angle / 2), sin(angle / 2) * rotation_axis]

Constructor & Destructor Documentation

◆ Quat() [1/4]

Quat::Quat ( )
inlinedefault

Intentionally not initialized for performance reasons.

◆ Quat() [2/4]

Quat::Quat ( const Quat inRHS)
default

◆ Quat() [3/4]

Quat::Quat ( float  inX,
float  inY,
float  inZ,
float  inW 
)
inline

◆ Quat() [4/4]

Quat::Quat ( Vec4Arg  inV)
inlineexplicit

Member Function Documentation

◆ Conjugated()

JPH_INLINE Quat Quat::Conjugated ( ) const
inline

The conjugate [w, -x, -y, -z] is the same as the inverse for unit quaternions.

◆ Dot()

JPH_INLINE float Quat::Dot ( QuatArg  inRHS) const
inline

Dot product.

◆ EnsureWPositive()

JPH_INLINE Quat Quat::EnsureWPositive ( ) const
inline

Ensures that the W component is positive by negating the entire quaternion if it is not. This is useful when you want to store a quaternion as a 3 vector by discarding W and reconstructing it as sqrt(1 - x^2 - y^2 - z^2).

◆ GetAxisAngle()

void Quat::GetAxisAngle ( Vec3 outAxis,
float &  outAngle 
) const

Get axis and angle that represents this quaternion, outAngle will always be in the range \([0, \pi]\).

◆ GetEulerAngles()

Vec3 Quat::GetEulerAngles ( ) const
inline

Conversion to Euler angles. Rotation order is X then Y then Z (RotZ * RotY * RotX). Angles in radians.

◆ GetPerpendicular()

JPH_INLINE Quat Quat::GetPerpendicular ( ) const
inline

Get a quaternion that is perpendicular to this quaternion.

◆ GetRotationAngle()

JPH_INLINE float Quat::GetRotationAngle ( Vec3Arg  inAxis) const
inline

Get rotation angle around inAxis (uses Swing Twist Decomposition to get the twist quaternion and uses q(axis, angle) = [cos(angle / 2), axis * sin(angle / 2)])

◆ GetSwingTwist()

void Quat::GetSwingTwist ( Quat outSwing,
Quat outTwist 
) const

Decomposes quaternion into swing and twist component:

\(q = q_{swing} \: q_{twist}\)

where \(q_{swing} \: \hat{x} = q_{twist} \: \hat{y} = q_{twist} \: \hat{z} = 0\)

In other words:

  • \(q_{twist}\) only rotates around the X-axis.
  • \(q_{swing}\) only rotates around the Y and Z-axis.
See also
Gino van den Bergen - Rotational Joint Limits in Quaternion Space - GDC 2016

◆ GetTwist()

Quat Quat::GetTwist ( Vec3Arg  inAxis) const

Swing Twist Decomposition: any quaternion can be split up as:

\[q = q_{swing} \: q_{twist}\]

where \(q_{twist}\) rotates only around axis v.

\(q_{twist}\) is:

\[q_{twist} = \frac{[q_w, q_{ijk} \cdot v \: v]}{\left|[q_w, q_{ijk} \cdot v \: v]\right|}\]

where q_w is the real part of the quaternion and q_i the imaginary part (a 3 vector).

The swing can then be calculated as:

\[q_{swing} = q \: q_{twist}^* \]

Where \(q_{twist}^*\) = complex conjugate of \(q_{twist}\)

◆ GetW()

JPH_INLINE float Quat::GetW ( ) const
inline

Get W component (real part)

◆ GetX()

JPH_INLINE float Quat::GetX ( ) const
inline

Get X component (imaginary part i)

◆ GetXYZ()

JPH_INLINE Vec3 Quat::GetXYZ ( ) const
inline

Get the imaginary part of the quaternion.

◆ GetXYZW()

JPH_INLINE Vec4 Quat::GetXYZW ( ) const
inline

Get the quaternion as a Vec4.

◆ GetY()

JPH_INLINE float Quat::GetY ( ) const
inline

Get Y component (imaginary part j)

◆ GetZ()

JPH_INLINE float Quat::GetZ ( ) const
inline

Get Z component (imaginary part k)

◆ Inversed()

JPH_INLINE Quat Quat::Inversed ( ) const
inline

Get inverse quaternion.

◆ InverseRotate()

Vec3 Quat::InverseRotate ( Vec3Arg  inValue) const

Rotate a vector by the inverse of this quaternion.

◆ IsClose()

bool Quat::IsClose ( QuatArg  inRHS,
float  inMaxDistSq = 1.0e-12f 
) const
inline

If this quaternion is close to inRHS. Note that q and -q represent the same rotation, this is not checked here.

◆ IsNaN()

bool Quat::IsNaN ( ) const
inline

If any component of this quaternion is a NaN (not a number)

◆ IsNormalized()

bool Quat::IsNormalized ( float  inTolerance = 1.0e-5f) const
inline

If the length of this quaternion is 1 +/- inTolerance.

◆ Length()

JPH_INLINE float Quat::Length ( ) const
inline

Length of quaternion.

Returns
Length of quaternion ( \(|v|\))

◆ LengthSq()

JPH_INLINE float Quat::LengthSq ( ) const
inline

Squared length of quaternion.

Returns
Squared length of quaternion ( \(|v|^2\))

◆ LERP()

Quat Quat::LERP ( QuatArg  inDestination,
float  inFraction 
) const

Linear interpolation between two quaternions (for small steps).

Parameters
inFractionis in the range [0, 1]
inDestinationThe destination quaternion
Returns
(1 - inFraction) * this + fraction * inDestination

◆ Normalized()

JPH_INLINE Quat Quat::Normalized ( ) const
inline

Normalize the quaternion (make it length 1)

◆ operator!=()

bool Quat::operator!= ( QuatArg  inRHS) const
inline

Check if two quaternions are different.

◆ operator*() [1/3]

JPH_INLINE Quat Quat::operator* ( float  inValue) const
inline

◆ operator*() [2/3]

JPH_NAMESPACE_BEGIN Quat Quat::operator* ( QuatArg  inRHS) const

◆ operator*() [3/3]

Vec3 Quat::operator* ( Vec3Arg  inValue) const

Rotate a vector by this quaternion.

◆ operator*=()

JPH_INLINE void Quat::operator*= ( float  inValue)
inline

◆ operator+()

JPH_INLINE Quat Quat::operator+ ( QuatArg  inRHS) const
inline

◆ operator+=()

JPH_INLINE void Quat::operator+= ( QuatArg  inRHS)
inline

◆ operator-() [1/2]

JPH_INLINE Quat Quat::operator- ( ) const
inline

◆ operator-() [2/2]

JPH_INLINE Quat Quat::operator- ( QuatArg  inRHS) const
inline

◆ operator-=()

JPH_INLINE void Quat::operator-= ( QuatArg  inRHS)
inline

◆ operator/()

JPH_INLINE Quat Quat::operator/ ( float  inValue) const
inline

◆ operator/=()

JPH_INLINE void Quat::operator/= ( float  inValue)
inline

◆ operator=()

Quat & Quat::operator= ( const Quat inRHS)
default

◆ operator==()

bool Quat::operator== ( QuatArg  inRHS) const
inline

Check if two quaternions are exactly equal.

◆ RotateAxisX()

Vec3 Quat::RotateAxisX ( ) const

Rotate a the vector (1, 0, 0) with this quaternion.

◆ RotateAxisY()

Vec3 Quat::RotateAxisY ( ) const

Rotate a the vector (0, 1, 0) with this quaternion.

◆ RotateAxisZ()

Vec3 Quat::RotateAxisZ ( ) const

Rotate a the vector (0, 0, 1) with this quaternion.

◆ Set()

JPH_INLINE void Quat::Set ( float  inX,
float  inY,
float  inZ,
float  inW 
)
inline

Set all components.

◆ SetW()

JPH_INLINE void Quat::SetW ( float  inW)
inline

◆ SetX()

JPH_INLINE void Quat::SetX ( float  inX)
inline

Set individual components.

◆ SetY()

JPH_INLINE void Quat::SetY ( float  inY)
inline

◆ SetZ()

JPH_INLINE void Quat::SetZ ( float  inZ)
inline

◆ sEulerAngles()

Quat Quat::sEulerAngles ( Vec3Arg  inAngles)
inlinestatic

Conversion from Euler angles. Rotation order is X then Y then Z (RotZ * RotY * RotX). Angles in radians.

◆ sFromTo()

Quat Quat::sFromTo ( Vec3Arg  inFrom,
Vec3Arg  inTo 
)
static

Create quaternion that rotates a vector from the direction of inFrom to the direction of inTo along the shortest path

See also
https://www.euclideanspace.com/maths/algebra/vectors/angleBetween/index.htm

◆ sIdentity()

static JPH_INLINE Quat Quat::sIdentity ( )
inlinestatic
Returns
[1, 0, 0, 0] (or in storage format Quat(0, 0, 0, 1))

◆ SLERP()

Quat Quat::SLERP ( QuatArg  inDestination,
float  inFraction 
) const

Spherical linear interpolation between two quaternions.

Parameters
inFractionis in the range [0, 1]
inDestinationThe destination quaternion
Returns
When fraction is zero this quaternion is returned, when fraction is 1 inDestination is returned. When fraction is between 0 and 1 an interpolation along the shortest path is returned.

◆ sLoadFloat3Unsafe()

Quat Quat::sLoadFloat3Unsafe ( const Float3 inV)
static

Load 3 floats from memory (X, Y and Z component and then calculates W) reads 32 bits extra which it doesn't use.

◆ sRandom()

template<class Random >
Quat Quat::sRandom ( Random &  inRandom)
inlinestatic

Random unit quaternion.

◆ sRotation()

Quat Quat::sRotation ( Vec3Arg  inAxis,
float  inAngle 
)
static

Rotation from axis and angle.

◆ StoreFloat3()

void Quat::StoreFloat3 ( Float3 outV) const

Store 3 as floats to memory (X, Y and Z component)

◆ sZero()

static JPH_INLINE Quat Quat::sZero ( )
inlinestatic
Returns
[0, 0, 0, 0]

Friends And Related Function Documentation

◆ operator*

Quat operator* ( float  inValue,
QuatArg  inRHS 
)
friend

◆ operator<<

ostream & operator<< ( ostream &  inStream,
QuatArg  inQ 
)
friend

To String.

Member Data Documentation

◆ mValue

Vec4 Quat::mValue

4 vector that stores [x, y, z, w] parts of the quaternion


The documentation for this class was generated from the following files: