quat.h file

Rotation quaternions (value and _ptr).

Unsuffixed angles are radians.

Functions

auto quat_identity(void) -> quaternion: Constructs the identity quaternion.
auto quat_mul(quaternion a, quaternion b) -> quaternion: Multiplies two quaternions (a * b).
auto quat_normalize(quaternion q) -> quaternion: Normalizes a quaternion.
auto quat_conjugate(quaternion q) -> quaternion: Returns the conjugate of a quaternion.
auto quat_inverse(quaternion q) -> quaternion: Returns the inverse of a quaternion.
auto quat_from_euler(vector3 euler) -> quaternion: Constructs a quaternion from Euler angles.
auto quat_from_euler_deg(vector3 euler_deg) -> quaternion: Constructs a quaternion from Euler angles in degrees.
auto quat_from_axis_angle(vector3 axis, vm_float_t radians) -> quaternion: Constructs a quaternion from a rotation axis and angle.
auto quat_from_axis_angle_deg(vector3 axis, vm_float_t degrees) -> quaternion: Constructs a quaternion from an axis and an angle in degrees.
auto quat_from_mat3(matrix3 m) -> quaternion: Builds a quaternion from a 3x3 rotation matrix.
auto quat_from_mat4(matrix4 m) -> quaternion: Builds a quaternion from the rotation of a 4x4 matrix.
auto quat_look(vector3 direction, vector3 up) -> quaternion: Constructs a quaternion that rotates from the negative Z axis towards the given direction, with the specified up vector.
auto quat_look_clip(vector3 direction, vector3 up, vm_clip_t clip) -> quaternion: Constructs a quaternion representing a look-at rotation with specified clip space.
auto quat_from_to(vector3 from, vector3 to) -> quaternion: Constructs a quaternion representing the shortest rotation from one vector to another.
auto quat_slerp(quaternion a, quaternion b, vm_float_t t) -> quaternion: Spherical-linearly interpolates from a to b by t.
auto quat_nlerp(quaternion a, quaternion b, vm_float_t t) -> quaternion: Normalized-linearly interpolates from a to b by t.
auto quat_integrate(quaternion q, vector3 omega, vm_float_t dt) -> quaternion: Integrates a quaternion using angular velocity.
auto quat_rotate_vec3(quaternion q, vector3 v) -> vector3: Rotates a vector3 by a quaternion.
auto quat_to_euler(quaternion q) -> vector3: Converts a quaternion to Euler angles in degrees (XYZ).
auto quat_to_euler_deg(quaternion q) -> vector3: Converts a quaternion to Euler angles in degrees.
auto quat_to_axis_angle(quaternion q, vm_float_t* radians) -> vector3: Converts a quaternion to axis-angle representation.
auto quat_to_axis_angle_deg(quaternion q, vm_float_t* degrees) -> vector3: Converts a quaternion to axis-angle representation in degrees.
auto quat_to_mat4(quaternion q) -> matrix4: Converts a quaternion to a 4x4 rotation matrix.
auto quat_to_mat3(quaternion q) -> matrix3: Converts a quaternion to a 3x3 rotation matrix.
auto quat_dot(quaternion a, quaternion b) -> vm_float_t: Returns the dot product of two quaternions.
auto quat_near(quaternion a, quaternion b, vm_float_t eps) -> bool: Returns true if a and b are within eps of each other.
void quat_identity_ptr(quaternion* res)
void quat_mul_ptr(quaternion* res, const quaternion* a, const quaternion* b): Hamilton product a * b (dispatched).
void quat_normalize_ptr(quaternion* res, const quaternion* q): Normalizes a quaternion (dispatched).
void quat_conjugate_ptr(quaternion* res, const quaternion* q): Writes the conjugate of a quaternion.
void quat_inverse_ptr(quaternion* res, const quaternion* q): Writes the inverse of a quaternion.
void quat_from_euler_ptr(quaternion* res, const vector3* euler): Converts Euler angles (in radians) to a normalized quaternion.
void quat_from_euler_deg_ptr(quaternion* res, const vector3* euler_deg): Converts Euler angles in degrees to a quaternion.
void quat_from_axis_angle_ptr(quaternion* res, const vector3* axis, vm_float_t radians): Converts an axis-angle rotation to a quaternion.
void quat_from_axis_angle_deg_ptr(quaternion* res, const vector3* axis, vm_float_t degrees): Converts an axis-angle rotation (in degrees) to a quaternion.
void quat_from_mat3_ptr(quaternion* res, const matrix3* m): Builds a quaternion from a 3x3 rotation matrix.
void quat_from_mat4_ptr(quaternion* res, const matrix4* m): Builds a quaternion from the rotation of a 4x4 matrix.
void quat_look_ptr(quaternion* res, const vector3* direction, const vector3* up): Orientation that aims local -Z along direction (RH / FPS camera).
void quat_look_clip_ptr(quaternion* res, const vector3* direction, const vector3* up, vm_clip_t clip): Orientation that aims along direction.
void quat_from_to_ptr(quaternion* res, const vector3* from, const vector3* to): Shortest rotation taking from onto to.
void quat_slerp_ptr(quaternion* res, const quaternion* a, const quaternion* b, vm_float_t t): Spherical-linearly interpolates from a to b by t.
void quat_nlerp_ptr(quaternion* res, const quaternion* a, const quaternion* b, vm_float_t t): Normalized-linearly interpolates from a to b by t.
void quat_rotate_vec3_ptr(vector3* res, const quaternion* q, const vector3* v): Rotates a vector3 by a quaternion.
void quat_to_euler_ptr(vector3* res, const quaternion* q): Converts a quaternion to Euler angles in degrees (XYZ).
void quat_to_euler_deg_ptr(vector3* res, const quaternion* q): Converts a quaternion to XYZ Euler angles in degrees.
void quat_to_axis_angle_ptr(vector3* axis, vm_float_t* radians, const quaternion* q): Converts a quaternion to an axis-angle representation.
void quat_to_axis_angle_deg_ptr(vector3* axis, vm_float_t* degrees, const quaternion* q): Converts a quaternion to an axis-angle representation, with the angle in degrees.
void quat_to_mat4_ptr(matrix4* res, const quaternion* q): Converts a unit quaternion to a 4x4 rotation matrix and stores in res.
void quat_to_mat3_ptr(matrix3* res, const quaternion* q): Converts a quaternion to a 3x3 rotation matrix.
void quat_integrate_ptr(quaternion* res, const quaternion* q, const vector3* omega, vm_float_t dt): Integrates angular velocity over a time step and applies the resulting rotation to the input quaternion.
auto quat_eq(quaternion a, quaternion b) -> bool: Returns true if two quaternions are equal within VECMAT_EPSILON.

