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]\).
JPH_INLINE Vec3	GetAngularVelocity (float inDeltaTime) const
	Calculate angular velocity given that this quaternion represents the rotation that is reached after inDeltaTime when starting from identity rotation.
Vec3	GetEulerAngles () const
	Conversion to Euler angles. Rotation order is X then Y then Z (RotZ * RotY * RotX). Angles in radians.
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 as 3 floats to memory (X, Y and Z component). Ensures that W is positive before storing.
JPH_INLINE void	StoreFloat4 (Float4 *outV) const
	Store as 4 floats.
JPH_INLINE uint32	CompressUnitQuat () const
	Compress a unit quaternion to a 32 bit value, precision is around 0.5 degree.
Constructors
	Quat ()=default
	Intentionally not initialized for performance reasons.
	Quat (const Quat &inRHS)=default
Quat &	operator= (const Quat &inRHS)=default
	Quat (float inX, float inY, float inZ, float inW)
	Quat (const Float4 &inV)
	Quat (Vec4Arg inV)
Tests
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.
JPH_INLINE void	SetX (float inX)
	Set individual components.
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.
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)

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. Rotation order is X then Y then Z (RotZ * RotY * RotX). Angles in radians.
static JPH_INLINE Quat	sMultiplyImaginary (Vec3Arg inLHS, QuatArg inRHS)
	Multiply a quaternion with imaginary components and no real component (x, y, z, 0) with a quaternion.
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.
static JPH_INLINE Quat	sDecompressUnitQuat (uint32 inValue)
	Decompress a unit quaternion from a 32 bit value.
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/5]

Quat::Quat ( )

inlinedefault

Intentionally not initialized for performance reasons.

Quat() [2/5]

Quat::Quat ( const Quat & inRHS )

default

Quat() [3/5]

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

inline

Quat() [4/5]

Quat::Quat ( const Float4 & inV )

inlineexplicit

Quat() [5/5]

Quat::Quat ( Vec4Arg inV )

inlineexplicit

Member Function Documentation

CompressUnitQuat()

JPH_INLINE uint32 Quat::CompressUnitQuat ( ) const

inline

Compress a unit quaternion to a 32 bit value, precision is around 0.5 degree.

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).

GetAngularVelocity()

Vec3 Quat::GetAngularVelocity

(

float

inDeltaTime

)

const

Calculate angular velocity given that this quaternion represents the rotation that is reached after inDeltaTime when starting from identity rotation.

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

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=()

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.

sDecompressUnitQuat()

static JPH_INLINE Quat Quat::sDecompressUnitQuat ( uint32 inValue )

inlinestatic

Decompress a unit quaternion from a 32 bit value.

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

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.

sMultiplyImaginary()

Quat Quat::sMultiplyImaginary ( Vec3Arg inLHS, QuatArg inRHS )

static

Multiply a quaternion with imaginary components and no real component (x, y, z, 0) with a quaternion.

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 as 3 floats to memory (X, Y and Z component). Ensures that W is positive before storing.

StoreFloat4()

void Quat::StoreFloat4

(

Float4 *

outV

)

const

Store as 4 floats.

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