How g-truc/glm works
This repository is the source tree for GLM, a mostly header-only C++ mathematics library modeled after GLSL. Architecturally, it is a single library product with no application runtime, network layer, or service topology; the main boundaries are between public API headers, internal implementation details, tests, and generated documentation.
1. Core product boundary
The public library lives under glm/. Consumers include these headers directly or via umbrella headers like glm/glm.hpp and glm/ext.hpp. The API provides vectors, matrices, quaternions, scalar helpers, and related math utilities intended to match GLSL naming and semantics.
2. Internal implementation layer
glm/detail/ contains the private machinery: type definitions, configuration/setup detection, compiler/platform feature checks, swizzle support, SIMD dispatch, and the shared inline implementation files (*.inl). This is the main internal boundary that public headers rely on but external users are not meant to touch.
3. Extension architecture
The library is organized by feature families:
• glm/gtc for promoted, stable extensions
• glm/gtx for experimental or optional extensions
• glm/ext for more granular extension headers and type variants
This split matters because it controls compilation cost and feature selection: users can pull in only the math surface they need.
4. Data model and math types
The central objects are scalar wrappers, vec*, mat*, and quat types. Most operations are implemented as inline free functions operating on these types, with naming and behavior designed to mirror GLSL. The repo includes both generic type families and specialized precision/alignment variants.
5. SIMD and platform-specific execution path
glm/simd/ and the *_simd.inl files provide optional accelerated code paths for architectures such as SSE/AVX/NEON/CUDA-like environments where supported. The architecture diagram should show SIMD as an optimization layer beneath the same API, not as a separate product.
6. Header-only consumption model
The default distribution model is header-only, which means there is no required runtime library, daemon, or service. Most functionality is available through templates and inline definitions, so the “build” boundary is largely about configuration and compile-time feature selection rather than linking against a large binary.
7. Optional compiled library support
The presence of CMakeLists.txt, glm/detail/glm.cpp, and install/package logic indicates that GLM can also be built and installed as a CMake package target, including a glm::glm library target and a glm::glm-header-only target. This matters for diagrams because the repository supports both direct include usage and packaged consumption.
8. Test architecture
The test/ tree is organized by API family:
• test/core for foundational types and core math functions
• test/ext for extension coverage
• test/gtc and test/gtx for extension-specific behavior
• test/bug for regression cases
• test/cmake for package/discovery behavior
• test/perf for performance-sensitive math paths
Tests are the main validation boundary and reflect the public module structure closely.
9. Performance and compatibility validation
The test/perf suite focuses on matrix/vector hot paths, while many core tests exercise compiler/configuration macros and edge cases. This shows GLM is heavily constrained by cross-compiler compatibility, constexpr behavior, and SIMD correctness rather than by runtime integration concerns.
10. Documentation pipeline
manual.md, doc/manual.pdf, and the large doc/api/ tree are generated documentation artifacts. The repo uses Doxygen-style API docs plus a written manual, so documentation is a first-class deliverable alongside the headers.
11. Build and packaging tooling
Top-level CMakeLists.txt plus the cmake/ helpers drive build, install, and uninstall behavior. The repository also contains packaging-related utility files under util/ and CI workflows under .github/workflows/. These are supporting infrastructure around the library, not runtime subsystems.
12. Repository shape for architecture diagrams
A good diagram should center on glm/ as the public API, branch downward into glm/detail/ and glm/simd/ as implementation layers, and branch sideways into test/ and doc/ as verification/documentation outputs. External inputs are limited to the consuming C++ compiler, CMake, and optional CI/package tooling; there are no external services in the runtime path.
Main entry points: detail detail/ · glm glm/ · ext.hpp Extensions · simd SIMD
Components 16
Public API
Headers consumed by users directly.
- glm/ · Primary public include surface for vectors, matrices, quaternions, and helpers.
glm - Umbrella · Convenience entry points such as glm/glm.hpp and glm/ext.hpp.
glm/glm.hpp - Core types · Fundamental vector, matrix, quaternion, and scalar type definitions.
glm/vec2.hpp - Extensions · GTC, GTX, and EXT headers that add promoted, optional, and granular functionality.
glm/ext.hpp - ext/ · Extension headers for specialized vector, matrix, scalar, and quaternion variants.
glm/ext - gtc/ · Promoted and generally stable extension modules.
glm/gtc - gtx/ · Optional and experimental extension modules.
glm/gtx
Implementation
Private machinery and optional SIMD paths.
- detail/ · Configuration, type machinery, and shared inline implementation details.
glm/detail - Setup · Compiler, platform, precision, and feature selection logic.
glm/detail/setup.hpp - Type impl · Shared vector, matrix, quaternion, and scalar implementation headers and inlines.
glm/detail/type_vec4.hpp - Func impl · Common inline function implementations for geometric, trigonometric, matrix, and packing operations.
glm/detail/func_common.inl - SIMD · Architecture-specific accelerated paths beneath the same API surface.
glm/simd
Validation
Tests and regression coverage.
Connections 21
- glm/ → Umbrella: entry points · Consumers usually start from umbrella headers.
- glm/ → Core types: defines · Public API exposes the core math types.
- glm/ → Extensions: organizes · Public API is split across extension families.
- Umbrella → detail/: includes · Umbrella headers rely on private internals.
- Core types → detail/: implemented by · Type declarations are backed by detail templates and inlines.
- Extensions → ext/: contains · Granular extension surface lives under glm/ext.
- Extensions → gtc/: contains · Stable promoted extensions live under glm/gtc.
- Extensions → gtx/: contains · Experimental extensions live under glm/gtx.
- detail/ → Setup: configures · Configuration and feature detection anchor the internals.
- detail/ → Type impl: defines · Core type machinery is centralized in detail headers.
- detail/ → Func impl: implements · Shared math operations are implemented inline here.
- detail/ → SIMD: optimizes · SIMD code paths accelerate the same operations when available.
- SIMD → Type impl: specializes · SIMD support specializes selected core types.
- SIMD → Func impl: accelerates · SIMD variants back selected math functions.
- CMake → glm/: packages · CMake targets package the header-only library surface.
- CMake → detail/: builds · Optional compiled target includes implementation sources.
- CMake → Tests: drives · Top-level build orchestrates the test matrix.
- Docs → glm/: documents · Manual and generated API docs describe the public surface.
- Tests → glm/: validates · Tests mirror the public module structure.
- Tests → detail/: checks internals · Core tests exercise configuration and compiler-specific behavior.
- Perf → SIMD: measures · Performance tests focus on optimized vector and matrix paths.