From 77e62163ea3b9403485e0538283f30fb2508a873 Mon Sep 17 00:00:00 2001 From: Recep Aslantas Date: Mon, 26 Feb 2018 16:21:04 +0300 Subject: [PATCH] docs: add docs for vec3 --- docs/source/affine.rst | 10 +- docs/source/api.rst | 1 + docs/source/vec3.rst | 273 +++++++++++++++++++++++++++++++++++++++++ include/cglm/vec3.h | 9 +- 4 files changed, 285 insertions(+), 8 deletions(-) create mode 100644 docs/source/vec3.rst diff --git a/docs/source/affine.rst b/docs/source/affine.rst index ee6c2ed..fdb2ef3 100644 --- a/docs/source/affine.rst +++ b/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 diff --git a/docs/source/api.rst b/docs/source/api.rst index 164dec4..57fe2b3 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -29,3 +29,4 @@ Follow the :doc:`build` documentation for this affine mat4 mat3 + vec3 diff --git a/docs/source/vec3.rst b/docs/source/vec3.rst new file mode 100644 index 0000000..55a1dc8 --- /dev/null +++ b/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 diff --git a/include/cglm/vec3.h b/include/cglm/vec3.h index 8600711..26adf7d 100644 --- a/include/cglm/vec3.h +++ b/include/cglm/vec3.h @@ -135,8 +135,8 @@ glm_vec_cross(vec3 a, vec3 b, vec3 d) { /*! * @brief norm * norm (magnitude) of vec * - * 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 + * 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 * * @param[in] v vector @@ -309,13 +309,16 @@ 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 float glm_vec_angle(vec3 v1, vec3 v2) { float norm; - + /* maybe compiler generate approximation instruction (rcp) */ norm = 1.0f / (glm_vec_norm(v1) * glm_vec_norm(v2)); return acosf(glm_vec_dot(v1, v2) * norm);