shz_quat.h File Reference

#include "shz_vector.h"
#include "shz_mem.h"
#include "inline/shz_quat.inl.h"

Include dependency graph for shz_quat.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	shz_quat_t

Typedefs
typedef shz_quat_t	shz_quat

Functions
Initialization
Routines for creating and initializing quaternions.
shz_quat_t	shz_quat_init (float w, float x, float y, float z) noexcept
shz_quat_t	shz_quat_identity (void) noexcept
bool	shz_quat_equal (shz_quat_t a, shz_quat_t b) noexcept
shz_quat_t	shz_quat_from_angles_xyz (float xangle, float yangle, float zangle) noexcept
shz_quat_t	shz_quat_from_axis_angle (shz_vec3_t axis, float angle) noexcept
shz_quat_t	shz_quat_from_look_axis (shz_vec3_t forward, shz_vec3_t up) noexcept
shz_quat_t	shz_quat_from_rotated_axis (shz_vec3_t v1, shz_vec3_t v2) noexcept
shz_quat_t	shz_quat_lerp (shz_quat_t a, shz_quat_t b, float t) noexcept
shz_quat_t	shz_quat_nlerp (shz_quat_t a, shz_quat_t b, float t) noexcept
shz_quat_t	shz_quat_slerp (shz_quat_t q, shz_quat_t p, float t) noexcept
shz_quat_t	shz_quat_squad (shz_quat_t q1, shz_quat_t q2, shz_quat_t s1, shz_quat_t s2, float t) noexcept
Properties
Routines returning derived values from a quaternion.
float	shz_quat_angle (shz_quat_t q) noexcept
shz_vec3_t	shz_quat_axis (shz_quat_t q) noexcept
float	shz_quat_angle_x (shz_quat_t q) noexcept
float	shz_quat_angle_y (shz_quat_t q) noexcept
float	shz_quat_angle_z (shz_quat_t q) noexcept
void	shz_quat_to_axis_angle (shz_quat_t q, shz_vec3_t *vec, float *angle) noexcept
shz_vec3_t	shz_quat_to_angles_xyz (shz_quat_t q) noexcept
float	shz_quat_magnitude_sqr (shz_quat_t quat) noexcept
float	shz_quat_magnitude (shz_quat_t quat) noexcept
float	shz_quat_magnitude_inv (shz_quat_t quat) noexcept
Modifiers
Routines for returning new quaternions derived from existing ones.
shz_quat_t	shz_quat_normalize (shz_quat_t quat) noexcept
shz_quat_t	shz_quat_normalize_safe (shz_quat_t quat) noexcept
shz_quat_t	shz_quat_conjugate (shz_quat_t quat) noexcept
shz_quat_t	shz_quat_inv (shz_quat_t quat) noexcept
shz_quat_t	shz_quat_neg (shz_quat_t quat) noexcept
Arithmetic
Routines performing calculations with quaternions.
shz_quat_t	shz_quat_add (shz_quat_t q, shz_quat_t p) noexcept
shz_quat_t	shz_quat_sub (shz_quat_t q, shz_quat_t p) noexcept
shz_quat_t	shz_quat_scale (shz_quat_t q, float f) noexcept
shz_quat_t	shz_quat_mult (shz_quat_t q1, shz_quat_t q2) noexcept
shz_quat_t	shz_quat_div (shz_quat_t q, shz_quat_t p) noexcept
float	shz_quat_dot (shz_quat_t q1, shz_quat_t q2) noexcept
shz_vec2_t	shz_quat_dot2 (shz_quat_t l, shz_quat_t r1, shz_quat_t r2) noexcept
shz_vec3_t	shz_quat_dot3 (shz_quat_t l, shz_quat_t r1, shz_quat_t r2, shz_quat_t r3) noexcept
Miscellaneous
Other types of quaternion operations.
float	shz_quat_angle_between (shz_quat_t q, shz_quat_t p) noexcept
shz_quat_t	shz_quat_rotate_towards (shz_quat_t from, shz_quat_t to, float max_angle) noexcept
Transformations
Routines for applying quaternion transforms.
shz_vec3_t	shz_quat_transform_vec3 (shz_quat_t q, shz_vec3_t v) noexcept

Detailed Description

Routines for operating upon quaternions.

