update docs

Fix simd signmask

docs/source/api.rst

@@ -1,59 +1,28 @@
-API documentation
+📚 API documentation
 ================================
 
-Some functions may exist twice,
+**cglm** provides a few APIs for similar functions.
-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
+* 📦 **Inline API**: All functions are inline. You can include **cglm/cglm.h** header
-of two **vec3**. Now we can also do this with :code:`glm_dot`,
+  to use this API. This is the default API. `glm_` is namespace/prefix for this API. 
-same for *_cross* and so on...
+* 📦 **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
+And also there are also sub categories:
-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
+* 📦 **Array API**: Types are raw arrays and functions takes array as argument. You can include **cglm/cglm.h** header
-of functions. Since functions in this header[s] are inline you don't need to
+  to use this API. This is the default API. `glm_` is namespace/prefix for this API. 
-build or link *cglm* against your project.
+* 📦 **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*
+📌 Since struct api and call api are built top of inline array api, follow inline array api docs for individual functions. 
-version of functions. You need to build *cglm* and link it.
-Follow the :doc:`build` documentation for this
 
 .. toctree::
    :maxdepth: 1
-   :caption: API categories:
+   :caption: API documentations:
 
-   affine
+   api_inline_array
-   affine-mat
+   api_struct
-   affine2d
+   api_call
-   cam
+   api_simd
-   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

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.

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

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

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 <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.

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 ------------------------------------------

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)

docs/source/index.rst

@@ -28,7 +28,7 @@ considered to be supported as optional.
    opengl
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: API:
 
    api

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~