mirror of
https://github.com/recp/cglm.git
synced 2025-10-03 16:51:35 +00:00
99 lines
3.9 KiB
ReStructuredText
99 lines
3.9 KiB
ReStructuredText
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.
|