Skip to content

Commit 50b1c18

Browse files
recprecp
committed
update docs
1 parent 44268d2 commit 50b1c18

File tree

9 files changed

+224
-54
lines changed

9 files changed

+224
-54
lines changed

‎docs/source/api.rst‎

Lines changed: 18 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,28 @@
1-
API documentation
1+
📚 API documentation
22
================================
33

4-
Some functions may exist twice,
5-
once for their namespace and once for global namespace
6-
to make easier to write very common functions
4+
**cglm** provides a few APIs for similar functions.
75

8-
For instance, in general we use :code:`glm_vec3_dot` to get dot product
9-
of two **vec3**. Now we can also do this with :code:`glm_dot`,
10-
same for *_cross* and so on...
6+
* 📦 **Inline API**: All functions are inline. You can include **cglm/cglm.h** header
7+
to use this API. This is the default API. `glm_` is namespace/prefix for this API.
8+
* 📦 **Call API**: All functions are not inline. You need to build *cglm* and link it
9+
to your project. You can include **cglm/call.h** header to use this API. `glmc_` is namespace/prefix for this API.
1110

12-
The original function stays where it is, the function in global namespace
13-
of same name is just an alias, so there is no call version of those functions.
14-
e.g there is no func like :code:`glmc_dot` because *glm_dot* is just alias for
15-
:code:`glm_vec3_dot`
11+
And also there are also sub categories:
1612

17-
By including **cglm/cglm.h** header you will include all inline version
18-
of functions. Since functions in this header[s] are inline you don't need to
19-
build or link *cglm* against your project.
13+
* 📦 **Array API**: Types are raw arrays and functions takes array as argument. You can include **cglm/cglm.h** header
14+
to use this API. This is the default API. `glm_` is namespace/prefix for this API.
15+
* 📦 **Struct API**: Types are union/struct and functions takes struct as argument and return structs if needed. You can include **cglm/struct.h** header
16+
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.
17+
* 📦 **SIMD API**: SIMD functions and helpers. `glmm_` is namespace/prefix for this API.
2018

21-
But by including **cglm/call.h** header you will include all *non-inline*
22-
version of functions. You need to build *cglm* and link it.
23-
Follow the :doc:`build` documentation for this
19+
📌 Since struct api and call api are built top of inline array api, follow inline array api docs for individual functions.
2420

2521
.. toctree::
2622
:maxdepth: 1
27-
:caption: API categories:
23+
:caption: API documentations:
2824

29-
affine
30-
affine-mat
31-
affine2d
32-
cam
33-
frustum
34-
box
35-
quat
36-
euler
37-
mat2
38-
mat3
39-
mat4
40-
vec2
41-
vec2-ext
42-
vec3
43-
vec3-ext
44-
vec4
45-
vec4-ext
46-
ivec2
47-
ivec3
48-
ivec4
49-
color
50-
plane
51-
project
52-
util
53-
io
54-
call
55-
sphere
56-
curve
57-
bezier
58-
version
59-
ray
25+
api_inline_array
26+
api_struct
27+
api_call
28+
api_simd

‎docs/source/api_call.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Call API
2+
================================
3+
4+
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.
5+
**c** stands for call.
6+
7+
You need to built cglm to use call api. See build instructions (:doc:`build`) for more details.
8+
9+
The functions except namespace **glmc_** are same as inline api. See ( :doc:`api_inline_array` ) for more details.
10+
11+
📌 In the future we can define option to forward inline functions or struct api to call api.

