diff options
Diffstat (limited to 'libs/cglm/docs/source/frustum.rst')
| -rw-r--r-- | libs/cglm/docs/source/frustum.rst | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/libs/cglm/docs/source/frustum.rst b/libs/cglm/docs/source/frustum.rst new file mode 100644 index 0000000..b58913c --- /dev/null +++ b/libs/cglm/docs/source/frustum.rst @@ -0,0 +1,168 @@ +.. default-domain:: C + +frustum +============= + +Header: cglm/frustum.h + +cglm provides convenient functions to extract frustum planes, corners... +All extracted corners are **vec4** so you must create array of **vec4** +not **vec3**. If you want to store them to save space you msut convert them +yourself. + +**vec4** is used to speed up functions need to corners. This is why frustum +fucntions use *vec4* instead of *vec3* + +Currenty related-functions use [-1, 1] clip space configuration to extract +corners but you can override it by prodiving **GLM_CUSTOM_CLIPSPACE** macro. +If you provide it then you have to all bottom macros as *vec4* + +Current configuration: + +.. code-block:: c + + /* near */ + GLM_CSCOORD_LBN {-1.0f, -1.0f, -1.0f, 1.0f} + GLM_CSCOORD_LTN {-1.0f, 1.0f, -1.0f, 1.0f} + GLM_CSCOORD_RTN { 1.0f, 1.0f, -1.0f, 1.0f} + GLM_CSCOORD_RBN { 1.0f, -1.0f, -1.0f, 1.0f} + + /* far */ + GLM_CSCOORD_LBF {-1.0f, -1.0f, 1.0f, 1.0f} + GLM_CSCOORD_LTF {-1.0f, 1.0f, 1.0f, 1.0f} + GLM_CSCOORD_RTF { 1.0f, 1.0f, 1.0f, 1.0f} + GLM_CSCOORD_RBF { 1.0f, -1.0f, 1.0f, 1.0f} + + +Explain of short names: + * **LBN**: left bottom near + * **LTN**: left top near + * **RTN**: right top near + * **RBN**: right bottom near + * **LBF**: left bottom far + * **LTF**: left top far + * **RTF**: right top far + * **RBF**: right bottom far + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Macros: + +.. code-block:: c + + GLM_LBN 0 /* left bottom near */ + GLM_LTN 1 /* left top near */ + GLM_RTN 2 /* right top near */ + GLM_RBN 3 /* right bottom near */ + + GLM_LBF 4 /* left bottom far */ + GLM_LTF 5 /* left top far */ + GLM_RTF 6 /* right top far */ + GLM_RBF 7 /* right bottom far */ + + GLM_LEFT 0 + GLM_RIGHT 1 + GLM_BOTTOM 2 + GLM_TOP 3 + GLM_NEAR 4 + GLM_FAR 5 + +Functions: + +1. :c:func:`glm_frustum_planes` +#. :c:func:`glm_frustum_corners` +#. :c:func:`glm_frustum_center` +#. :c:func:`glm_frustum_box` +#. :c:func:`glm_frustum_corners_at` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_frustum_planes(mat4 m, vec4 dest[6]) + + | extracts view frustum planes + + planes' space: + - if m = proj: View Space + - if m = viewProj: World Space + - if m = MVP: Object Space + + You probably want to extract planes in world space so use viewProj as m + Computing viewProj: + + .. code-block:: c + + glm_mat4_mul(proj, view, viewProj); + + Exracted planes order: [left, right, bottom, top, near, far] + + Parameters: + | *[in]* **m** matrix + | *[out]* **dest** exracted view frustum planes + +.. c:function:: void glm_frustum_corners(mat4 invMat, vec4 dest[8]) + + | extracts view frustum corners using clip-space coordinates + + corners' space: + - if m = invViewProj: World Space + - if m = invMVP: Object Space + + You probably want to extract corners in world space so use **invViewProj** + Computing invViewProj: + + .. code-block:: c + + glm_mat4_mul(proj, view, viewProj); + ... + glm_mat4_inv(viewProj, invViewProj); + + if you have a near coord at **i** index, + you can get it's far coord by i + 4; + follow example below to understand that + + For instance to find center coordinates between a near and its far coord: + + .. code-block:: c + + for (j = 0; j < 4; j++) { + glm_vec3_center(corners[i], corners[i + 4], centerCorners[i]); + } + + corners[i + 4] is far of corners[i] point. + + Parameters: + | *[in]* **invMat** matrix + | *[out]* **dest** exracted view frustum corners + +.. c:function:: void glm_frustum_center(vec4 corners[8], vec4 dest) + + | finds center of view frustum + + Parameters: + | *[in]* **corners** view frustum corners + | *[out]* **dest** view frustum center + +.. c:function:: void glm_frustum_box(vec4 corners[8], mat4 m, vec3 box[2]) + + | finds bounding box of frustum relative to given matrix e.g. view mat + + Parameters: + | *[in]* **corners** view frustum corners + | *[in]* **m** matrix to convert existing conners + | *[out]* **box** bounding box as array [min, max] + +.. c:function:: void glm_frustum_corners_at(vec4 corners[8], float splitDist, float farDist, vec4 planeCorners[4]) + + | finds planes corners which is between near and far planes (parallel) + + this will be helpful if you want to split a frustum e.g. CSM/PSSM. This will + find planes' corners but you will need to one more plane. + Actually you have it, it is near, far or created previously with this func ;) + + Parameters: + | *[in]* **corners** frustum corners + | *[in]* **splitDist** split distance + | *[in]* **farDist** far distance (zFar) + | *[out]* **planeCorners** plane corners [LB, LT, RT, RB] |