This file contains the public type(s) and interface providing the quaternion math API.

Author

2025, 2026 Falco Girgis

2025 Oleg Endo

Copyright

MIT License

Definition in file shz_quat.h.

Typedef Documentation

shz_quat

typedef shz_quat_t shz_quat

Alternate shz_quat_t C typedef for those who hate POSIX style.

Definition at line 49 of file shz_quat.h.

Function Documentation

shz_quat_init()

shz_quat_t shz_quat_init ( float w, float x, float y, float z )

noexcept

Initializes and returns a new quaternion with the given components, in WXYZ order.

shz_quat_identity()

shz_quat_t shz_quat_identity ( void )

noexcept

Initializes and returns an identity quaternion.

shz_quat_equal()

bool shz_quat_equal ( shz_quat_t a, shz_quat_t b )

noexcept

Returns true if the two given quaternions are considered equal based on either absolute or relative tolerance.

shz_quat_from_angles_xyz()

shz_quat_t shz_quat_from_angles_xyz ( float xangle, float yangle, float zangle )

noexcept

Initializes and returns a quaternion with the given X-Y-Z rotations in radians.

The rotation is applied first around the X-axis, then the Y-, then the Z-axis.

Note

These angles are Tait-Bryan angles representing an intrinsic rotation.

shz_quat_from_axis_angle()

shz_quat_t shz_quat_from_axis_angle ( shz_vec3_t axis, float angle )

noexcept

Initializes and returns a quaternion representing a rotation of angle radians about the given axis.

shz_quat_from_look_axis()

shz_quat_t shz_quat_from_look_axis ( shz_vec3_t forward, shz_vec3_t up )

noexcept

Creates a quaternion looking in the given direction with the given reference direction.

shz_quat_from_rotated_axis()

shz_quat_t shz_quat_from_rotated_axis ( shz_vec3_t v1, shz_vec3_t v2 )

noexcept

Returns the quaternion representing the rotation from axis v1 to v2.

shz_quat_lerp()

shz_quat_t shz_quat_lerp ( shz_quat_t a, shz_quat_t b, float t )

noexcept

Returns the quaternion that is linearly interpolating a to b, by a t factor of 0.0f-1.0f.

shz_quat_nlerp()

shz_quat_t shz_quat_nlerp ( shz_quat_t a, shz_quat_t b, float t )

noexcept

Equivalent to shz_quat_lerp(), except that the resulting quaternion is normalized.

shz_quat_slerp()

shz_quat_t shz_quat_slerp ( shz_quat_t q, shz_quat_t p, float t )

noexcept

Returns the quaternion that is spherically linearly interpolating a to b, by a t factor of 0.0f-1.0f.

shz_quat_squad()

shz_quat_t shz_quat_squad ( shz_quat_t q1, shz_quat_t q2, shz_quat_t s1, shz_quat_t s2, float t )

noexcept

Evaluates a smooth cubic spherical interpolation (SQUAD) at parameter t.

Note

SQUAD(q1, q2, s1, s2, t) = slerp(slerp(q1, q2, t), slerp(s1, s2, t), 2t(1-t))

Parameters

q1	Start quaternion.
q2	End quaternion.
s1	Inner control point for q1 (typically computed from surrounding keyframes).
s2	Inner control point for q2 (typically computed from surrounding keyframes).
t	Interpolation factor in [0, 1].

Returns

Resulting interpolated quaternion

shz_quat_angle()

float shz_quat_angle ( shz_quat_t q )

noexcept

Returns the angle of rotation from the given quaternion.

shz_quat_axis()

shz_vec3_t shz_quat_axis ( shz_quat_t q )

noexcept

Returns the axis of rotation from the given quaternion.

shz_quat_angle_x()

float shz_quat_angle_x ( shz_quat_t q )

noexcept

Returns the angle of rotation the quaternion represents about the X axis in radians.

shz_quat_angle_y()

float shz_quat_angle_y ( shz_quat_t q )

noexcept

Returns the angle of rotation the quaternion represents about the Y axis in radians.

shz_quat_angle_z()

float shz_quat_angle_z ( shz_quat_t q )

noexcept

Returns the angle of rotation the quaternion represents about the Z axis in radians.

shz_quat_to_axis_angle()

void shz_quat_to_axis_angle ( shz_quat_t q, shz_vec3_t * vec, float * angle )

