From 878e8297672c73b04f8595c78320148dfdd7c428 Mon Sep 17 00:00:00 2001 From: Recep Aslantas Date: Sun, 23 Oct 2022 12:00:17 +0300 Subject: [PATCH] update docs --- docs/source/affine-common.rst | 129 ++++++++++++++++++ docs/source/affine-post.rst | 129 ++++++++++++++++++ docs/source/affine-pre.rst | 240 ++++++++++++++++++++++++++++++++++ docs/source/affine.rst | 239 +++++++-------------------------- docs/source/project.rst | 35 +++-- 5 files changed, 569 insertions(+), 203 deletions(-) create mode 100644 docs/source/affine-common.rst create mode 100644 docs/source/affine-post.rst create mode 100644 docs/source/affine-pre.rst diff --git a/docs/source/affine-common.rst b/docs/source/affine-common.rst new file mode 100644 index 0000000..b66352c --- /dev/null +++ b/docs/source/affine-common.rst @@ -0,0 +1,129 @@ +.. default-domain:: C + +3D Affine Transforms (common) +================================================================================ + +Common transfrom functions. + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions: + +1. :c:func:`glm_translate_make` +#. :c:func:`glm_scale_to` +#. :c:func:`glm_scale_make` +#. :c:func:`glm_scale` +#. :c:func:`glm_scale_uni` +#. :c:func:`glm_rotate_make` +#. :c:func:`glm_rotate_atm` +#. :c:func:`glm_decompose_scalev` +#. :c:func:`glm_uniscaled` +#. :c:func:`glm_decompose_rs` +#. :c:func:`glm_decompose` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_translate_make(mat4 m, vec3 v) + + creates NEW translate transform matrix by *v* vector. + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** translate vector [x, y, z] + +.. c:function:: void glm_scale_to(mat4 m, vec3 v, mat4 dest) + + scale existing transform matrix by *v* vector and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **v** scale vector [x, y, z] + | *[out]* **dest** scaled matrix + +.. c:function:: void glm_scale_make(mat4 m, vec3 v) + + creates NEW scale matrix by v vector + + Parameters: + | *[out]* **m** affine transfrom + | *[in]* **v** scale vector [x, y, z] + +.. c:function:: void glm_scale(mat4 m, vec3 v) + + scales existing transform matrix by v vector + and stores result in same matrix + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** scale vector [x, y, z] + +.. c:function:: void glm_scale_uni(mat4 m, float s) + + applies uniform scale to existing transform matrix v = [s, s, s] + and stores result in same matrix + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** scale factor + +.. c:function:: void glm_rotate_make(mat4 m, float angle, vec3 axis) + + creates NEW rotation matrix by angle and axis, + axis will be normalized so you don't need to normalize it + + Parameters: + | *[out]* **m** affine transfrom + | *[in]* **axis** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_rotate_atm(mat4 m, vec3 pivot, float angle, vec3 axis) + + | creates NEW rotation matrix by angle and axis at given point + | this creates rotation matrix, it assumes you don't have a matrix + + | this should work faster than glm_rotate_at because it reduces one glm_translate. + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **pivot** pivot, anchor point, rotation center + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_decompose_scalev(mat4 m, vec3 s) + + decompose scale vector + + Parameters: + | *[in]* **m** affine transform + | *[out]* **s** scale vector (Sx, Sy, Sz) + +.. c:function:: bool glm_uniscaled(mat4 m) + + returns true if matrix is uniform scaled. + This is helpful for creating normal matrix. + + Parameters: + | *[in]* **m** matrix + +.. c:function:: void glm_decompose_rs(mat4 m, mat4 r, vec3 s) + + decompose rotation matrix (mat4) and scale vector [Sx, Sy, Sz] + DON'T pass projected matrix here + + Parameters: + | *[in]* **m** affine transform + | *[out]* **r** rotation matrix + | *[out]* **s** scale matrix + +.. c:function:: void glm_decompose(mat4 m, vec4 t, mat4 r, vec3 s) + + decompose affine transform, TODO: extract shear factors. + DON'T pass projected matrix here + + Parameters: + | *[in]* **m** affine transfrom + | *[out]* **t** translation vector + | *[out]* **r** rotation matrix (mat4) + | *[out]* **s** scaling vector [X, Y, Z] diff --git a/docs/source/affine-post.rst b/docs/source/affine-post.rst new file mode 100644 index 0000000..b1d268d --- /dev/null +++ b/docs/source/affine-post.rst @@ -0,0 +1,129 @@ +.. default-domain:: C + +3D Affine Transforms (post) +================================================================================ + +Post transfrom functions are similar to pre transform functions except order of application is reversed. +Post transform functions are applied after the object is transformed with given (model matrix) transfrom. + +Ther are named af + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions: + +1. :c:func:`glm_translated_to` +#. :c:func:`glm_translated` +#. :c:func:`glm_translated_x` +#. :c:func:`glm_translated_y` +#. :c:func:`glm_translated_z` +#. :c:func:`glm_rotated_x` +#. :c:func:`glm_rotated_y` +#. :c:func:`glm_rotated_z` +#. :c:func:`glm_rotated` +#. :c:func:`glm_rotated_at` +#. :c:func:`glm_spinned` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_translated_to(mat4 m, vec3 v, mat4 dest) + + translate existing transform matrix by *v* vector and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **v** translate vector [x, y, z] + | *[out]* **dest** translated matrix + +.. c:function:: void glm_translated(mat4 m, vec3 v) + + translate existing transform matrix by *v* vector + and stores result in same matrix + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** translate vector [x, y, z] + +.. c:function:: void glm_translated_x(mat4 m, float x) + + translate existing transform matrix by x factor + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** x factor + +.. c:function:: void glm_translated_y(mat4 m, float y) + + translate existing transform matrix by *y* factor + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** y factor + +.. c:function:: void glm_translated_z(mat4 m, float z) + + translate existing transform matrix by *z* factor + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** z factor + +.. c:function:: void glm_rotated_x(mat4 m, float angle, mat4 dest) + + rotate existing transform matrix around X axis by angle + and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[out]* **dest** rotated matrix + +.. c:function:: void glm_rotated_y(mat4 m, float angle, mat4 dest) + + rotate existing transform matrix around Y axis by angle + and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[out]* **dest** rotated matrix + +.. c:function:: void glm_rotated_z(mat4 m, float angle, mat4 dest) + + rotate existing transform matrix around Z axis by angle + and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[out]* **dest** rotated matrix + +.. c:function:: void glm_rotated(mat4 m, float angle, vec3 axis) + + rotate existing transform matrix around Z axis by angle and axis + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_rotated_at(mat4 m, vec3 pivot, float angle, vec3 axis) + + rotate existing transform around given axis by angle at given pivot point (rotation center) + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **pivot** pivot, anchor point, rotation center + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_spinned(mat4 m, float angle, vec3 axis) + + | rotate existing transform matrix around given axis by angle around self (doesn't affected by position) + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis diff --git a/docs/source/affine-pre.rst b/docs/source/affine-pre.rst new file mode 100644 index 0000000..fe10205 --- /dev/null +++ b/docs/source/affine-pre.rst @@ -0,0 +1,240 @@ +.. default-domain:: C + +3D Affine Transforms (pre) +================================================================================ + +Pre transfrom functions which are regular transfrom functions. + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions: + +1. :c:func:`glm_translate_to` +#. :c:func:`glm_translate` +#. :c:func:`glm_translate_x` +#. :c:func:`glm_translate_y` +#. :c:func:`glm_translate_z` +#. :c:func:`glm_translate_make` +#. :c:func:`glm_scale_to` +#. :c:func:`glm_scale_make` +#. :c:func:`glm_scale` +#. :c:func:`glm_scale_uni` +#. :c:func:`glm_rotate_x` +#. :c:func:`glm_rotate_y` +#. :c:func:`glm_rotate_z` +#. :c:func:`glm_rotate_make` +#. :c:func:`glm_rotate` +#. :c:func:`glm_rotate_at` +#. :c:func:`glm_rotate_atm` +#. :c:func:`glm_decompose_scalev` +#. :c:func:`glm_uniscaled` +#. :c:func:`glm_decompose_rs` +#. :c:func:`glm_decompose` +#. :c:func:`glm_spin` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: void glm_translate_to(mat4 m, vec3 v, mat4 dest) + + translate existing transform matrix by *v* vector and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **v** translate vector [x, y, z] + | *[out]* **dest** translated matrix + +.. c:function:: void glm_translate(mat4 m, vec3 v) + + translate existing transform matrix by *v* vector + and stores result in same matrix + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** translate vector [x, y, z] + +.. c:function:: void glm_translate_x(mat4 m, float x) + + translate existing transform matrix by x factor + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** x factor + +.. c:function:: void glm_translate_y(mat4 m, float y) + + translate existing transform matrix by *y* factor + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** y factor + +.. c:function:: void glm_translate_z(mat4 m, float z) + + translate existing transform matrix by *z* factor + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** z factor + +.. c:function:: void glm_translate_make(mat4 m, vec3 v) + + creates NEW translate transform matrix by *v* vector. + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** translate vector [x, y, z] + +.. c:function:: void glm_scale_to(mat4 m, vec3 v, mat4 dest) + + scale existing transform matrix by *v* vector and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **v** scale vector [x, y, z] + | *[out]* **dest** scaled matrix + +.. c:function:: void glm_scale_make(mat4 m, vec3 v) + + creates NEW scale matrix by v vector + + Parameters: + | *[out]* **m** affine transfrom + | *[in]* **v** scale vector [x, y, z] + +.. c:function:: void glm_scale(mat4 m, vec3 v) + + scales existing transform matrix by v vector + and stores result in same matrix + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** scale vector [x, y, z] + +.. c:function:: void glm_scale_uni(mat4 m, float s) + + applies uniform scale to existing transform matrix v = [s, s, s] + and stores result in same matrix + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **v** scale factor + +.. c:function:: void glm_rotate_x(mat4 m, float angle, mat4 dest) + + rotate existing transform matrix around X axis by angle + and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[out]* **dest** rotated matrix + +.. c:function:: void glm_rotate_y(mat4 m, float angle, mat4 dest) + + rotate existing transform matrix around Y axis by angle + and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[out]* **dest** rotated matrix + +.. c:function:: void glm_rotate_z(mat4 m, float angle, mat4 dest) + + rotate existing transform matrix around Z axis by angle + and store result in dest + + Parameters: + | *[in]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[out]* **dest** rotated matrix + +.. c:function:: void glm_rotate_make(mat4 m, float angle, vec3 axis) + + creates NEW rotation matrix by angle and axis, + axis will be normalized so you don't need to normalize it + + Parameters: + | *[out]* **m** affine transfrom + | *[in]* **axis** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_rotate(mat4 m, float angle, vec3 axis) + + rotate existing transform matrix around Z axis by angle and axis + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_rotate_at(mat4 m, vec3 pivot, float angle, vec3 axis) + + rotate existing transform around given axis by angle at given pivot point (rotation center) + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **pivot** pivot, anchor point, rotation center + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_rotate_atm(mat4 m, vec3 pivot, float angle, vec3 axis) + + | creates NEW rotation matrix by angle and axis at given point + | this creates rotation matrix, it assumes you don't have a matrix + + | this should work faster than glm_rotate_at because it reduces one glm_translate. + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **pivot** pivot, anchor point, rotation center + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis + +.. c:function:: void glm_decompose_scalev(mat4 m, vec3 s) + + decompose scale vector + + Parameters: + | *[in]* **m** affine transform + | *[out]* **s** scale vector (Sx, Sy, Sz) + +.. c:function:: bool glm_uniscaled(mat4 m) + + returns true if matrix is uniform scaled. + This is helpful for creating normal matrix. + + Parameters: + | *[in]* **m** matrix + +.. c:function:: void glm_decompose_rs(mat4 m, mat4 r, vec3 s) + + decompose rotation matrix (mat4) and scale vector [Sx, Sy, Sz] + DON'T pass projected matrix here + + Parameters: + | *[in]* **m** affine transform + | *[out]* **r** rotation matrix + | *[out]* **s** scale matrix + +.. c:function:: void glm_decompose(mat4 m, vec4 t, mat4 r, vec3 s) + + decompose affine transform, TODO: extract shear factors. + DON'T pass projected matrix here + + Parameters: + | *[in]* **m** affine transfrom + | *[out]* **t** translation vector + | *[out]* **r** rotation matrix (mat4) + | *[out]* **s** scaling vector [X, Y, Z] + +.. c:function:: void glm_spin(mat4 m, float angle, vec3 axis) + + | rotate existing transform matrix around given axis by angle around self (doesn't affected by position) + + Parameters: + | *[in, out]* **m** affine transfrom + | *[in]* **angle** angle (radians) + | *[in]* **axis** axis diff --git a/docs/source/affine.rst b/docs/source/affine.rst index df2dcb7..722373c 100644 --- a/docs/source/affine.rst +++ b/docs/source/affine.rst @@ -5,6 +5,18 @@ Header: cglm/affine.h +Before starting, **cglm** provides two kind of transform functions; pre and post. + +Pre functions (`T' = Tnew * T`) are like `glm_translate`, `glm_rotate` which means it will translate the vector first and then apply the model transformation. +Post functions (`T' = T * Tnew`) are like `glm_translated`, `glm_rotated` which means it will apply the model transformation first and then translate the vector. + +`glm_translate`, `glm_rotate` are pre functions and are similar to C++ **glm** which you are familiar with. + +In new versions of **cglm** we added `glm_translated`, `glm_rotated`... which are post functions, +they are useful in some cases, e.g. append transform to existing transform (apply/append transform as last transfrom T' = T * Tnew). + +Post functions are named after pre functions with `ed` suffix, e.g. `glm_translate` -> `glm_translated`. So don't mix them up. + Initialize Transform Matrices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Functions with **_make** prefix expect you don't have a matrix and they create @@ -25,6 +37,9 @@ since scale factors are stored in rotation matrix, same may also true for scalli cglm provides some functions for rotating around at given point e.g. **glm_rotate_at**, **glm_quat_rotate_at**. Use them or follow next section for algorihm ("Rotate or Scale around specific Point (Pivot Point / Anchor Point)"). +Also **cglm** provides :c:func:`glm_spin` and :c:func:`glm_spinned` functions to rotate around itself. No need to give pivot. +These functions are useful for rotating around center of object. + Rotate or Scale around specific Point (Anchor Point) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -34,7 +49,8 @@ If you want to rotate model around arbibtrary point follow these steps: 2. Apply rotation (or scaling maybe) 3. Move model back from origin to pivot (reverse of step-1): **translate(pivot.x, pivot.y, pivot.z)** -**glm_rotate_at**, **glm_quat_rotate_at** and their helper functions works that way. +**glm_rotate_at**, **glm_quat_rotate_at** and their helper functions works that way. +So if you use them you don't need to do these steps manually which are done by **cglm**. The implementation would be: @@ -45,6 +61,13 @@ The implementation would be: glm_rotate(m, angle, axis); glm_translate(m, pivotInv); /* pivotInv = -pivot */ +or just: + +.. code-block:: c + :linenos: + + glm_rotate_at(m, pivot, angle, axis); + .. _TransformsOrder: Transforms Order @@ -54,7 +77,7 @@ It is important to understand this part especially if you call transform functions multiple times `glm_translate`, `glm_rotate`, `glm_scale` and `glm_quat_rotate` and their -helpers functions works like this (cglm may provide reverse order too as alternative in the future): +helpers functions works like this (cglm provides reverse order as `ed` suffix e.g `glm_translated`, `glm_rotated` see post transforms): .. code-block:: c :linenos: @@ -147,199 +170,27 @@ Functions: #. :c:func:`glm_decompose_rs` #. :c:func:`glm_decompose` +Post functions (**NEW**): + +1. :c:func:`glm_translated_to` +#. :c:func:`glm_translated` +#. :c:func:`glm_translated_x` +#. :c:func:`glm_translated_y` +#. :c:func:`glm_translated_z` +#. :c:func:`glm_rotated_x` +#. :c:func:`glm_rotated_y` +#. :c:func:`glm_rotated_z` +#. :c:func:`glm_rotated` +#. :c:func:`glm_rotated_at` +#. :c:func:`glm_spinned` + Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ -.. c:function:: void glm_translate_to(mat4 m, vec3 v, mat4 dest) +.. toctree:: + :maxdepth: 1 + :caption: Affine categories: - translate existing transform matrix by *v* vector and store result in dest - - Parameters: - | *[in]* **m** affine transfrom - | *[in]* **v** translate vector [x, y, z] - | *[out]* **dest** translated matrix - -.. c:function:: void glm_translate(mat4 m, vec3 v) - - translate existing transform matrix by *v* vector - and stores result in same matrix - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **v** translate vector [x, y, z] - -.. c:function:: void glm_translate_x(mat4 m, float x) - - translate existing transform matrix by x factor - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **v** x factor - -.. c:function:: void glm_translate_y(mat4 m, float y) - - translate existing transform matrix by *y* factor - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **v** y factor - -.. c:function:: void glm_translate_z(mat4 m, float z) - - translate existing transform matrix by *z* factor - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **v** z factor - -.. c:function:: void glm_translate_make(mat4 m, vec3 v) - - creates NEW translate transform matrix by *v* vector. - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **v** translate vector [x, y, z] - -.. c:function:: void glm_scale_to(mat4 m, vec3 v, mat4 dest) - - scale existing transform matrix by *v* vector and store result in dest - - Parameters: - | *[in]* **m** affine transfrom - | *[in]* **v** scale vector [x, y, z] - | *[out]* **dest** scaled matrix - -.. c:function:: void glm_scale_make(mat4 m, vec3 v) - - creates NEW scale matrix by v vector - - Parameters: - | *[out]* **m** affine transfrom - | *[in]* **v** scale vector [x, y, z] - -.. c:function:: void glm_scale(mat4 m, vec3 v) - - scales existing transform matrix by v vector - and stores result in same matrix - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **v** scale vector [x, y, z] - -.. c:function:: void glm_scale_uni(mat4 m, float s) - - applies uniform scale to existing transform matrix v = [s, s, s] - and stores result in same matrix - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **v** scale factor - -.. c:function:: void glm_rotate_x(mat4 m, float angle, mat4 dest) - - rotate existing transform matrix around X axis by angle - and store result in dest - - Parameters: - | *[in]* **m** affine transfrom - | *[in]* **angle** angle (radians) - | *[out]* **dest** rotated matrix - -.. c:function:: void glm_rotate_y(mat4 m, float angle, mat4 dest) - - rotate existing transform matrix around Y axis by angle - and store result in dest - - Parameters: - | *[in]* **m** affine transfrom - | *[in]* **angle** angle (radians) - | *[out]* **dest** rotated matrix - -.. c:function:: void glm_rotate_z(mat4 m, float angle, mat4 dest) - - rotate existing transform matrix around Z axis by angle - and store result in dest - - Parameters: - | *[in]* **m** affine transfrom - | *[in]* **angle** angle (radians) - | *[out]* **dest** rotated matrix - -.. c:function:: void glm_rotate_make(mat4 m, float angle, vec3 axis) - - creates NEW rotation matrix by angle and axis, - axis will be normalized so you don't need to normalize it - - Parameters: - | *[out]* **m** affine transfrom - | *[in]* **axis** angle (radians) - | *[in]* **axis** axis - -.. c:function:: void glm_rotate(mat4 m, float angle, vec3 axis) - - rotate existing transform matrix around Z axis by angle and axis - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **angle** angle (radians) - | *[in]* **axis** axis - -.. c:function:: void glm_rotate_at(mat4 m, vec3 pivot, float angle, vec3 axis) - - rotate existing transform around given axis by angle at given pivot point (rotation center) - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **pivot** pivot, anchor point, rotation center - | *[in]* **angle** angle (radians) - | *[in]* **axis** axis - -.. c:function:: void glm_rotate_atm(mat4 m, vec3 pivot, float angle, vec3 axis) - - | creates NEW rotation matrix by angle and axis at given point - | this creates rotation matrix, it assumes you don't have a matrix - - | this should work faster than glm_rotate_at because it reduces one glm_translate. - - Parameters: - | *[in, out]* **m** affine transfrom - | *[in]* **pivot** pivot, anchor point, rotation center - | *[in]* **angle** angle (radians) - | *[in]* **axis** axis - -.. c:function:: void glm_decompose_scalev(mat4 m, vec3 s) - - decompose scale vector - - Parameters: - | *[in]* **m** affine transform - | *[out]* **s** scale vector (Sx, Sy, Sz) - -.. c:function:: bool glm_uniscaled(mat4 m) - - returns true if matrix is uniform scaled. - This is helpful for creating normal matrix. - - Parameters: - | *[in]* **m** matrix - -.. c:function:: void glm_decompose_rs(mat4 m, mat4 r, vec3 s) - - decompose rotation matrix (mat4) and scale vector [Sx, Sy, Sz] - DON'T pass projected matrix here - - Parameters: - | *[in]* **m** affine transform - | *[out]* **r** rotation matrix - | *[out]* **s** scale matrix - -.. c:function:: void glm_decompose(mat4 m, vec4 t, mat4 r, vec3 s) - - decompose affine transform, TODO: extract shear factors. - DON'T pass projected matrix here - - Parameters: - | *[in]* **m** affine transfrom - | *[out]* **t** translation vector - | *[out]* **r** rotation matrix (mat4) - | *[out]* **s** scaling vector [X, Y, Z] + affine-common + affine-pre + affine-post diff --git a/docs/source/project.rst b/docs/source/project.rst index b31a86a..161a2a7 100644 --- a/docs/source/project.rst +++ b/docs/source/project.rst @@ -21,14 +21,14 @@ Functions: Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ -.. c:function:: void glm_unprojecti(vec3 pos, mat4 invMat, vec4 vp, vec3 dest) +.. c:function:: void glm_unprojecti(vec3 pos, mat4 invMat, vec4 vp, vec3 dest) | maps the specified viewport coordinates into specified space [1] the matrix should contain projection matrix. if you don't have ( and don't want to have ) an inverse matrix then use - glm_unproject version. You may use existing inverse of matrix in somewhere - else, this is why glm_unprojecti exists to save save inversion cost + :c:func:`glm_unproject` version. You may use existing inverse of matrix in somewhere + else, this is why **glm_unprojecti** exists to save inversion cost [1] space: - if m = invProj: View Space @@ -57,7 +57,7 @@ Functions documentation | maps the specified viewport coordinates into specified space [1] the matrix should contain projection matrix. - this is same as glm_unprojecti except this function get inverse matrix for + this is same as :c:func:`glm_unprojecti` except this function get inverse matrix for you. [1] space: @@ -80,7 +80,7 @@ Functions documentation | *[in]* **vp** viewport as [x, y, width, height] | *[out]* **dest** unprojected coordinates -.. c:function:: void glm_project(vec3 pos, mat4 m, vec4 vp, vec3 dest) +.. c:function:: void glm_project(vec3 pos, mat4 m, vec4 vp, vec3 dest) | map object coordinates to window coordinates @@ -91,12 +91,29 @@ Functions documentation glm_mat4_mul(proj, view, viewProj); glm_mat4_mul(viewProj, model, MVP); - this could be useful for gettng a bbox which fits with view frustum and - object bounding boxes. In this case you crop view frustum box with objects - box - Parameters: | *[in]* **pos** object coordinates | *[in]* **m** MVP matrix | *[in]* **vp** viewport as [x, y, width, height] | *[out]* **dest** projected coordinates + +.. c:function:: float glm_project_z(vec3 pos, mat4 m) + + | map object's z coordinate to window coordinates + + this is same as :c:func:`glm_project` except this function projects only Z coordinate + which reduces a few calculations and parameters. + + Computing MVP: + + .. code-block:: c + + glm_mat4_mul(proj, view, viewProj); + glm_mat4_mul(viewProj, model, MVP); + + Parameters: + | *[in]* **pos** object coordinates + | *[in]* **m** MVP matrix + + Returns: + projected z coordinate \ No newline at end of file