diff --git a/docs/source/api.rst b/docs/source/api.rst index 408eae7..10b0fa3 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -35,10 +35,13 @@ Follow the :doc:`build` documentation for this euler mat4 mat3 + mat2 vec3 vec3-ext vec4 vec4-ext + vec2 + vec2-ext color plane project diff --git a/docs/source/mat2.rst b/docs/source/mat2.rst new file mode 100644 index 0000000..6e55c83 --- /dev/null +++ b/docs/source/mat2.rst @@ -0,0 +1,179 @@ +.. default-domain:: C + +mat2 +==== + +Header: cglm/mat2.h + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Macros: + +1. GLM_mat2_IDENTITY_INIT +#. GLM_mat2_ZERO_INIT +#. GLM_mat2_IDENTITY +#. GLM_mat2_ZERO + +Functions: + +1. :c:func:`glm_mat2_copy` +#. :c:func:`glm_mat2_identity` +#. :c:func:`glm_mat2_identity_array` +#. :c:func:`glm_mat2_zero` +#. :c:func:`glm_mat2_mul` +#. :c:func:`glm_mat2_transpose_to` +#. :c:func:`glm_mat2_transpose` +#. :c:func:`glm_mat2_mulv` +#. :c:func:`glm_mat2_scale` +#. :c:func:`glm_mat2_det` +#. :c:func:`glm_mat2_inv` +#. :c:func:`glm_mat2_trace` +#. :c:func:`glm_mat2_swap_col` +#. :c:func:`glm_mat2_swap_row` +#. :c:func:`glm_mat2_rmc` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_mat2_copy(mat2 mat, mat2 dest) + + copy mat2 to another one (dest). + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat2_identity(mat2 mat) + + copy identity mat2 to mat, or makes mat to identiy + + Parameters: + | *[out]* **mat** matrix + +.. c:function:: void glm_mat2_identity_array(mat2 * __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_mat2_zero(mat2 mat) + + make given matrix zero + + Parameters: + | *[in,out]* **mat** matrix to + +.. c:function:: void glm_mat2_mul(mat2 m1, mat2 m2, mat2 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 + + mat2 m = GLM_mat2_IDENTITY_INIT; + glm_mat2_mul(m, m, m); + + Parameters: + | *[in]* **m1** left matrix + | *[in]* **m2** right matrix + | *[out]* **dest** destination matrix + +.. c:function:: void glm_mat2_transpose_to(mat2 m, mat2 dest) + + transpose mat4 and store in dest + source matrix will not be transposed unless dest is m + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat2_transpose(mat2 m) + + tranpose mat2 and store result in same matrix + + Parameters: + | *[in]* **mat** source + | *[out]* **dest** destination + +.. c:function:: void glm_mat2_mulv(mat2 m, vec2 v, vec2 dest) + + multiply mat4 with vec4 (column vector) and store in dest vector + + Parameters: + | *[in]* **mat** mat2 (left) + | *[in]* **v** vec2 (right, column vector) + | *[out]* **dest** destination (result, column vector) + +.. c:function:: void glm_mat2_scale(mat2 m, float s) + + multiply matrix with scalar + + Parameters: + | *[in, out]* **mat** matrix + | *[in]* **dest** scalar + +.. c:function:: float glm_mat2_det(mat2 mat) + + returns mat2 determinant + + Parameters: + | *[in]* **mat** matrix + + Returns: + mat2 determinant + +.. c:function:: void glm_mat2_inv(mat2 mat, mat2 dest) + + inverse mat2 and store in dest + + Parameters: + | *[in]* **mat** matrix + | *[out]* **dest** destination (inverse matrix) + +.. c:function:: void glm_mat2_trace(mat2 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_mat2_swap_col(mat2 mat, int col1, int col2) + + swap two matrix columns + + Parameters: + | *[in, out]* **mat** matrix + | *[in]* **col1** col1 + | *[in]* **col2** col2 + +.. c:function:: void glm_mat2_swap_row(mat2 mat, int row1, int row2) + + swap two matrix rows + + Parameters: + | *[in, out]* **mat** matrix + | *[in]* **row1** row1 + | *[in]* **row2** row2 + +.. c:function:: float glm_mat2_rmc(vec2 r, mat2 m, vec2 c) + + | **rmc** stands for **Row** * **Matrix** * **Column** + + | helper for R (row vector) * M (matrix) * C (column vector) + + | the result is scalar because R * M = Matrix1x2 (row vector), + | then Matrix1x2 * Vec2 (column vector) = Matrix1x1 (Scalar) + + Parameters: + | *[in]* **r** row vector or matrix1x2 + | *[in]* **m** matrix2x2 + | *[in]* **c** column vector or matrix2x1 + + Returns: + scalar value e.g. Matrix1x1 diff --git a/docs/source/vec2-ext.rst b/docs/source/vec2-ext.rst new file mode 100644 index 0000000..619d48f --- /dev/null +++ b/docs/source/vec2-ext.rst @@ -0,0 +1,134 @@ +.. default-domain:: C + +vec2 extra +========== + +Header: cglm/vec2-ext.h + +There are some functions are in called in extra header. These are called extra +because they are not used like other functions in vec2.h in the future some of +these functions ma be moved to vec2 header. + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions: + +1. :c:func:`glm_vec2_fill` +#. :c:func:`glm_vec2_eq` +#. :c:func:`glm_vec2_eq_eps` +#. :c:func:`glm_vec2_eq_all` +#. :c:func:`glm_vec2_eqv` +#. :c:func:`glm_vec2_eqv_eps` +#. :c:func:`glm_vec2_max` +#. :c:func:`glm_vec2_min` +#. :c:func:`glm_vec2_isnan` +#. :c:func:`glm_vec2_isinf` +#. :c:func:`glm_vec2_isvalid` +#. :c:func:`glm_vec2_sign` +#. :c:func:`glm_vec2_sqrt` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_vec2_fill(vec2 v, float val) + + fill a vector with specified value + + Parameters: + | *[in,out]* **dest** destination + | *[in]* **val** value + + +.. c:function:: bool glm_vec2_eq(vec2 v, float val) + + check if vector is equal to value (without epsilon) + + Parameters: + | *[in]* **v** vector + | *[in]* **val** value + +.. c:function:: bool glm_vec2_eq_eps(vec2 v, float val) + + check if vector is equal to value (with epsilon) + + Parameters: + | *[in]* **v** vector + | *[in]* **val** value + +.. c:function:: bool glm_vec2_eq_all(vec2 v) + + check if vectors members are equal (without epsilon) + + Parameters: + | *[in]* **v** vector + +.. c:function:: bool glm_vec2_eqv(vec2 v1, vec2 v2) + + check if vector is equal to another (without epsilon) vector + + Parameters: + | *[in]* **vec** vector 1 + | *[in]* **vec** vector 2 + +.. c:function:: bool glm_vec2_eqv_eps(vec2 v1, vec2 v2) + + check if vector is equal to another (with epsilon) + + Parameters: + | *[in]* **v1** vector1 + | *[in]* **v2** vector2 + +.. c:function:: float glm_vec2_max(vec2 v) + + max value of vector + + Parameters: + | *[in]* **v** vector + +.. c:function:: float glm_vec2_min(vec2 v) + + min value of vector + + Parameters: + | *[in]* **v** vector + +.. c:function:: bool glm_vec2_isnan(vec2 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_vec2_isinf(vec2 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_vec2_isvalid(vec2 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_vec2_sign(vec2 v, vec2 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_vec2_sqrt(vec2 v, vec2 dest) + + square root of each vector item + + Parameters: + | *[in]* **v** vector + | *[out]* **dest** destination vector (sqrt(v)) diff --git a/docs/source/vec2.rst b/docs/source/vec2.rst new file mode 100644 index 0000000..1b5888c --- /dev/null +++ b/docs/source/vec2.rst @@ -0,0 +1,375 @@ +.. default-domain:: C + +vec2 +==== + +Header: cglm/vec2.h + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Macros: + +1. GLM_vec2_ONE_INIT +#. GLM_vec2_ZERO_INIT +#. GLM_vec2_ONE +#. GLM_vec2_ZERO + +Functions: + +1. :c:func:`glm_vec2` +#. :c:func:`glm_vec2_copy` +#. :c:func:`glm_vec2_zero` +#. :c:func:`glm_vec2_one` +#. :c:func:`glm_vec2_dot` +#. :c:func:`glm_vec2_cross` +#. :c:func:`glm_vec2_norm2` +#. :c:func:`glm_vec2_norm` +#. :c:func:`glm_vec2_add` +#. :c:func:`glm_vec2_adds` +#. :c:func:`glm_vec2_sub` +#. :c:func:`glm_vec2_subs` +#. :c:func:`glm_vec2_mul` +#. :c:func:`glm_vec2_scale` +#. :c:func:`glm_vec2_scale_as` +#. :c:func:`glm_vec2_div` +#. :c:func:`glm_vec2_divs` +#. :c:func:`glm_vec2_addadd` +#. :c:func:`glm_vec2_subadd` +#. :c:func:`glm_vec2_muladd` +#. :c:func:`glm_vec2_muladds` +#. :c:func:`glm_vec2_maxadd` +#. :c:func:`glm_vec2_minadd` +#. :c:func:`glm_vec2_negate` +#. :c:func:`glm_vec2_negate_to` +#. :c:func:`glm_vec2_normalize` +#. :c:func:`glm_vec2_normalize_to` +#. :c:func:`glm_vec2_rotate` +#. :c:func:`glm_vec2_distance2` +#. :c:func:`glm_vec2_distance` +#. :c:func:`glm_vec2_maxv` +#. :c:func:`glm_vec2_minv` +#. :c:func:`glm_vec2_clamp` +#. :c:func:`glm_vec2_lerp` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_vec2(vec4 v4, vec2 dest) + + init vec2 using vec3 + + Parameters: + | *[in]* **v3** vector3 + | *[out]* **dest** destination + +.. c:function:: void glm_vec2_copy(vec2 a, vec2 dest) + + copy all members of [a] to [dest] + + Parameters: + | *[in]* **a** source + | *[out]* **dest** destination + +.. c:function:: void glm_vec2_zero(vec2 v) + + makes all members 0.0f (zero) + + Parameters: + | *[in, out]* **v** vector + +.. c:function:: void glm_vec2_one(vec2 v) + + makes all members 1.0f (one) + + Parameters: + | *[in, out]* **v** vector + +.. c:function:: float glm_vec2_dot(vec2 a, vec2 b) + + dot product of vec2 + + Parameters: + | *[in]* **a** vector1 + | *[in]* **b** vector2 + + Returns: + dot product + +.. c:function:: void glm_vec2_cross(vec2 a, vec2 b, vec2 d) + + cross product of two vector (RH) + + | ref: http://allenchou.net/2013/07/cross-product-of-2d-vectors/ + + Parameters: + | *[in]* **a** vector 1 + | *[in]* **b** vector 2 + | *[out]* **dest** destination + + Returns: + Z component of cross product + +.. c:function:: float glm_vec2_norm2(vec2 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_vec2_norm(vec2 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_vec2_add(vec2 a, vec2 b, vec2 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_vec2_adds(vec2 a, float s, vec2 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_vec2_sub(vec2 v1, vec2 v2, vec2 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_vec2_subs(vec2 v, float s, vec2 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_vec2_mul(vec2 a, vec2 b, vec2 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_vec2_scale(vec2 v, float s, vec2 dest) + + multiply/scale vec2 vector with scalar: result = v * s + + + Parameters: + | *[in]* **v** vector + | *[in]* **s** scalar + | *[out]* **dest** destination vector + +.. c:function:: void glm_vec2_scale_as(vec2 v, float s, vec2 dest) + + make vec2 vector scale as specified: result = unit(v) * s + + Parameters: + | *[in]* **v** vector + | *[in]* **s** scalar + | *[out]* **dest** destination vector + +.. c:function:: void glm_vec2_div(vec2 a, vec2 b, vec2 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_vec2_divs(vec2 v, float s, vec2 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_vec2_addadd(vec2 a, vec2 b, vec2 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_vec2_subadd(vec2 a, vec2 b, vec2 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_vec2_muladd(vec2 a, vec2 b, vec2 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_vec2_muladds(vec2 a, float s, vec2 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_vec2_maxadd(vec2 a, vec2 b, vec2 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_vec2_minadd(vec2 a, vec2 b, vec2 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_vec2_negate(vec2 v) + + negate vector components + + Parameters: + | *[in, out]* **v** vector + +.. c:function:: void glm_vec2_negate_to(vec2 v, vec2 dest) + + negate vector components and store result in dest + + Parameters: + | *[in]* **v** vector + | *[out]* **dest** negated vector + +.. c:function:: void glm_vec2_normalize(vec2 v) + + normalize vec2 and store result in same vec + + Parameters: + | *[in, out]* **v** vector + +.. c:function:: void glm_vec2_normalize_to(vec2 vec, vec2 dest) + + normalize vec2 to dest + + Parameters: + | *[in]* **vec** source + | *[out]* **dest** destination + +.. c:function:: void glm_vec2_rotate(vec2 v, float angle, vec2 dest) + + rotate vec2 around axis by angle using Rodrigues' rotation formula + + Parameters: + | *[in]* **v** vector + | *[in]* **axis** axis vector + | *[out]* **dest** destination + +.. c:function:: float glm_vec2_distance2(vec2 v1, vec2 v2) + + squared distance between two vectors + + Parameters: + | *[in]* **mat** vector1 + | *[in]* **row1** vector2 + + Returns: + | squared distance (distance * distance) + +.. c:function:: float glm_vec2_distance(vec2 v1, vec2 v2) + + distance between two vectors + + Parameters: + | *[in]* **mat** vector1 + | *[in]* **row1** vector2 + + Returns: + | distance + +.. c:function:: void glm_vec2_maxv(vec2 v1, vec2 v2, vec2 dest) + + max values of vectors + + Parameters: + | *[in]* **v1** vector1 + | *[in]* **v2** vector2 + | *[out]* **dest** destination + +.. c:function:: void glm_vec2_minv(vec2 v1, vec2 v2, vec2 dest) + + min values of vectors + + Parameters: + | *[in]* **v1** vector1 + | *[in]* **v2** vector2 + | *[out]* **dest** destination + +.. c:function:: void glm_vec2_clamp(vec2 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_vec2_lerp(vec2 from, vec2 to, float t, vec2 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