# g-truc/glm architecture

> Architecture diagram of the GitHub repository g-truc/glm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/g-truc/glm
- Repository: https://github.com/g-truc/glm

## Overview

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: [`glm/detail`](https://github.com/g-truc/glm/tree/master/glm/detail) (detail/), [`glm`](https://github.com/g-truc/glm/tree/master/glm) (glm/), [`glm/ext.hpp`](https://github.com/g-truc/glm/blob/master/glm/ext.hpp) (Extensions), [`glm/simd`](https://github.com/g-truc/glm/tree/master/glm/simd) (SIMD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_glm_api["glm/<br/>header-only math API"]
  node_glm_umbrella["Umbrella<br/>entry headers<br/>[glm.hpp]"]
  node_glm_core_types["Core types<br/>math families<br/>[vec2.hpp]"]
  node_glm_extensions["Extensions<br/>feature families<br/>[ext.hpp]"]
  node_glm_ext["ext/<br/>granular extensions"]
  node_glm_gtc["gtc/<br/>stable extensions"]
  node_glm_gtx["gtx/<br/>experimental extensions"]
end

subgraph group_impl["Implementation"]
  node_glm_detail["detail/<br/>private internals"]
  node_glm_setup["Setup<br/>config detection<br/>[setup.hpp]"]
  node_glm_types["Type impl<br/>core templates<br/>[type_vec4.hpp]"]
  node_glm_funcs["Func impl<br/>inline math ops<br/>[func_common.inl]"]
  node_glm_simd["SIMD<br/>optimized paths"]
end

subgraph group_validation["Validation"]
  node_glm_tests["Tests<br/>validation suite"]
  node_glm_perf["Perf<br/>hot-path tests"]
end

subgraph group_ops["Build & Docs"]
  node_glm_build["CMake<br/>build & package<br/>[CMakeLists.txt]"]
  node_glm_doc["Docs<br/>[manual.md]"]
end

node_glm_api -->|"entry points"| node_glm_umbrella
node_glm_api -->|"defines"| node_glm_core_types
node_glm_api -->|"organizes"| node_glm_extensions
node_glm_umbrella -->|"includes"| node_glm_detail
node_glm_core_types -->|"implemented by"| node_glm_detail
node_glm_extensions -->|"contains"| node_glm_ext
node_glm_extensions -->|"contains"| node_glm_gtc
node_glm_extensions -->|"contains"| node_glm_gtx
node_glm_detail -->|"configures"| node_glm_setup
node_glm_detail -->|"defines"| node_glm_types
node_glm_detail -->|"implements"| node_glm_funcs
node_glm_detail -->|"optimizes"| node_glm_simd
node_glm_simd -->|"specializes"| node_glm_types
node_glm_simd -->|"accelerates"| node_glm_funcs
node_glm_build -->|"packages"| node_glm_api
node_glm_build -->|"builds"| node_glm_detail
node_glm_build -->|"drives"| node_glm_tests
node_glm_doc -->|"documents"| node_glm_api
node_glm_tests -->|"validates"| node_glm_api
node_glm_tests -->|"checks internals"| node_glm_detail
node_glm_perf -->|"measures"| node_glm_simd

click node_glm_api "https://github.com/g-truc/glm/tree/master/glm"
click node_glm_umbrella "https://github.com/g-truc/glm/blob/master/glm/glm.hpp"
click node_glm_core_types "https://github.com/g-truc/glm/blob/master/glm/vec2.hpp"
click node_glm_extensions "https://github.com/g-truc/glm/blob/master/glm/ext.hpp"
click node_glm_detail "https://github.com/g-truc/glm/tree/master/glm/detail"
click node_glm_setup "https://github.com/g-truc/glm/blob/master/glm/detail/setup.hpp"
click node_glm_types "https://github.com/g-truc/glm/blob/master/glm/detail/type_vec4.hpp"
click node_glm_funcs "https://github.com/g-truc/glm/blob/master/glm/detail/func_common.inl"
click node_glm_simd "https://github.com/g-truc/glm/tree/master/glm/simd"
click node_glm_ext "https://github.com/g-truc/glm/tree/master/glm/ext"
click node_glm_gtc "https://github.com/g-truc/glm/tree/master/glm/gtc"
click node_glm_gtx "https://github.com/g-truc/glm/tree/master/glm/gtx"
click node_glm_build "https://github.com/g-truc/glm/blob/master/CMakeLists.txt"
click node_glm_doc "https://github.com/g-truc/glm/blob/master/manual.md"
click node_glm_tests "https://github.com/g-truc/glm/tree/master/test"
click node_glm_perf "https://github.com/g-truc/glm/tree/master/test/perf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_glm_api,node_glm_umbrella,node_glm_core_types,node_glm_extensions,node_glm_ext,node_glm_gtc,node_glm_gtx toneBlue
class node_glm_detail,node_glm_setup,node_glm_types,node_glm_funcs,node_glm_simd toneAmber
class node_glm_tests,node_glm_perf toneMint
class node_glm_build,node_glm_doc toneRose
```

## Components

### Public API

Headers consumed by users directly.

- [glm/](https://github.com/g-truc/glm/tree/master/glm): header-only math API · Primary public include surface for vectors, matrices, quaternions, and helpers. · `glm`
- [Umbrella](https://github.com/g-truc/glm/blob/master/glm/glm.hpp): entry headers · Convenience entry points such as glm/glm.hpp and glm/ext.hpp. · `glm/glm.hpp`
- [Core types](https://github.com/g-truc/glm/blob/master/glm/vec2.hpp): math families · Fundamental vector, matrix, quaternion, and scalar type definitions. · `glm/vec2.hpp`
- [Extensions](https://github.com/g-truc/glm/blob/master/glm/ext.hpp): feature families · GTC, GTX, and EXT headers that add promoted, optional, and granular functionality. · `glm/ext.hpp`
- [ext/](https://github.com/g-truc/glm/tree/master/glm/ext): granular extensions · Extension headers for specialized vector, matrix, scalar, and quaternion variants. · `glm/ext`
- [gtc/](https://github.com/g-truc/glm/tree/master/glm/gtc): stable extensions · Promoted and generally stable extension modules. · `glm/gtc`
- [gtx/](https://github.com/g-truc/glm/tree/master/glm/gtx): experimental extensions · Optional and experimental extension modules. · `glm/gtx`

### Implementation

Private machinery and optional SIMD paths.

- [detail/](https://github.com/g-truc/glm/tree/master/glm/detail): private internals · Configuration, type machinery, and shared inline implementation details. · `glm/detail`
- [Setup](https://github.com/g-truc/glm/blob/master/glm/detail/setup.hpp): config detection · Compiler, platform, precision, and feature selection logic. · `glm/detail/setup.hpp`
- [Type impl](https://github.com/g-truc/glm/blob/master/glm/detail/type_vec4.hpp): core templates · Shared vector, matrix, quaternion, and scalar implementation headers and inlines. · `glm/detail/type_vec4.hpp`
- [Func impl](https://github.com/g-truc/glm/blob/master/glm/detail/func_common.inl): inline math ops · Common inline function implementations for geometric, trigonometric, matrix, and packing operations. · `glm/detail/func_common.inl`
- [SIMD](https://github.com/g-truc/glm/tree/master/glm/simd): optimized paths · Architecture-specific accelerated paths beneath the same API surface. · `glm/simd`

### Validation

Tests and regression coverage.

- [Tests](https://github.com/g-truc/glm/tree/master/test): validation suite · Core, extension, regression, package, and performance coverage. · `test`
- [Perf](https://github.com/g-truc/glm/tree/master/test/perf): hot-path tests · Performance-focused validation of matrix and vector operations. · `test/perf`

### Build & Docs

CMake, packaging, and generated documentation.

- [CMake](https://github.com/g-truc/glm/blob/master/CMakeLists.txt): build & package · Build, install, and package support including library targets. · `CMakeLists.txt`
- [Docs](https://github.com/g-truc/glm/blob/master/manual.md): generated docs · Manual and generated API reference artifacts. · `manual.md`

## Connections

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