add cglm as 3rd-party library

1 files changed, 503 insertions, 0 deletions

diff --git a/libs/cglm/docs/source/vec3.rst b/libs/cglm/docs/source/vec3.rst
new file mode 100644
index 0000000..17e4824
--- /dev/null
+++ b/libs/cglm/docs/source/vec3.rst
@@ -0,0 +1,503 @@
+.. default-domain:: C
+
+vec3
+====
+
+Header: cglm/vec3.h
+
+ **Important:** *cglm* was used **glm_vec_** namespace for vec3 functions until
+ **v0.5.0**, since **v0.5.0** cglm uses **glm_vec3_** namespace for vec3.
+
+ Also `glm_vec3_flipsign` has been renamed to `glm_vec3_negate`
+
+We mostly use vectors in graphics math, to make writing code faster
+and easy to read, some *vec3* functions are aliased in global namespace.
+For instance :c:func:`glm_dot` is alias of :c:func:`glm_vec3_dot`,
+alias means inline wrapper here. There is no call verison of alias functions
+
+There are also functions for rotating *vec3* vector. **_m4**, **_m3** prefixes
+rotate *vec3* with matrix.
+
+Table of contents (click to go):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Macros:
+
+1. glm_vec3_dup(v, dest)
+#. GLM_VEC3_ONE_INIT
+#. GLM_VEC3_ZERO_INIT
+#. GLM_VEC3_ONE
+#. GLM_VEC3_ZERO
+#. GLM_YUP
+#. GLM_ZUP
+#. GLM_XUP
+
+Functions:
+
+1. :c:func:`glm_vec3`
+#. :c:func:`glm_vec3_copy`
+#. :c:func:`glm_vec3_zero`
+#. :c:func:`glm_vec3_one`
+#. :c:func:`glm_vec3_dot`
+#. :c:func:`glm_vec3_norm2`
+#. :c:func:`glm_vec3_norm`
+#. :c:func:`glm_vec3_add`
+#. :c:func:`glm_vec3_adds`
+#. :c:func:`glm_vec3_sub`
+#. :c:func:`glm_vec3_subs`
+#. :c:func:`glm_vec3_mul`
+#. :c:func:`glm_vec3_scale`
+#. :c:func:`glm_vec3_scale_as`
+#. :c:func:`glm_vec3_div`
+#. :c:func:`glm_vec3_divs`
+#. :c:func:`glm_vec3_addadd`
+#. :c:func:`glm_vec3_subadd`
+#. :c:func:`glm_vec3_muladd`
+#. :c:func:`glm_vec3_muladds`
+#. :c:func:`glm_vec3_maxadd`
+#. :c:func:`glm_vec3_minadd`
+#. :c:func:`glm_vec3_flipsign`
+#. :c:func:`glm_vec3_flipsign_to`
+#. :c:func:`glm_vec3_inv`
+#. :c:func:`glm_vec3_inv_to`
+#. :c:func:`glm_vec3_negate`
+#. :c:func:`glm_vec3_negate_to`
+#. :c:func:`glm_vec3_normalize`
+#. :c:func:`glm_vec3_normalize_to`
+#. :c:func:`glm_vec3_cross`
+#. :c:func:`glm_vec3_crossn`
+#. :c:func:`glm_vec3_distance2`
+#. :c:func:`glm_vec3_distance`
+#. :c:func:`glm_vec3_angle`
+#. :c:func:`glm_vec3_rotate`
+#. :c:func:`glm_vec3_rotate_m4`
+#. :c:func:`glm_vec3_rotate_m3`
+#. :c:func:`glm_vec3_proj`
+#. :c:func:`glm_vec3_center`
+#. :c:func:`glm_vec3_maxv`
+#. :c:func:`glm_vec3_minv`
+#. :c:func:`glm_vec3_ortho`
+#. :c:func:`glm_vec3_clamp`
+#. :c:func:`glm_vec3_lerp`
+
+Functions documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: void  glm_vec3(vec4 v4, vec3 dest)
+
+    init vec3 using vec4
+
+    Parameters:
+      | *[in]*  **v4**    vector4
+      | *[out]* **dest**  destination
+
+.. c:function:: void  glm_vec3_copy(vec3 a, vec3 dest)
+
+    copy all members of [a] to [dest]
+
+    Parameters:
+      | *[in]*  **a**     source
+      | *[out]* **dest**  destination
+
+.. c:function:: void  glm_vec3_zero(vec3 v)
+
+    makes all members 0.0f (zero)
+
+    Parameters:
+      | *[in, out]*  **v**     vector
+
+.. c:function:: void  glm_vec3_one(vec3 v)
+
+    makes all members 1.0f (one)
+
+    Parameters:
+      | *[in, out]*  **v**     vector
+
+.. c:function:: float  glm_vec3_dot(vec3 a, vec3 b)
+
+    dot product of vec3
+
+    Parameters:
+      | *[in]*  **a**  vector1
+      | *[in]*  **b**  vector2
+
+    Returns:
+      dot product
+
+.. c:function:: void  glm_vec3_cross(vec3 a, vec3 b, vec3 d)
+
+    cross product of two vector (RH)
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  destination
+
+.. c:function:: void  glm_vec3_crossn(vec3 a, vec3 b, vec3 dest)
+
+    cross product of two vector (RH) and normalize the result
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  destination
+
+.. c:function:: float  glm_vec3_norm2(vec3 v)
+
+    norm * norm (magnitude) of vector
+
+    we can use this func instead of calling norm * norm, because it would call
+    sqrtf fuction twice but with this func we can avoid func call, maybe this is
+    not good name for this func
+
+    Parameters:
+      | *[in]*  **v**   vector
+
+    Returns:
+      square of norm / magnitude
+
+.. c:function:: float  glm_vec3_norm(vec3 vec)
+
+    | euclidean norm (magnitude), also called L2 norm
+    | this will give magnitude of vector in euclidean space
+
+    Parameters:
+      | *[in]*  **vec**   vector
+
+.. c:function:: void  glm_vec3_add(vec3 a, vec3 b, vec3 dest)
+
+    add a vector to b vector store result in dest
+
+    Parameters:
+      | *[in]*  **a**     vector1
+      | *[in]*  **b**     vector2
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void  glm_vec3_adds(vec3 a, float s, vec3 dest)
+
+    add scalar to v vector store result in dest (d = v + vec(s))
+
+    Parameters:
+      | *[in]*  **v**     vector
+      | *[in]*  **s**     scalar
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void  glm_vec3_sub(vec3 v1, vec3 v2, vec3 dest)
+
+    subtract b vector from a vector store result in dest (d = v1 - v2)
+
+    Parameters:
+      | *[in]*  **a**     vector1
+      | *[in]*  **b**     vector2
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void  glm_vec3_subs(vec3 v, float s, vec3 dest)
+
+    subtract scalar from v vector store result in dest (d = v - vec(s))
+
+    Parameters:
+      | *[in]*  **v**     vector
+      | *[in]*  **s**     scalar
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void  glm_vec3_mul(vec3 a, vec3 b, vec3 d)
+
+    multiply two vector (component-wise multiplication)
+
+    Parameters:
+      | *[in]*  **a**     vector
+      | *[in]*  **b**     scalar
+      | *[out]* **d**     result = (a[0] * b[0], a[1] * b[1], a[2] * b[2])
+
+.. c:function:: void glm_vec3_scale(vec3 v, float s, vec3 dest)
+
+     multiply/scale vec3 vector with scalar: result = v * s
+
+
+    Parameters:
+      | *[in]*  **v**     vector
+      | *[in]*  **s**     scalar
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void  glm_vec3_scale_as(vec3 v, float s, vec3 dest)
+
+    make vec3 vector scale as specified: result = unit(v) * s
+
+    Parameters:
+      | *[in]*  **v**     vector
+      | *[in]*  **s**     scalar
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void  glm_vec3_div(vec3 a, vec3 b, vec3 dest)
+
+    div vector with another component-wise division: d = a / b
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  result = (a[0] / b[0], a[1] / b[1], a[2] / b[2])
+
+.. c:function:: void  glm_vec3_divs(vec3 v, float s, vec3 dest)
+
+    div vector with scalar: d = v / s
+
+    Parameters:
+      | *[in]*  **v**     vector
+      | *[in]*  **s**     scalar
+      | *[out]* **dest**  result = (a[0] / s, a[1] / s, a[2] / s])
+
+.. c:function:: void  glm_vec3_addadd(vec3 a, vec3 b, vec3 dest)
+
+    | add two vectors and add result to sum
+    | it applies += operator so dest must be initialized
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  dest += (a + b)
+
+.. c:function:: void  glm_vec3_subadd(vec3 a, vec3 b, vec3 dest)
+
+    | sub two vectors and add result to sum
+    | it applies += operator so dest must be initialized
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  dest += (a - b)
+
+.. c:function:: void  glm_vec3_muladd(vec3 a, vec3 b, vec3 dest)
+
+    | mul two vectors and add result to sum
+    | it applies += operator so dest must be initialized
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  dest += (a * b)
+
+.. c:function:: void  glm_vec3_muladds(vec3 a, float s, vec3 dest)
+
+    | mul vector with scalar and add result to sum
+    | it applies += operator so dest must be initialized
+
+    Parameters:
+      | *[in]*  **a**     vector
+      | *[in]*  **s**     scalar
+      | *[out]* **dest**  dest += (a * b)
+
+.. c:function:: void  glm_vec3_maxadd(vec3 a, vec3 b, vec3 dest)
+
+    | add max of two vector to result/dest
+    | it applies += operator so dest must be initialized
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  dest += (a * b)
+
+.. c:function:: void  glm_vec3_minadd(vec3 a, vec3 b, vec3 dest)
+
+    | add min of two vector to result/dest
+    | it applies += operator so dest must be initialized
+
+    Parameters:
+      | *[in]*  **a**     vector 1
+      | *[in]*  **b**     vector 2
+      | *[out]* **dest**  dest += (a * b)
+
+.. c:function:: void  glm_vec3_flipsign(vec3 v)
+
+    **DEPRACATED!**
+
+    use :c:func:`glm_vec3_negate`
+
+    Parameters:
+      | *[in, out]*  **v**    vector
+
+.. c:function:: void  glm_vec3_flipsign_to(vec3 v, vec3 dest)
+
+    **DEPRACATED!**
+
+    use :c:func:`glm_vec3_negate_to`
+
+    Parameters:
+      | *[in]*  **v**       vector
+      | *[out]* **dest**    negated vector
+
+.. c:function:: void  glm_vec3_inv(vec3 v)
+
+    **DEPRACATED!**
+
+    use :c:func:`glm_vec3_negate`
+
+    Parameters:
+      | *[in, out]*  **v**    vector
+
+.. c:function:: void  glm_vec3_inv_to(vec3 v, vec3 dest)
+
+    **DEPRACATED!**
+
+    use :c:func:`glm_vec3_negate_to`
+
+    Parameters:
+      | *[in]*  **v**     source
+      | *[out]* **dest**  destination
+
+.. c:function:: void  glm_vec3_negate(vec3 v)
+
+    negate vector components
+
+    Parameters:
+      | *[in, out]*  **v**    vector
+
+.. c:function:: void  glm_vec3_negate_to(vec3 v, vec3 dest)
+
+    negate vector components and store result in dest
+
+    Parameters:
+      | *[in]*  **v**       vector
+      | *[out]* **dest**    negated vector
+
+.. c:function:: void  glm_vec3_normalize(vec3 v)
+
+    normalize vec3 and store result in same vec
+
+    Parameters:
+      | *[in, out]*  **v**    vector
+
+.. c:function:: void  glm_vec3_normalize_to(vec3 vec, vec3 dest)
+
+     normalize vec3 to dest
+
+    Parameters:
+      | *[in]*   **vec**   source
+      | *[out]*  **dest**  destination
+
+.. c:function:: float  glm_vec3_angle(vec3 v1, vec3 v2)
+
+    angle betwen two vector
+
+    Parameters:
+      | *[in]*  **v1**   vector1
+      | *[in]*  **v2**   vector2
+
+    Return:
+      | angle as radians
+
+.. c:function:: void  glm_vec3_rotate(vec3 v, float angle, vec3 axis)
+
+     rotate vec3 around axis by angle using Rodrigues' rotation formula
+
+    Parameters:
+      | *[in, out]*  **v**      vector
+      | *[in]*       **axis**   axis vector (will be normalized)
+      | *[in]*       **angle**  angle (radians)
+
+.. c:function:: void  glm_vec3_rotate_m4(mat4 m, vec3 v, vec3 dest)
+
+    apply rotation matrix to vector
+
+    Parameters:
+      | *[in]*  **m**     affine matrix or rot matrix
+      | *[in]*  **v**     vector
+      | *[out]* **dest**  rotated vector
+
+.. c:function:: void  glm_vec3_rotate_m3(mat3 m, vec3 v, vec3 dest)
+
+    apply rotation matrix to vector
+
+    Parameters:
+      | *[in]*  **m**     affine matrix or rot matrix
+      | *[in]*  **v**     vector
+      | *[out]* **dest**  rotated vector
+
+.. c:function:: void  glm_vec3_proj(vec3 a, vec3 b, vec3 dest)
+
+    project a vector onto b vector
+
+    Parameters:
+      | *[in]*  **a**     vector1
+      | *[in]*  **b**     vector2
+      | *[out]* **dest**  projected vector
+
+.. c:function:: void  glm_vec3_center(vec3 v1, vec3 v2, vec3 dest)
+
+    find center point of two vector
+
+    Parameters:
+      | *[in]*  **v1**    vector1
+      | *[in]*  **v2**    vector2
+      | *[out]* **dest**  center point
+
+.. c:function:: float  glm_vec3_distance2(vec3 v1, vec3 v2)
+
+    squared distance between two vectors
+
+    Parameters:
+      | *[in]*  **v1**  vector1
+      | *[in]*  **v2**  vector2
+
+    Returns:
+      | squared distance (distance * distance)
+
+.. c:function:: float  glm_vec3_distance(vec3 v1, vec3 v2)
+
+    distance between two vectors
+
+    Parameters:
+      | *[in]*  **v1**  vector1
+      | *[in]*  **v2**  vector2
+
+    Returns:
+      | distance
+
+.. c:function:: void  glm_vec3_maxv(vec3 v1, vec3 v2, vec3 dest)
+
+    max values of vectors
+
+    Parameters:
+      | *[in]*  **v1**    vector1
+      | *[in]*  **v2**    vector2
+      | *[out]* **dest**  destination
+
+.. c:function:: void  glm_vec3_minv(vec3 v1, vec3 v2, vec3 dest)
+
+    min values of vectors
+
+    Parameters:
+      | *[in]*  **v1**    vector1
+      | *[in]*  **v2**    vector2
+      | *[out]* **dest**  destination
+
+.. c:function:: void  glm_vec3_ortho(vec3 v, vec3 dest)
+
+    possible orthogonal/perpendicular vector
+
+    References:
+      * `On picking an orthogonal vector (and combing coconuts) <http://lolengine.net/blog/2013/09/21/picking-orthogonal-vector-combing-coconuts>`_
+
+    Parameters:
+      | *[in]*  **v**     vector
+      | *[out]* **dest**  orthogonal/perpendicular vector
+
+.. c:function:: void  glm_vec3_clamp(vec3 v, float minVal, float maxVal)
+
+    constrain a value to lie between two further values
+
+    Parameters:
+      | *[in, out]*  **v**       vector
+      | *[in]*       **minVal**  minimum value
+      | *[in]*       **maxVal**  maximum value
+
+.. c:function:: void  glm_vec3_lerp(vec3 from, vec3 to, float t, vec3 dest)
+
+    linear interpolation between two vector
+
+    | formula:  from + s * (to - from)
+
+    Parameters:
+      | *[in]*  **from**   from value
+      | *[in]*  **to**     to value
+      | *[in]*  **t**      interpolant (amount) clamped between 0 and 1
+      | *[out]* **dest**   destination