YourWishes/cglm
1
0
Fork 0
mirror of https://github.com/recp/cglm.git synced 2026-02-17 03:39:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Recep Aslantas
2022-10-23 12:00:17 +03:00
parent 7c7ac8b82e
commit 878e829767
5 changed files with 569 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
docs/source/affine-common.rst Normal file
View File

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

129
docs/source/affine-post.rst Normal file
View File

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

240
docs/source/affine-pre.rst Normal file
View File

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

239
docs/source/affine.rst
View File

@@ -5,6 +5,18 @@
Header: cglm/affine.h 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 Initialize Transform Matrices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions with **_make** prefix expect you don't have a matrix and they create 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. 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)"). **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) 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) 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)** 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: The implementation would be:
@@ -45,6 +61,13 @@ The implementation would be:
glm_rotate(m, angle, axis); glm_rotate(m, angle, axis);
glm_translate(m, pivotInv); /* pivotInv = -pivot */ glm_translate(m, pivotInv); /* pivotInv = -pivot */
or just:
.. code-block:: c
:linenos:
glm_rotate_at(m, pivot, angle, axis);
.. _TransformsOrder: .. _TransformsOrder:
Transforms Order Transforms Order
@@ -54,7 +77,7 @@ It is important to understand this part especially if you call transform
functions multiple times functions multiple times
`glm_translate`, `glm_rotate`, `glm_scale` and `glm_quat_rotate` and their `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 .. code-block:: c
:linenos: :linenos:
@@ -147,199 +170,27 @@ Functions:
#. :c:func:`glm_decompose_rs` #. :c:func:`glm_decompose_rs`
#. :c:func:`glm_decompose` #. :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 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 affine-common
affine-pre
Parameters: affine-post
| *[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]

35
docs/source/project.rst
View File

@@ -21,14 +21,14 @@ Functions:
Functions documentation 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] | maps the specified viewport coordinates into specified space [1]
the matrix should contain projection matrix. the matrix should contain projection matrix.
if you don't have ( and don't want to have ) an inverse matrix then use 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 :c:func:`glm_unproject` version. You may use existing inverse of matrix in somewhere
else, this is why glm_unprojecti exists to save save inversion cost else, this is why **glm_unprojecti** exists to save inversion cost
[1] space: [1] space:
- if m = invProj: View Space - if m = invProj: View Space
@@ -57,7 +57,7 @@ Functions documentation
| maps the specified viewport coordinates into specified space [1] | maps the specified viewport coordinates into specified space [1]
the matrix should contain projection matrix. 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. you.
[1] space: [1] space:
@@ -80,7 +80,7 @@ Functions documentation
| *[in]* **vp** viewport as [x, y, width, height] | *[in]* **vp** viewport as [x, y, width, height]
| *[out]* **dest** unprojected coordinates | *[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 | map object coordinates to window coordinates
@@ -91,12 +91,29 @@ Functions documentation
glm_mat4_mul(proj, view, viewProj); glm_mat4_mul(proj, view, viewProj);
glm_mat4_mul(viewProj, model, MVP); 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: Parameters:
| *[in]* **pos** object coordinates | *[in]* **pos** object coordinates
| *[in]* **m** MVP matrix | *[in]* **m** MVP matrix
| *[in]* **vp** viewport as [x, y, width, height] | *[in]* **vp** viewport as [x, y, width, height]
| *[out]* **dest** projected coordinates | *[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