add cglm as 3rd-party library

1 files changed, 304 insertions, 0 deletions

diff --git a/libs/cglm/docs/source/mat4.rst b/libs/cglm/docs/source/mat4.rst
new file mode 100644
index 0000000..33251b9
--- /dev/null
+++ b/libs/cglm/docs/source/mat4.rst
@@ -0,0 +1,304 @@
+.. 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 (click 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_identity_array`
+#. :c:func:`glm_mat4_zero`
+#. :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_mat3_trace`
+#. :c:func:`glm_mat3_trace3`
+#. :c:func:`glm_mat4_quat`
+#. :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`
+#. :c:func:`glm_mat4_rmc`
+
+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_identity_array(mat4 * __restrict mat, size_t count)
+
+    make given matrix array's each element identity matrix
+
+    Parameters:
+      | *[in,out]* **mat**  matrix array (must be aligned (16/32) if alignment is not disabled)
+      | *[in]* **count**  count of matrices
+
+.. c:function:: void  glm_mat4_zero(mat4 mat)
+
+    make given matrix zero
+
+    Parameters:
+      | *[in,out]* **mat**  matrix to
+
+.. 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:: void 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)
+      | *[in]*  **last**  4th item to make it vec4
+      | *[out]* **dest**  vec4 (result, column vector)
+
+.. c:function:: void  glm_mat4_mulv3(mat4 m, vec3 v, float last, vec3 dest)
+
+    | multiply **vec3** with **mat4** and get **vec3** as result
+    |
+    | actually the result is **vec4**, after multiplication, 
+      the last component is trimmed, if you need the result's last component 
+      then don't use this function and consider to use **glm_mat4_mulv()**
+
+    Parameters:
+      | *[in]*  **m**     mat4(affine transform)
+      | *[in]*  **v**     vec3
+      | *[in]*  **last**  4th item to make it vec4
+      | *[out]* **dest**  result vector (vec3)
+
+.. c:function:: void  glm_mat4_trace(mat4 m)
+
+    | sum of the elements on the main diagonal from upper left to the lower right
+
+    Parameters:
+      | *[in]*  **m**  matrix
+
+    Returns:
+        trace of matrix
+
+.. c:function:: void  glm_mat4_trace3(mat4 m)
+
+    | trace of matrix (rotation part)
+    | sum of the elements on the main diagonal from upper left to the lower right
+
+    Parameters:
+      | *[in]*  **m**  matrix
+
+    Returns:
+        trace of matrix
+
+.. c:function:: void  glm_mat4_quat(mat4 m, versor dest)
+
+    convert mat4's rotation part to quaternion
+
+    Parameters:
+    | *[in]*  **m**     affine matrix
+    | *[out]* **dest**  destination quaternion
+
+.. 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
+
+.. c:function:: float  glm_mat4_rmc(vec4 r, mat4 m, vec4 c)
+
+    | **rmc** stands for **Row** * **Matrix** * **Column**
+
+    | helper for  R (row vector) * M (matrix) * C (column vector)
+
+    | the result is scalar because R * M = Matrix1x4 (row vector),
+    | then Matrix1x4 * Vec4 (column vector) = Matrix1x1 (Scalar)
+
+    Parameters:
+      | *[in]*  **r**  row vector or matrix1x4
+      | *[in]*  **m**  matrix4x4
+      | *[in]*  **c**  column vector or matrix4x1
+
+    Returns:
+        scalar value e.g. Matrix1x1