External/cglm
1
0
Fork 0
mirror of https://github.com/recp/cglm.git synced 2025-12-24 04:22:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #390 from waywardmonkeys/doc-improvements

Browse Source 
Doc improvements
This commit is contained in:
Recep Aslantas
2024-02-12 12:21:59 +03:00
committed by GitHub
parent eb9a200b6c 47a27f9d07
commit 4896b2ea8d
20 changed files with 47 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/ci.yml vendored
View File

@@ -173,7 +173,7 @@ jobs:
- name: Build
working-directory: docs
run: sphinx-build source build
run: sphinx-build -W --keep-going source build
build_meson:
name: Meson / ${{ matrix.os }}

103
docs/source/affine-pre.rst
View File

@@ -78,49 +78,6 @@ Functions documentation
| *[in, out]* **m** affine transform
| *[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 transform
| *[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 transform
| *[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 transform
| *[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 transform
| *[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 transform
| *[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
@@ -151,16 +108,6 @@ Functions documentation
| *[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 transform
| *[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
@@ -180,56 +127,6 @@ Functions documentation
| *[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 transform
| *[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 transform
| *[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)

3
docs/source/api_inline_array.rst
View File

@@ -9,7 +9,7 @@ In the future there may be option to forward struct api to call api instead of i
📌 **USE this API docs for similar functions in struct and call api**
📌 In struct api you can omit namespace e.g :code:`glms_vec3_dot` can be called as :code:`vec3_dot` in struct api, see :doc:`struct-api` to configure struct api for more details.
📌 In struct api you can omit namespace e.g :code:`glms_vec3_dot` can be called as :code:`vec3_dot` in struct api, see :doc:`api_struct` to configure struct api for more details.
📌 In struct api functions can return struct/union
📌 In struct api you can access items like **.x**, **.y**, **.z**, **.w**, **.r**, **.g**, **.b**, **.a**, **.m00**, **m01**...
@@ -43,6 +43,7 @@ Follow the :doc:`build` documentation for this
cam
frustum
box
aabb2d
quat
euler
mat2

6
docs/source/build.rst
View File

@@ -3,9 +3,9 @@ Build cglm
| **cglm** does not have any external dependencies.
**NOTE:**
If you only need to inline versions, you don't need to build **cglm**, you don't need to link it to your program.
Just import cglm to your project as dependency / external lib by copy-paste then use it as usual
.. note::
If you only need to inline versions, you don't need to build **cglm**, you don't need to link it to your program.
Just import cglm to your project as dependency / external lib by copy-paste then use it as usual
CMake (All platforms):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

12
docs/source/cam.rst
View File

@@ -18,10 +18,10 @@ fast if you don't care specific projection values.
*_decomp* means decompose; these function can help to decompose projection
matrices.
**NOTE**: Be careful when working with high range (very small near, very large
far) projection matrices. You may not get exact value you gave.
**float** type cannot store very high precision so you will lose precision.
Also your projection matrix will be inaccurate due to losing precision
.. note:: Be careful when working with high range (very small near, very large
far) projection matrices. You may not get exact value you gave.
**float** type cannot store very high precision so you will lose precision.
Also your projection matrix will be inaccurate due to losing precision
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -178,7 +178,7 @@ Functions documentation
| set up view matrix
**NOTE:** The UP vector must not be parallel to the line of sight from the eye point to the reference point.
.. note:: The UP vector must not be parallel to the line of sight from the eye point to the reference point.
Parameters:
| *[in]* **eye** eye vector
@@ -194,7 +194,7 @@ Functions documentation
target self then this might be useful. Because you need to get target
from direction.
**NOTE:** The UP vector must not be parallel to the line of sight from the eye point to the reference point.
.. note:: The UP vector must not be parallel to the line of sight from the eye point to the reference point.
Parameters:
| *[in]* **eye** eye vector

6
docs/source/getting_started.rst
View File

@@ -42,9 +42,9 @@ Allocations:
*cglm* doesn't alloc any memory on heap. So it doesn't provide any allocator.
You must allocate memory yourself. You should alloc memory for out parameters too if you pass pointer of memory location. When allocating memory, don't forget that **vec4** and **mat4** require alignment.
**NOTE:** Unaligned **vec4** and unaligned **mat4** operations will be supported in the future. Check todo list.
Because you may want to multiply a CGLM matrix with external matrix.
There is no guarantee that non-CGLM matrix is aligned. Unaligned types will have *u* prefix e.g. **umat4**
.. note:: Unaligned **vec4** and unaligned **mat4** operations will be supported in the future. Check todo list.
Because you may want to multiply a CGLM matrix with external matrix.
There is no guarantee that non-CGLM matrix is aligned. Unaligned types will have *u* prefix e.g. **umat4**
Array vs Struct:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

6
docs/source/io.rst
View File

@@ -24,9 +24,9 @@ Example to print mat4 matrix:
/* ... */
glm_mat4_print(transform, stderr);
**NOTE:** print functions use **%0.4f** precision if you need more
(you probably will in some cases), you can change it temporary.
cglm may provide precision parameter in the future
.. note:: print functions use **%0.4f** precision if you need more
(you probably will in some cases), you can change it temporary.
cglm may provide precision parameter in the future.
Changes since **v0.7.3**:
* Now mis-alignment of columns are fixed: larger numbers are printed via %g and others are printed via %f. Column widths are calculated before print.

2
docs/source/mat2.rst
View File

@@ -184,7 +184,7 @@ Functions documentation
Create mat2 matrix from pointer
| NOTE: **@src** must contain at least 4 elements.
.. note:: **@src** must contain at least 4 elements.
Parameters:
| *[in]* **src** pointer to an array of floats

2
docs/source/mat2x3.rst
View File

@@ -45,7 +45,7 @@ Functions documentation
Create mat2x3 matrix from pointer
| NOTE: **@src** must contain at least 6 elements.
.. note:: **@src** must contain at least 6 elements.
Parameters:
| *[in]* **src** pointer to an array of floats

2
docs/source/mat2x4.rst
View File

@@ -45,7 +45,7 @@ Functions documentation
Create mat2x4 matrix from pointer
| NOTE: **@src** must contain at least 8 elements.
.. note:: **@src** must contain at least 8 elements.
Parameters:
| *[in]* **src** pointer to an array of floats

2
docs/source/mat3.rst
View File

@@ -194,7 +194,7 @@ Functions documentation
Create mat3 matrix from pointer
| NOTE: **@src** must contain at least 9 elements.
.. note:: **@src** must contain at least 9 elements.
Parameters:
| *[in]* **src** pointer to an array of floats

3
docs/source/mat3x2.rst
View File

@@ -45,7 +45,8 @@ Functions documentation
Create mat3x2 matrix from pointer
| NOTE: **@src** must contain at least 6 elements.
.. note:: **@src** must contain at least 6 elements.
Parameters:
| *[in]* **src** pointer to an array of floats
| *[out]* **dest** destination matrix3x2

3
docs/source/mat3x4.rst
View File

@@ -45,7 +45,8 @@ Functions documentation
Create mat3x4 matrix from pointer
| NOTE: **@src** must contain at least 12 elements.
.. note::: **@src** must contain at least 12 elements.
Parameters:
| *[in]* **src** pointer to an array of floats
| *[out]* **dest** destination matrix3x4

8
docs/source/mat4.rst
View File

@@ -34,8 +34,8 @@ Functions:
#. :c:func:`glm_mat4_mulN`
#. :c:func:`glm_mat4_mulv`
#. :c:func:`glm_mat4_mulv3`
#. :c:func:`glm_mat3_trace`
#. :c:func:`glm_mat3_trace3`
#. :c:func:`glm_mat4_trace`
#. :c:func:`glm_mat4_trace3`
#. :c:func:`glm_mat4_quat`
#. :c:func:`glm_mat4_transpose_to`
#. :c:func:`glm_mat4_transpose`
@@ -263,7 +263,7 @@ Functions documentation
| e.g Newton-Raphson. this should work faster than normal,
| to get more precise use glm_mat4_inv version.
| NOTE: You will lose precision, glm_mat4_inv is more accurate
.. note:: You will lose precision, glm_mat4_inv is more accurate
Parameters:
| *[in]* **mat** source
@@ -308,7 +308,7 @@ Functions documentation
Create mat4 matrix from pointer
| NOTE: **@src** must contain at least 16 elements.
.. note:: **@src** must contain at least 16 elements.
Parameters:
| *[in]* **src** pointer to an array of floats

3
docs/source/mat4x2.rst
View File

@@ -45,7 +45,8 @@ Functions documentation
Create mat4x2 matrix from pointer
| NOTE: **@src** must contain at least 8 elements.
.. note:: **@src** must contain at least 8 elements.
Parameters:
| *[in]* **src** pointer to an array of floats
| *[out]* **dest** destination matrix4x2

3
docs/source/mat4x3.rst
View File

@@ -45,7 +45,8 @@ Functions documentation
Create mat4x3 matrix from pointer
| NOTE: **@src** must contain at least 12 elements.
.. note:: **@src** must contain at least 12 elements.
Parameters:
| *[in]* **src** pointer to an array of floats
| *[out]* **dest** destination matrix4x3

2
docs/source/quat.rst
View File

@@ -426,7 +426,7 @@ Functions documentation
Create quaternion from pointer
| NOTE: **@src** must contain at least 4 elements. cglm store quaternions as [x, y, z, w].
.. note:: **@src** must contain at least 4 elements. cglm store quaternions as [x, y, z, w].
Parameters:
| *[in]* **src** pointer to an array of floats

3
docs/source/vec2.rst
View File

@@ -389,7 +389,8 @@ Functions documentation
Create two dimensional vector from pointer
| NOTE: **@src** must contain at least 2 elements.
.. note:: **@src** must contain at least 2 elements.
Parameters:
| *[in]* **src** pointer to an array of floats
| *[out]* **dest** destination vector

2
docs/source/vec3.rst
View File

@@ -507,7 +507,7 @@ Functions documentation
Create three dimensional vector from pointer
| NOTE: **@src** must contain at least 3 elements.
.. note::: **@src** must contain at least 3 elements.
Parameters:
| *[in]* **src** pointer to an array of floats

10
docs/source/vec4.rst
View File

@@ -108,6 +108,13 @@ Functions documentation
Parameters:
| *[in, out]* **v** vector
.. c:function:: void glm_vec4_one(vec4 v)
makes all members one
Parameters:
| *[in, out]* **v** vector
.. c:function:: float glm_vec4_dot(vec4 a, vec4 b)
dot product of vec4
@@ -412,7 +419,8 @@ Functions documentation
Create four dimensional vector from pointer
| NOTE: **@src** must contain at least 4 elements.
.. note:: **@src** must contain at least 4 elements.
Parameters:
| *[in]* **src** pointer to an array of floats
| *[out]* **dest** destination vector