mirror of
https://github.com/recp/cglm.git
synced 2026-01-05 22:59:12 +00:00
update docs
This commit is contained in:
Recep Aslantas
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user