Quaternions can be used to represent rotations in 3D space. More...

#include <Quat.h>

Public Types
using	ComponentType = Type

Public Member Functions
	XII_DECLARE_POD_TYPE ()

	xiiQuatTemplate (Type x, Type y, Type z, Type w)
	For internal use. You should never construct quaternions this way.

void	SetIdentity ()
	Sets the Quaternion to the identity.

void	ReconstructFromMat3 (const xiiMat3Template< Type > &m)
	Reconstructs a rotation quaternion from a matrix that may contain scaling and mirroring.

void	ReconstructFromMat4 (const xiiMat4Template< Type > &m)
	Reconstructs a rotation quaternion from a matrix that may contain scaling and mirroring.

const Type *	GetData () const
	Returns the data as an array.

Type *	GetData ()
	Returns the data as an array.

void	Normalize ()
	Normalizes the quaternion to unit length. ALL rotation-quaternions should be normalized at all times (automatically).

void	GetRotationAxisAndAngle (xiiVec3Template< Type > &out_vAxis, xiiAngleTemplate< Type > &out_angle, Type fEpsilon=xiiMath::DefaultEpsilon< Type >()) const
	Returns the rotation-axis and angle, that this quaternion rotates around.

xiiVec3Template< Type >	GetVectorPart () const
	Returns the x,y,z components as a vector.

const xiiMat3Template< Type >	GetAsMat3 () const
	Returns the Quaternion as a matrix.

const xiiMat4Template< Type >	GetAsMat4 () const
	Returns the Quaternion as a matrix.

bool	IsValid (Type fEpsilon=xiiMath::DefaultEpsilon< Type >()) const
	Checks whether all components are neither NaN nor infinite and that the quaternion is normalized.

bool	IsNaN () const
	Checks whether any component is NaN.

bool	IsEqualRotation (const xiiQuatTemplate &qOther, Type fEpsilon) const
	Determines whether this and qOther represent the same rotation. This is a rather slow operation.

void	Invert ()
	Inverts the rotation, so instead of rotating N degrees around an axis, the quaternion will rotate -N degrees around its axis.

const xiiQuatTemplate< Type >	GetInverse () const
	Returns a quaternion that represents the negative / inverted rotation. E.g. the one that would rotate back to identity.

const xiiQuatTemplate< Type >	GetNegated () const
	Returns the Quaternion with all 4 components negated. This is not the same as the inverted rotation!

Type	Dot (const xiiQuatTemplate &rhs) const
	Returns the dot-product of the two quaternions (commutative, order does not matter).

xiiVec3Template< Type >	Rotate (const xiiVec3Template< Type > &v) const
	Returns v rotated by the quaternion. Same as operator*.

void	GetAsEulerAngles (xiiAngleTemplate< Type > &out_x, xiiAngleTemplate< Type > &out_y, xiiAngleTemplate< Type > &out_z) const
	Converts the quaternion to Euler angles.

Static Public Member Functions
static const xiiQuatTemplate< Type >	MakeIdentity ()
	Static function that returns a quaternion that represents the identity rotation (none).

static xiiQuatTemplate< Type >	MakeFromElements (Type x, Type y, Type z, Type w)
	Sets the individual elements of the quaternion directly. Note that x,y,z do NOT represent a rotation axis, and w does NOT represent an angle.

static xiiQuatTemplate< Type >	MakeFromAxisAndAngle (const xiiVec3Template< Type > &vRotationAxis, xiiAngleTemplate< Type > angle)
	Creates a quaternion from a rotation-axis and an angle.

static xiiQuatTemplate< Type >	MakeShortestRotation (const xiiVec3Template< Type > &vDirFrom, const xiiVec3Template< Type > &vDirTo)
	Creates a quaternion, that rotates through the shortest arc from "vDirFrom" to "vDirTo".

static xiiQuatTemplate< Type >	MakeFromMat3 (const xiiMat3Template< Type > &m)
	Creates a quaternion from the given matrix.

static xiiQuatTemplate< Type >	MakeSlerp (const xiiQuatTemplate &qFrom, const xiiQuatTemplate &qTo, Type t)
	Returns a quaternion that is the spherical linear interpolation of the other two.

static xiiQuatTemplate< Type >	MakeFromEulerAngles (const xiiAngleTemplate< Type > &x, const xiiAngleTemplate< Type > &y, const xiiAngleTemplate< Type > &z)
	Sets the quaternion from Euler angles.

Public Attributes
Type	x

Type	y

Type	z

Type	w

Detailed Description

