update docs

docs/source/quat.rst

@@ -5,17 +5,16 @@ quaternions
 
 Header: cglm/quat.h
 
- **Important:** *cglm* stores quaternion as [w, x, y, z] in memory, don't
+ **Important:** *cglm* stores quaternion as **[x, y, z, w]** in memory
- forget that when changing quaternion items manually. For instance *quat[3]*
+ since **v0.4.0** it was **[w, x, y, z]**
- is *quat.z* and *quat[0*] is *quat.w*. This may change in the future if *cglm*
+ before v0.4.0 ( **v0.3.5 and earlier** ). w is real part.
- will got enough request to do that. Probably it will not be changed in near
- future
 
-There are some TODOs for quaternions check TODO list to see them.
+What you can do with quaternions with existing functions is (Some of them):
 
-Also **versor** is identity quaternion so the type may change to **vec4** or
+- You can rotate transform matrix using quaterion
-something else. This will not affect existing functions for your engine because
+- You can rotate vector using quaterion
-*versor* is alias of *vec4*
+- You can create view matrix using quaterion
+- You can create a lookrotation (from source point to dest)
 
 Table of contents (click to go):
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -28,14 +27,35 @@ Macros:
 Functions:
 
 1. :c:func:`glm_quat_identity`
+#. :c:func:`glm_quat_init`
 #. :c:func:`glm_quat`
 #. :c:func:`glm_quatv`
+#. :c:func:`glm_quat_copy`
 #. :c:func:`glm_quat_norm`
 #. :c:func:`glm_quat_normalize`
+#. :c:func:`glm_quat_normalize_to`
 #. :c:func:`glm_quat_dot`
-#. :c:func:`glm_quat_mulv`
+#. :c:func:`glm_quat_conjugate`
+#. :c:func:`glm_quat_inv`
+#. :c:func:`glm_quat_add`
+#. :c:func:`glm_quat_sub`
+#. :c:func:`glm_quat_real`
+#. :c:func:`glm_quat_imag`
+#. :c:func:`glm_quat_imagn`
+#. :c:func:`glm_quat_imaglen`
+#. :c:func:`glm_quat_angle`
+#. :c:func:`glm_quat_axis`
+#. :c:func:`glm_quat_mul`
 #. :c:func:`glm_quat_mat4`
+#. :c:func:`glm_quat_mat4t`
+#. :c:func:`glm_quat_mat3`
+#. :c:func:`glm_quat_mat3t`
+#. :c:func:`glm_quat_lerp`
 #. :c:func:`glm_quat_slerp`
+#. :c:func:`glm_quat_look`
+#. :c:func:`glm_quat_for`
+#. :c:func:`glm_quat_forp`
+#. :c:func:`glm_quat_rotatev`
 
 Functions documentation
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -47,10 +67,23 @@ Functions documentation
     Parameters:
       | *[in, out]*  **q**    quaternion
 
+.. c:function:: void  glm_quat_init(versor q, float x, float y, float z, float w)
+
+    | inits quaternion with given values
+
+    Parameters:
+      | *[out]* **q**      quaternion
+      | *[in]*  **x**      imag.x
+      | *[in]*  **y**      imag.y
+      | *[in]*  **z**      imag.z
+      | *[in]*  **w**      w (real part)
+
 .. c:function:: void  glm_quat(versor q, float  angle, float  x, float  y, float  z)
 
     | creates NEW quaternion with individual axis components
 
+    | given axis will be normalized
+
     Parameters:
       | *[out]* **q**      quaternion
       | *[in]*  **angle**  angle (radians)
@@ -58,14 +91,24 @@ Functions documentation
       | *[in]*  **y**      axis.y
       | *[in]*  **z**      axis.z
 
-.. c:function:: void  glm_quatv(versor q, float  angle, vec3   v)
+.. c:function:: void  glm_quatv(versor q, float  angle, vec3   axis)
 
     | creates NEW quaternion with axis vector
 
