diff --git a/docs/source/quat.rst b/docs/source/quat.rst index 863eed5..ab99838 100644 --- a/docs/source/quat.rst +++ b/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 - 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 diff --git a/docs/source/util.rst b/docs/source/util.rst index a9f4066..f8dbac4 100644 --- a/docs/source/util.rst +++ b/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 diff --git a/docs/source/vec3-ext.rst b/docs/source/vec3-ext.rst index e632de9..c2c0bfc 100644 --- a/docs/source/vec3-ext.rst +++ b/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)) diff --git a/docs/source/vec3.rst b/docs/source/vec3.rst index 355178d..8529333 100644 --- a/docs/source/vec3.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~ @@ -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 diff --git a/docs/source/vec4-ext.rst b/docs/source/vec4-ext.rst index 11613ad..722424e 100644 --- a/docs/source/vec4-ext.rst +++ b/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)) diff --git a/docs/source/vec4.rst b/docs/source/vec4.rst index ac1b9c5..6955246 100644 --- a/docs/source/vec4.rst +++ b/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 diff --git a/include/cglm/quat.h b/include/cglm/quat.h index c9927bb..d82a301 100644 --- a/include/cglm/quat.h +++ b/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] 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 diff --git a/include/cglm/vec3.h b/include/cglm/vec3.h index 1cbf508..714165b 100644 --- a/include/cglm/vec3.h +++ b/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 diff --git a/include/cglm/vec4-ext.h b/include/cglm/vec4-ext.h index 77ba1fa..53b02a8 100644 --- a/include/cglm/vec4-ext.h +++ b/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