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]\).
Vec3	GetEulerAngles () const
	Conversion to Euler angles.
JPH_INLINE Vec3	operator* (Vec3Arg inValue) const
	Rotate a vector by this quaternion.
JPH_INLINE Vec3	InverseRotate (Vec3Arg inValue) const
	Rotate a vector by the inverse of this quaternion.
JPH_INLINE Vec3	RotateAxisX () const
	Rotate a the vector (1, 0, 0) with this quaternion.
JPH_INLINE Vec3	RotateAxisY () const
	Rotate a the vector (0, 1, 0) with this quaternion.
JPH_INLINE Vec3	RotateAxisZ () const
	Rotate a the vector (0, 0, 1) with this quaternion.
JPH_INLINE float	Dot (QuatArg inRHS) const
	Dot product
JPH_INLINE Quat	Conjugated () const
	The conjugate [w, -x, -y, -z] is the same as the inverse for unit quaternions.
JPH_INLINE Quat	Inversed () const
	Get inverse quaternion.
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).
JPH_INLINE Quat	GetPerpendicular () const
	Get a quaternion that is perpendicular to this quaternion.
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)])
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)
Constructors
	Quat ()=default
	Intentionally not initialized for performance reasons.
	Quat (const Quat &inRHS)=default
	Quat (float inX, float inY, float inZ, float inW)
	Quat (Vec4Arg inV)
Tests <br>
bool	operator== (QuatArg inRHS) const
	Check if two quaternions are exactly equal.
bool	operator!= (QuatArg inRHS) const
	Check if two quaternions are different.
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.
bool	IsNormalized (float inTolerance=1.0e-5f) const
	If the length of this quaternion is 1 +/- inTolerance.
bool	IsNaN () const
	If any component of this quaternion is a NaN (not a number)
Get components
JPH_INLINE float	GetX () const
	Get X component (imaginary part i)
JPH_INLINE float	GetY () const
	Get Y component (imaginary part j)
JPH_INLINE float	GetZ () const
	Get Z component (imaginary part k)
JPH_INLINE float	GetW () const
	Get W component (real part)
JPH_INLINE Vec3	GetXYZ () const
	Get the imaginary part of the quaternion.
JPH_INLINE Vec4	GetXYZW () const
	Get the quaternion as a Vec4.
Length / normalization operations <br>
JPH_INLINE float	LengthSq () const
JPH_INLINE float	Length () const
JPH_INLINE Quat	Normalized () const
	Normalize the quaternion (make it length 1)

Static Public Member Functions
static JPH_INLINE Quat	sRotation (Vec3Arg inAxis, float inAngle)
	Rotation from axis and angle.
static JPH_INLINE Quat	sFromTo (Vec3Arg inFrom, Vec3Arg inTo)
template<class Random >
static Quat	sRandom (Random &inRandom)
	Random unit quaternion.
static Quat	sEulerAngles (Vec3Arg inAngles)
	Conversion from Euler angles.
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.
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

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

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.

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

inFraction	is in the range [0, 1]
inDestination	The 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==()

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.

sEulerAngles()

Quat Quat::sEulerAngles ( Vec3Arg inAngles )

inlinestatic

Conversion from Euler angles.

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

inFraction	is in the range [0, 1]
inDestination	The 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 Symbol 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:

• Jolt/Math/Quat.h
• Jolt/Math/Quat.inl