+    | given axis will be normalized
+
     Parameters:
       | *[out]* **q**      quaternion
       | *[in]*  **angle**  angle (radians)
-      | *[in]*  **v**      axis
+      | *[in]*  **axis**   axis (will be normalized)
+
+.. c:function:: void  glm_quat_copy(versor q, versor dest)
+
+    | copy quaternion to another one
+
+    Parameters:
+      | *[in]*  **q**     source quaternion
+      | *[out]* **dest**  destination quaternion
 
 .. c:function:: float  glm_quat_norm(versor q)
 
@@ -77,6 +120,14 @@ Functions documentation
     Returns:
       norm (magnitude)
 
+.. c:function:: void  glm_quat_normalize_to(versor q, versor dest)
+
+    | normalize quaternion and store result in dest, original one will not be normalized
+
+    Parameters:
+      | *[in]*  **q**    quaternion to normalize into
+      | *[out]* **dest** destination quaternion
+
 .. c:function:: void  glm_quat_normalize(versor q)
 
     | normalize quaternion
@@ -84,24 +135,118 @@ Functions documentation
     Parameters:
       | *[in, out]*  **q** quaternion
 
-.. c:function:: float  glm_quat_dot(versor q, versor r)
+.. c:function:: float  glm_quat_dot(versor p, versor q)
 
     dot product of two quaternion
 
     Parameters:
-      | *[in]*  **q1**   quaternion 1
+      | *[in]*  **p**   quaternion 1
-      | *[in]*  **q2**   quaternion 2
+      | *[in]*  **q**   quaternion 2
 
     Returns:
       dot product
 
-.. c:function:: void  glm_quat_mulv(versor q1, versor q2, versor dest)
+.. c:function:: void  glm_quat_conjugate(versor q, versor dest)
+
+    conjugate of quaternion
+
+    Parameters:
+      | *[in]*  **q**      quaternion
+      | *[in]*  **dest**   conjugate
+
+.. c:function:: void  glm_quat_inv(versor q, versor dest)
+
+    inverse of non-zero quaternion
+
+    Parameters:
+      | *[in]*  **q**      quaternion
+      | *[in]*  **dest**   inverse quaternion
+
+.. c:function:: void  glm_quat_add(versor p, versor q, versor dest)
+
+    add (componentwise) two quaternions and store result in dest
+
+    Parameters:
+      | *[in]*  **p**      quaternion 1
+      | *[in]*  **q**      quaternion 2
+      | *[in]*  **dest**   result quaternion
+
+.. c:function:: void  glm_quat_sub(versor p, versor q, versor dest)
+
+    subtract (componentwise) two quaternions and store result in dest
+
+    Parameters:
+      | *[in]*  **p**      quaternion 1
+      | *[in]*  **q**      quaternion 2
+      | *[in]*  **dest**   result quaternion
+
+.. c:function:: float  glm_quat_real(versor q)
+
+    returns real part of quaternion
+
+    Parameters:
+      | *[in]*  **q**   quaternion
+
+    Returns:
+      real part (quat.w)
+
+.. c:function:: void  glm_quat_imag(versor q, vec3 dest)
+
+    returns imaginary part of quaternion
+
+    Parameters:
+      | *[in]*   **q**      quaternion
+      | *[out]*  **dest**   imag
+
+.. c:function:: void  glm_quat_imagn(versor q, vec3 dest)
+
+    returns normalized imaginary part of quaternion
+
+    Parameters:
+      | *[in]*   **q**      quaternion
+      | *[out]*  **dest**   imag
+
+.. c:function:: float  glm_quat_imaglen(versor q)
+
+    returns length of imaginary part of quaternion
+
+    Parameters:
+      | *[in]*   **q**      quaternion
+
+    Returns:
+      norm of imaginary part
+
+.. c:function:: float  glm_quat_angle(versor q)
+
+    returns angle of quaternion
+
+    Parameters:
+      | *[in]*  **q**   quaternion
+
+    Returns:
+      angles of quat (radians)
+
+.. c:function:: void  glm_quat_axis(versor q, versor dest)
+
+    axis of quaternion
+
+    Parameters:
+      | *[in]*   **p**      quaternion
+      | *[out]*  **dest**   axis of quaternion
+
+.. c:function:: void  glm_quat_mul(versor p, versor q, versor dest)
 
     | multiplies two quaternion and stores result in dest
 
