Quaternion
Module of libSIMDx86

The Quaternion module of libSIMDx86
gives functions to accelerate quaternion operations commonly used in
calculations of imaginary numbers and 3D rotations in character
animation that cannot suffer from Gimbal Lock. Quaternions are stored
in xyzw format, NOT wxyz. Quaternions represent rotation along an
arbitrary axis with a certain angle. Specifically, a quaternion can
be defined as:

*Qx*
= *Ax* * sin(*r*/2);*Qy* = *Ay* *
sin(*r*/2);*Qz* = *Az* * sin(*r*/2);*Qw*
= cos(*r*/2);

Where *A* represents the 3D axis of
rotation, *r* represents the angle in radians, and *Q*
represents the quaternion.

#include <SIMDx86/quaternion.h>

typedef struct SIMDx86Quaternion

{

float x;

float y;

float z;

float w;

} SIMDx86Quaternion;

void
SIMDx86Quaternion_Normalize(SIMDx86Quaternion* pQuat);

Normalizes pQuat and stores it in pQuat.

void SIMDx86Quaternion_NormalizeOf(SIMDx86Quaternion* pOut, const SIMDx86Quaternion* pQuat);

Normalizes pQuat and stores it in pOut.

float SIMDx86Quaternion_Length(const SIMDx86Quaternion* pQuat);

Returns the length of a pQuat. Quaternions should be at unit length (i.e. 1.0f), but if not, then this function can be used to check whether the quaternion needs to be normalized. However, it is slower to compute the length, than call SIMDx86Quaternion_Normalize(). This function is provided for debuging mainly.

float SIMDx86Quaternion_LengthSq(const SIMDx86Quaternion* pQuat);

Returns the length of pQuat. Quaternions should be at unit length (i.e. 1.0), but if not, then this function can be used to check whether the quaternion needs to be normalized. However, it is slower to compute the square length, than call SIMDx86Quaternion_Normalize(). This function is provided for debuging mainly.

void SIMDx86Quaternion_Multiply(SIMDx86Quaternion* pLeft, const SIMDx86Quaternion* pRight);

Multiplies pLeft by pRight and stores the result in pLeft. The result is not explicitly normalized, but will be normal if two normal quaternions are used as inputs.

void SIMDx86Quaternion_MultiplyOf(SIMDx86Quaternion* pOut, const SIMDx86Quaternion* pLeft,

const SIMDx86Quaternion* pRight);

Multiplies pLeft by pRight and stores the result in pOut. The result is not explicitly normalized, but will be normal if two normal quaternions are used as inputs.

void SIMDx86Quaternion_Conjugate(SIMDx86Quaternion* pQuat);

Stores the conjugate of pQuat in pQuat.

void SIMDx86Quaternion_ConjugateOf(SIMDx86Quaternion* pOut, const SIMDx86Quaternion* pIn);

Stores the conjugate of pIn in pOut.

void SIMDx86Quaternion_ToMatrix(SIMDx86Matrix* pMat, const SIMDx86Quaternion* pQuat);

Converts pQuat into a rotational 4x4 Matrix stored in pMat. This is primarily used for storing quaternions in skeletal animation files and then converting them to matricies at runtime to be blended.

void
SIMDx86Quaternion_Rotate(SIMDx86Quaternion* pOut, float
rads, float x, float
y, float z);

This
constructs a quaternion around an arbitrary axis at the rotation of
rads radians and stores it in
pOut. The quaternion is normal
(i.e. of unit length), even if the arbitrary axis composed from x,
y, and z
is not.

void SIMDx86Quaternion_Slerp(SIMDx86Quaternion* pOut, const SIMDx86Quaternion* pSrc1, const SIMDx86Quaternion* pSrc2, float scalar);

This performs a spherical linear interpolation between pSrc1 and pSrc2, with scalar being a clamped float in the range of [0.0, 1.0], where 0.0f yields pSrc1, and 1.0 yields pSrc2. The result is stored in pOut. This is commonly used in skeletal animation to interpolate between to two rotation frames where scalar represents the percent complete the animation is, such that 0% (0.0) yields the start, and 100% (1.0) yields the final animation. The result is undefined if scalar is not in the [0.0, 1.0] range.