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

docs: use sphinx_rtd_theme theme dor documentation

Browse Source
This commit is contained in:
Recep Aslantas
2019-03-17 09:33:38 +03:00
parent ee1937f28d
commit 8fa21a1837
6 changed files with 96 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/source/build.rst
View File

@@ -1,9 +1,7 @@
Building cglm
Build cglm
================================
| **cglm** does not have external dependencies except for unit testing.
| When you pulled cglm repo with submodules all dependencies will be pulled too.
| `build-deps.sh` will pull all dependencies/submodules and build for you.
| **cglm** does not have external dependencies except for unit testing. When you pulled **cglm** repo with submodules all dependencies will be pulled too. `build-deps.sh` will pull all dependencies/submodules and build for you.
External dependencies:
* cmocka - for unit testing
@@ -12,7 +10,8 @@ External dependencies:
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
**Unix (Autotools):**
Unix (Autotools):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
:linenos:
@@ -26,11 +25,12 @@ Just import cglm to your project as dependency / external lib by copy-paste then
$ [sudo] make install # install to system (optional)
**make** will build cglm to **.libs** sub folder in project folder.
If you don't want to install cglm to your system's folder you can get static and dynamic libs in this folder.
If you don't want to install **cglm** to your system's folder you can get static and dynamic libs in this folder.
**Build dependencies (windows):**
Windows (MSBuild):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows related build files, project files are located in win folder,
Windows related build files, project files are located in `win` folder,
make sure you are inside in cglm/win folder.
Code Analysis are enabled, it may take awhile to build.
@@ -50,3 +50,19 @@ then try to build with *devenv*:
$ devenv cglm.sln /Build Release
Currently tests are not available on Windows.
Documentation (Sphinx):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**cglm** uses sphinx framework for documentation, it allows lot of formats for documentation. To see all options see sphinx build page:
https://www.sphinx-doc.org/en/master/man/sphinx-build.html
Example build:
.. code-block:: bash
:linenos:
$ cd cglm/docs
$ sphinx-build source build

16
docs/source/conf.py
View File

@@ -90,7 +90,7 @@ todo_include_todos = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -99,13 +99,13 @@ html_theme = 'alabaster'
# html_theme_options = {}
html_theme_options = {
'github_banner': 'true',
'github_button': 'true',
'github_user': 'recp',
'github_repo': 'cglm',
'travis_button': 'true',
'show_related': 'true',
'fixed_sidebar': 'true'
# 'github_banner': 'true',
# 'github_button': 'true',
# 'github_user': 'recp',
# 'github_repo': 'cglm',
# 'travis_button': 'true',
# 'show_related': 'true',
# 'fixed_sidebar': 'true'
}
# Add any paths that contain custom static files (such as style sheets) here,

23
docs/source/features.rst Normal file
View File

@@ -0,0 +1,23 @@
Features
================================================================================
* general purpose matrix operations (mat4, mat3)
* chain matrix multiplication (square only)
* general purpose vector operations (cross, dot, rotate, proj, angle...)
* affine transforms
* matrix decomposition (extract rotation, scaling factor)
* optimized affine transform matrices (mul, rigid-body inverse)
* camera (lookat)
* projections (ortho, perspective)
* quaternions
* euler angles / yaw-pitch-roll to matrix
* extract euler angles
* inline or pre-compiled function call
* frustum (extract view frustum planes, corners...)
* bounding box (AABB in Frustum (culling), crop, merge...)
* bounding sphere
* project, unproject
* easing functions
* curves
* curve interpolation helpers (SMC, deCasteljau...)
* and other...

28
docs/source/getting_started.rst
View File

@@ -9,23 +9,26 @@ Types:
.. code-block:: c
:linenos:
typedef float vec3[3];
typedef int ivec3[3];
typedef CGLM_ALIGN(16) float vec4[4];
typedef float vec2[2];
typedef float vec3[3];
typedef int ivec3[3];
typedef CGLM_ALIGN_IF(16) float vec4[4];
typedef vec4 versor;
typedef vec3 mat3[3];
typedef vec3 mat3[3];
typedef vec4 mat4[4];
typedef vec4 versor;
#ifdef __AVX__
typedef CGLM_ALIGN_IF(32) vec4 mat4[4];
#else
typedef CGLM_ALIGN_IF(16) vec4 mat4[4];
#endif
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*
Alignment is Required:
Alignment Is Required:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**vec4** and **mat4** requires 16 byte alignment because vec4 and mat4 operations are
vectorized by SIMD instructions (SSE/AVX).
**vec4** and **mat4** requires 16 (32 for **mat4** if AVX is enabled) byte alignment because **vec4** and **mat4** operations are vectorized by SIMD instructions (SSE/AVX/NEON).
**UPDATE:**
By starting v0.4.5 cglm provides an option to disable alignment requirement, it is enabled as default
@@ -37,10 +40,9 @@ 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 alignment.
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.
**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**

45
docs/source/index.rst
View File

@@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to cglm's documentation!
cglm Documentation
================================
**cglm** is optimized 3D math library written in C99 (compatible with C89).
@@ -14,33 +14,36 @@ is considered to be supported as optional.
Also currently only **float** type is supported for most operations.
**Features**
* general purpose matrix operations (mat4, mat3)
* chain matrix multiplication (square only)
* general purpose vector operations (cross, dot, rotate, proj, angle...)
* affine transforms
* matrix decomposition (extract rotation, scaling factor)
* optimized affine transform matrices (mul, rigid-body inverse)
* camera (lookat)
* projections (ortho, perspective)
* quaternions
* euler angles / yaw-pitch-roll to matrix
* extract euler angles
* inline or pre-compiled function call
* frustum (extract view frustum planes, corners...)
* bounding box (AABB in Frustum (culling), crop, merge...)
.. toctree::
:maxdepth: 1
:caption: Table Of Contents:
:maxdepth: 2
:caption: Getting Started:
features
build
getting_started
.. toctree::
:maxdepth: 2
:caption: How To:
opengl
.. toctree::
:maxdepth: 2
:caption: API:
api
.. toctree::
:maxdepth: 2
:caption: Options:
opt
.. toctree::
:maxdepth: 2
:caption: Troubleshooting:
troubleshooting
Indices and tables

4
docs/source/opengl.rst
View File

@@ -43,9 +43,9 @@ array of matrices:
/* ... */
glUniformMatrix4fv(location, count, GL_FALSE, (float *)matrix);
in this way, passing aray of matrices is same
in this way, passing aray of matrices is same
Passing / Uniforming Vectors to OpenGL:
Passing / Uniforming Vectors to OpenGL:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You don't need to do extra thing when passing cglm vectors to OpengL or other APIs.