+    | this is also called Hamilton Product
+
+    | According to WikiPedia:
+    | The product of two rotation quaternions [clarification needed] will be
+      equivalent to the rotation q followed by the rotation p
+
     Parameters:
-      | *[in]*  **q1**    quaternion 1
+      | *[in]*  **p**     quaternion 1 (first rotation)
-      | *[in]*  **q2**    quaternion 2
+      | *[in]*  **q**     quaternion 2 (second rotation)
       | *[out]* **dest**  result quaternion
 
 .. c:function:: void  glm_quat_mat4(versor q, mat4 dest)
@@ -112,13 +257,100 @@ Functions documentation
       | *[in]*  **q**     quaternion
       | *[out]* **dest**  result matrix
 
+.. c:function:: void  glm_quat_mat4t(versor q, mat4 dest)
+
+    | convert quaternion to mat4 (transposed). This is transposed version of glm_quat_mat4
+
+    Parameters:
+      | *[in]*  **q**     quaternion
+      | *[out]* **dest**  result matrix
+
+.. c:function:: void  glm_quat_mat3(versor q, mat3 dest)
+
+    | convert quaternion to mat3
+
+    Parameters:
+      | *[in]*  **q**     quaternion
+      | *[out]* **dest**  result matrix
+
+.. c:function:: void  glm_quat_mat3t(versor q, mat3 dest)
+
+    | convert quaternion to mat3 (transposed). This is transposed version of glm_quat_mat3
+
+    Parameters:
+      | *[in]*  **q**     quaternion
+      | *[out]* **dest**  result matrix
+
+.. c:function:: void  glm_quat_lerp(versor from, versor to, float t, versor dest)
+
+    | interpolates between two quaternions
+    | using spherical linear interpolation (LERP)
+
+    Parameters:
+      | *[in]*  **from**  from
+      | *[in]*  **to**    to
+      | *[in]*  **t**     interpolant (amount) clamped between 0 and 1
+      | *[out]* **dest**  result quaternion
+
 .. c:function:: void glm_quat_slerp(versor q, versor r, float  t, versor dest)
 
     | interpolates between two quaternions
     | using spherical linear interpolation (SLERP)
 
     Parameters:
-      | *[in]*  **q**     from
+      | *[in]*  **from**  from
-      | *[in]*  **r**     to
+      | *[in]*  **to**    to
-      | *[in]*  **t**     amout
+      | *[in]*  **t**     interpolant (amount) clamped between 0 and 1
       | *[out]* **dest**  result quaternion
