diff --git a/README.md b/README.md index 8c63fb0..84b321e 100644 --- a/README.md +++ b/README.md @@ -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.
-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
@@ -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) diff --git a/configure.ac b/configure.ac index 1fea297..a77cd68 100644 --- a/configure.ac +++ b/configure.ac @@ -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]) diff --git a/docs/source/affine-mat.rst b/docs/source/affine-mat.rst index 0d09e12..0c0fcaa 100644 --- a/docs/source/affine-mat.rst +++ b/docs/source/affine-mat.rst @@ -1,6 +1,6 @@ .. default-domain:: C -Affine Transform Matrix (Specialized Functions) +affine transform matrix (specialized functions) ================================================================================ Header: cglm/affine-mat.h diff --git a/docs/source/affine.rst b/docs/source/affine.rst index fdb2ef3..c34921f 100644 --- a/docs/source/affine.rst +++ b/docs/source/affine.rst @@ -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: diff --git a/docs/source/api.rst b/docs/source/api.rst index 7db4f83..e2c03d4 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -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 diff --git a/docs/source/box.rst b/docs/source/box.rst new file mode 100644 index 0000000..b753b3f --- /dev/null +++ b/docs/source/box.rst @@ -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 diff --git a/docs/source/call.rst b/docs/source/call.rst new file mode 100644 index 0000000..f7765a7 --- /dev/null +++ b/docs/source/call.rst @@ -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) diff --git a/docs/source/cam.rst b/docs/source/cam.rst index 2725334..a9f1ce7 100644 --- a/docs/source/cam.rst +++ b/docs/source/cam.rst @@ -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: diff --git a/docs/source/color.rst b/docs/source/color.rst new file mode 100644 index 0000000..62a4dc1 --- /dev/null +++ b/docs/source/color.rst @@ -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 diff --git a/docs/source/conf.py b/docs/source/conf.py index e02fea3..7ad96a1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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. diff --git a/docs/source/euler.rst b/docs/source/euler.rst index 1cf64ed..260aec7 100644 --- a/docs/source/euler.rst +++ b/docs/source/euler.rst @@ -1,6 +1,6 @@ .. default-domain:: C -Euler Angles +euler angles ============ Header: cglm/euler.h diff --git a/docs/source/frustum.rst b/docs/source/frustum.rst new file mode 100644 index 0000000..0ace87d --- /dev/null +++ b/docs/source/frustum.rst @@ -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] diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index d16f326..89c231c 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -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: diff --git a/docs/source/index.rst b/docs/source/index.rst index 3241872..25e7cb3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 diff --git a/docs/source/io.rst b/docs/source/io.rst new file mode 100644 index 0000000..9cf8900 --- /dev/null +++ b/docs/source/io.rst @@ -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 diff --git a/docs/source/mat3.rst b/docs/source/mat3.rst index 60e548c..9b00417 100644 --- a/docs/source/mat3.rst +++ b/docs/source/mat3.rst @@ -5,7 +5,7 @@ mat3 Header: cglm/mat3.h -Table of contents (clik func/macro to go): +Table of contents (click to go): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Macros: diff --git a/docs/source/mat4.rst b/docs/source/mat4.rst index 27d9225..1a391cb 100644 --- a/docs/source/mat4.rst +++ b/docs/source/mat4.rst @@ -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: diff --git a/docs/source/opengl.rst b/docs/source/opengl.rst new file mode 100644 index 0000000..e6b37e0 --- /dev/null +++ b/docs/source/opengl.rst @@ -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. diff --git a/docs/source/plane.rst b/docs/source/plane.rst new file mode 100644 index 0000000..b9afbed --- /dev/null +++ b/docs/source/plane.rst @@ -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 diff --git a/docs/source/quat.rst b/docs/source/quat.rst index 064aa19..863eed5 100644 --- a/docs/source/quat.rst +++ b/docs/source/quat.rst @@ -1,6 +1,6 @@ .. default-domain:: C -Quaternions +quaternions =========== Header: cglm/quat.h diff --git a/docs/source/util.rst b/docs/source/util.rst new file mode 100644 index 0000000..048be70 --- /dev/null +++ b/docs/source/util.rst @@ -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 diff --git a/docs/source/vec3-ext.rst b/docs/source/vec3-ext.rst index 112e2a3..e632de9 100644 --- a/docs/source/vec3-ext.rst +++ b/docs/source/vec3-ext.rst @@ -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: diff --git a/docs/source/vec3.rst b/docs/source/vec3.rst index 4458362..2ae95f0 100644 --- a/docs/source/vec3.rst +++ b/docs/source/vec3.rst @@ -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: diff --git a/docs/source/vec4-ext.rst b/docs/source/vec4-ext.rst index d9c6e0b..11613ad 100644 --- a/docs/source/vec4-ext.rst +++ b/docs/source/vec4-ext.rst @@ -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: diff --git a/docs/source/vec4.rst b/docs/source/vec4.rst index 5409c1e..60be7fa 100644 --- a/docs/source/vec4.rst +++ b/docs/source/vec4.rst @@ -5,7 +5,7 @@ vec4 Header: cglm/vec4.h -Table of contents (clik func/macro to go): +Table of contents (click to go): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Macros: diff --git a/include/cglm/version.h b/include/cglm/version.h index ce2f784..e654df6 100644 --- a/include/cglm/version.h +++ b/include/cglm/version.h @@ -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 */