Scalar-query pointer adapters

Header-only _ptr forms for functions that return a scalar or bool.

The by-value function is the body. Pointers must not be NULL. These are not SIMD kernels and are not exported from the library.

static auto quat_dot_ptr(const quaternion* a, const quaternion* b) -> vm_float_t: Pointer adapter for quat_dot().
static auto quat_near_ptr(const quaternion* a, const quaternion* b, vm_float_t eps) -> bool: Pointer adapter for quat_near().
static auto quat_eq_ptr(const quaternion* a, const quaternion* b) -> bool: Pointer adapter for quat_eq().

Function documentation

quaternion quat_identity(void)

Constructs the identity quaternion.

Returns	The identity quaternion.

quaternion quat_mul(quaternion a, quaternion b)

Multiplies two quaternions (a * b).

Parameters
a	The first quaternion.
b	The second quaternion.
Returns	The resulting product quaternion.

quaternion quat_normalize(quaternion q)

Normalizes a quaternion.

Parameters
q	The input quaternion.
Returns	The normalized quaternion.

quaternion quat_conjugate(quaternion q)

Returns the conjugate of a quaternion.

Parameters
q	Input quaternion.
Returns	The resulting quaternion.

quaternion quat_inverse(quaternion q)

Returns the inverse of a quaternion.

Parameters
q	Input quaternion.
Returns	The resulting quaternion.

quaternion quat_from_euler(vector3 euler)

Constructs a quaternion from Euler angles.

Parameters
euler	Euler angles in radians.
Returns	The resulting quaternion.

