diff --git a/docs/source/api.rst b/docs/source/api.rst index 2caa11e..94164b1 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -27,6 +27,7 @@ Follow the :doc:`build` documentation for this :caption: API categories: affine + cam mat4 mat3 vec3 diff --git a/docs/source/cam.rst b/docs/source/cam.rst new file mode 100644 index 0000000..2725334 --- /dev/null +++ b/docs/source/cam.rst @@ -0,0 +1,298 @@ +.. default-domain:: C + +Camera +====== + +Header: cglm/cam.h + +There are many convenient functions for camera. For instance :c:func:`glm_look` +is just wrapper for :c:func:`glm_lookat`. Sometimes you only have direction +instead of target, so that makes easy to build view matrix using direction. +There is also :c:func:`glm_look_anyup` function which can help build view matrix +without providing UP axis. It uses :c:func:`glm_vec_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 (clik func/macro to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions: + +1. :c:func:`glm_frustum` +#. :c:func:`glm_ortho` +#. :c:func:`glm_ortho_aabb` +#. :c:func:`glm_ortho_aabb_p` +#. :c:func:`glm_ortho_aabb_pz` +#. :c:func:`glm_ortho_default` +#. :c:func:`glm_ortho_default_s` +#. :c:func:`glm_perspective` +#. :c:func:`glm_perspective_default` +#. :c:func:`glm_perspective_resize` +#. :c:func:`glm_lookat` +#. :c:func:`glm_look` +#. :c:func:`glm_look_anyup` +#. :c:func:`glm_persp_decomp` +#. :c:func:`glm_persp_decompv` +#. :c:func:`glm_persp_decomp_x` +#. :c:func:`glm_persp_decomp_y` +#. :c:func:`glm_persp_decomp_z` +#. :c:func:`glm_persp_decomp_far` +#. :c:func:`glm_persp_decomp_near` +#. :c:func:`glm_persp_fovy` +#. :c:func:`glm_persp_aspect` +#. :c:func:`glm_persp_sizes` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: 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]* **d** result matrix + +.. c:function:: 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]* **d** result matrix + + Returns: + square of norm / magnitude + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: 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]* **aspect** aspect ratio ( width / height ) + | *[in]* **nearVal** near clipping plane + | *[in]* **farVal** far clipping planes + | *[out]* **dest** result matrix + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: void glm_lookat(vec3 eye, vec3 center, vec3 up, mat4 dest) + + | set up view matrix + + Parameters: + | *[in]* **eye** eye vector + | *[in]* **center** center vector + | *[in]* **up** up vector + | *[out]* **dest** result matrix + +.. c:function:: void glm_look(vec3 eye, vec3 dir, vec3 up, mat4 dest) + + | set up view matrix + + convenient wrapper for :c:func:`glm_lookat`: if you only have direction not + target self then this might be useful. Because you need to get target + from direction. + + Parameters: + | *[in]* **eye** eye vector + | *[in]* **center** direction vector + | *[in]* **up** up vector + | *[out]* **dest** result matrix + +.. c:function:: void glm_look_anyup(vec3 eye, vec3 dir, mat4 dest) + + | set up view matrix + + convenient wrapper for :c:func:`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]* **center** direction vector + | *[out]* **dest** result matrix + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: 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 / botom axis) + + Parameters: + | *[in]* **proj** perspective projection matrix + | *[out]* **top** top + | *[out]* **bottom** bottom + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: 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 + +.. c:function:: float glm_persp_aspect(mat4 proj) + + | returns aspect ratio of perspective projection + + Parameters: + | *[in]* **proj** perspective projection matrix + +.. c:function:: 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] diff --git a/include/cglm/cam.h b/include/cglm/cam.h index 9290ffa..acd573c 100644 --- a/include/cglm/cam.h +++ b/include/cglm/cam.h @@ -7,54 +7,53 @@ /* Functions: - CGLM_INLINE void glm_frustum(float left, - float right, - float bottom, - float top, - float nearVal, - float farVal, - mat4 dest); - CGLM_INLINE void glm_ortho(float left, - float right, - float bottom, - float top, - float nearVal, - float farVal, - mat4 dest); - CGLM_INLINE void glm_ortho_default(float aspect, mat4 dest); - CGLM_INLINE void glm_ortho_default_s(float aspect, float size, mat4 dest); - CGLM_INLINE void glm_perspective(float fovy, - float aspect, - float nearVal, - float farVal, - mat4 dest); - CGLM_INLINE void glm_perspective_default(float aspect, mat4 dest); - CGLM_INLINE void glm_perspective_resize(float aspect, mat4 proj); - CGLM_INLINE void glm_lookat(vec3 eye, vec3 center, vec3 up, mat4 dest); - CGLM_INLINE void glm_persp_decomp(mat4 proj, - float * __restrict nearVal, - float * __restrict farVal, - float * __restrict top, - float * __restrict bottom, - float * __restrict left, - float * __restrict right); - CGLM_INLINE void glm_persp_decompv(mat4 proj, float dest[6]); - CGLM_INLINE void glm_persp_decomp_x(mat4 proj, - float * __restrict left, - float * __restrict right); - CGLM_INLINE void glm_persp_decomp_y(mat4 proj, - float * __restrict top, - float * __restrict bottom); - CGLM_INLINE void glm_persp_decomp_z(mat4 proj, - float * __restrict nearVal, - float * __restrict farVal); - CGLM_INLINE void glm_persp_decomp_far(mat4 proj, float * __restrict farVal); - CGLM_INLINE void glm_persp_decomp_near(mat4 proj, float *__restrict nearVal); - CGLM_INLINE void glm_frustum_planes(mat4 m, vec4 dest[6]); - CGLM_INLINE void glm_frustum_corners(mat4 invMat, vec4 dest[8]); - CGLM_INLINE glm_ortho_box(vec3 box[2], mat4 dest); - CGLM_INLINE void glm_ortho_boxp(vec3 box[2], float padding, mat4 dest); - CGLM_INLINE void glm_ortho_boxp(vec3 box[2], float padding, mat4 dest); + CGLM_INLINE void glm_frustum(float left, + float right, + float bottom, + float top, + float nearVal, + float farVal, + mat4 dest) + CGLM_INLINE void glm_ortho(float left, + float right, + float bottom, + float top, + float nearVal, + float farVal, + mat4 dest) + CGLM_INLINE void glm_ortho_aabb(vec3 box[2], mat4 dest) + CGLM_INLINE void glm_ortho_aabb_p(vec3 box[2], float padding, mat4 dest) + CGLM_INLINE void glm_ortho_aabb_pz(vec3 box[2], float padding, mat4 dest) + CGLM_INLINE void glm_ortho_default(float aspect, mat4 dest) + CGLM_INLINE void glm_ortho_default_s(float aspect, float size, mat4 dest) + CGLM_INLINE void glm_perspective(float fovy, + float aspect, + float nearVal, + float farVal, + mat4 dest) + CGLM_INLINE void glm_perspective_default(float aspect, mat4 dest) + CGLM_INLINE void glm_perspective_resize(float aspect, mat4 proj) + CGLM_INLINE void glm_lookat(vec3 eye, vec3 center, vec3 up, mat4 dest) + CGLM_INLINE void glm_look(vec3 eye, vec3 dir, vec3 up, mat4 dest) + CGLM_INLINE void glm_look_anyup(vec3 eye, vec3 dir, mat4 dest) + CGLM_INLINE void glm_persp_decomp(mat4 proj, + float *nearVal, + float *farVal, + float *top, + float *bottom, + float *left, + float *right) + CGLM_INLINE void glm_persp_decompv(mat4 proj, float dest[6]) + CGLM_INLINE void glm_persp_decomp_x(mat4 proj, float *left, float *right) + CGLM_INLINE void glm_persp_decomp_y(mat4 proj, float *top, float *bottom) + CGLM_INLINE void glm_persp_decomp_z(mat4 proj, + float *nearVal, + float *farVal) + CGLM_INLINE void glm_persp_decomp_far(mat4 proj, float *farVal) + CGLM_INLINE void glm_persp_decomp_near(mat4 proj, float *nearVal) + CGLM_INLINE float glm_persp_fovy(mat4 proj) + CGLM_INLINE float glm_persp_aspect(mat4 proj) + CGLM_INLINE void glm_persp_sizes(mat4 proj, float fovy, vec4 dest) */ #ifndef cglm_vcam_h @@ -303,7 +302,7 @@ glm_perspective_default(float aspect, /*! * @brief resize perspective matrix by aspect ratio ( width / height ) - * this very make easy to resize proj matrix when window, viewport + * this makes very easy to resize proj matrix when window /viewport * reized * * @param[in] aspect aspect ratio ( width / height ) @@ -458,7 +457,7 @@ glm_persp_decompv(mat4 proj, float dest[6]) { * @brief decomposes left and right values of perspective projection. * x stands for x axis (left / right axis) * - * @param[in] proj perspective projection matrix + * @param[in] proj perspective projection matrix * @param[out] left left * @param[out] right right */ @@ -572,10 +571,7 @@ glm_persp_aspect(mat4 proj) { } /*! - * @brief returns aspect ratio of perspective projection - * - * if you don't have fovy then use glm_persp_fovy(proj) to get it - * or pass directly: glm_persp_sizes(proj, glm_persp_fovy(proj), sizes); + * @brief returns sizes of near and far planes of perspective projection * * @param[in] proj perspective projection matrix * @param[in] fovy fovy (see brief)