Repository files navigation

A highly optimized 2D|3D math library. Also known as OpenGL Mathematics (glm) for C.cglm provides fast and ergonomic math functions to ease graphics programming. It is community friendly – feel free to report any bugs and issues you face.
If you're using C++, you might want to check outGLM

• Allocation-free
• Header-only
• SIMD-optimized
• API-agnostic

All functions and their parameters are documented above their declaration inside their corresponding headers.
Alternatively, you can read the complete documentationhere.

cglm can be used in it's entirety as a header-only library simply by includingcglm/cglm.h. If you wish to link against it instead, it can be built using one of the supported build systems. Detailed information about building on individual platforms and build systems along with the instructions for building the documentation can be found inBUILDING.md.

Include thecglm/cglm.h header and use functions with theglm_ prefix.

#include"cglm/cglm.h"// ...vec2vector;glm_vec2_zero(vector);

Includecglm/struct.h and useglms_.

#include"cglm/struct.h"// ...vec2svector=glms_vec2_zero();

Includecglm/call.h and useglmc_.

#include"cglm/call.h"// ...vec2vector;glmc_vec2_zero(vector);

While cglm by default aligns what's necessary, it is possible to disable this by definingCGLM_ALL_UNALIGNED. If you're targeting machines with any kind of SIMD support, make sure that allvec4,mat4 andmat2 arguments you pass to cglm functions are aligned to prevent unexpected crashes, alternatively use the unaligned versions if present.

The struct API works as follows (note thes suffix on types,glms_ prefix on functions andGLMS_ on constants):

#include<cglm/struct.h>mat4smat=GLMS_MAT4_IDENTITY_INIT;mat4sinv=glms_mat4_inv(mat);

Struct functions generally take parametersby copy andreturn the results rather than taking pointers and writing to out parameters. That means your variables can usually beconst, if you're into that.

The types used are actually unions that allow access to the same data in multiple ways. One of these involves anonymous structures available since C11. MSVC supports them in earlier versions out of the box and GCC/Clang as well if you enable-fms-extensions.To explicitly enable anonymous structures#define CGLM_USE_ANONYMOUS_STRUCT 1, or0 to disable them.For backwards compatibility, you can also#define CGLM_NO_ANONYMOUS_STRUCT to disable them. If you don't specify explicitly, cglm will attempt a best guess based on your compiler and C version.

• _dup (duplicate) functions were renamed to_copy. For instance:glm_vec_dup ->glm_vec3_copy.
• OpenGL related functions were dropped to make cglm API independent.
• [bugfix] Euler angles had been previously implemented in reverse order (extrinsic). This was fixed to be intrinsic.
• [major change] Starting withv0.4.0, quaternions are stored as [x, y, z, w]. Previously it was [w, x, y, z].
• [api rename] Starting withv0.4.5,glm_simd_ functions are renamed toglmm_.
• [new option] Starting withv0.4.5, alignment requirements can be disabled. Read more in the documentation.
• [major change] Starting withv0.5.0, vec3 functions occupy theglm_vec3_ namespace. This used to beglm_vec_ in earlier versions.
• [major change] Starting withv0.5.1,vec3 andmat3 types are not aligned by default.
• [major change] Starting withv0.7.3, inline print functions are disabled by default in release mode to eliminate printing costs (see the Options chapter of the docs).
  Colored output can be disabled (see documentation).
• [major change] Starting withv0.8.3, alternate clipspace configurations are supported. TheCGLM_FORCE_DEPTH_ZERO_TO_ONE andCGLM_FORCE_LEFT_HANDED flags are provided to control clip depth and handedness. This makes it easier to incorporate cglm into projects using graphics APIs such as Vulkan or Metal. Seehttps://cglm.readthedocs.io/en/latest/opt.html#clipspace-option-s

• scalar and simd (sse, avx, neon...) optimizations
• general purpose matrix operations (mat4, mat3)
• chain matrix multiplication (square only)
• general purpose vector operations (cross, dot, rotate, proj, angle...)
• affine transformations
• matrix decomposition (extract rotation, scaling factor)
• optimized affine transform matrices (mul, rigid-body inverse)
• camera (lookat)
• projections (ortho, perspective)
• quaternions
• euler angles / yaw-pitch-roll to matrix
• extract euler angles
• frustum (extract view frustum planes, corners...)
• bounding box (AABB in Frustum (culling), crop, merge...)
• bounding sphere
• project, unproject
• easing functions
• curves
• curve interpolation helpers (SMC, deCasteljau...)
• comversion helpers from cglm types to Apple's simd library to pass cglm types to Metal GL without packing them on both sides
• ray intersection helpers

Like other graphics libraries (especially OpenGL), cglm uses column-major layout to keep matrices in memory.   While we might support row-major matrices in the future, currently if you need your matrices to be in row-major layout you have to transpose them.

cglm contains general purpose mat4 product and inverse functions but also provides optimized versions for affine transformations. If you want to multiply two affine transformation matrices you can use glm_mul instead of glm_mat4_mul and glm_inv_tr (ROT + TR) instead glm_mat4_inv.

/* multiplication */mat4modelMat;glm_mul(T,R,modelMat);/* othonormal rot + tr matrix inverse (rigid-body) */glm_inv_tr(modelMat);

This project exists thanks to all the people who contribute. [Contribute]

Thank you to all our backers! 🙏 [Become a backer]

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]