NAME

M_Quaternion — Agar-Math quaternion

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>
#include <agar/math/m.h>

DESCRIPTION

The M_Quaternion structure describes a quaternion. Quaternions are a non-commutative extension of complex numbers (see M_Complex(3)). Quaternions provide a convenient way of representing and concatenating rotations. The structure is defined as:

typedef struct m_quaternion {
	M_Real w, x, y, z;
} M_Quaternion;

INITIALIZATION

M_Quaternion
M_QuaternionMultIdentity(void);

M_Quaternion
M_QuaternionAddIdentity(void);

M_Quaternion
M_ReadQuaternion(AG_DataSource *ds);

void
M_WriteQuaternion(AG_DataSource *ds, M_Quaternion q);

The M_QuaternionMultIdentity() routine returns the multiplicative identity (1,0,0,0). M_QuaternionAddIdentity() returns the additive identity (0,0,0,0).

The M_ReadQuaternion() function reads a quaternion from an AG_DataSource(3) and returns it. M_WriteQuaternion() writes a quaternion to a data source.

CONVERSION ROUTINES

void
M_QuaternionpToAxisAngle(const M_Quaternion *q, M_Vector3 *axis, M_Real *theta);

void
M_QuaternionpToAxisAngle3(const M_Quaternion *q, M_Real *theta, M_Real *x, M_Real *y, M_Real *z);

M_Quaternion
M_QuaternionFromAxisAngle(M_Vector3 axis, M_Real theta);

M_Quaternion
M_QuaternionFromAxisAngle3(M_Real theta, M_Real x, M_Real y, M_Real z);

void
M_QuaternionpFromAxisAngle(M_Quaternion *q, M_Vector3 axis, M_Real theta);

void
M_QuaternionpFromAxisAngle3(M_Quaternion *q, M_Real theta, M_Real x, M_Real y, M_Real z);

void
M_QuaternionFromEulv(M_Quaternion *q, M_Real a, M_Real b, M_Real c);

M_Quaternion
M_QuaternionFromEul(M_Real a, M_Real b, M_Real c);

void
M_QuaternionToMatrix44(M_Matrix44 *A, const M_Quaternion *q);

The M_QuaternionpToAxisAngle() function obtains a rotation in axis-angle format from a quaternion q. The axis is returned into v and angle into theta. The M_QuaternionpToAxisAngle3() variant returns the axis into x, y and z.

M_QuaternionFromAxisAngle() returns a quaternion describing a rotation of theta radians about the axis vector. The M_QuaternionFromAxisAngle3() form accepts individual x, y, z arguments.

The M_QuaternionpFromAxisAngle() and M_QuaternionpFromAxisAngle3() variants write the resulting quaternion into q as opposed to returning it.

M_QuaternionFromEulv() and M_QuaternionFromEul() return a quaternion describing a rotation given the set of Euler angles.

M_QuaternionToMatrix44() converts the rotation described by quaternion q into a 4x4 matrix A.

ARITHMETIC OPERATIONS

void

M_Quaternion
M_QuaternionConj(M_Quaternion q);

M_Quaternion
M_QuaternionConjp(const M_Quaternion *q);

void
M_QuaternionConjv(M_Quaternion *q);

M_Quaternion
M_QuaternionScale(M_Quaternion q, M_Real c);

M_Quaternion
M_QuaternionScalep(const M_Quaternion *q, M_Real c);

void
M_QuaternionScalev(M_Quaternion *q, M_Real c);

M_Quaternion
M_QuaternionConcat(const M_Quaternion *q1, const M_Quaternion *q2);

M_Quaternion
M_QuaternionMult(M_Quaternion q1, M_Quaternion q2);

M_Quaternion
M_QuaternionMultp(const M_Quaternion *q1, const M_Quaternion *q2);

void
M_QuaternionMultv(M_Quaternion *q, const M_Quaternion *q1, const M_Quaternion *q2);

M_Quaternion
M_QuaternionNormp(const M_Quaternion *q);

void
M_QuaternionNormv(M_Quaternion *q);

M_Quaternion
M_QuaternionInverse(M_Quaternion q);

M_Quaternion
M_QuaternionInversep(const M_Quaternion *q);

void
M_QuaternionInversev(M_Quaternion *q);

M_Quaternion
M_QuaternionSLERP(M_Quaternion q1, M_Quaternion q2, M_Real c);

M_Quaternion
M_QuaternionSLERPp(const M_Quaternion *q1, const M_Quaternion *q2, M_Real c);

M_QuaternionConj(), M_QuaternionConjp() and M_QuaternionConjv() return the conjugate of q.

M_QuaternionScale(), M_QuaternionScalep() and M_QuaternionScalev() return the quaternion q scaled by factor c.

M_QuaternionConcat() concatenates the rotations described by q1 and q2 and returns the resulting quaternion.

M_QuaternionMult(), M_QuaternionMultp() and M_QuaternionMultv() compute the product of q1 and q2.

M_QuaternionNormp() and M_QuaternionNormv() return the normalized form of q (equivalent to normalizing q as a vector).

M_QuaternionInverse(), M_QuaternionInversep() and M_QuaternionInversev() return the inverse (i.e., the normalized form of the conjugate) of q.

The functions M_QuaternionSLERP() and M_QuaternionSLERPp() perform spherical linear interpolation (SLERP) between q1 and q2, by factor c, and returns the result.

SEE ALSO

AG_DataSource(3), AG_Intro(3), M_Complex(3), M_Matrix(3), M_Real(3), M_Vector(3)

HISTORY

The M_Quaternion structure first appeared in Agar 1.3.4.