+
+.. c:function:: void  glm_quat_look(vec3 eye, versor ori, mat4 dest)
+
+    | creates view matrix using quaternion as camera orientation
+
+    Parameters:
+      | *[in]*  **eye**   eye
+      | *[in]*  **ori**   orientation in world space as quaternion
+      | *[out]* **dest**  result matrix
+
+.. c:function:: void  glm_quat_for(vec3 dir, vec3 fwd, vec3 up, versor dest)
+
+    | creates look rotation quaternion
+
+    Parameters:
+      | *[in]*  **dir**   direction to look
+      | *[in]*  **fwd**   forward vector
+      | *[in]*  **up**    up vector
+      | *[out]* **dest**  result matrix
+
+.. c:function:: void  glm_quat_forp(vec3 from, vec3 to, vec3 fwd, vec3 up, versor dest)
+
+    | creates look rotation quaternion using source and  destination positions p suffix stands for position
+
+    | this is similar to glm_quat_for except this computes direction for glm_quat_for for you.
+
+    Parameters:
+      | *[in]*  **from**  source point
+      | *[in]*  **to**    destination point
+      | *[in]*  **fwd**   forward vector
+      | *[in]*  **up**    up vector
+      | *[out]* **dest**  result matrix
+
+.. c:function:: void  glm_quat_rotatev(versor q, vec3 v, vec3 dest)
+
+    | crotate vector using using quaternion
+
+    Parameters:
+      | *[in]*  **q**     quaternion
+      | *[in]*  **v**     vector to rotate
+      | *[out]* **dest**  rotated vector
+
+.. c:function:: void glm_quat_rotate(mat4 m, versor q, mat4 dest)
+
+    | rotate existing transform matrix using quaternion
+
+    instead of passing identity matrix, consider to use quat_mat4 functions
+
+    Parameters:
+      | *[in]*  **m**     existing transform matrix to rotate
+      | *[in]*  **q**     quaternion
+      | *[out]* **dest**  rotated matrix/transform

docs/source/util.rst

@@ -22,6 +22,7 @@ Functions:
 #. :c:func:`glm_min`
 #. :c:func:`glm_max`
 #. :c:func:`glm_clamp`
+#. :c:func:`glm_lerp`
 
 Functions documentation
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -121,3 +122,17 @@ Functions documentation
 
     Returns:
       clamped value
+
+.. c:function:: float  glm_lerp(float from, float to, float t)
+
+    linear interpolation between two number
+
+    | formula:  from + s * (to - from)
+
+    Parameters:
+      | *[in]*  **from**   from value
+      | *[in]*  **to**     to value
+      | *[in]*  **t**      interpolant (amount) clamped between 0 and 1
+
+    Returns:
+       interpolated value

docs/source/vec3-ext.rst

@@ -23,6 +23,11 @@ Functions:
 #. :c:func:`glm_vec_eqv_eps`
 #. :c:func:`glm_vec_max`
 #. :c:func:`glm_vec_min`
+#. :c:func:`glm_vec_isnan`
+#. :c:func:`glm_vec_isinf`
+#. :c:func:`glm_vec_isvalid`
+#. :c:func:`glm_vec_sign`
+#. :c:func:`glm_vec_sqrt`
 
 Functions documentation
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -96,3 +101,43 @@ Functions documentation
 
     Parameters:
       | *[in]*  **v**  vector
+
+.. c:function:: bool glm_vec_isnan(vec3 v)
+
+    | check if one of items is NaN (not a number)
+    | you should only use this in DEBUG mode or very critical asserts
+
+    Parameters:
+      | *[in]*  **v**  vector
+
+.. c:function:: bool glm_vec_isinf(vec3 v)
+
+    | check if one of items is INFINITY
+    | you should only use this in DEBUG mode or very critical asserts
+
+    Parameters:
+      | *[in]*  **v**  vector
+
+.. c:function:: bool glm_vec_isvalid(vec3 v)
+
+    | check if all items are valid number
+    | you should only use this in DEBUG mode or very critical asserts
+
+    Parameters:
+      | *[in]*  **v**  vector
+
+.. c:function:: void glm_vec_sign(vec3 v, vec3 dest)
+
+    get sign of 32 bit float as +1, -1, 0
+
+    Parameters:
+      | *[in]*   **v**     vector
+      | *[out]*  **dest**  sign vector (only keeps signs as -1, 0, -1)
+
+.. c:function:: void glm_vec_sqrt(vec3 v, vec3 dest)
+
+    square root of each vector item
+
+    Parameters:
+      | *[in]*   **v**     vector
+      | *[out]*  **dest**  destination vector (sqrt(v))

docs/source/vec3.rst

@@ -40,6 +40,7 @@ Functions:
 #. :c:func:`glm_vec_scale`
 #. :c:func:`glm_vec_scale_as`
 #. :c:func:`glm_vec_flipsign`