quaternion quat_from_euler_deg(vector3 euler_deg)

Constructs a quaternion from Euler angles in degrees.

Parameters
euler_deg	Euler angles in degrees.
Returns	The resulting quaternion.

quaternion quat_from_axis_angle(vector3 axis, vm_float_t radians)

Constructs a quaternion from a rotation axis and angle.

Parameters
axis	The rotation axis. Must be normalized.
radians	The rotation angle in radians.
Returns	The resulting rotation quaternion.

quaternion quat_from_axis_angle_deg(vector3 axis, vm_float_t degrees)

Constructs a quaternion from an axis and an angle in degrees.

Parameters
axis	The rotation axis.
degrees	The rotation angle in degrees.
Returns	The resulting quaternion.

quaternion quat_from_mat3(matrix3 m)

Builds a quaternion from a 3x3 rotation matrix.

Parameters
m	Input matrix.
Returns	The resulting quaternion.

quaternion quat_from_mat4(matrix4 m)

Builds a quaternion from the rotation of a 4x4 matrix.

Parameters
m	Input matrix.
Returns	The resulting quaternion.

quaternion quat_look(vector3 direction, vector3 up)

Constructs a quaternion that rotates from the negative Z axis towards the given direction, with the specified up vector.

Parameters
direction	The target direction vector to look towards.
up	The up vector.
Returns	The look rotation quaternion.

quaternion quat_look_clip(vector3 direction, vector3 up, vm_clip_t clip)

Constructs a quaternion representing a look-at rotation with specified clip space.

Parameters
direction	The forward direction vector.
up	The up direction vector.
clip	The clip space convention.
Returns	The look-at quaternion.

quaternion quat_from_to(vector3 from, vector3 to)

Constructs a quaternion representing the shortest rotation from one vector to another.

Parameters
from	The source direction vector.
to	The target direction vector.
Returns	Quaternion that rotates `from` into `to`.

quaternion quat_slerp(quaternion a, quaternion b, vm_float_t t)

Spherical-linearly interpolates from a to b by t.

Parameters
a	First input quaternion.
b	Second input quaternion.
t	Interpolation factor.
Returns	The resulting quaternion.

quaternion quat_nlerp(quaternion a, quaternion b, vm_float_t t)

Normalized-linearly interpolates from a to b by t.

Parameters
a	First input quaternion.
b	Second input quaternion.
t	Interpolation factor.
Returns	The resulting quaternion.

quaternion quat_integrate(quaternion q, vector3 omega, vm_float_t dt)

Integrates a quaternion using angular velocity.

Parameters
q	The starting quaternion.
omega	Angular velocity vector.
dt	Time delta.
Returns	The integrated quaternion.

vector3 quat_rotate_vec3(quaternion q, vector3 v)

Rotates a vector3 by a quaternion.

Parameters
q	Input quaternion.
v	Input vector.
Returns	The resulting vector3.

vector3 quat_to_euler(quaternion q)

Converts a quaternion to Euler angles in degrees (XYZ).

Parameters
q	Input quaternion.
Returns	The resulting vector3.

vector3 quat_to_euler_deg(quaternion q)

Converts a quaternion to Euler angles in degrees.

Parameters
q	The quaternion to convert.
Returns	The Euler angles in degrees as a vector3.

vector3 quat_to_axis_angle(quaternion q, vm_float_t* radians)

Converts a quaternion to axis-angle representation.

Parameters
q	The input quaternion.
radians	Pointer to a float that receives the rotation angle in radians.
Returns	The rotation axis vector.

vector3 quat_to_axis_angle_deg(quaternion q, vm_float_t* degrees)

Converts a quaternion to axis-angle representation in degrees.

Parameters
q	Input quaternion.
degrees	Pointer to a float that receives the rotation angle in degrees.
Returns	The rotation axis vector.

matrix4 quat_to_mat4(quaternion q)

Converts a quaternion to a 4x4 rotation matrix.

Parameters
q	The input quaternion.
Returns	The equivalent matrix4.

matrix3 quat_to_mat3(quaternion q)

Converts a quaternion to a 3x3 rotation matrix.

