From fc424631a4560b66a7b250310877b4fc378ede74 Mon Sep 17 00:00:00 2001 From: Recep Aslantas Date: Sat, 24 Feb 2018 13:18:28 +0300 Subject: [PATCH] docs: add docs for api, mat4 --- docs/source/api.rst | 29 ++++++ docs/source/index.rst | 1 + docs/source/mat4.rst | 231 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 261 insertions(+) create mode 100644 docs/source/api.rst create mode 100644 docs/source/mat4.rst diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..5c54521 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,29 @@ +API documentation +================================ + +Some functions may exist twice, +once for their namespace and once for global namespace +to make easier to write very common functions + +For instance, in general we use :code:`glm_vec_dot` to get dot product +of two **vec3**. Now we can also do this with :code:`glm_dot`, +same for *_cross* and so on... + +The original function stays where it is, the function in global namespace +of same name is just an alias, so there is no call version of those functions. +e.g there is no func like :code:`glmc_dot` because *glm_dot* is just alias for +:code:`glm_vec_dot` + +By including **cglm/cglm.h** header you will include all inline version +of functions. Since functions in this header[s] are inline you don't need to +build or link *cglm* against your project. + +But by including **cglm/call.h** header you will include all *non-inline* +version of functions. You need to build *cglm* and link it. +Follow the :doc:`build` documentation for this + +.. toctree:: + :maxdepth: 2 + :caption: API categories: + + mat4 diff --git a/docs/source/index.rst b/docs/source/index.rst index ae51468..3241872 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -38,6 +38,7 @@ Also currently only **float** type is supported for most operations. build getting_started + api Indices and tables ================== diff --git a/docs/source/mat4.rst b/docs/source/mat4.rst new file mode 100644 index 0000000..dffe18a --- /dev/null +++ b/docs/source/mat4.rst @@ -0,0 +1,231 @@ +.. default-domain:: C + +mat4 +==== + +Header: cglm/mat4.h + +Important: :c:func:`glm_mat4_scale` multiplies mat4 with scalar, if you need to +apply scale transform use :c:func:`glm_scale` functions. + +Table of contents (clik func/macro to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Macros: + +1. GLM_MAT4_IDENTITY_INIT +#. GLM_MAT4_ZERO_INIT +#. GLM_MAT4_IDENTITY +#. GLM_MAT4_ZERO +#. glm_mat4_udup(mat, dest) +#. glm_mat4_dup(mat, dest) + +Functions: + +1. :c:func:`glm_mat4_ucopy` +#. :c:func:`glm_mat4_copy` +#. :c:func:`glm_mat4_identity` +#. :c:func:`glm_mat4_pick3` +#. :c:func:`glm_mat4_pick3t` +#. :c:func:`glm_mat4_ins3` +#. :c:func:`glm_mat4_mul` +#. :c:func:`glm_mat4_mulN` +#. :c:func:`glm_mat4_mulv` +#. :c:func:`glm_mat4_mulv3` +#. :c:func:`glm_mat4_transpose_to` +#. :c:func:`glm_mat4_transpose` +#. :c:func:`glm_mat4_scale_p` +#. :c:func:`glm_mat4_scale` +#. :c:func:`glm_mat4_det` +#. :c:func:`glm_mat4_inv` +#. :c:func:`glm_mat4_inv_fast` +#. :c:func:`glm_mat4_swap_col` +#. :c:func:`glm_mat4_swap_row` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_mat4_ucopy(mat4 mat, mat4 dest) + + copy mat4 to another one (dest). u means align is not required for dest + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat4_copy(mat4 mat, mat4 dest) + + copy mat4 to another one (dest). + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat4_identity(mat4 mat) + + copy identity mat4 to mat, or makes mat to identiy + + Parameters: + | *[out]* **mat** matrix + +.. c:function:: void glm_mat4_pick3(mat4 mat, mat3 dest) + + copy upper-left of mat4 to mat3 + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat4_pick3t(mat4 mat, mat4 dest) + + copy upper-left of mat4 to mat3 (transposed) + the postfix t stands for transpose + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat4_ins3(mat3 mat, mat4 dest) + + copy mat3 to mat4's upper-left. this function does not fill mat4's other + elements. To do that use glm_mat4. + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat4_mul(mat4 m1, mat4 m2, mat4 dest) + + multiply m1 and m2 to dest + m1, m2 and dest matrices can be same matrix, it is possible to write this: + + .. code-block:: c + + mat4 m = GLM_MAT4_IDENTITY_INIT; + glm_mat4_mul(m, m, m); + + Parameters: + | *[in]* **m1** left matrix + | *[in]* **m2** right matrix + | *[out]* **dest** destination matrix + +.. c:function:: glm_mat4_mulN(mat4 * __restrict matrices[], int len, mat4 dest) + + mupliply N mat4 matrices and store result in dest + | this function lets you multiply multiple (more than two or more...) + | matrices + + | multiplication will be done in loop, this may reduce instructions + | size but if **len** is too small then compiler may unroll whole loop + + .. code-block:: c + + mat m1, m2, m3, m4, res; + glm_mat4_mulN((mat4 *[]){&m1, &m2, &m3, &m4}, 4, res); + + Parameters: + | *[in]* **matrices** array of mat4 + | *[in]* **len** matrices count + | *[out]* **dest** destination matrix + +.. c:function:: void glm_mat4_mulv(mat4 m, vec4 v, vec4 dest) + + multiply mat4 with vec4 (column vector) and store in dest vector + + Parameters: + | *[in]* **m** mat4 (left) + | *[in]* **v** vec4 (right, column vector) + | *[out]* **dest** vec4 (result, column vector) + +.. c:function:: void glm_mat4_mulv3(mat4 m, vec3 v, vec3 dest) + + multiply vector with mat4's mat3 part(rotation) + + Parameters: + | *[in]* **m** mat4 (left) + | *[in]* **v** vec3 (right, column vector) + | *[out]* **dest** vec3 (result, column vector) + +.. c:function:: void glm_mat4_transpose_to(mat4 m, mat4 dest) + + transpose mat4 and store in dest + source matrix will not be transposed unless dest is m + + Parameters: + | *[in]* **m** matrix + | *[out]* **dest** destination matrix + +.. c:function:: void glm_mat4_transpose(mat4 m) + + tranpose mat4 and store result in same matrix + + Parameters: + | *[in]* **m** source + | *[out]* **dest** destination matrix + +.. c:function:: void glm_mat4_scale_p(mat4 m, float s) + + scale (multiply with scalar) matrix without simd optimization + + Parameters: + | *[in, out]* **m** matrix + | *[in]* **s** scalar + +.. c:function:: void glm_mat4_scale(mat4 m, float s) + + scale (multiply with scalar) matrix + THIS IS NOT SCALE TRANSFORM, use glm_scale for that. + + Parameters: + | *[in, out]* **m** matrix + | *[in]* **s** scalar + +.. c:function:: float glm_mat4_det(mat4 mat) + + mat4 determinant + + Parameters: + | *[in]* **mat** matrix + + Return: + | determinant + +.. c:function:: void glm_mat4_inv(mat4 mat, mat4 dest) + + inverse mat4 and store in dest + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination matrix (inverse matrix) + +.. c:function:: void glm_mat4_inv_fast(mat4 mat, mat4 dest) + + inverse mat4 and store in dest + + | this func uses reciprocal approximation without extra corrections + | e.g Newton-Raphson. this should work faster than normal, + | to get more precise use glm_mat4_inv version. + + | NOTE: You will lose precision, glm_mat4_inv is more accurate + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat4_swap_col(mat4 mat, int col1, int col2) + + swap two matrix columns + + Parameters: + | *[in, out]* **mat** matrix + | *[in]* **col1** col1 + | *[in]* **col2** col2 + +.. c:function:: void glm_mat4_swap_row(mat4 mat, int row1, int row2) + + swap two matrix rows + + Parameters: + | *[in, out]* **mat** matrix + | *[in]* **row1** row1 + | *[in]* **row2** row2