camera — cglm 0.9.6 documentation

# camera

Header: cglm/cam.h

There are many convenient functions for camera. For instance `glm_look()` is just wrapper for `glm_lookat()`. Sometimes you only have direction instead of target, so that makes easy to build view matrix using direction. There is also `glm_look_anyup()` function which can help build view matrix without providing UP axis. It uses `glm_vec3_ortho()` to get a UP axis and builds view matrix.

You can also _default versions of ortho and perspective to build projection fast if you don’t care specific projection values.

_decomp means decompose; these function can help to decompose projection matrices.

Note

Be careful when working with high range (very small near, very large far) projection matrices. You may not get exact value you gave. float type cannot store very high precision so you will lose precision. Also your projection matrix will be inaccurate due to losing precision

## Table of contents (click to go):

Functions:

1. `glm_frustum()`

2. `glm_ortho()`

3. `glm_ortho_aabb()`

4. `glm_ortho_aabb_p()`

5. `glm_ortho_aabb_pz()`

6. `glm_ortho_default()`

7. `glm_ortho_default_s()`

8. `glm_perspective()`

9. `glm_persp_move_far()`

10. `glm_perspective_default()`

11. `glm_perspective_resize()`

12. `glm_lookat()`

13. `glm_look()`

14. `glm_look_anyup()`

15. `glm_persp_decomp()`

16. `glm_persp_decompv()`

17. `glm_persp_decomp_x()`

18. `glm_persp_decomp_y()`

19. `glm_persp_decomp_z()`

20. `glm_persp_decomp_far()`

21. `glm_persp_decomp_near()`

22. `glm_persp_fovy()`

23. `glm_persp_aspect()`

24. `glm_persp_sizes()`

## Functions documentation

void glm_frustum(float left, float right, float bottom, float top, float nearVal, float farVal, mat4 dest)
  set up perspective peprojection matrix
  Parameters:
    [in] left viewport.left
    [in] right viewport.right
    [in] bottom viewport.bottom
    [in] top viewport.top
    [in] nearVal near clipping plane
    [in] farVal far clipping plane
    [out] dest result matrix

void glm_ortho(float left, float right, float bottom, float top, float nearVal, float farVal, mat4 dest)
  set up orthographic projection matrix
  Parameters:
    [in] left viewport.left
    [in] right viewport.right
    [in] bottom viewport.bottom
    [in] top viewport.top
    [in] nearVal near clipping plane
    [in] farVal far clipping plane
    [out] dest result matrix

void glm_ortho_aabb(vec3 box[2], mat4 dest)
  set up orthographic projection matrix using bounding box
  bounding box (AABB) must be in view space
  Parameters:
    [in] box AABB
    [in] dest result matrix

void glm_ortho_aabb_p(vec3 box[2], float padding, mat4 dest)
  set up orthographic projection matrix using bounding box
  bounding box (AABB) must be in view space

  this version adds padding to box

  Parameters:
    [in] box AABB
    [in] padding padding
    [out] dest result matrix

void glm_ortho_aabb_pz(vec3 box[2], float padding, mat4 dest)
  set up orthographic projection matrix using bounding box
  bounding box (AABB) must be in view space

  this version adds Z padding to box

  Parameters:
    [in] box AABB
    [in] padding padding for near and far
    [out] dest result matrix
  Returns:

    square of norm / magnitude

void glm_ortho_default(float aspect, mat4 dest)
  set up unit orthographic projection matrix
  Parameters:
    [in] aspect aspect ration ( width / height )
    [out] dest result matrix

void glm_ortho_default_s(float aspect, float size, mat4 dest)
  set up orthographic projection matrix with given CUBE size
  Parameters:
    [in] aspect aspect ration ( width / height )
    [in] size cube size
    [out] dest result matrix

void glm_perspective(float fovy, float aspect, float nearVal, float farVal, mat4 dest)
  set up perspective projection matrix
  Parameters:
    [in] fovy field of view angle (in radians)
    [in] aspect aspect ratio ( width / height )
    [in] nearVal near clipping plane
    [in] farVal far clipping planes
    [out] dest result matrix