+#. :c:func:`glm_vec_flipsign_to`
 #. :c:func:`glm_vec_inv`
 #. :c:func:`glm_vec_inv_to`
 #. :c:func:`glm_vec_normalize`
@@ -54,6 +55,7 @@ Functions:
 #. :c:func:`glm_vec_minv`
 #. :c:func:`glm_vec_ortho`
 #. :c:func:`glm_vec_clamp`
+#. :c:func:`glm_vec_lerp`
 
 Functions documentation
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -159,6 +161,14 @@ Functions documentation
     Parameters:
       | *[in, out]*  **v**    vector
 
+.. c:function:: void  glm_vec_flipsign_to(vec3 v, vec3 dest)
+
+    flip sign of all vec3 members and store result in dest
+
+    Parameters:
+      | *[in]*  **v**       vector
+      | *[out]* **dest**    negated vector
+
 .. c:function:: void  glm_vec_inv(vec3 v)
 
     make vector as inverse/opposite of itself
@@ -206,7 +216,7 @@ Functions documentation
 
     Parameters:
       | *[in, out]*  **v**      vector
-      | *[in]*       **axis**   axis vector (must be unit vector)
+      | *[in]*       **axis**   axis vector (will be normalized)
       | *[out]*      **angle**  angle (radians)
 
 .. c:function:: void  glm_vec_rotate_m4(mat4 m, vec3 v, vec3 dest)
@@ -281,3 +291,15 @@ Functions documentation
       | *[in, out]*  **v**       vector
       | *[in]*       **minVal**  minimum value
       | *[in]*       **maxVal**  maximum value
+
+.. c:function:: void  glm_vec_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

docs/source/vec4-ext.rst

@@ -96,3 +96,43 @@ Functions documentation
 
     Parameters:
       | *[in]*  **v**  vector
+
+.. c:function:: bool glm_vec4_isnan(vec4 v)
+
+    | check if one of items is NaN (not a number)
+    | you should only use this in DEBUG mode or very critical asserts
+
+    Parameters:
+      | *[in]*  **v**  vector
+
+.. c:function:: bool glm_vec4_isinf(vec4 v)
+
+    | check if one of items is INFINITY
+    | you should only use this in DEBUG mode or very critical asserts
+
+    Parameters:
+      | *[in]*  **v**  vector
+
+.. c:function:: bool glm_vec4_isvalid(vec4 v)
+
+    | check if all items are valid number
+    | you should only use this in DEBUG mode or very critical asserts
+
+    Parameters:
+      | *[in]*  **v**  vector
+
+.. c:function:: void glm_vec4_sign(vec4 v, vec4 dest)
+
+    get sign of 32 bit float as +1, -1, 0
+
+    Parameters:
+      | *[in]*   **v**     vector
+      | *[out]*  **dest**  sign vector (only keeps signs as -1, 0, -1)
+
+.. c:function:: void glm_vec4_sqrt(vec4 v, vec4 dest)
+
+    square root of each vector item
+
+    Parameters:
+      | *[in]*   **v**     vector
+      | *[out]*  **dest**  destination vector (sqrt(v))

docs/source/vec4.rst

@@ -32,6 +32,7 @@ Functions:
 #. :c:func:`glm_vec4_scale`
 #. :c:func:`glm_vec4_scale_as`
 #. :c:func:`glm_vec4_flipsign`
+#. :c:func:`glm_vec_flipsign_to`
 #. :c:func:`glm_vec4_inv`
 #. :c:func:`glm_vec4_inv_to`
 #. :c:func:`glm_vec4_normalize`
@@ -40,6 +41,12 @@ Functions:
 #. :c:func:`glm_vec4_maxv`
 #. :c:func:`glm_vec4_minv`
 #. :c:func:`glm_vec4_clamp`
