This repository has been archived on 2024-07-27. You can view files and clone it, but cannot push or open issues or pull requests.
Wotos-mpv/lib/cglm/docs/source/vec3.rst

504 lines
13 KiB
ReStructuredText
Raw Normal View History

2023-01-07 11:49:22 +00:00
.. 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