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

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

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