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

#include <Quat.h>

Public Types
using	ComponentType = Type

Public Member Functions
	PL_DECLARE_POD_TYPE ()

	plQuatTemplate (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 plMat3Template< Type > &m)
	Reconstructs a rotation quaternion from a matrix that may contain scaling and mirroring.

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

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

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

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

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

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

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

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

bool	IsValid (Type fEpsilon=plMath::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 plQuatTemplate &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 plQuatTemplate< Type >	GetInverse () const
	Returns a quaternion that represents the negative / inverted rotation. E.g. the one that would rotate back to identity.

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

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

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

void	GetAsEulerAngles (plAngle &out_x, plAngle &out_y, plAngle &out_z) const
	Converts the quaternion to Euler angles.

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

static plQuatTemplate< 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 plQuatTemplate< Type >	MakeFromAxisAndAngle (const plVec3Template< Type > &vRotationAxis, plAngle angle)
	Creates a quaternion from a rotation-axis and an angle.

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

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

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

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

Public Attributes
Type	x

Type	y

Type	z

Type	w

Detailed Description

template<typename Type>
class plQuatTemplate< 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 >

PL_FORCE_INLINE void plQuatTemplate< 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 plQuatTemplate< Type >::IsEqualRotation	(	const plQuatTemplate< 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 >

PL_ALWAYS_INLINE plQuatTemplate< Type > plQuatTemplate< 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 >

plQuatTemplate< Type > plQuatTemplate< Type >::MakeFromEulerAngles	(	const plAngle &	x,
		const plAngle &	y,
		const plAngle &	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 >

plQuatTemplate< Type > plQuatTemplate< Type >::MakeShortestRotation	(	const plVec3Template< Type > &	vDirFrom,
		const plVec3Template< 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 plQuatTemplate< Type >::ReconstructFromMat3 ( const plMat3Template< 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 plQuatTemplate< Type >::ReconstructFromMat4 ( const plMat4Template< 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:

Code/Engine/Foundation/Math/Declarations.h
Code/Engine/Foundation/Math/Quat.h
Code/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()