quaternions

Header: cglm/quat.h

Important: cglm stores quaternion as [x, y, z, w] in memory since v0.4.0 it was [w, x, y, z] before v0.4.0 ( v0.3.5 and earlier ). w is real part.

What you can do with quaternions with existing functions is (Some of them):

  • You can rotate transform matrix using quaterion
  • You can rotate vector using quaterion
  • You can create view matrix using quaterion
  • You can create a lookrotation (from source point to dest)

Functions documentation

void glm_quat_identity(versor q)
makes given quat to identity
Parameters:
[in, out] q quaternion
void glm_quat_identity_array(versor * __restrict q, size_t count)
make given quaternion array’s each element identity quaternion
Parameters:
[in, out] q quat array (must be aligned (16) if alignment is not disabled)
[in] count count of quaternions
void glm_quat_init(versor q, float x, float y, float z, float w)
inits quaternion with given values
Parameters:
[out] q quaternion
[in] x imag.x
[in] y imag.y
[in] z imag.z
[in] w w (real part)
void glm_quat(versor q, float  angle, float  x, float  y, float  z)
creates NEW quaternion with individual axis components
given axis will be normalized
Parameters:
[out] q quaternion
[in] angle angle (radians)
[in] x axis.x
[in] y axis.y
[in] z axis.z
void glm_quatv(versor q, float  angle, vec3  axis)
creates NEW quaternion with axis vector
given axis will be normalized
Parameters:
[out] q quaternion
[in] angle angle (radians)
[in] axis axis (will be normalized)
void glm_quat_copy(versor q, versor dest)
copy quaternion to another one
Parameters:
[in] q source quaternion
[out] dest destination quaternion
float glm_quat_norm(versor q)
returns norm (magnitude) of quaternion
Parameters:
[in] a quaternion
Returns:
norm (magnitude)
void glm_quat_normalize_to(versor q, versor dest)
normalize quaternion and store result in dest, original one will not be normalized
Parameters:
[in] q quaternion to normalize into
[out] dest destination quaternion
void glm_quat_normalize(versor q)
normalize quaternion
Parameters:
[in, out] q quaternion
float glm_quat_dot(versor p, versor q)

dot product of two quaternion

Parameters:
[in] p quaternion 1
[in] q quaternion 2
Returns:
dot product
void glm_quat_conjugate(versor q, versor dest)

conjugate of quaternion

Parameters:
[in] q quaternion
[in] dest conjugate
void glm_quat_inv(versor q, versor dest)

inverse of non-zero quaternion

Parameters:
[in] q quaternion
[in] dest inverse quaternion
void glm_quat_add(versor p, versor q, versor dest)

add (componentwise) two quaternions and store result in dest

Parameters:
[in] p quaternion 1
[in] q quaternion 2
[in] dest result quaternion
void glm_quat_sub(versor p, versor q, versor dest)

subtract (componentwise) two quaternions and store result in dest

Parameters:
[in] p quaternion 1
[in] q quaternion 2
[in] dest result quaternion
float glm_quat_real(versor q)

returns real part of quaternion

Parameters:
[in] q quaternion
Returns:
real part (quat.w)
void glm_quat_imag(versor q, vec3 dest)

returns imaginary part of quaternion

Parameters:
[in] q quaternion
[out] dest imag
void glm_quat_imagn(versor q, vec3 dest)

returns normalized imaginary part of quaternion

Parameters:
[in] q quaternion
[out] dest imag
float glm_quat_imaglen(versor q)

returns length of imaginary part of quaternion

Parameters:
[in] q quaternion
Returns:
norm of imaginary part
float glm_quat_angle(versor q)

returns angle of quaternion

Parameters:
[in] q quaternion
Returns:
angles of quat (radians)
void glm_quat_axis(versor q, versor dest)

axis of quaternion

Parameters:
[in] p quaternion
[out] dest axis of quaternion
void glm_quat_mul(versor p, versor q, versor dest)
multiplies two quaternion and stores result in dest
this is also called Hamilton Product
According to WikiPedia:
The product of two rotation quaternions [clarification needed] will be equivalent to the rotation q followed by the rotation p
Parameters:
[in] p quaternion 1 (first rotation)
[in] q quaternion 2 (second rotation)
[out] dest result quaternion
void glm_quat_mat4(versor q, mat4 dest)
convert quaternion to mat4
Parameters:
[in] q quaternion
[out] dest result matrix
void glm_quat_mat4t(versor q, mat4 dest)
convert quaternion to mat4 (transposed). This is transposed version of glm_quat_mat4
Parameters:
[in] q quaternion
[out] dest result matrix
void glm_quat_mat3(versor q, mat3 dest)
convert quaternion to mat3
Parameters:
[in] q quaternion
[out] dest result matrix
void glm_quat_mat3t(versor q, mat3 dest)
convert quaternion to mat3 (transposed). This is transposed version of glm_quat_mat3
Parameters:
[in] q quaternion
[out] dest result matrix
void glm_quat_lerp(versor from, versor to, float t, versor dest)
interpolates between two quaternions
using spherical linear interpolation (LERP)
Parameters:
[in] from from
[in] to to
[in] t interpolant (amount) clamped between 0 and 1
[out] dest result quaternion
void glm_quat_slerp(versor q, versor r, float  t, versor dest)
interpolates between two quaternions
using spherical linear interpolation (SLERP)
Parameters:
[in] from from
[in] to to
[in] t interpolant (amount) clamped between 0 and 1
[out] dest result quaternion
void glm_quat_look(vec3 eye, versor ori, mat4 dest)
creates view matrix using quaternion as camera orientation
Parameters:
[in] eye eye
[in] ori orientation in world space as quaternion
[out] dest result matrix
void glm_quat_for(vec3 dir, vec3 fwd, vec3 up, versor dest)
creates look rotation quaternion
Parameters:
[in] dir direction to look
[in] fwd forward vector
[in] up up vector
[out] dest result matrix
void glm_quat_forp(vec3 from, vec3 to, vec3 fwd, vec3 up, versor dest)
creates look rotation quaternion using source and destination positions p suffix stands for position
this is similar to glm_quat_for except this computes direction for glm_quat_for for you.
Parameters:
[in] from source point
[in] to destination point
[in] fwd forward vector
[in] up up vector
[out] dest result matrix
void glm_quat_rotatev(versor q, vec3 v, vec3 dest)
crotate vector using using quaternion
Parameters:
[in] q quaternion
[in] v vector to rotate
[out] dest rotated vector
void glm_quat_rotate(mat4 m, versor q, mat4 dest)
rotate existing transform matrix using quaternion

instead of passing identity matrix, consider to use quat_mat4 functions

Parameters:
[in] m existing transform matrix to rotate
[in] q quaternion
[out] dest rotated matrix/transform
void glm_quat_rotate_at(mat4 m, versor q, vec3 pivot)
rotate existing transform matrix using quaternion at pivot point
Parameters:
[in, out] m existing transform matrix to rotate
[in] q quaternion
[in] pivot pivot
void glm_quat_rotate(mat4 m, versor q, mat4 dest)
rotate NEW transform matrix using quaternion at pivot point
this creates rotation matrix, it assumes you don’t have a matrix
this should work faster than glm_quat_rotate_at because it reduces one glm_translate.
Parameters:
[in, out] m existing transform matrix to rotate
[in] q quaternion
[in] pivot pivot