mirror of
https://github.com/recp/cglm.git
synced 2025-10-04 01:00:46 +00:00
update docs
This commit is contained in:
Recep Aslantas
@@ -1,59 +1,28 @@
|
||||
API documentation
|
||||
📚 API documentation
|
||||
================================
|
||||
|
||||
Some functions may exist twice,
|
||||
once for their namespace and once for global namespace
|
||||
to make easier to write very common functions
|
||||
**cglm** provides a few APIs for similar functions.
|
||||
|
||||
For instance, in general we use :code:`glm_vec3_dot` to get dot product
|
||||
of two **vec3**. Now we can also do this with :code:`glm_dot`,
|
||||
same for *_cross* and so on...
|
||||
* 📦 **Inline API**: All functions are inline. You can include **cglm/cglm.h** header
|
||||
to use this API. This is the default API. `glm_` is namespace/prefix for this API.
|
||||
* 📦 **Call API**: All functions are not inline. You need to build *cglm* and link it
|
||||
to your project. You can include **cglm/call.h** header to use this API. `glmc_` is namespace/prefix for this API.
|
||||
|
||||
The original function stays where it is, the function in global namespace
|
||||
of same name is just an alias, so there is no call version of those functions.
|
||||
e.g there is no func like :code:`glmc_dot` because *glm_dot* is just alias for
|
||||
:code:`glm_vec3_dot`
|
||||
And also there are also sub categories:
|
||||
|
||||
By including **cglm/cglm.h** header you will include all inline version
|
||||
of functions. Since functions in this header[s] are inline you don't need to
|
||||
build or link *cglm* against your project.
|
||||
* 📦 **Array API**: Types are raw arrays and functions takes array as argument. You can include **cglm/cglm.h** header
|
||||
to use this API. This is the default API. `glm_` is namespace/prefix for this API.
|
||||
* 📦 **Struct API**: Types are union/struct and functions takes struct as argument and return structs if needed. You can include **cglm/struct.h** header
|
||||
to use this API. This also includes **cglm/cglm.h** header.`glms_` is namespace/prefix for this API but your can omit or change it, see struct api docs.
|
||||
* 📦 **SIMD API**: SIMD functions and helpers. `glmm_` is namespace/prefix for this API.
|
||||
|
||||
But by including **cglm/call.h** header you will include all *non-inline*
|
||||
version of functions. You need to build *cglm* and link it.
|
||||
Follow the :doc:`build` documentation for this
|
||||
📌 Since struct api and call api are built top of inline array api, follow inline array api docs for individual functions.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: API categories:
|
||||
:caption: API documentations:
|
||||
|
||||
affine
|
||||
affine-mat
|
||||
affine2d
|
||||
cam
|
||||
frustum
|
||||
box
|
||||
quat
|
||||
euler
|
||||
mat2
|
||||
mat3
|
||||
mat4
|
||||
vec2
|
||||
vec2-ext
|
||||
vec3
|
||||
vec3-ext
|
||||
vec4
|
||||
vec4-ext
|
||||
ivec2
|
||||
ivec3
|
||||
ivec4
|
||||
color
|
||||
plane
|
||||
project
|
||||
util
|
||||
io
|
||||
call
|
||||
sphere
|
||||
curve
|
||||
bezier
|
||||
version
|
||||
ray
|
||||
api_inline_array
|
||||
api_struct
|
||||
api_call
|
||||
api_simd
|
||||
|
||||
11
docs/source/api_call.rst
Normal file
11
docs/source/api_call.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
Call API
|
||||
================================
|
||||
|
||||
Call API is pre-built API for making calls from library. It is built on top of the array api. **glmc_** is the namespace for the call api.
|
||||
**c** stands for call.
|
||||
|
||||
You need to built cglm to use call api. See build instructions (:doc:`build`) for more details.
|
||||
|
||||
The functions except namespace **glmc_** are same as inline api. See ( :doc:`api_inline_array` ) for more details.
|
||||
|
||||
📌 In the future we can define option to forward inline functions or struct api to call api.
|
||||
70
docs/source/api_inline_array.rst
Normal file
70
docs/source/api_inline_array.rst
Normal file
@@ -0,0 +1,70 @@
|
||||
Array API - Inline (Default)
|
||||
========================================
|
||||
|
||||
This is the default API of *cglm*. All functions are forced to be inlined
|
||||
and struct api, call api uses this inline api to share implementation.
|
||||
|
||||
📌 Call api is also array api but it is not inlined.
|
||||
In the future there may be option to forward struct api to call api instead of inline api to reduce binary size if needed.
|
||||
|
||||
📌 **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 functions can return struct/union
|
||||
📌 In struct api you can access items like **.x**, **.y**, **.z**, **.w**, **.r**, **.g**, **.b**, **.a**, **.m00**, **m01**...
|
||||
|
||||
Some functions may exist twice, once for their namespace and once for global namespace
|
||||
to make easier to write very common functions
|
||||
|
||||
For instance, in general we use :code:`glm_vec3_dot` to get dot product
|
||||
of two **vec3**. Now we can also do this with :code:`glm_dot`,
|
||||
same for *_cross* and so on...
|
||||
|
||||
The original function stays where it is, the function in global namespace
|
||||
of same name is just an alias, so there is no call version of those functions.
|
||||
e.g there is no func like :code:`glmc_dot` because *glm_dot* is just alias for
|
||||
:code:`glm_vec3_dot`
|
||||
|
||||
By including **cglm/cglm.h** header you will include all inline version
|
||||
of functions. Since functions in this header[s] are inline you don't need to
|
||||
build or link *cglm* against your project.
|
||||
|
||||
But by including **cglm/call.h** header you will include all *non-inline*
|
||||
version of functions. You need to build *cglm* and link it.
|
||||
Follow the :doc:`build` documentation for this
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: API categories:
|
||||
|
||||
affine
|
||||
affine-mat
|
||||
affine2d
|
||||
cam
|
||||
frustum
|
||||
box
|
||||
quat
|
||||
euler
|
||||
mat2
|
||||
mat3
|
||||
mat4
|
||||
vec2
|
||||
vec2-ext
|
||||
vec3
|
||||
vec3-ext
|
||||
vec4
|
||||
vec4-ext
|
||||
ivec2
|
||||
ivec3
|
||||
ivec4
|
||||
color
|
||||
plane
|
||||
project
|
||||
util
|
||||
io
|
||||
call
|
||||
sphere
|
||||
curve
|
||||
bezier
|
||||
version
|
||||
ray
|
||||
12
docs/source/api_simd.rst
Normal file
12
docs/source/api_simd.rst
Normal file
@@ -0,0 +1,12 @@
|
||||
SIMD API
|
||||
================================
|
||||
|
||||
SIMD api is special api for SIMD operations. **glmm_** prefix is used for SIMD operations in cglm. It is used in many places in cglm.
|
||||
You can use it for your own SIMD operations too. In the future the api may be extended by time.
|
||||
|
||||
Supported SIMD architectures ( may vary by time )
|
||||
|
||||
* SSE / SSE2
|
||||
* AVX
|
||||
* NEON
|
||||
* WASM 128
|
||||
98
docs/source/api_struct.rst
Normal file
98
docs/source/api_struct.rst
Normal file
@@ -0,0 +1,98 @@
|
||||
Struct API
|
||||
================================
|
||||
|
||||
Struct API is alternative API to array api to use **cglm** with improved type safety and easy to use.
|
||||
Since struct api is built top of array api, every struct API is not documented here.
|
||||
See array api documentation for more information for individual functions.
|
||||
|
||||
By default struct api adds `s` suffix to every type name e.g. vec3s, mat4s, versors etc.
|
||||
Also struct api `s` suffix to namespace e.g. `glms_vec3_add`, `glms_mat4_mul` etc.
|
||||
|
||||
By starting v0.9.0, struct api namespace is configurable. We can omit **glms_** namespace or
|
||||
even change it with custom name to move existing api integrations to **cglm** more easliy...
|
||||
We can also add **s** to functin names if we want e.g. `glms_vec3_add()` -> `vec3_add()` or `vec3s_add()`.
|
||||
|
||||
By including **cglm/struct.h** header you will include all struct api. It will also include **cglm/cglm.h** too.
|
||||
Since struct apis are inline you don't need to build or link *cglm* against
|
||||
your project unless if you want to use pre-built call-api too.
|
||||
|
||||
Struct API is built top of array api. So you can mix them.
|
||||
Use **.raw** union member to access raw array data to use it with array api.
|
||||
|
||||
Unlike array api ([0], [1], [0][0] ...), it is also possible to use struct api
|
||||
with **.x**, **.y**, **.z**, **.w**, **.r**, **.g**, **.b**, **.a**, **.m00**, **m01**...
|
||||
accessors to access individual elements/properties of vectors and matrices.
|
||||
|
||||
Struct API usage:
|
||||
-----------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <cglm/struct.h>
|
||||
|
||||
mat4s m1 = glms_mat4_identity(); /* init... */
|
||||
mat4s m2 = glms_mat4_identity(); /* init... */
|
||||
mat4s m3 = glms_mat4_mul(glms_mat4_mul(m1, m2), glms_mat4_mul(m3, m4));
|
||||
|
||||
vec3s v1 = { 1.0f, 0.0f, 0.0f };
|
||||
vec3s v2 = { 0.0f, 1.0f, 0.0f };
|
||||
vec4s v4 = { 0.0f, 1.0f, 0.0f, 0.0f };
|
||||
vec4 v5a = { 0.0f, 1.0f, 0.0f, 0.0f };
|
||||
|
||||
mat4s m4 = glms_rotate(m3, M_PI_2,
|
||||
glms_vec3_cross(glms_vec3_add(v1, v6)
|
||||
glms_vec3_add(v1, v7)));
|
||||
|
||||
v1.x = 1.0f; v1.y = 0.0f; v1.z = 0.0f;
|
||||
// or
|
||||
v1.raw[0] = 1.0f; v1.raw[1] = 0.0f; v1.raw[2] = 0.0f;
|
||||
|
||||
/* use struct api with array api (mix them). */
|
||||
/* use .raw to access array and use it with array api */
|
||||
|
||||
glm_vec4_add(m4.col[0].raw, v5a, m4.col[0].raw);
|
||||
glm_mat4_mulv(m4.raw, v4.raw, v5a);
|
||||
|
||||
or omit `glms_` namespace completely (see options below):
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CGLM_OMIT_NS_FROM_STRUCT_API
|
||||
|
||||
#include <cglm/struct.h>
|
||||
|
||||
mat4s m1 = mat4_identity(); /* init... */
|
||||
mat4s m2 = mat4_identity(); /* init... */
|
||||
mat4s m3 = mat4_mul(mat4_mul(m1, m2), mat4_mul(m3, m4));
|
||||
|
||||
vec3s v1 = { 1.0f, 0.0f, 0.0f };
|
||||
vec3s v2 = { 0.0f, 1.0f, 0.0f };
|
||||
vec4s v4 = { 0.0f, 1.0f, 0.0f, 0.0f };
|
||||
vec4 v5a = { 0.0f, 1.0f, 0.0f, 0.0f };
|
||||
|
||||
mat4s m4 = glms_rotate(m3, M_PI_2,
|
||||
vec3_cross(vec3_add(v1, v6)
|
||||
vec3_add(v1, v7)));
|
||||
|
||||
v1.x = 1.0f; v1.y = 0.0f; v1.z = 0.0f;
|
||||
// or
|
||||
v1.raw[0] = 1.0f; v1.raw[1] = 0.0f; v1.raw[2] = 0.0f;
|
||||
|
||||
/* use struct api with array api (mix them) */
|
||||
glm_vec4_add(m4.col[0].raw, v5a, m4.col[0].raw);
|
||||
glm_mat4_mulv(m4.raw, v4.raw, v5a);
|
||||
|
||||
Configuring the Struct API:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To configure the Struct API namespace, you can define the following macros before including the cglm/struct.h header:
|
||||
|
||||
- **CGLM_OMIT_NS_FROM_STRUCT_API**: omits CGLM_STRUCT_API_NS (`glms_`) namespace completely if there is sub namespace e.g `mat4_`, `vec4_` ... DEFAULT is not defined
|
||||
- **CGLM_STRUCT_API_NS**: define name space for struct api, DEFAULT is **glms**
|
||||
- **CGLM_STRUCT_API_NAME_SUFFIX**: define name suffix, DEFAULT is **empty** e.g defining it as #define CGLM_STRUCT_API_NAME_SUFFIX s will add s suffix to mat4_mul -> mat4s_mul
|
||||
|
||||
|
||||
Detailed documentation for Struct API:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Since struct api if built top of array api, see array api functions for more information about individual functions.
|
||||
@@ -71,7 +71,7 @@ release = u'0.9.0'
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
language = 'en'
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
@@ -111,7 +111,7 @@ html_theme_options = {
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
# html_static_path = ['_static']
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ------------------------------------------
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
Features
|
||||
================================================================================
|
||||
|
||||
* **scalar** and **simd** (sse, avx, neon...) optimizations
|
||||
* **scalar** and **simd** (sse, avx, neon, wasm...) optimizations
|
||||
* option to use different clipspaces e.g. Left Handed, Zero-to-One... (currrently right handed negative-one is default)
|
||||
* array api and struct api, you can use arrays or structs.
|
||||
* general purpose matrix operations (mat4, mat3)
|
||||
|
||||
@@ -28,7 +28,7 @@ considered to be supported as optional.
|
||||
opengl
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
:caption: API:
|
||||
|
||||
api
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
.. default-domain:: C
|
||||
|
||||
Options
|
||||
🛠️ Options
|
||||
===============================================================================
|
||||
|
||||
A few options are provided via macros.
|
||||
@@ -90,6 +90,16 @@ You have to extra options for dot product: **CGLM_SSE4_DOT** and **CGLM_SSE3_DOT
|
||||
|
||||
otherwise cglm will use custom cglm's hadd functions which are optimized too.
|
||||
|
||||
Struct API Options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To configure the Struct API namespace, you can define the following macros before including the cglm/struct.h header:
|
||||
|
||||
- **CGLM_OMIT_NS_FROM_STRUCT_API**: omits CGLM_STRUCT_API_NS (`glms_`) namespace completely if there is sub namespace e.g `mat4_`, `vec4_` ... DEFAULT is not defined
|
||||
- **CGLM_STRUCT_API_NS**: define name space for struct api, DEFAULT is **glms**
|
||||
- **CGLM_STRUCT_API_NAME_SUFFIX**: define name suffix, DEFAULT is **empty** e.g defining it as #define CGLM_STRUCT_API_NAME_SUFFIX s will add s suffix to mat4_mul -> mat4s_mul
|
||||
|
||||
|
||||
Print Options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
Reference in New Issue
Block a user