void glm_persp_move_far(mat4 proj, float deltaFar)
  extend perspective projection matrix’s far distance
  this function does not guarantee far >= near, be aware of that!
  Parameters:
    [in, out] proj projection matrix to extend
    [in] deltaFar distance from existing far (negative to shink)

void glm_perspective_default(float aspect, mat4 dest)

  > set up perspective projection matrix with default near/far and angle values

  Parameters:
    [in] aspect aspect aspect ratio ( width / height )
    [out] dest result matrix

void glm_perspective_resize(float aspect, mat4 proj)
  resize perspective matrix by aspect ratio ( width / height ) this makes very easy to resize proj matrix when window / viewport reized
  Parameters:
    [in] aspect aspect ratio ( width / height )
    [in, out] proj perspective projection matrix

void glm_lookat(vec3 eye, vec3 center, vec3 up, mat4 dest)
  set up view matrix

  Note

  The UP vector must not be parallel to the line of sight from the eye point to the reference point.

  Parameters:
    [in] eye eye vector
    [in] center center vector
    [in] up up vector
    [out] dest result matrix

void glm_look(vec3 eye, vec3 dir, vec3 up, mat4 dest)
  set up view matrix

  convenient wrapper for `glm_lookat()`: if you only have direction not target self then this might be useful. Because you need to get target from direction.

  Note

  The UP vector must not be parallel to the line of sight from the eye point to the reference point.

  Parameters:
    [in] eye eye vector
    [in] dir direction vector
    [in] up up vector
    [out] dest result matrix

void glm_look_anyup(vec3 eye, vec3 dir, mat4 dest)
  set up view matrix

  convenient wrapper for `glm_look()` if you only have direction and if you don’t care what UP vector is then this might be useful to create view matrix

  Parameters:
    [in] eye eye vector
    [in] dir direction vector
    [out] dest result matrix

void glm_persp_decomp(mat4 proj, float *nearVal, float *farVal, float *top, float *bottom, float *left, float *right)
  decomposes frustum values of perspective projection.
  Parameters:
    [in] eye perspective projection matrix
    [out] nearVal near
    [out] farVal far
    [out] top top
    [out] bottom bottom
    [out] left left
    [out] right right

void glm_persp_decompv(mat4 proj, float dest[6])
  decomposes frustum values of perspective projection.
  this makes easy to get all values at once
  Parameters:
    [in] proj perspective projection matrix
    [out] dest array

void glm_persp_decomp_x(mat4 proj, float *left, float *right)
  decomposes left and right values of perspective projection.
  x stands for x axis (left / right axis)
  Parameters:
    [in] proj perspective projection matrix
    [out] left left
    [out] right right

void glm_persp_decomp_y(mat4 proj, float *top, float *bottom)
  decomposes top and bottom values of perspective projection.
  y stands for y axis (top / bottom axis)
  Parameters:
    [in] proj perspective projection matrix
    [out] top top
    [out] bottom bottom

void glm_persp_decomp_z(mat4 proj, float *nearVal, float *farVal)
  decomposes near and far values of perspective projection.
  z stands for z axis (near / far axis)
  Parameters:
    [in] proj perspective projection matrix
    [out] nearVal near
    [out] farVal far

void glm_persp_decomp_far(mat4 proj, float *__restrict farVal)
  decomposes far value of perspective projection.
  Parameters:
    [in] proj perspective projection matrix
    [out] farVal far

void glm_persp_decomp_near(mat4 proj, float *__restrict nearVal)
  decomposes near value of perspective projection.
  Parameters:
    [in] proj perspective projection matrix
    [out] nearVal near

float glm_persp_fovy(mat4 proj)
  returns field of view angle along the Y-axis (in radians)

  if you need to degrees, use glm_deg to convert it or use this: fovy_deg = glm_deg(glm_persp_fovy(projMatrix))

  Parameters:
    [in] proj perspective projection matrix
  Returns:
    fovy in radians

float glm_persp_aspect(mat4 proj)
  returns aspect ratio of perspective projection
  Parameters:
    [in] proj perspective projection matrix

void glm_persp_sizes(mat4 proj, float fovy, vec4 dest)
  returns sizes of near and far planes of perspective projection
  Parameters:
    [in] proj perspective projection matrix
    [in] fovy fovy (see brief)
    [out] dest sizes order: [Wnear, Hnear, Wfar, Hfar]