External/cglm
1
0
Fork 0
mirror of https://github.com/recp/cglm.git synced 2025-10-03 16:51:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Recep Aslantas
2018-04-11 12:34:20 +03:00
parent de55850136
commit 0e63c245d4
9 changed files with 414 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
docs/source/quat.rst
View File

@@ -5,17 +5,16 @@ quaternions
Header: cglm/quat.h
**Important:** *cglm* stores quaternion as [w, x, y, z] in memory, don't
forget that when changing quaternion items manually. For instance *quat[3]*
is *quat.z* and *quat[0*] is *quat.w*. This may change in the future if *cglm*
will got enough request to do that. Probably it will not be changed in near
future
**Important:** *cglm* stores quaternion as **[x, y, z, w]** in memory
since **v0.4.0** it was **[w, x, y, z]**
before v0.4.0 ( **v0.3.5 and earlier** ). w is real part.
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
something else. This will not affect existing functions for your engine because
*versor* is alias of *vec4*
- You can rotate transform matrix using quaterion
- You can rotate vector using quaterion
- 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]* **q2** quaternion 2
| *[in]* **p** quaternion 1
| *[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]* **q2** quaternion 2
| *[in]* **p** quaternion 1 (first rotation)
| *[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]* **r** to
| *[in]* **t** amout
| *[in]* **from** from
| *[in]* **to** to
| *[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

15
docs/source/util.rst
View File

@@ -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

45
docs/source/vec3-ext.rst
View File

@@ -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))

26
docs/source/vec3.rst
View File

@@ -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
~~~~~~~~~~~~~~~~~~~~~~~
@@ -157,7 +159,15 @@ Functions documentation
flip sign of all vec3 members
Parameters:
| *[in, out]* **v** vector
| *[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)
@@ -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

40
docs/source/vec4-ext.rst
View File

@@ -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))

27
docs/source/vec4.rst
View File

@@ -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

11
include/cglm/quat.h
View File

@@ -226,8 +226,8 @@ glm_quat_normalize(versor q) {
/*!
* @brief dot product of two quaternion
*
* @param[in] q1 quaternion 1
* @param[in] q2 quaternion 2
* @param[in] p quaternion 1
* @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

2
include/cglm/vec3.h
View File

@@ -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

4
include/cglm/vec4-ext.h
View File

@@ -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