‎docs/source/api_inline_array.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Array API - Inline (Default)
2+
========================================
3+
4+
This is the default API of *cglm*. All functions are forced to be inlined
5+
and struct api, call api uses this inline api to share implementation.
6+
7+
📌 Call api is also array api but it is not inlined.
8+
In the future there may be option to forward struct api to call api instead of inline api to reduce binary size if needed.
9+
10+
📌 **USE this API docs for similar functions in struct and call api**
11+
12+
📌 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.
13+
📌 In struct api functions can return struct/union
14+
📌 In struct api you can access items like **.x**, **.y**, **.z**, **.w**, **.r**, **.g**, **.b**, **.a**, **.m00**, **m01**...
15+
16+
Some functions may exist twice, once for their namespace and once for global namespace
17+
to make easier to write very common functions
18+
19+
For instance, in general we use :code:`glm_vec3_dot` to get dot product
20+
of two **vec3**. Now we can also do this with :code:`glm_dot`,
21+
same for *_cross* and so on...
22+
23+
The original function stays where it is, the function in global namespace
24+
of same name is just an alias, so there is no call version of those functions.
25+
e.g there is no func like :code:`glmc_dot` because *glm_dot* is just alias for
26+
:code:`glm_vec3_dot`
27+
28+
By including **cglm/cglm.h** header you will include all inline version
29+
of functions. Since functions in this header[s] are inline you don't need to
30+
build or link *cglm* against your project.
31+
32+
But by including **cglm/call.h** header you will include all *non-inline*
33+
version of functions. You need to build *cglm* and link it.
34+
Follow the :doc:`build` documentation for this
35+
36+
.. toctree::
37+
:maxdepth: 1
38+
:caption: API categories:
39+
40+
affine
41+
affine-mat
42+
affine2d
43+
cam
44+
frustum
45+
box
46+
quat
47+
euler
48+
mat2
49+
mat3
50+
mat4
51+
vec2
52+
vec2-ext
53+
vec3
54+
vec3-ext
55+
vec4
56+
vec4-ext
57+
ivec2
58+
ivec3
59+
ivec4
60+
color
61+
plane
62+
project
63+
util
64+
io
65+
call
66+
sphere
67+
curve
68+
bezier
69+
version
70+
ray

‎docs/source/api_simd.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
SIMD API
2+
================================
3+
4+
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.
5+
You can use it for your own SIMD operations too. In the future the api may be extended by time.
6+
7+
Supported SIMD architectures ( may vary by time )
8+
9+
* SSE / SSE2
10+
* AVX
11+
* NEON
12+
* WASM 128

‎docs/source/api_struct.rst‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
Struct API
2+
================================
3+
4+
Struct API is alternative API to array api to use **cglm** with improved type safety and easy to use.
5+
Since struct api is built top of array api, every struct API is not documented here.
6+
See array api documentation for more information for individual functions.
7+
8+
By default struct api adds `s` suffix to every type name e.g. vec3s, mat4s, versors etc.
9+
Also struct api `s` suffix to namespace e.g. `glms_vec3_add`, `glms_mat4_mul` etc.
10+
11+
By starting v0.9.0, struct api namespace is configurable. We can omit **glms_** namespace or
12+
even change it with custom name to move existing api integrations to **cglm** more easliy...
13+
We can also add **s** to functin names if we want e.g. `glms_vec3_add()` -> `vec3_add()` or `vec3s_add()`.
14+
15+
By including **cglm/struct.h** header you will include all struct api. It will also include **cglm/cglm.h** too.
16+
Since struct apis are inline you don't need to build or link *cglm* against
17+
your project unless if you want to use pre-built call-api too.
18+
19+
Struct API is built top of array api. So you can mix them.
20+
Use **.raw** union member to access raw array data to use it with array api.
21+
22+
Unlike array api ([0], [1], [0][0] ...), it is also possible to use struct api
23+
with **.x**, **.y**, **.z**, **.w**, **.r**, **.g**, **.b**, **.a**, **.m00**, **m01**...
24+
accessors to access individual elements/properties of vectors and matrices.
25+
26+
Struct API usage:
27+
-----------------
28+
29+
.. code-block:: c
30+
31+
#include <cglm/struct.h>
32+
33+
mat4s m1 = glms_mat4_identity(); /* init... */
34+
mat4s m2 = glms_mat4_identity(); /* init... */
35+
mat4s m3 = glms_mat4_mul(glms_mat4_mul(m1, m2), glms_mat4_mul(m3, m4));
36+
37+
vec3s v1 = { 1.0f, 0.0f, 0.0f };
38+
vec3s v2 = { 0.0f, 1.0f, 0.0f };
39+
vec4s v4 = { 0.0f, 1.0f, 0.0f, 0.0f };
40+
vec4 v5a = { 0.0f, 1.0f, 0.0f, 0.0f };
41+
42+
mat4s m4 = glms_rotate(m3, M_PI_2,
43+
glms_vec3_cross(glms_vec3_add(v1, v6)
44+
glms_vec3_add(v1, v7)));
45+
46+
v1.x = 1.0f; v1.y = 0.0f; v1.z = 0.0f;
47+
// or
48+
v1.raw[0] = 1.0f; v1.raw[1] = 0.0f; v1.raw[2] = 0.0f;
49+
50+
/* use struct api with array api (mix them). */
51+
/* use .raw to access array and use it with array api */
52+
53+
glm_vec4_add(m4.col[0].raw, v5a, m4.col[0].raw);
54+
glm_mat4_mulv(m4.raw, v4.raw, v5a);
55+
56+
or omit `glms_` namespace completely (see options below):
57+
58+
.. code-block:: c
59+
60+
#define CGLM_OMIT_NS_FROM_STRUCT_API
61+
62+
#include <cglm/struct.h>
63+
64+
mat4s m1 = mat4_identity(); /* init... */
65+
mat4s m2 = mat4_identity(); /* init... */
66+
mat4s m3 = mat4_mul(mat4_mul(m1, m2), mat4_mul(m3, m4));
67+
68+
vec3s v1 = { 1.0f, 0.0f, 0.0f };
69+
vec3s v2 = { 0.0f, 1.0f, 0.0f };
70+
vec4s v4 = { 0.0f, 1.0f, 0.0f, 0.0f };
71+
vec4 v5a = { 0.0f, 1.0f, 0.0f, 0.0f };
72+
73+
mat4s m4 = glms_rotate(m3, M_PI_2,
74+
vec3_cross(vec3_add(v1, v6)
75+
vec3_add(v1, v7)));
76+
77+
v1.x = 1.0f; v1.y = 0.0f; v1.z = 0.0f;
78+
// or
79+
v1.raw[0] = 1.0f; v1.raw[1] = 0.0f; v1.raw[2] = 0.0f;
80+
81+
/* use struct api with array api (mix them) */
82+
glm_vec4_add(m4.col[0].raw, v5a, m4.col[0].raw);
83+
glm_mat4_mulv(m4.raw, v4.raw, v5a);
84+
85+
Configuring the Struct API:
86+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87+
88+
To configure the Struct API namespace, you can define the following macros before including the cglm/struct.h header:
89+
90+
- **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
91+
- **CGLM_STRUCT_API_NS**: define name space for struct api, DEFAULT is **glms**
92+
- **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
93+
94+
95+
Detailed documentation for Struct API:
96+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97+
98+
Since struct api if built top of array api, see array api functions for more information about individual functions.