Parameters
q	Input quaternion.
Returns	The resulting matrix3.

vm_float_t quat_dot(quaternion a, quaternion b)

Returns the dot product of two quaternions.

Parameters
a	First input quaternion.
b	Second input quaternion.
Returns	The resulting vm_float_t.

bool quat_near(quaternion a, quaternion b, vm_float_t eps)

Returns true if a and b are within eps of each other.

Parameters
a	First input quaternion.
b	Second input quaternion.
eps	Distance tolerance.
Returns	True if a and b are within eps.

void quat_mul_ptr(quaternion* res, const quaternion* a, const quaternion* b)

Hamilton product a * b (dispatched).

Parameters
res	Result quaternion.
a	Left quaternion.
b	Right quaternion.

void quat_normalize_ptr(quaternion* res, const quaternion* q)

Normalizes a quaternion (dispatched).

Parameters
res	Result quaternion.
q	Input quaternion.

void quat_conjugate_ptr(quaternion* res, const quaternion* q)

Writes the conjugate of a quaternion.

Parameters
res	Output value.
q	Input quaternion.

void quat_inverse_ptr(quaternion* res, const quaternion* q)

Writes the inverse of a quaternion.

Parameters
res	Output value.
q	Input quaternion.

void quat_from_euler_ptr(quaternion* res, const vector3* euler)

Converts Euler angles (in radians) to a normalized quaternion.

Parameters
res	Pointer to the quaternion that will receive the result.
euler	Pointer to a vector3 containing the Euler angles in radians (x, y, z).

Computes a quaternion from the given Euler rotation vector using the XYZ (Tait-Bryan) convention. The resulting quaternion is guaranteed to be normalized.

void quat_from_euler_deg_ptr(quaternion* res, const vector3* euler_deg)

Converts Euler angles in degrees to a quaternion.

Parameters
res	Pointer to the quaternion to store the result.
euler_deg	Pointer to the vector containing Euler angles in degrees.

void quat_from_axis_angle_ptr(quaternion* res, const vector3* axis, vm_float_t radians)

Converts an axis-angle rotation to a quaternion.

Parameters
res	Pointer to the quaternion that will receive the result.
axis	Pointer to the rotation axis vector.
radians	Rotation angle around the axis in radians.

The axis vector is normalized internally. The angle is given in radians.

void quat_from_axis_angle_deg_ptr(quaternion* res, const vector3* axis, vm_float_t degrees)

Converts an axis-angle rotation (in degrees) to a quaternion.

Parameters
res	Pointer to the quaternion that will receive the result.
axis	Pointer to the rotation axis vector.
degrees	Rotation angle around the axis in degrees.

void quat_from_mat3_ptr(quaternion* res, const matrix3* m)

Builds a quaternion from a 3x3 rotation matrix.

Parameters
res	Output value.
m	Input matrix.

void quat_from_mat4_ptr(quaternion* res, const matrix4* m)

Builds a quaternion from the rotation of a 4x4 matrix.

Parameters
res	Output value.
m	Input matrix.

void quat_look_ptr(quaternion* res, const vector3* direction, const vector3* up)

Orientation that aims local -Z along direction (RH / FPS camera).

Parameters
res	Result quaternion.
direction	Look direction.
up	World up hint.

Matches the rotation part of mat4_look_from_dir inverted (view-to-world).

void quat_look_clip_ptr(quaternion* res, const vector3* direction, const vector3* up, vm_clip_t clip)

Orientation that aims along direction.

Parameters
res	Result quaternion.
direction	Look direction.
up	World up hint.
clip	Clip-space convention selecting handedness.

RH: local -Z maps to direction. LH: local +Z maps to direction.

void quat_from_to_ptr(quaternion* res, const vector3* from, const vector3* to)

Shortest rotation taking from onto to.

Parameters
res	Result quaternion.
from	Source direction.
to	Target direction.

Opposite vectors pick a stable orthogonal axis (180 deg). Near-parallel vectors return identity.

void quat_slerp_ptr(quaternion* res, const quaternion* a, const quaternion* b, vm_float_t t)

Spherical-linearly interpolates from a to b by t.