+#. :c:func:`glm_vec4_lerp`
+#. :c:func:`glm_vec4_isnan`
+#. :c:func:`glm_vec4_isinf`
+#. :c:func:`glm_vec4_isvalid`
+#. :c:func:`glm_vec4_sign`
+#. :c:func:`glm_vec4_sqrt`
 
 Functions documentation
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -146,6 +153,14 @@ Functions documentation
     Parameters:
     | *[in, out]*  **v**    vector
 
+.. c:function:: void  glm_vec4_flipsign_to(vec4 v, vec4 dest)
+
+    flip sign of all vec4 members and store result in dest
+
+    Parameters:
+      | *[in]*  **v**       vector
+      | *[out]* **dest**    negated vector
+
 .. c:function:: void  glm_vec4_inv(vec4 v)
 
     make vector as inverse/opposite of itself
@@ -213,3 +228,15 @@ Functions documentation
       | *[in, out]*  **v**       vector
       | *[in]*       **minVal**  minimum value
       | *[in]*       **maxVal**  maximum value
+
+.. c:function:: void  glm_vec4_lerp(vec4 from, vec4 to, float t, vec4 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

include/cglm/quat.h

@@ -226,8 +226,8 @@ glm_quat_normalize(versor q) {
 /*!
  * @brief dot product of two quaternion
  *
- * @param[in]  q1  quaternion 1
+ * @param[in]  p  quaternion 1
- * @param[in]  q2  quaternion 2
+ * @param[in]  q  quaternion 2
  */
 CGLM_INLINE
 float
@@ -303,6 +303,7 @@ glm_quat_real(versor q) {
  * @brief returns imaginary part of quaternion
  *
  * @param[in]   q    quaternion
+ * @param[out]  dest imag
  */
 CGLM_INLINE
 void
@@ -649,6 +650,7 @@ glm_quat_look(vec3 eye, versor ori, mat4 dest) {
 /*!
  * @brief creates look rotation quaternion
  *
+ * @param[in]   dir   direction to look
  * @param[in]   fwd   forward vector
  * @param[in]   up    up vector
  * @param[out]  dest  destination quaternion
@@ -683,6 +685,7 @@ glm_quat_for(vec3 dir, vec3 fwd, vec3 up, versor dest) {
  *
  * @param[in]   from  source point
  * @param[in]   to    destination point
+ * @param[in]   fwd   forward vector
  * @param[in]   up    up vector
  * @param[out]  dest  destination quaternion
  */
@@ -699,7 +702,7 @@ glm_quat_forp(vec3 from, vec3 to, vec3 fwd, vec3 up, versor dest) {
  *
  * @param[in]   q     quaternion
  * @param[in]   v     vector to rotate
- * @param[out]  dest  destination vector
+ * @param[out]  dest  rotated vector
  */
 CGLM_INLINE
 void
@@ -727,7 +730,7 @@ glm_quat_rotatev(versor q, vec3 v, vec3 dest) {
  *
  * @param[in]   m     existing transform matrix
  * @param[in]   q     quaternion
- * @param[out]  dest  destination matrix
+ * @param[out]  dest  rotated matrix/transform
  */
 CGLM_INLINE
 void

include/cglm/vec3.h

@@ -246,7 +246,7 @@ glm_vec_flipsign(vec3 v) {
  * @brief flip sign of all vec3 members and store result in dest
  *
  * @param[in]   v     vector
- * @param[out]  dest  vector
+ * @param[out]  dest  result vector
  */
 CGLM_INLINE
 void

include/cglm/vec4-ext.h

@@ -175,7 +175,7 @@ glm_vec4_min(vec4 v) {
 }
 
 /*!
- * @brief check if all items are NaN (not a number)
+ * @brief check if one of items is NaN (not a number)
  *        you should only use this in DEBUG mode or very critical asserts
  *
  * @param[in] v vector
@@ -187,7 +187,7 @@ glm_vec4_isnan(vec4 v) {
 }
 
 /*!
- * @brief check if all items are INFINITY
+ * @brief check if one of items is INFINITY
  *        you should only use this in DEBUG mode or very critical asserts
  *
  * @param[in] v vector