diff --git a/docs/source/api.rst b/docs/source/api.rst index 7ffb823..4712030 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -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 diff --git a/docs/source/api_call.rst b/docs/source/api_call.rst new file mode 100644 index 0000000..9e8fff3 --- /dev/null +++ b/docs/source/api_call.rst @@ -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. \ No newline at end of file diff --git a/docs/source/api_inline_array.rst b/docs/source/api_inline_array.rst new file mode 100644 index 0000000..56a0dd7 --- /dev/null +++ b/docs/source/api_inline_array.rst @@ -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 diff --git a/docs/source/api_simd.rst b/docs/source/api_simd.rst new file mode 100644 index 0000000..3a5024d --- /dev/null +++ b/docs/source/api_simd.rst @@ -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 diff --git a/docs/source/api_struct.rst b/docs/source/api_struct.rst new file mode 100644 index 0000000..c2dc305 --- /dev/null +++ b/docs/source/api_struct.rst @@ -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 + + 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 + + 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. diff --git a/docs/source/conf.py b/docs/source/conf.py index c37d8dc..d9b6db3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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 ------------------------------------------ diff --git a/docs/source/features.rst b/docs/source/features.rst index 8113f63..7b61599 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -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) diff --git a/docs/source/index.rst b/docs/source/index.rst index 34a71c4..1cc3bbe 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,7 +28,7 @@ considered to be supported as optional. opengl .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: API: api diff --git a/docs/source/opt.rst b/docs/source/opt.rst index 9b28054..6abd8ec 100644 --- a/docs/source/opt.rst +++ b/docs/source/opt.rst @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~