Quaternion
Quaternion stores four components (x, y, z, w), where (x, y, z) is the vector part and w is the scalar part. Unit quaternions encode 3D rotations without the gimbal lock and order ambiguity of Euler angles, compose through multiplication, and interpolate smoothly.
Rotations assume the quaternion is normalized. Construct one from an axis and angle with FromAxisAngle, extract a Matrix4 with GetMatrix, or recover a quaternion from a rotation matrix using the matrix constructor.
Construction
Constructors
Quaternion() constexpr
Constructs a quaternion from a rotation matrix.
Recovers the rotation encoded in the upper-left 3×3 block of the matrix using the branch that maximizes numerical stability. The matrix is assumed to be a pure rotation (orthonormal, no scale or shear).
Quaternion::Quaternion(const Matrix4& m);| Parameter | Description |
|---|---|
| m | Input rotation matrix. |
Quaternion() constexpr
Constructs a quaternion from individual components.
Quaternion::Quaternion(float x, float y, float z, float w);| Parameter | Description |
|---|---|
| x | X component of the vector part. |
| y | Y component of the vector part. |
| z | Z component of the vector part. |
| w | Scalar component. |
Properties
w float
Scalar component.
float w {1.0f};x float
X component of the vector part.
float x {0.0f};y float
Y component of the vector part.
float y {0.0f};z float
Z component of the vector part.
float z {0.0f};Functions
Converts the quaternion into a 4×4 rotation matrix.
Assumes the quaternion is normalized.
Matrix4 Quaternion::GetMatrix() const;Length() float
Returns the quaternion length.
float Quaternion::Length() const;LengthSquared() float
Returns the squared quaternion length.
Useful when comparing lengths without paying the cost of a square root.
float Quaternion::LengthSquared() const;Normalize() Quaternion&
Normalizes the quaternion in-place.
If the length is zero, the quaternion is left unchanged.
Quaternion& Quaternion::Normalize();Quaternion::FromAxisAngle() Quaternion
Builds a quaternion from an axis and angle.
static constexpr Quaternion Quaternion::FromAxisAngle(const Vector3& axis, float angle);| Parameter | Description |
|---|---|
| axis | Rotation axis; normalized internally. |
| angle | Rotation angle in radians. |
Quaternion::Identity() Quaternion
Returns the identity quaternion (0, 0, 0, 1).
static constexpr Quaternion Quaternion::Identity();Conjugate() Quaternion
Returns the conjugate of a quaternion.
Negates the vector part, leaving the scalar part unchanged. For a unit quaternion the conjugate is also its inverse.
Quaternion Conjugate(const Quaternion& q);| Parameter | Description |
|---|---|
| q | Input quaternion. |
Dot() float
Computes the dot product of two quaternions.
float Dot(const Quaternion& a, const Quaternion& b);| Parameter | Description |
|---|---|
| a | First quaternion. |
| b | Second quaternion. |
Inverse() Quaternion
Returns the inverse of a quaternion.
If the quaternion has zero length, the identity quaternion is returned.
Quaternion Inverse(const Quaternion& q);| Parameter | Description |
|---|---|
| q | Input quaternion. |
Normalize() Quaternion
Returns a normalized copy of a quaternion.
If the input has zero length, the identity quaternion is returned.
Quaternion Normalize(const Quaternion& q);| Parameter | Description |
|---|---|
| q | Input quaternion. |
operator*() Quaternion
Composes two rotations using the Hamilton product.
The result applies b first, then a, mirroring matrix multiplication. Quaternion multiplication is not commutative.
Quaternion operator* (const Quaternion& a, const Quaternion& b);| Parameter | Description |
|---|---|
| a | Second rotation to apply. |
| b | First rotation to apply. |
Rotates a 3D vector by a quaternion.
Assumes the quaternion is normalized.
Vector3 operator* (const Quaternion& q, const Vector3& v);| Parameter | Description |
|---|---|
| q | Rotation quaternion. |
| v | Vector to rotate. |
operator*() Quaternion
Multiplies a quaternion by a scalar.
Quaternion operator* (const Quaternion& q, float n);| Parameter | Description |
|---|---|
| q | Input quaternion. |
| n | Scalar value. |
operator*() Quaternion
Multiplies a scalar by a quaternion.
Quaternion operator* (float n, const Quaternion& q);| Parameter | Description |
|---|---|
| n | Scalar value. |
| q | Input quaternion. |
operator+() Quaternion
Adds two quaternions component-wise.
Quaternion operator+(const Quaternion& a, const Quaternion& b);| Parameter | Description |
|---|---|
| a | First quaternion. |
| b | Second quaternion. |
operator-() Quaternion
Subtracts one quaternion from another component-wise.
Quaternion operator-(const Quaternion& a, const Quaternion& b);| Parameter | Description |
|---|---|
| a | First quaternion. |
| b | Second quaternion. |
operator-() Quaternion
Negates a quaternion.
The result represents the same rotation as the input.
Quaternion operator-(const Quaternion& q);| Parameter | Description |
|---|---|
| q | Input quaternion. |
Slerp() Quaternion
Spherically interpolates between two quaternions.
Interpolates along the shortest arc and falls back to normalized linear interpolation when the inputs are nearly parallel.
Quaternion Slerp(const Quaternion& a, const Quaternion& b, float f);| Parameter | Description |
|---|---|
| a | Start rotation. |
| b | End rotation. |
| f | Interpolation factor in . |