mirror of
https://github.com/recp/cglm.git
synced 2025-12-24 04:22:36 +00:00
docs: add docs for api, mat4
This commit is contained in:
Recep Aslantas
29
docs/source/api.rst
Normal file
29
docs/source/api.rst
Normal file
@@ -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
|
||||
@@ -38,6 +38,7 @@ Also currently only **float** type is supported for most operations.
|
||||
|
||||
build
|
||||
getting_started
|
||||
api
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
231
docs/source/mat4.rst
Normal file
231
docs/source/mat4.rst
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user