cglm/docs/source/opt.rst

.. default-domain:: C

🛠️ Options
===============================================================================

A few options are provided via macros.

Alignment Option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As default, cglm requires types to be aligned. Alignment requirements:

vec3:   8 byte
vec4:   16 byte
mat4:   16 byte
versor: 16 byte

By starting **v0.4.5** cglm provides an option to disable alignment requirement.
To enable this option define **CGLM_ALL_UNALIGNED** macro before all headers.
You can define it in Xcode, Visual Studio (or other IDEs) or you can also prefer
to define it in build system. If you use pre-compiled versions then you
have to compile cglm with **CGLM_ALL_UNALIGNED** macro.

**VERY VERY IMPORTANT:** If you use cglm in multiple projects and
 those projects are depends on each other, then

 | *ALWAYS* or *NEVER USE* **CGLM_ALL_UNALIGNED** macro in linked projects

 if you do not know what you are doing. Because a cglm header included
 via 'project A' may force types to be aligned and another cglm header
 included via 'project B' may not require alignment. In this case
 cglm functions will read from and write to **INVALID MEMORY LOCATIONs**.

 ALWAYS USE SAME CONFIGURATION / OPTION for **cglm** if you have multiple projects.

 For instance if you set CGLM_ALL_UNALIGNED in a project then set it in other projects too

Clipspace Option[s]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By starting **v0.8.3** cglm provides options to switch between clipspace configurations.

Clipspace related files are located at `include/cglm/[struct]/clipspace.h` but 
these are included in related files like `cam.h`. If you don't want to change your existing 
clipspace configuration and want to use different clipspace function like `glm_lookat_zo` or `glm_lookat_lh_zo`...
then you can include individual headers or just define `CGLM_CLIPSPACE_INCLUDE_ALL` which will iclude all headers for you.

1. **CGLM_CLIPSPACE_INCLUDE_ALL**
2. **CGLM_FORCE_DEPTH_ZERO_TO_ONE**
3. **CGLM_FORCE_LEFT_HANDED**


1. **CGLM_CLIPSPACE_INCLUDE_ALL**:

By defining this macro, **cglm** will include all clipspace functions for you by just using
`#include cglm/cglm.h` or `#include cglm/struct.h` or `#include cglm/call.h`

Otherwise you need to include header you want manually e.g. `#include cglm/clipspace/view_rh_zo.h`

2. **CGLM_FORCE_DEPTH_ZERO_TO_ONE**

This is similar to **GLM**'s **GLM_FORCE_DEPTH_ZERO_TO_ONE** option. 
This will set clip space between 0 to 1 which makes **cglm** Vulkan, Metal friendly. 

You can use functions like `glm_lookat_lh_zo()` individually. By setting **CGLM_FORCE_DEPTH_ZERO_TO_ONE**
functions in cam.h for instance will use `_zo` versions.

3. **CGLM_FORCE_LEFT_HANDED**

Force **cglm** to use the left handed coordinate system by default, currently **cglm** uses right handed coordinate system as default,
you can change this behavior with this option.

**VERY VERY IMPORTANT:**

Be careful if you include **cglm** in multiple projects.

SSE and SSE2 Shuffle Option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**_mm_shuffle_ps** generates **shufps** instruction even if registers are same.
You can force it to generate **pshufd** instruction by defining
**CGLM_USE_INT_DOMAIN** macro. As default it is not defined.

SSE3 and SSE4 Dot Product Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You have to extra options for dot product: **CGLM_SSE4_DOT** and **CGLM_SSE3_DOT**.

- If **SSE4** is enabled then you can define **CGLM_SSE4_DOT** to force cglm to use **_mm_dp_ps** instruction.
- If **SSE3** is enabled then you can define **CGLM_SSE3_DOT** to force cglm to use **_mm_hadd_ps** instructions.

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

1. **CGLM_DEFINE_PRINTS**
2. **CGLM_NO_PRINTS_NOOP** (use CGLM_DEFINE_PRINTS)

Inline prints are only enabled in **DEBUG** mode or if **CGLM_DEFINE_PRINTS** is defined.
**glmc_** versions will always print too.

Because **cglm** tried to enable print functions in debug mode and disable them in
release/production mode to eliminate printing costs when we do not need them.

**cglm** checks **DEBUG** or **_DEBUG** macros to test debug mode, if these are not working for you then you can use 
**CGLM_DEFINE_PRINTS** to force enable, or create a PR to introduce new macro to test against debugging mode.

If DEBUG mode is not enabled then print functions will be emptied to eliminate print function calls.
You can disable this feature too by defining **CGLM_DEFINE_PRINTS** macro top of cglm header 
or in project/build settings...

3. **CGLM_PRINT_PRECISION**    5

precision.

4. **CGLM_PRINT_MAX_TO_SHORT** 1e5

if a number is greater than this value then %g will be used, since this is shorten print you won't be able to see high precision.

5. **CGLM_PRINT_COLOR**        "\033[36m"
6. **CGLM_PRINT_COLOR_RESET**  "\033[0m"

You can disable colorful print output by defining **CGLM_PRINT_COLOR** and **CGLM_PRINT_COLOR_RESET** as empty macro.
Because some terminals may not support colors.