template<typename Type>
class xiiQuatTemplate< Type >

Quaternions can be used to represent rotations in 3D space.

Quaternions are useful to represent 3D rotations, as they are smaller and more efficient than matrices and can be concatenated easily, without having the 'Gimbal Lock' problem of Euler Angles. Either use a full blown transformation (e.g. a 4x4 matrix) to represent a object, or use a Quaternion bundled with a position vector, if (non-uniform) scale is not required. Quaternions can also easily be interpolated (via Slerp). This implementation also allows to convert back and forth between Quaternions and Matrices easily.

Quaternions have no 'IsIdentical' or 'IsEqual' function, as there can be different representations for the same rotation, and it is rather difficult to check this. So to not convey any false notion of being equal (or rather unequal), those functions are not provided.

Member Function Documentation

◆ Invert()

template<typename Type>

XII_FORCE_INLINE void xiiQuatTemplate< Type >::Invert ( )

Inverts the rotation, so instead of rotating N degrees around an axis, the quaternion will rotate -N degrees around its axis.

This modifies the quaternion in place. If you want to get the inverse as a copy, use GetInverse().

◆ IsEqualRotation()

template<typename Type>

bool xiiQuatTemplate< Type >::IsEqualRotation	(	const xiiQuatTemplate< Type > &	qOther,
		Type	fEpsilon ) const

Determines whether this and qOther represent the same rotation. This is a rather slow operation.

Currently it fails when one of the given quaternions is identity (so no rotation, at all), as it tries to compare rotation axis' and angles, which is undefined for the identity quaternion (also there are infinite representations for 'identity', so it's difficult to check for it).

◆ MakeFromElements()

template<typename Type>

XII_ALWAYS_INLINE xiiQuatTemplate< Type > xiiQuatTemplate< Type >::MakeFromElements	(	Type	x,
		Type	y,
		Type	z,
		Type	w )

staticnodiscard

Sets the individual elements of the quaternion directly. Note that x,y,z do NOT represent a rotation axis, and w does NOT represent an angle.

Use this function only if you have good understanding of quaternion math and know exactly what you are doing.

◆ MakeFromEulerAngles()

template<typename Type>

xiiQuatTemplate< Type > xiiQuatTemplate< Type >::MakeFromEulerAngles	(	const xiiAngleTemplate< Type > &	x,
		const xiiAngleTemplate< Type > &	y,
		const xiiAngleTemplate< Type > &	z )

staticnodiscard

Sets the quaternion from Euler angles.

Taken from here (yaw->pitch->roll, ZYX order or 3-2-1 order): https://en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles

◆ MakeShortestRotation()

template<typename Type>

xiiQuatTemplate< Type > xiiQuatTemplate< Type >::MakeShortestRotation	(	const xiiVec3Template< Type > &	vDirFrom,
		const xiiVec3Template< Type > &	vDirTo )

staticnodiscard

Creates a quaternion, that rotates through the shortest arc from "vDirFrom" to "vDirTo".

Note: This function will ALWAYS return a quaternion that rotates from one direction to another. If both directions are identical, it is the unit rotation (none). If they are exactly opposing, this will be ANY 180.0 degree rotation. That means the vectors will align perfectly, but there is no determine rotation for other points that might be rotated with this quaternion. If a main / fallback axis is needed to rotate points, you need to calculate such a rotation with other means.

◆ ReconstructFromMat3()

template<typename Type>

void xiiQuatTemplate< Type >::ReconstructFromMat3 ( const xiiMat3Template< Type > & m )

Reconstructs a rotation quaternion from a matrix that may contain scaling and mirroring.

In skeletal animation it is possible that matrices with mirroring are used, that need to be converted to a proper quaternion, even though a rotation with mirroring can't be represented by a quaternion. This function reconstructs a valid quaternion from such matrices. Obviously the mirroring information gets lost, but it is typically not needed any further anway.

◆ ReconstructFromMat4()

template<typename Type>

void xiiQuatTemplate< Type >::ReconstructFromMat4 ( const xiiMat4Template< Type > & m )

Reconstructs a rotation quaternion from a matrix that may contain scaling and mirroring.

See also: ReconstructFromMat3()

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

/home/runner/work/XII/XII/Source/Engine/Foundation/Math/Declarations.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Math/Quat.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Math/Implementation/Quat_inl.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ Invert()

◆ IsEqualRotation()

◆ MakeFromElements()

◆ MakeFromEulerAngles()

◆ MakeShortestRotation()

◆ ReconstructFromMat3()

◆ ReconstructFromMat4()