noexcept

Returns both the axis and angle of rotation simultaneously (faster if both are needed) from the given quaternion.

shz_quat_to_angles_xyz()

shz_vec3_t shz_quat_to_angles_xyz ( shz_quat_t q )

noexcept

Returns the roll, pitch, and yaw angles of rotation represented by the given quaternion.

shz_quat_magnitude_sqr()

float shz_quat_magnitude_sqr ( shz_quat_t quat )

noexcept

Returns the squared magnitude of the given quaternion.

shz_quat_magnitude()

float shz_quat_magnitude ( shz_quat_t quat )

noexcept

Returns the magnitude of the given quaternion.

shz_quat_magnitude_inv()

float shz_quat_magnitude_inv ( shz_quat_t quat )

noexcept

Returns the inverse magnitude of the given quaternion.

shz_quat_normalize()

shz_quat_t shz_quat_normalize ( shz_quat_t quat )

noexcept

Returns the normalized form of the given quaternion.

shz_quat_normalize_safe()

shz_quat_t shz_quat_normalize_safe ( shz_quat_t quat )

noexcept

SAFELY returns the normalized form of the given quaternion.

Returns the identity quaternion when magnitude is 0.0f.

shz_quat_conjugate()

shz_quat_t shz_quat_conjugate ( shz_quat_t quat )

noexcept

Returns the conjugate of the given quaternion.

shz_quat_inv()

shz_quat_t shz_quat_inv ( shz_quat_t quat )

noexcept

Returns the inverse of the given quaternion.

shz_quat_neg()

shz_quat_t shz_quat_neg ( shz_quat_t quat )

noexcept

Returns the negation of the given quaternion.

shz_quat_add()

shz_quat_t shz_quat_add ( shz_quat_t q, shz_quat_t p )

noexcept

Returns the quaternion produced from adding each component of the given quaternions.

shz_quat_sub()

shz_quat_t shz_quat_sub ( shz_quat_t q, shz_quat_t p )

noexcept

Returns the quaternion produced from subtracting each component of quaternion p from quaterion q.

shz_quat_scale()

shz_quat_t shz_quat_scale ( shz_quat_t q, float f )

noexcept

Scales the components of the given quaternion by the given factor.

shz_quat_mult()

shz_quat_t shz_quat_mult ( shz_quat_t q1, shz_quat_t q2 )

noexcept

Multiplies the two quaternions, returning the result as a new quaternion.

shz_quat_div()

shz_quat_t shz_quat_div ( shz_quat_t q, shz_quat_t p )

noexcept

Divides quaternion p by quaternion q (multiplying by its inverse), returning the resulting quaternion.

shz_quat_dot()

float shz_quat_dot ( shz_quat_t q1, shz_quat_t q2 )

noexcept

Returns the dot product of the two quaternions.

shz_quat_dot2()

shz_vec2_t shz_quat_dot2 ( shz_quat_t l, shz_quat_t r1, shz_quat_t r2 )

noexcept

Returns the two dot products taken between the l quaternion and the r1 and r2 quaternions.

shz_quat_dot3()

shz_vec3_t shz_quat_dot3 ( shz_quat_t l, shz_quat_t r1, shz_quat_t r2, shz_quat_t r3 )

noexcept

Returns the two dot products taken between the l quaternion and the r1, r2, and r3 quaternions.

shz_quat_angle_between()

float shz_quat_angle_between ( shz_quat_t q, shz_quat_t p )

noexcept

Returns the angle in radians between the rotations represented by quaternions q and p.

shz_quat_rotate_towards()

shz_quat_t shz_quat_rotate_towards ( shz_quat_t from, shz_quat_t to, float max_angle )

noexcept

Rotates quaternion from towards quaternion to by at most max_angle radians.

Note

Returns to if the angle between them is already less than max_angle.

shz_quat_transform_vec3()

shz_vec3_t shz_quat_transform_vec3 ( shz_quat_t q, shz_vec3_t v )

noexcept

Rotates a vector by the given quaternion.

Note

This routine is meant for one-off rotations of a single vector by a single quaternion. If you plan to rotate multiple vectors by the same quaternion, you should use the XMTRX API to apply the quaternion as a rotation matrix.

See also

shz_xmtrx_apply_rotation_quat()