From 8fa21a1837783154589fbef2fc2a515aa5360946 Mon Sep 17 00:00:00 2001 From: Recep Aslantas Date: Sun, 17 Mar 2019 09:33:38 +0300 Subject: [PATCH] docs: use sphinx_rtd_theme theme dor documentation --- docs/source/build.rst | 32 +++++++++++++++++------ docs/source/conf.py | 16 ++++++------ docs/source/features.rst | 23 +++++++++++++++++ docs/source/getting_started.rst | 28 ++++++++++---------- docs/source/index.rst | 45 ++++++++++++++++++--------------- docs/source/opengl.rst | 4 +-- 6 files changed, 96 insertions(+), 52 deletions(-) create mode 100644 docs/source/features.rst diff --git a/docs/source/build.rst b/docs/source/build.rst index 842c761..c725ab4 100644 --- a/docs/source/build.rst +++ b/docs/source/build.rst @@ -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 + diff --git a/docs/source/conf.py b/docs/source/conf.py index 9fd800a..c2b6ba0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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, diff --git a/docs/source/features.rst b/docs/source/features.rst new file mode 100644 index 0000000..69e8cd1 --- /dev/null +++ b/docs/source/features.rst @@ -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... diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 2f8511c..bf2b8f3 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -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** diff --git a/docs/source/index.rst b/docs/source/index.rst index cfdf220..38c9e37 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 diff --git a/docs/source/opengl.rst b/docs/source/opengl.rst index e6b37e0..a38d572 100644 --- a/docs/source/opengl.rst +++ b/docs/source/opengl.rst @@ -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.