Parameters
res	Output value.
a	First input quaternion.
b	Second input quaternion.
t	Interpolation factor.

void quat_nlerp_ptr(quaternion* res, const quaternion* a, const quaternion* b, vm_float_t t)

Normalized-linearly interpolates from a to b by t.

Parameters
res	Output value.
a	First input quaternion.
b	Second input quaternion.
t	Interpolation factor.

void quat_rotate_vec3_ptr(vector3* res, const quaternion* q, const vector3* v)

Rotates a vector3 by a quaternion.

Parameters
res	Output value.
q	Input quaternion.
v	Input vector.

void quat_to_euler_ptr(vector3* res, const quaternion* q)

Converts a quaternion to Euler angles in degrees (XYZ).

Parameters
res	Output value.
q	Input quaternion.

void quat_to_euler_deg_ptr(vector3* res, const quaternion* q)

Converts a quaternion to XYZ Euler angles in degrees.

Parameters
res	Euler angles in degrees (x, y, z).
q	Input quaternion.

void quat_to_axis_angle_ptr(vector3* axis, vm_float_t* radians, const quaternion* q)

Converts a quaternion to an axis-angle representation.

Parameters
axis	Pointer to the vector3 that will receive the rotation axis.
radians	Pointer to a float that will receive the rotation angle in radians, or NULL.
q	Pointer to the input quaternion.

The quaternion is first normalized. The axis is stored in the provided vector3 pointer. The rotation angle in radians is optionally written to the radians pointer if it is not NULL. When the axis cannot be uniquely determined (near zero rotation) the axis is set to (1, 0, 0).

void quat_to_axis_angle_deg_ptr(vector3* axis, vm_float_t* degrees, const quaternion* q)

Converts a quaternion to an axis-angle representation, with the angle in degrees.

Parameters
axis	Pointer to the vector3 that will receive the normalized rotation axis.
degrees	Pointer to a float that will receive the rotation angle in degrees (may be NULL).
q	Pointer to the source quaternion.

Extracts the rotation axis and rotation angle (in degrees) equivalent to the given quaternion. The quaternion is first normalized internally. If the quaternion represents no rotation, the axis is set to (1, 0, 0).

void quat_to_mat4_ptr(matrix4* res, const quaternion* q)

Converts a unit quaternion to a 4x4 rotation matrix and stores in res.

Parameters
res	Pointer to the output matrix4.
q	Pointer to the input quaternion (should be normalized).

Starts with the identity matrix and applies rotation components.

void quat_to_mat3_ptr(matrix3* res, const quaternion* q)

Converts a quaternion to a 3x3 rotation matrix.

Parameters
res	Output value.
q	Input quaternion.

void quat_integrate_ptr(quaternion* res, const quaternion* q, const vector3* omega, vm_float_t dt)

Integrates angular velocity over a time step and applies the resulting rotation to the input quaternion.

Parameters
res	Pointer to the quaternion where the integrated result is stored.
q	Pointer to the source quaternion.
omega	Pointer to the angular velocity vector (in radians per second).
dt	Time step (in seconds).

Computes a delta quaternion from the angular velocity and timestep, multiplies it with the source quaternion and normalizes the result.

bool quat_eq(quaternion a, quaternion b)

Returns true if two quaternions are equal within VECMAT_EPSILON.

Parameters
a	First quaternion.
b	Second quaternion.
Returns	True if a and b are approximately equal.

static vm_float_t quat_dot_ptr(const quaternion* a, const quaternion* b)

Pointer adapter for quat_dot().

Parameters
a	Must not be NULL.
b	Must not be NULL.
Returns	Same value as the by-value function.

Same result as the by-value function.

static bool quat_near_ptr(const quaternion* a, const quaternion* b, vm_float_t eps)

Pointer adapter for quat_near().

Parameters
a	Must not be NULL.
b	Must not be NULL.
eps	Passed through to quat_near().
Returns	Same value as the by-value function.

Same result as the by-value function.

static bool quat_eq_ptr(const quaternion* a, const quaternion* b)

Pointer adapter for quat_eq().

Parameters
a	Must not be NULL.
b	Must not be NULL.
Returns	Same value as the by-value function.

Same result as the by-value function.