docs: add docs for vec3

docs/source/affine.rst

@@ -57,7 +57,7 @@ Functions documentation
 
 .. c:function:: void  glm_translate(mat4 m, vec3 v)
 
-    translate existing transform matrix by v vector
+    translate existing transform matrix by *v* vector
     and stores result in same matrix
 
     Parameters:
@@ -74,7 +74,7 @@ Functions documentation
 
 .. c:function:: void  glm_translate_y(mat4 m, float y)
 
-    translate existing transform matrix by y factor
+    translate existing transform matrix by *y* factor
 
     Parameters:
       | *[in, out]* **m**  affine transfrom
@@ -82,7 +82,7 @@ Functions documentation
 
 .. c:function:: void  glm_translate_z(mat4 m, float z)
 
-    translate existing transform matrix by z factor
+    translate existing transform matrix by *z* factor
 
     Parameters:
       | *[in, out]* **m**  affine transfrom
@@ -90,7 +90,7 @@ Functions documentation
 
 .. c:function:: void  glm_translate_make(mat4 m, vec3 v)
 
-    creates NEW translate transform matrix by v vector
+    creates NEW translate transform matrix by *v* vector.
 
     Parameters:
       | *[in, out]* **m**  affine transfrom
@@ -98,7 +98,7 @@ Functions documentation
 
 .. c:function:: void  glm_scale_to(mat4 m, vec3 v, mat4 dest)
 
-    scale existing transform matrix by v vector and store result in dest
+    scale existing transform matrix by *v* vector and store result in dest
 
     Parameters:
       | *[in]*  **m**    affine transfrom

docs/source/api.rst

@@ -29,3 +29,4 @@ Follow the :doc:`build` documentation for this
    affine
    mat4
    mat3
+   vec3

docs/source/vec3.rst

@@ -0,0 +1,273 @@
+.. default-domain:: C
+
+vec3
+====
+
+Header: cglm/vec3.h
+
+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_vec_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 (clik func/macro to go):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Macros:
+
+1. glm_vec_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_vec_copy`
+#. :c:func:`glm_vec_dot`
+#. :c:func:`glm_vec_cross`
+#. :c:func:`glm_vec_norm2`
+#. :c:func:`glm_vec_norm`
+#. :c:func:`glm_vec_add`
+#. :c:func:`glm_vec_sub`
+#. :c:func:`glm_vec_scale`
+#. :c:func:`glm_vec_scale_as`
+#. :c:func:`glm_vec_flipsign`
+#. :c:func:`glm_vec_inv`
+#. :c:func:`glm_vec_inv_to`
+#. :c:func:`glm_vec_normalize`
+#. :c:func:`glm_vec_normalize_to`
+#. :c:func:`glm_vec_distance`
+#. :c:func:`glm_vec_angle`
+#. :c:func:`glm_vec_rotate`
+#. :c:func:`glm_vec_rotate_m4`
+#. :c:func:`glm_vec_proj`
+#. :c:func:`glm_vec_center`
+#. :c:func:`glm_vec_maxv`
+#. :c:func:`glm_vec_minv`
+#. :c:func:`glm_vec_ortho`
+
+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_vec_copy(vec3 a, vec3 dest)
+
+     copy all members of [a] to [dest]
+
+    Parameters:
+      | *[in]*  **a**     source
+      | *[out]* **dest**  destination
+
+.. c:function:: float  glm_vec_dot(vec3 a, vec3 b)
+
+    dot product of vec3
+
+    Parameters:
+      | *[in]*  **a**  vector1
+      | *[in]*  **b**  vector2
+
+    Returns:
+      dot product
+
+.. c:function:: void  glm_vec_cross(vec3 a, vec3 b, vec3 d)
+
+    cross product
+
+    Parameters:
+      | *[in]*  **a**  source 1
+      | *[in]*  **b**  source 2
+      | *[out]* **d**  destination
+
+.. c:function:: float  glm_vec_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_vec_norm(vec3 vec)
+
+    norm (magnitude) of vec3
+
+    Parameters:
+      | *[in]*  **vec**   vector
+
+.. c:function:: void  glm_vec_add(vec3 v1, vec3 v2, vec3 dest)
+
+    add v2 vector to v1 vector store result in dest
+
+    Parameters:
+      | *[in]*  **v1**    vector1
+      | *[in]*  **v2**    vector2
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void  glm_vec_sub(vec3 v1, vec3 v2, vec3 dest)
+
+    subtract v2 vector from v1 vector store result in dest
+
+    Parameters:
+      | *[in]*  **v1**    vector1
+      | *[in]*  **v2**    vector2
+      | *[out]* **dest**  destination vector
+
+.. c:function:: void glm_vec_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_vec_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_vec_flipsign(vec3 v)
+
+    flip sign of all vec3 members
+
+    Parameters:
+    | *[in, out]*  **v**    vector
+
+.. c:function:: void  glm_vec_inv(vec3 v)
+
+    make vector as inverse/opposite of itself
+
+    Parameters:
+      | *[in, out]*  **v**    vector
+
+.. c:function:: void  glm_vec_inv_to(vec3 v, vec3 dest)
+
+    inverse/opposite vector
+
+    Parameters:
+      | *[in]*  **v**     source
+      | *[out]* **dest**  destination
+
+.. c:function:: void  glm_vec_normalize(vec3 v)
+
+    normalize vec3 and store result in same vec
+
+    Parameters:
+      | *[in, out]*  **v**    vector
+
+.. c:function:: void  glm_vec_normalize_to(vec3 vec, vec3 dest)
+
+     normalize vec3 to dest
+
+    Parameters:
+      | *[in]*   **vec**   source
+      | *[out]*  **dest**  destination
+
+.. c:function:: float  glm_vec_angle(vec3 v1, vec3 v2)
+
+    angle betwen two vector
+
+    Parameters:
+      | *[in]*  **v1**   vector1
+      | *[in]*  **v2**   vector2
+
+    Return:
+      | angle as radians
+
+.. c:function:: void  glm_vec_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 (must be unit vector)
+      | *[out]*      **angle**  angle (radians)
+
+.. c:function:: void  glm_vec_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_vec_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_vec_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_vec_distance(vec3 v1, vec3 v2)
+
+    distance between two vectors
+
+    Parameters:
+      | *[in]*  **mat**   vector1
+      | *[in]*  **row1**  vector2
+
+    Returns:
+      | distance
+
+.. c:function:: void  glm_vec_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_vec_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_vec_ortho(vec3 v, vec3 dest)
+
+    possible orthogonal/perpendicular vector
+
+    Parameters:
+      | *[in]*  **mat**   vector
+      | *[out]* **dest**  orthogonal/perpendicular vector

include/cglm/vec3.h

@@ -309,6 +309,9 @@ glm_vec_normalize_to(vec3 vec, vec3 dest) {
 /*!
  * @brief angle betwen two vector
  *
+ * @param[in] v1  vector1
+ * @param[in] v2  vector2
+ *
  * @return angle as radians
  */
 CGLM_INLINE