quaternions — cglm 0.9.6 documentation

# 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 quaternion

- You can rotate vector using quaternion

- You can create view matrix using quaternion

- You can create a lookrotation (from source point to dest)

## Table of contents (click to go):

Macros:

1. GLM_QUAT_IDENTITY_INIT

2. GLM_QUAT_IDENTITY

Functions:

1. `glm_quat_identity()`

2. `glm_quat_identity_array()`

3. `glm_quat_init()`

4. `glm_quat()`

5. `glm_quatv()`

6. `glm_quat_copy()`

7. `glm_quat_from_vecs()`

8. `glm_quat_norm()`

9. `glm_quat_normalize()`

10. `glm_quat_normalize_to()`

11. `glm_quat_dot()`

12. `glm_quat_conjugate()`

13. `glm_quat_inv()`

14. `glm_quat_add()`

15. `glm_quat_sub()`

16. `glm_quat_real()`

17. `glm_quat_imag()`

18. `glm_quat_imagn()`

19. `glm_quat_imaglen()`

20. `glm_quat_angle()`

21. `glm_quat_axis()`

22. `glm_quat_mul()`

23. `glm_quat_mat4()`

24. `glm_quat_mat4t()`

25. `glm_quat_mat3()`

26. `glm_quat_mat3t()`

27. `glm_quat_lerp()`

28. `glm_quat_nlerp()`

29. `glm_quat_slerp()`

30. `glm_quat_slerp_longest()`

31. `glm_quat_look()`

32. `glm_quat_for()`

33. `glm_quat_forp()`

34. `glm_quat_rotatev()`

35. `glm_quat_rotate()`

36. `glm_quat_rotate_at()`

37. `glm_quat_rotate_atm()`

38. `glm_quat_make()`

## 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

void glm_quat_from_vecs(vec3 a, vec3 b, versor dest)
  compute unit quaternion needed to rotate a into b
  References:

    - Finding quaternion representing the rotation from one vector to another

    - Quaternion from two vectors

    - Angle between vectors

  Parameters:
    [in] a unit vector
    [in] b unit vector
    [in] dest unit 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_nlerp(versor q, versor r, float t, versor dest)
  interpolates between two quaternions
  taking the shortest rotation path using
  normalized linear interpolation (NLERP)
  This is a cheaper alternative to slerp; most games use nlerp
  for animations as it visually makes little difference.
  References:

    - Understanding Slerp, Then Not Using it

    - Lerp, Slerp and Nlerp

  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_slerp_longest(versor q, versor r, float t, versor dest)
  interpolates between two quaternions
  using spherical linear interpolation (SLERP) and always takes the longest path
  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 up, versor dest)
  creates look rotation quaternion
  Parameters:
    [in] dir direction to look
    [in] up up vector
    [out] dest result matrix

void glm_quat_forp(vec3 from, vec3 to, 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] 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_atm(mat4 m, versor q, vec3 pivot)
  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

void glm_quat_make(const float *__restrict src, versor dest)

  Create quaternion from pointer

  Note

  @src must contain at least 4 elements. cglm store quaternions as [x, y, z, w].

  Parameters:
    [in] src pointer to an array of floats
    [out] dest destination quaternion