cglm uses glm prefix for all functions e.g. glm_lookat. You can see supported types in common header file:
1 2 3 4 5 6 7 8 9 10 11 12
typedef float vec2; typedef float vec3; typedef int ivec3; typedef CGLM_ALIGN_IF(16) float vec4; typedef vec4 versor; typedef vec3 mat3; #ifdef __AVX__ typedef CGLM_ALIGN_IF(32) vec4 mat4; #else typedef CGLM_ALIGN_IF(16) vec4 mat4; #endif
As you can see types don’t store extra informations in favor of space. You can send these values e.g. matrix to OpenGL directly without casting or calling a function like value_ptr
Alignment Is Required:¶
vec4 and mat4 requires 16 (32 for mat4 if AVX is enabled) byte alignment because vec4 and mat4 operations are vectorized by SIMD instructions (SSE/AVX/NEON).
By starting v0.4.5 cglm provides an option to disable alignment requirement, it is enabled as defaultCheck 🛠️ Options page for more details
Also alignment is disabled for older msvc verisons as default. Now alignment is only required in Visual Studio 2017 version 15.6+ if CGLM_ALL_UNALIGNED macro is not defined.
cglm doesn’t alloc any memory on heap. So it doesn’t provide any allocator. You must allocate memory yourself. You should alloc memory for out parameters too if you pass pointer of memory location. When allocating memory, don’t forget that vec4 and mat4 require alignment.
NOTE: Unaligned vec4 and unaligned mat4 operations will be supported in the future. Check todo list. Because you may want to multiply a CGLM matrix with external matrix. There is no guarantee that non-CGLM matrix is aligned. Unaligned types will have u prefix e.g. umat4
Array vs Struct:¶
cglm uses arrays for vector and matrix types. So you can’t access individual elements like vec.x, vec.y, vec.z… You must use subscript to access vector elements e.g. vec, vec, vec.
Also I think it is more meaningful to access matrix elements with subscript e.g matrix instead of matrix._23. Since matrix is array of vectors, vectors are also defined as array. This makes types homogeneous.
Since C doesn’t support return arrays, cglm also doesn’t support this feature.
cglm provides a few way to call a function to do same operation.
- Inline - glm_, glm_u
- Pre-compiled - glmc_, glmc_u
For instance glm_mat4_mul is inline (all glm_ functions are inline), to make it non-inline (pre-compiled), call it as glmc_mat4_mul from library, to use unaligned version use glm_umat4_mul (todo).
Most functions have dest parameter for output. For instance mat4_mul func looks like this:
CGLM_INLINE void glm_mat4_mul(mat4 m1, mat4 m2, mat4 dest)
The dest parameter is out parameter. Result will be stored in dest. Also in this case matrix multiplication order is dest = m1 * m2.
- Changing parameter order will change the multiplication order.
- You can pass all parameter same (this is similar to m1 *= m1), you can pass dest as m1 or m2 (this is similar to m1 *= m2)
v postfix in function names¶
You may see v postfix in some function names, v stands for vector. For instance consider a function that accepts three parameters x, y, z. This function may be overloaded by v postfix to accept vector (vec3) instead of separate parameters. In some places the v means that it will be apply to a vector.
_to postfix in function names¶
_to version of function will store the result in specified parameter instead of in-out parameter. Some functions don’t have _to prefix but they still behave like this e.g. glm_mat4_mul.