External/cglm
1
0
Fork 0
mirror of https://github.com/recp/cglm.git synced 2025-10-03 16:51:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

complete documentation

Browse Source
This commit is contained in:
Recep Aslantas
2018-03-03 17:59:50 +03:00
parent 1fd0a74478
commit 0e964a1a62
26 changed files with 675 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@@ -1,6 +1,7 @@
# 🎥 OpenGL Mathematics (glm) for `C`
[![Build Status](https://travis-ci.org/recp/cglm.svg?branch=master)](https://travis-ci.org/recp/cglm)
[![Build status](https://ci.appveyor.com/api/projects/status/av7l3gc0yhfex8y4/branch/master?svg=true)](https://ci.appveyor.com/project/recp/cglm/branch/master)
[![Documentation Status](https://readthedocs.org/projects/cglm/badge/?version=latest)](http://cglm.readthedocs.io/en/latest/?badge=latest)
[![Coverage Status](https://coveralls.io/repos/github/recp/cglm/badge.svg?branch=master)](https://coveralls.io/github/recp/cglm?branch=master)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/6a62b37d5f214f178ebef269dc4a6bf1)](https://www.codacy.com/app/recp/cglm?utm_source=github.com&utm_medium=referral&utm_content=recp/cglm&utm_campaign=Badge_Grade)
@@ -9,7 +10,7 @@ The original glm library is for C++ only (templates, namespaces, classes...), th
#### Documentation
Almost all functions (inline versions) and parameters are documented inside related headers. <br />
Complete documentation is in progress: http://cglm.readthedocs.io
Complete documentation: http://cglm.readthedocs.io
#### Note for previous versions:
@@ -29,15 +30,15 @@ https://github.com/g-truc/glm
- Welcome!
#### Note for experienced developers:
- Since I'm testing this library in my projects, sometimes bugs occurs; finding that bug[s] and making improvements would be more easy with multiple developer/contributor and their projects or knowledge. Consider to make some tests if you suspect something is wrong and any feedbacks, contributions and bug reports are always welcome.
- Since I'm testing this library in my projects, sometimes bugs occurs; finding that bug[s] and making improvements would be more easy with multiple developer/contributor and their projects or knowledge. Consider to make some tests if you suspect something is wrong and any feedbacks, contributions and bug reports are always welcome.
#### Allocations?
`cglm` doesn't alloc any memory on heap. So it doesn't provide any allocator. You should alloc memory for **out** parameters too if you pass pointer of memory location. Don't forget that **vec4** (also quat/**versor**) and **mat4** must be aligned (16-bytes), because *cglm* uses SIMD instructions to optimize most operations if available.
#### Allocations?
`cglm` doesn't alloc any memory on heap. So it doesn't provide any allocator. You should alloc memory for **out** parameters too if you pass pointer of memory location. Don't forget that **vec4** (also quat/**versor**) and **mat4** must be aligned (16-bytes), because *cglm* uses SIMD instructions to optimize most operations if available.
#### Returning vector or matrix... ?
Since almost all types are arrays and **C** doesn't allow returning arrays, so **cglm** doesn't support this feature. In the future *cglm* may use **struct** for some types for this purpose.
Since almost all types are arrays and **C** doesn't allow returning arrays, so **cglm** doesn't support this feature. In the future *cglm* may use **struct** for some types for this purpose.
#### Other APIs like Vulkan, Metal, Dx?
#### Other APIs like Vulkan, Metal, Dx?
Currently *cglm* uses default clip space configuration (-1, 1) for camera functions (perspective, extract corners...), in the future other clip space configurations will be supported
<hr/>
@@ -121,8 +122,8 @@ MIT. check the LICENSE file
### Unix (Autotools)
```bash
$ sh ./build-deps.sh # run only once (dependencies) [Optional].
$ # You can pass this step if you don't want to run `make check` for tests.
$ sh ./build-deps.sh # run only once (dependencies) [Optional].
$ # You can pass this step if you don't want to run `make check` for tests.
$ # cglm uses cmocka for tests and it may reqiure cmake for building it
$
$ sh autogen.sh
@@ -146,6 +147,15 @@ if `msbuild` won't work (because of multi version VS) then try to build with `de
$ devenv cglm.sln /Build Release
```
### Building Docs
First you need install Sphinx: http://www.sphinx-doc.org/en/master/usage/installation.html
then:
```bash
$ cd docs
$ sphinx-build source build
```
it will compile docs into build folder, you can run index.html inside that function.
## How to use
If you want to use inline versions of funcstions then; include main header
```C
@@ -201,7 +211,7 @@ Option 2: Cast matrix to pointer type (also valid for multiple dimensional array
glUniformMatrix4fv(location, 1, GL_FALSE, (float *)matrix);
```
You can pass same way to another APIs e.g. Vulkan, DX...
You can pass same way to another APIs e.g. Vulkan, DX...
## Notes
@@ -213,5 +223,5 @@ You can pass same way to another APIs e.g. Vulkan, DX...
- [ ] Unit tests for comparing cglm with glm results
- [x] Add version info
- [ ] Unaligned operations (e.g. `glm_umat4_mul`)
- [ ] Extra documentation
- [x] Extra documentation
- [ ] ARM Neon Arch (In Progress)

2
configure.ac
View File

@@ -7,7 +7,7 @@
#*****************************************************************************
AC_PREREQ([2.69])
AC_INIT([cglm], [0.2.1], [info@recp.me])
AC_INIT([cglm], [0.3.4], [info@recp.me])
AM_INIT_AUTOMAKE([-Wall -Werror foreign subdir-objects])
AC_CONFIG_MACRO_DIR([m4])

2
docs/source/affine-mat.rst
View File

@@ -1,6 +1,6 @@
.. default-domain:: C
Affine Transform Matrix (Specialized Functions)
affine transform matrix (specialized functions)
================================================================================
Header: cglm/affine-mat.h

4
docs/source/affine.rst
View File

@@ -1,6 +1,6 @@
.. default-domain:: C
Affine Transforms
affine transforms
================================================================================
Header: cglm/affine.h
@@ -15,7 +15,7 @@ before sending to transfrom functions.
There are also functions to decompose transform matrix. These functions can't
decompose matrix after projected.
Table of contents (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:

9
docs/source/api.rst
View File

@@ -23,12 +23,14 @@ version of functions. You need to build *cglm* and link it.
Follow the :doc:`build` documentation for this
.. toctree::
:maxdepth: 2
:maxdepth: 1
:caption: API categories:
affine
affine-mat
cam
frustum
box
quat
euler
mat4
@@ -37,3 +39,8 @@ Follow the :doc:`build` documentation for this
vec3-ext
vec4
vec4-ext
color
plane
util
io
call

92
docs/source/box.rst Normal file
View File

@@ -0,0 +1,92 @@
.. default-domain:: C
axis aligned bounding box (AABB)
================================================================================
Header: cglm/box.h
Some convenient functions provided for AABB.
**Definition of box:**
cglm defines box as two dimensional array of vec3.
The first element is **min** point and the second one is **max** point.
If you have another type e.g. struct or even another representation then you must
convert it before and after call cglm box function.
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:
1. :c:func:`glm_aabb_transform`
#. :c:func:`glm_aabb_merge`
#. :c:func:`glm_aabb_crop`
#. :c:func:`glm_aabb_crop_until`
Functions documentation
~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: void glm_aabb_transform(vec3 box[2], mat4 m, vec3 dest[2])
| apply transform to Axis-Aligned Bounding Box
Parameters:
| *[in]* **box** bounding box
| *[in]* **m** transform matrix
| *[out]* **dest** transformed bounding box
.. c:function:: void glm_aabb_merge(vec3 box1[2], vec3 box2[2], vec3 dest[2])
| merges two AABB bounding box and creates new one
two box must be in same space, if one of box is in different space then
you should consider to convert it's space by glm_box_space
Parameters:
| *[in]* **box1** bounding box 1
| *[in]* **box2** bounding box 2
| *[out]* **dest** merged bounding box
.. c:function:: void glm_aabb_crop(vec3 box[2], vec3 cropBox[2], vec3 dest[2])
| crops a bounding box with another one.
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]* **box** bounding box 1
| *[in]* **cropBox** crop box
| *[out]* **dest** cropped bounding box
.. c:function:: void glm_frustum_box(vec4 corners[8], mat4 m, vec3 box[2])
| crops a bounding box with another one.
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]* **box** bounding box
| *[in]* **cropBox** crop box
| *[in]* **clampBox** miniumum box
| *[out]* **dest** cropped bounding box
.. c:function:: bool glm_aabb_frustum(vec3 box[2], vec4 planes[6])
| check if AABB intersects with frustum planes
this could be useful for frustum culling using AABB.
OPTIMIZATION HINT:
if planes order is similar to LEFT, RIGHT, BOTTOM, TOP, NEAR, FAR
then this method should run even faster because it would only use two
planes if object is not inside the two planes
fortunately cglm extracts planes as this order! just pass what you got!
Parameters:
| *[in]* **box** bounding box
| *[out]* **planes** frustum planes

19
docs/source/call.rst Normal file
View File

@@ -0,0 +1,19 @@
.. default-domain:: C
precompiled functions (call)
================================================================================
All funcitons in **glm_** namespace are forced to **inline**.
Most functions also have pre-compiled version.
Precompiled versions are in **glmc_** namespace. *c* in the namespace stands for
"call".
Since precompiled functions are just wrapper for inline verisons,
these functions are not documented individually.
It would be duplicate documentation also it
would be hard to sync documentation between inline and call verison for me.
By including **clgm/cglm.h** you include all inline verisons. To get precompiled
versions you need to include **cglm/call.h** header it also includes all
call versions plus *clgm/cglm.h* (inline verisons)

4
docs/source/cam.rst
View File

@@ -1,6 +1,6 @@
.. default-domain:: C
Camera
camera
======
Header: cglm/cam.h
@@ -23,7 +23,7 @@ matrices.
**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 (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:

34
docs/source/color.rst Normal file
View File

@@ -0,0 +1,34 @@
.. default-domain:: C
color
================================================================================
Header: cglm/color.h
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:
1. :c:func:`glm_luminance`
Functions documentation
~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: float glm_luminance(vec3 rgb)
| averages the color channels into one value
This function uses formula in COLLADA 1.5 spec which is
.. code-block:: text
luminance = (color.r * 0.212671) +
(color.g * 0.715160) +
(color.b * 0.072169)
It is based on the ISO/CIE color standards (see ITU-R Recommendation BT.709-4),
that averages the color channels into one value
Parameters:
| *[in]* **rgb** RGB color

4
docs/source/conf.py
View File

@@ -62,9 +62,9 @@ author = u'Recep Aslantas'
# built documents.
#
# The short X.Y version.
version = u'0.3.3'
version = u'0.3.4'
# The full version, including alpha/beta/rc tags.
release = u'0.3.3'
release = u'0.3.4'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

2
docs/source/euler.rst
View File

@@ -1,6 +1,6 @@
.. default-domain:: C
Euler Angles
euler angles
============
Header: cglm/euler.h

168
docs/source/frustum.rst Normal file
View File

@@ -0,0 +1,168 @@
.. default-domain:: C
frustum
=============
Header: cglm/frustum.h
cglm provides convenient functions to extract frustum planes, corners...
All extracted corners are **vec4** so you must create array of **vec4**
not **vec3**. If you want to store them to save space you msut convert them
yourself.
**vec4** is used to speed up functions need to corners. This is why frustum
fucntions use *vec4* instead of *vec3*
Currenty related-functions use [-1, 1] clip space configuration to extract
corners but you can override it by prodiving **GLM_CUSTOM_CLIPSPACE** macro.
If you provide it then you have to all bottom macros as *vec4*
Current configuration:
.. code-block:: c
/* near */
GLM_CSCOORD_LBN {-1.0f, -1.0f, -1.0f, 1.0f}
GLM_CSCOORD_LTN {-1.0f, 1.0f, -1.0f, 1.0f}
GLM_CSCOORD_RTN { 1.0f, 1.0f, -1.0f, 1.0f}
GLM_CSCOORD_RBN { 1.0f, -1.0f, -1.0f, 1.0f}
/* far */
GLM_CSCOORD_LBF {-1.0f, -1.0f, 1.0f, 1.0f}
GLM_CSCOORD_LTF {-1.0f, 1.0f, 1.0f, 1.0f}
GLM_CSCOORD_RTF { 1.0f, 1.0f, 1.0f, 1.0f}
GLM_CSCOORD_RBF { 1.0f, -1.0f, 1.0f, 1.0f}
Explain of short names:
* **LBN**: left bottom near
* **LTN**: left top near
* **RTN**: right top near
* **RBN**: right bottom near
* **LBF**: left bottom far
* **LTF**: left top far
* **RTF**: right top far
* **RBF**: right bottom far
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Macros:
.. code-block:: c
GLM_LBN 0 /* left bottom near */
GLM_LTN 1 /* left top near */
GLM_RTN 2 /* right top near */
GLM_RBN 3 /* right bottom near */
GLM_LBF 4 /* left bottom far */
GLM_LTF 5 /* left top far */
GLM_RTF 6 /* right top far */
GLM_RBF 7 /* right bottom far */
GLM_LEFT 0
GLM_RIGHT 1
GLM_BOTTOM 2
GLM_TOP 3
GLM_NEAR 4
GLM_FAR 5
Functions:
1. :c:func:`glm_frustum_planes`
#. :c:func:`glm_frustum_corners`
#. :c:func:`glm_frustum_center`
#. :c:func:`glm_frustum_box`
#. :c:func:`glm_frustum_corners_at`
Functions documentation
~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: void glm_frustum_planes(mat4 m, vec4 dest[6])
| extracts view frustum planes
planes' space:
- if m = proj: View Space
- if m = viewProj: World Space
- if m = MVP: Object Space
You probably want to extract planes in world space so use viewProj as m
Computing viewProj:
.. code-block:: c
glm_mat4_mul(proj, view, viewProj);
Exracted planes order: [left, right, bottom, top, near, far]
Parameters:
| *[in]* **m** matrix
| *[out]* **dest** exracted view frustum planes
.. c:function:: void glm_frustum_corners(mat4 invMat, vec4 dest[8])
| extracts view frustum corners using clip-space coordinates
corners' space:
- if m = invViewProj: World Space
- if m = invMVP: Object Space
You probably want to extract corners in world space so use **invViewProj**
Computing invViewProj:
.. code-block:: c
glm_mat4_mul(proj, view, viewProj);
...
glm_mat4_inv(viewProj, invViewProj);
if you have a near coord at **i** index,
you can get it's far coord by i + 4;
follow example below to understand that
For instance to find center coordinates between a near and its far coord:
.. code-block:: c
for (j = 0; j < 4; j++) {
glm_vec_center(corners[i], corners[i + 4], centerCorners[i]);
}
corners[i + 4] is far of corners[i] point.
Parameters:
| *[in]* **invMat** matrix
| *[out]* **dest** exracted view frustum corners
.. c:function:: void glm_frustum_center(vec4 corners[8], vec4 dest)
| finds center of view frustum
Parameters:
| *[in]* **corners** view frustum corners
| *[out]* **dest** view frustum center
.. c:function:: void glm_frustum_box(vec4 corners[8], mat4 m, vec3 box[2])
| finds bounding box of frustum relative to given matrix e.g. view mat
Parameters:
| *[in]* **corners** view frustum corners
| *[in]* **m** matrix to convert existing conners
| *[out]* **box** bounding box as array [min, max]
.. c:function:: void glm_frustum_corners_at(vec4 corners[8], float splitDist, float farDist, vec4 planeCorners[4])
| finds planes corners which is between near and far planes (parallel)
this will be helpful if you want to split a frustum e.g. CSM/PSSM. This will
find planes' corners but you will need to one more plane.
Actually you have it, it is near, far or created previously with this func ;)
Parameters:
| *[in]* **corners** frustum corners
| *[in]* **splitDist** split distance
| *[in]* **farDist** far distance (zFar)
| *[out]* **planeCorners** plane corners [LB, LT, RT, RB]

46
docs/source/getting_started.rst
View File

@@ -1,9 +1,8 @@
Getting Started
================================
.. image:: cglm-intro.png
:width: 492px 
:height: 297px
:align: center
Types:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**cglm** uses **glm** prefix for all functions e.g. glm_lookat. You can see supported types in common header file:
@@ -22,23 +21,50 @@ Getting Started
As you can see types don't store extra informations in favor of space.
You can send these values e.g. matrix to OpenGL directly without casting or calling a function like *value_ptr*
*vec4* and *mat4* requires 16 byte aligment because vec4 and mat4 operations are
Aligment is Required:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**vec4** and **mat4** requires 16 byte aligment because vec4 and mat4 operations are
vectorized by SIMD instructions (SSE/AVX).
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** requires aligment.
**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:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*cglm* uses arrays for vector and matrix types. So you can't access individual
elements like vec.x, vec.y, vec.z... You must use subscript to access vector elements
e.g. vec[0], vec[1], vec[2].
Also I think it is more meaningful to access matrix elements with subscript
e.g **matrix[2][3]** instead of **matrix._23**. Since matrix is array of vectors,
vectors are also defined as array. This makes types homogeneous.
**Return arrays?**
Since C doesn't support return arrays, cglm also doesn't support this feature.
Function design:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. image:: cglm-intro.png
:width: 492px 
:height: 297px
:align: center
cglm provides a few way to call a function to do same operation.
* Inline - *glm_, glm_u*
* aligned
* unaligned (todo)
* Pre-compiled - *glmc_, glmc_u*
* aligned
* unaligned (todo)
For instance **glm_mat4_mul** is inline (all *glm_* functions are inline), to make it non-inline (pre-compiled)
For instance **glm_mat4_mul** is inline (all *glm_* functions are inline), to make it non-inline (pre-compiled),
call it as **glmc_mat4_mul** from library, to use unaligned version use **glm_umat4_mul** (todo).
Most functions have **dest** parameter for output. For instance mat4_mul func looks like this:

3
docs/source/index.rst
View File

@@ -33,11 +33,12 @@ Also currently only **float** type is supported for most operations.
.. toctree::
:maxdepth: 2
:maxdepth: 1
:caption: Table Of Contents:
build
getting_started
opengl
api
Indices and tables

92
docs/source/io.rst Normal file
View File

@@ -0,0 +1,92 @@
.. default-domain:: C
io (input / output e.g. print)
================================================================================
Header: cglm/io.h
There are some built-in print functions which may save your time,
especially for debugging.
All functions accept **FILE** parameter which makes very flexible.
You can even print it to file on disk.
In general you will want to print them to console to see results.
You can use **stdout** and **stderr** to write results to console.
Some programs may occupy **stdout** but you can still use **stderr**.
Using **stderr** is suggested.
Example to print mat4 matrix:
.. code-block:: c
mat4 transform;
/* ... */
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
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:
1. :c:func:`glm_mat4_print`
#. :c:func:`glm_mat3_print`
#. :c:func:`glm_vec4_print`
#. :c:func:`glm_vec3_print`
#. :c:func:`glm_ivec3_print`
#. :c:func:`glm_versor_print`
Functions documentation
~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: void glm_mat4_print(mat4 matrix, FILE * __restrict ostream)
| print mat4 to given stream
Parameters:
| *[in]* **matrix** matrix
| *[in]* **ostream** FILE to write
.. c:function:: void glm_mat3_print(mat3 matrix, FILE * __restrict ostream)
| print mat3 to given stream
Parameters:
| *[in]* **matrix** matrix
| *[in]* **ostream** FILE to write
.. c:function:: void glm_vec4_print(vec4 vec, FILE * __restrict ostream)
| print vec4 to given stream
Parameters:
| *[in]* **vec** vector
| *[in]* **ostream** FILE to write
.. c:function:: void glm_vec3_print(vec3 vec, FILE * __restrict ostream)
| print vec3 to given stream
Parameters:
| *[in]* **vec** vector
| *[in]* **ostream** FILE to write
.. c:function:: void glm_ivec3_print(ivec3 vec, FILE * __restrict ostream)
| print ivec3 to given stream
Parameters:
| *[in]* **vec** vector
| *[in]* **ostream** FILE to write
.. c:function:: void glm_versor_print(versor vec, FILE * __restrict ostream)
| print quaternion to given stream
Parameters:
| *[in]* **vec** quaternion
| *[in]* **ostream** FILE to write

2
docs/source/mat3.rst
View File

@@ -5,7 +5,7 @@ mat3
Header: cglm/mat3.h
Table of contents (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Macros:

2
docs/source/mat4.rst
View File

@@ -8,7 +8,7 @@ Header: cglm/mat4.h
Important: :c:func:`glm_mat4_scale` multiplies mat4 with scalar, if you need to
apply scale transform use :c:func:`glm_scale` functions.
Table of contents (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Macros:

61
docs/source/opengl.rst Normal file
View File

@@ -0,0 +1,61 @@
How to send vector or matrix to OpenGL like API
==================================================
*cglm*'s vector and matrix types are arrays. So you can send them directly to a
function which accecpts pointer. But you may got warnings for matrix because it is
two dimensional array.
Passing / Uniforming Matrix to OpenGL:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**glUniformMatrix4fv** accepts float pointer, you can pass matrix to that parameter
and it should work but with warnings. "You can pass" doesn't mean that you must pass like that.
**Correct options:**
Correct doesn't mean correct way to use OpenGL it is just shows correct way to pass cglm type to it.
1. Pass first column
---------------------
The goal is that pass address of matrix, first element of matrix is also address of matrix,
because it is array of vectors and vector is array of floats.
.. code-block:: c
mat4 matrix;
/* ... */
glUniformMatrix4fv(location, 1, GL_FALSE, matrix[0]);
array of matrices:
.. code-block:: c
mat4 matrix;
/* ... */
glUniformMatrix4fv(location, count, GL_FALSE, matrix[0][0]);
1. Cast matrix to pointer
--------------------------
.. code-block:: c
mat4 matrix;
/* ... */
glUniformMatrix4fv(location, count, GL_FALSE, (float *)matrix);
in this way, passing aray of matrices is same
Passing / Uniforming Vectors to OpenGL:¶
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You don't need to do extra thing when passing cglm vectors to OpengL or other APIs.
Because a function like **glUniform4fv** accepts vector as pointer. cglm's vectors
are array of floats. So you can pass it directly ot those functions:
.. code-block:: c
vec4 vec;
/* ... */
glUniform4fv(location, 1, vec);
this show how to pass **vec4** others are same.

33
docs/source/plane.rst Normal file
View File

@@ -0,0 +1,33 @@
.. default-domain:: C
plane
================================================================================
Header: cglm/plane.h
Plane extract functions are in frustum header and documented
in :doc:`frustum` page.
**Definition of plane:**
Plane equation: **Ax + By + Cz + D = 0**
Plan is stored in **vec4** as **[A, B, C, D]**. (A, B, C) is normal and D is distance
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:
1. :c:func:`glm_plane_normalize`
Functions documentation
~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: void glm_plane_normalize(vec4 plane)
| normalizes a plane
Parameters:
| *[in, out]* **plane** pnale to normalize

2
docs/source/quat.rst
View File

@@ -1,6 +1,6 @@
.. default-domain:: C
Quaternions
quaternions
===========
Header: cglm/quat.h

93
docs/source/util.rst Normal file
View File

@@ -0,0 +1,93 @@
.. default-domain:: C
utils / helpers
================================================================================
Header: cglm/util.h
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:
1. :c:func:`glm_sign`
#. :c:func:`glm_rad`
#. :c:func:`glm_deg`
#. :c:func:`glm_make_rad`
#. :c:func:`glm_make_deg`
#. :c:func:`glm_pow2`
Functions documentation
~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: int glm_sign(int val)
| returns sign of 32 bit integer as +1 or -1
Parameters:
| *[in]* **val** an integer
Returns:
sign of given number
.. c:function:: float glm_rad(float deg)
| convert degree to radians
Parameters:
| *[in]* **deg** angle in degrees
.. c:function:: float glm_deg(float rad)
| convert radians to degree
Parameters:
| *[in]* **rad** angle in radians
.. c:function:: void glm_make_rad(float *degm)
| convert exsisting degree to radians. this will override degrees value
Parameters:
| *[in, out]* **deg** pointer to angle in degrees
.. c:function:: void glm_make_deg(float *rad)
| convert exsisting radians to degree. this will override radians value
Parameters:
| *[in, out]* **rad** pointer to angle in radians
.. c:function:: float glm_pow2(float x)
| multiplies given parameter with itself = x * x or powf(x, 2)
Parameters:
| *[in]* **x** value
Returns:
square of a given number
.. c:function:: float glm_min(float a, float b)
| returns minimum of given two values
Parameters:
| *[in]* **a** number 1
| *[in]* **b** number 2
Returns:
minimum value
.. c:function:: float glm_max(float a, float b)
| returns maximum of given two values
Parameters:
| *[in]* **a** number 1
| *[in]* **b** number 2
Returns:
maximum value

2
docs/source/vec3-ext.rst
View File

@@ -9,7 +9,7 @@ There are some functions are in called in extra header. These are called extra
because they are not used like other functions in vec3.h in the future some of
these functions ma be moved to vec3 header.
Table of contents (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:

2
docs/source/vec3.rst
View File

@@ -13,7 +13,7 @@ alias means inline wrapper here. There is no call verison of alias functions
There are also functions for rotating *vec3* vector. **_m4**, **_m3** prefixes
rotate *vec3* with matrix.
Table of contents (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Macros:

2
docs/source/vec4-ext.rst
View File

@@ -9,7 +9,7 @@ There are some functions are in called in extra header. These are called extra
because they are not used like other functions in vec4.h in the future some of
these functions ma be moved to vec4 header.
Table of contents (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functions:

2
docs/source/vec4.rst
View File

@@ -5,7 +5,7 @@ vec4
Header: cglm/vec4.h
Table of contents (clik func/macro to go):
Table of contents (click to go):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Macros:

2
include/cglm/version.h
View File

@@ -10,6 +10,6 @@
#define CGLM_VERSION_MAJOR 0
#define CGLM_VERSION_MINOR 3
#define CGLM_VERSION_PATCH 3
#define CGLM_VERSION_PATCH 4
#endif /* cglm_version_h */