Quaternion Operations

Quaternions provide a compact and efficient way to represent rotations in 3D space. They avoid issues like gimbal lock that can plague Euler angles. The DirectXMath library offers a comprehensive set of functions for manipulating quaternions.

Identity Quaternion

The identity quaternion represents no rotation.

XMVECTOR XMQuaternionIdentity();

Parameters

  • None

Return Value

  • An XMVECTOR representing the identity quaternion (0, 0, 0, 1).

Quaternion from Euler Angles

Creates a quaternion from a set of Euler angles (pitch, yaw, roll). The order of rotations matters.

XMVECTOR XMQuaternionRotationRollPitchYaw(
    float Pitch,
    float Yaw,
    float Roll
);

Parameters

  • Pitch: The rotation around the X-axis (in radians).
  • Yaw: The rotation around the Y-axis (in radians).
  • Roll: The rotation around the Z-axis (in radians).

Return Value

  • An XMVECTOR representing the quaternion.

Quaternion from Axis and Angle

Creates a quaternion from a rotation axis and an angle (in radians).

XMVECTOR XMQuaternionRotationAxis(
    FXMVECTOR Axis,
    float Angle
);

Parameters

  • Axis: A normalized XMVECTOR representing the rotation axis.
  • Angle: The rotation angle (in radians).

Return Value

  • An XMVECTOR representing the quaternion.

Quaternion from Matrix

Extracts a quaternion from a rotation matrix.

XMVECTOR XMQuaternionRotationMatrix(
    FXMMATRIX M
);

Parameters

  • M: The XMMATRIX containing the rotation.

Return Value

  • An XMVECTOR representing the quaternion.

Quaternion Multiplication

Multiplies two quaternions. This operation concatenates the rotations they represent.

XMVECTOR XMQuaternionMultiply(
    FXMVECTOR Q1,
    FXMVECTOR Q2
);

Parameters

  • Q1: The first quaternion.
  • Q2: The second quaternion.

Return Value

  • An XMVECTOR representing the product of Q1 and Q2.

Quaternion Conjugate

Computes the conjugate of a quaternion.

XMVECTOR XMQuaternionConjugate(
    FXMVECTOR Q
);

Parameters

  • Q: The input quaternion.

Return Value

  • An XMVECTOR representing the conjugate of Q.

Quaternion Inverse

Computes the inverse of a quaternion. For a unit quaternion, the inverse is its conjugate.

XMVECTOR XMQuaternionInverse(
    FXMVECTOR Q
);

Parameters

  • Q: The input quaternion.

Return Value

  • An XMVECTOR representing the inverse of Q.

Quaternion Normalize

Normalizes a quaternion to ensure it represents a unit quaternion.

XMVECTOR XMQuaternionNormalize(
    FXMVECTOR Q
);

Parameters

  • Q: The input quaternion.

Return Value

  • An XMVECTOR representing the normalized quaternion.

Quaternion Dot Product

Computes the dot product of two quaternions.

XMVECTOR XMQuaternionDot(
    FXMVECTOR Q1,
    FXMVECTOR Q2
);

Parameters

  • Q1: The first quaternion.
  • Q2: The second quaternion.

Return Value

  • An XMVECTOR containing the dot product in the x-component. The other components are undefined.

Quaternion Slerp (Spherical Linear Interpolation)

Performs spherical linear interpolation between two quaternions.

XMVECTOR XMQuaternionSlerp(
    FXMVECTOR Q0,
    FXMVECTOR Q1,
    float t
);

Parameters

  • Q0: The starting quaternion.
  • Q1: The ending quaternion.
  • t: The interpolation factor, typically between 0.0 and 1.0.

Return Value

  • An XMVECTOR representing the interpolated quaternion.

Quaternion Squad (Spherical Cubic Interpolation)

Performs spherical cubic interpolation for smoother interpolation between multiple quaternions.

XMVECTOR XMQuaternionSquad(
    FXMVECTOR Q0,
    FXMVECTOR Q1,
    FXMVECTOR Q2,
    FXMVECTOR Q3,
    float t
);

Parameters

  • Q0: The previous quaternion.
  • Q1: The current quaternion.
  • Q2: The next quaternion.
  • Q3: The subsequent quaternion.
  • t: The interpolation factor, typically between 0.0 and 1.0.

Return Value

  • An XMVECTOR representing the interpolated quaternion.

Quaternion to Matrix

Converts a quaternion into a rotation matrix.

XMMATRIX XMMatrixRotationQuaternion(
    FXMVECTOR Q
);

Parameters

  • Q: The input quaternion.

Return Value

  • An XMMATRIX representing the rotation.

Example Usage:

#include <DirectXMath.h>

// ...

using namespace DirectX;

// Define pitch, yaw, and roll in radians
float pitch = XMConvertToRadians(30.0f);
float yaw = XMConvertToRadians(45.0f);
float roll = XMConvertToRadians(15.0f);

// Create a quaternion from Euler angles
XMVECTOR quaternion = XMQuaternionRotationRollPitchYaw(pitch, yaw, roll);

// Create a rotation matrix from the quaternion
XMMATRIX rotationMatrix = XMMatrixRotationQuaternion(quaternion);

// Example of combining rotations
XMVECTOR quaternion2 = XMQuaternionRotationAxis(XMVectorSet(0.0f, 1.0f, 0.0f, 0.0f), XMConvertToRadians(90.0f));
XMVECTOR combinedQuaternion = XMQuaternionMultiply(quaternion, quaternion2);
XMMATRIX combinedMatrix = XMMatrixRotationQuaternion(combinedQuaternion);