‎docs/source/conf.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@
7171
#
7272
# This is also used if you do content translation via gettext catalogs.
7373
# Usually you set "language" from the command line for these cases.
74-
language = None
74+
language = 'en'
7575

7676
# List of patterns, relative to source directory, that match files and
7777
# directories to ignore when looking for source files.
@@ -111,7 +111,7 @@
111111
# Add any paths that contain custom static files (such as style sheets) here,
112112
# relative to this directory. They are copied after the builtin static files,
113113
# so a file named "default.css" will overwrite the builtin "default.css".
114-
html_static_path = ['_static']
114+
# html_static_path = ['_static']
115115

116116

117117
# -- Options for HTMLHelp output ------------------------------------------

‎docs/source/features.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Features
22
================================================================================
33

4-
* **scalar** and **simd** (sse, avx, neon...) optimizations
4+
* **scalar** and **simd** (sse, avx, neon, wasm...) optimizations
55
* option to use different clipspaces e.g. Left Handed, Zero-to-One... (currrently right handed negative-one is default)
66
* array api and struct api, you can use arrays or structs.
77
* general purpose matrix operations (mat4, mat3)

‎docs/source/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ considered to be supported as optional.
2828
opengl
2929

3030
.. toctree::
31-
:maxdepth: 2
31+
:maxdepth: 3
3232
:caption: API:
3333

3434
api

‎docs/source/opt.rst‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. default-domain:: C
22

3-
Options
3+
🛠️ Options
44
===============================================================================
55

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

9191
otherwise cglm will use custom cglm's hadd functions which are optimized too.
9292

93+
Struct API Options
94+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95+
96+
To configure the Struct API namespace, you can define the following macros before including the cglm/struct.h header:
97+
98+
- **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
99+
- **CGLM_STRUCT_API_NS**: define name space for struct api, DEFAULT is **glms**
100+
- **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
101+
102+
93103
Print Options
94104
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95105

0 commit comments

Comments
 (0)