# raysan5/raygui architecture

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

- Interactive diagram: https://gitdiagram.com/raysan5/raygui
- Repository: https://github.com/raysan5/raygui

## Overview

##### Project type + purpose (what you are diagramming)

- **Host Application** (your tool/game/editor) owns the main loop.
- **raylib** (or another backend) provides rendering, windowing, input, font/texture primitives.
- Repo also includes **examples** (consumers) and **build/project scaffolding** (CMake/VS).

So the “system” is best expressed as **(A) build-time packaging** + **(B) runtime frame loop interactions**.

##### Core library
- `src/raygui.h`
The entire public API + implementation (when `RAYGUI_IMPLEMENTATION` is defined in exactly one translation unit). This is the core component.

##### Styles subsystem (data + loaders)
- `styles/**` and `styles/README.md`
- Each style folder has `.rgs` sources and generated `style_*.h`.

##### Examples (reference consumers / integration)
- `examples/*/*.c` and some local headers (`gui_*_editor.h`, `gui_window_file_dialog.h`, etc.)

##### Build + IDE integration
- `projects/CMake/**` (incl. `FindRaylib.cmake`)
- `projects/VS2022/**`
These define how raygui + raylib are located and built. This is “build-time architecture”.

##### Repo meta
- `README.md`, `HISTORY.md`, `LICENSE`
Not architectural components, but README contains the key constraints: header-only, immediate mode, raylib alignment.

##### Key README constraints to reflect

- **Immediate-mode GUI**: controls are re-described every frame; raygui keeps minimal internal state (no “retained widget tree”).
- **Header-only / single compilation unit rule**: `RAYGUI_IMPLEMENTATION` defined once.
- **Dependency alignment**: raygui master aligns with raylib master.
- **Standalone backend supported**: raygui can be adapted to other engines (explicit extension point).

##### Host App (C/C++)
2. **raygui (src/raygui.h)** (header-only; may be turned into `raygui.c` for shared lib builds)
##### Build System (CMake project / VS solution)

- Host App → includes → `raygui.h`
- Host App → links against → raylib
- raygui → uses → raylib API (rendering/input/font/texture primitives)
- Build System → resolves/locates → raylib (e.g., `FindRaylib.cmake`)
- Optional branch: “Build as shared library” path (copy/rename to `raygui.c` + `-DRAYGUI_IMPLEMENTATION -DBUILD_LIBTYPE_SHARED`)

**Callouts to annotate:**
- “Define `RAYGUI_IMPLEMENTATION` in exactly one TU”
- “Master branch alignment with raylib”

Goal: show the per-frame interactions (this is the core of immediate mode).

**Nodes:**

##### raygui style table / metrics / font

**Edges:**
- Style sources → (external tool: rGuiStyler) → generated headers / style files
- Host app → loads style at runtime → raygui style state

**Callouts:**
- “Default style auto-loaded”

Because this is a library, accuracy comes from showing *who calls whom*:

- **Host App calls raygui** (not the other way around).
- **raygui depends on raylib/backend** for:
- drawing primitives
- input state
- fonts/texture handling (as applicable)

**optional mode**:
- `raygui` ↔ `Backend Adapter Layer` ↔ `Other graphics/input lib`
And point to `examples/standalone/raygui_custom_backend.h` as the concrete hint in-tree that this seam exists.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram A — Build-time Architecture
  %% =========================
  subgraph "Diagram A — Repository / Build-time Architecture"
    direction TB

    subgraph "Consumer Layer (Build Target)"
      direction TB
      HostApp["Host Tool/App (C/C++)"]:::consumer
      Examples["Examples (reference consumer apps)"]:::consumer
    end

    subgraph "Core Library (Header-only)"
      direction TB
      Raygui["raygui (single-file header-only)"]:::core
      RuleOnce["Constraint: define 'RAYGUI_IMPLEMENTATION' in exactly one TU"]:::note
      Immediate["Immediate-mode: UI re-described every frame (minimal internal state)"]:::note
      Align["Constraint: raygui master aligns with raylib master"]:::note
    end

    subgraph "Resources (Optional)"
      direction TB
      Styles["Styles (themes)"]:::resource
      StylesDoc["Styles documentation"]:::doc
      StyleSources["Style sources (.rgs)"]:::resource
      StyleGenerated["Generated style headers (style_*.h)"]:::resource
      ExampleStyleHeaders["Example-bundled style headers"]:::resource
      Icons["Icons header (embedded icon pack)"]:::resource
      IconsSrc["Icons source (.rgi)"]:::resource
    end

    subgraph "Backend / Dependencies"
      direction TB
      Raylib["raylib (external dependency)"]:::external
      Platform["Platform libs (OS + OpenGL/etc.)"]:::external
      Standalone["Standalone backend mode (optional)"]:::external
    end

    subgraph "Build + IDE Scaffolding"
      direction TB
      CMake["CMake build scaffolding"]:::build
      FindRaylib["CMake module: FindRaylib.cmake"]:::build
      VS["Visual Studio 2022 solution/projects"]:::build
      VSExamples["VS2022 example projects (*.vcxproj)"]:::build
      VSRaylib["VS2022 raylib project ref"]:::build
      Readme["Repo docs: README constraints"]:::doc
      History["Repo history: HISTORY (alignment context)"]:::doc
    end

    %% Build-time relationships (dashed)
    HostApp -.->|"includes"| Raygui
    Examples -.->|"includes"| Raygui

    HostApp -.->|"links"| Raylib
    Examples -.->|"links"| Raylib

    Raygui -.->|"uses API (draw/input/font/texture)"| Raylib
    Raylib -.->|"links"| Platform

    CMake -.->|"builds"| HostApp
    CMake -.->|"builds"| Examples
    CMake -.->|"configures"| Raygui
    CMake -.->|"resolves"| FindRaylib
    FindRaylib -.->|"locates"| Raylib

    VS -.->|"builds"| Examples
    VS -.->|"contains"| VSExamples
    VS -.->|"references"| VSRaylib
    VSRaylib -.->|"builds"| Raylib

    Styles -.->|"optionally included/loaded"| Raygui
    Icons -.->|"optionally included"| Raygui

    StylesDoc -.->|"documents"| Styles
    Readme -.->|"documents"| Raygui
    History -.->|"context"| Align

    RuleOnce -.->|"applies to"| Raygui
    Immediate -.->|"describes"| Raygui
    Align -.->|"tracks"| Raylib
  end

  %% =========================
  %% Diagram B — Runtime Frame Loop / Control Call-flow
  %% =========================
  subgraph "Diagram B — Runtime Frame Loop / Control Call-flow"
    direction TB

    subgraph "External Stimuli"
      direction TB
      UserInput["User input (mouse/keyboard)"]:::external
    end

    subgraph "Backend (raylib or other)"
      direction TB
      BackendInput["Window/Input state"]:::external
      BackendDraw["Renderer draw primitives"]:::external
    end

    subgraph "Host Application (Main Loop)"
      direction TB
      MainLoop["Main loop (per frame)"]:::consumer
      AppState["App state variables (UI state lives here)"]:::consumer
    end

    subgraph "raygui (Immediate-mode UI)"
      direction TB
      Controls["Control calls (e.g., GuiButton, GuiMessageBox, etc.)"]:::core
      StyleState["Style state (GuiGetStyle/GuiSetStyle)"]:::core
      StyleLoad["Runtime style loading (GuiLoadStyle)"]:::core
      IconsUse["Icons usage (GuiIconText / '#id#' markup)"]:::core
      ReturnVals["Return values (clicked/toggled/edited/selected)"]:::core
    end

    %% Runtime flow (solid)
    UserInput -->|"events"| BackendInput
    BackendInput -->|"poll/read"| MainLoop

    MainLoop -->|"calls controls"| Controls
    Controls -->|"reads input"| BackendInput

    MainLoop -->|"loads/sets style"| StyleLoad
    StyleLoad -->|"updates"| StyleState
    Controls -->|"reads style"| StyleState

    MainLoop -->|"uses icons"| IconsUse
    IconsUse -->|"affects text/icon draw"| Controls

    Controls -->|"issues draw calls"| BackendDraw
    BackendDraw -->|"presents frame"| MainLoop

    Controls -->|"returns"| ReturnVals
    ReturnVals -->|"updates"| AppState
    AppState -->|"drives next frame UI"| MainLoop
  end

  %% =========================
  %% Diagram C — Resource / Styling & Icons Pipeline
  %% =========================
  subgraph "Diagram C — Resource / Styling & Icons Pipeline"
    direction TB

    subgraph "Style Authoring & Packaging"
      direction TB
      RgsSources["Style sources (.rgs)"]:::resource
      RGuiStyler["External tool: rGuiStyler (style generator)"]:::external
      StyleHeaders["Generated headers (style_*.h)"]:::resource
      StyleFiles["Style files for runtime load"]:::resource
    end

    subgraph "Icons Authoring & Usage"
      direction TB
      Rgi["Icons source pack (.rgi)"]:::resource
      IconsHeader["Icons header (embedded array)"]:::resource
      IconsNote["Icons: 256 @ 16x16, 1-bit, embedded array"]:::note
    end

    subgraph "Runtime Consumption"
      direction TB
      HostCalls["Host app calls (GuiLoadStyle/GuiSetStyle)"]:::consumer
      RayguiStyleTable["raygui style table/metrics/font"]:::core
      HostIconText["Host app uses GuiIconText / '#id#' markup"]:::consumer
      RayguiRender["raygui renders styled controls + icons"]:::core
    end

    %% Pipelines
    RgsSources -->|"processed by"| RGuiStyler
    RGuiStyler -->|"outputs"| StyleHeaders
    RGuiStyler -->|"outputs"| StyleFiles

    HostCalls -->|"loads"| StyleFiles
    HostCalls -->|"includes optional"| StyleHeaders
    HostCalls -->|"sets"| RayguiStyleTable

    Rgi -->|"generates/feeds"| IconsHeader
    IconsHeader -->|"provides glyphs to"| RayguiRender
    IconsNote -.->|"describes"| IconsHeader

    HostIconText -->|"passes icon markup"| RayguiRender
    RayguiStyleTable -->|"styles"| RayguiRender
  end

  %% =========================
  %% Standalone backend seam (explicit extension point)
  %% =========================
  subgraph "Optional Extension — Standalone Backend Adapter Seam"
    direction TB
    CustomBackend["Custom backend adapter header"]:::external
    StandaloneApp["Standalone backend example app"]:::consumer
    OtherBackend["Other graphics/input backend"]:::external

    StandaloneApp -->|"calls raygui controls"| Raygui
    Raygui -->|"through adapter"| CustomBackend
    CustomBackend -->|"maps to"| OtherBackend
  end

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click Raygui "https://github.com/raysan5/raygui/blob/master/src/raygui.h"

  click Styles "https://github.com/raysan5/raygui/tree/master/styles/"
  click StylesDoc "https://github.com/raysan5/raygui/blob/master/styles/README.md"
  click StyleSources "https://github.com/raysan5/raygui/blob/master/styles/*/style_*.rgs"
  click StyleGenerated "https://github.com/raysan5/raygui/blob/master/styles/*/style_*.h"
  click ExampleStyleHeaders "https://github.com/raysan5/raygui/blob/master/examples/styles/style_*.h"

  click Icons "https://github.com/raysan5/raygui/blob/master/icons/raygui_icons.h"
  click IconsSrc "https://github.com/raysan5/raygui/blob/master/icons/raygui_icons.rgi"

  click Examples "https://github.com/raysan5/raygui/tree/master/examples/"
  click CustomBackend "https://github.com/raysan5/raygui/blob/master/examples/standalone/raygui_custom_backend.h"
  click StandaloneApp "https://github.com/raysan5/raygui/blob/master/examples/standalone/raygui_standalone.c"

  click CMake "https://github.com/raysan5/raygui/blob/master/projects/CMake/CMakeLists.txt"
  click FindRaylib "https://github.com/raysan5/raygui/blob/master/projects/CMake/cmake/FindRaylib.cmake"
  click VS "https://github.com/raysan5/raygui/blob/master/projects/VS2022/raygui.sln"
  click VSExamples "https://github.com/raysan5/raygui/blob/master/projects/VS2022/examples/*.vcxproj"
  click VSRaylib "https://github.com/raysan5/raygui/blob/master/projects/VS2022/raylib/raylib.vcxproj"

  click Readme "https://github.com/raysan5/raygui/blob/master/README.md"
  click History "https://github.com/raysan5/raygui/blob/master/HISTORY.md"

  %% =========================
  %% Styles (color)
  %% =========================
  classDef consumer fill:#1f6feb,stroke:#0b2f6b,color:#ffffff,stroke-width:1.5px
  classDef core fill:#f59e0b,stroke:#8a4b00,color:#111827,stroke-width:1.5px
  classDef external fill:#9ca3af,stroke:#374151,color:#111827,stroke-width:1.5px
  classDef resource fill:#22c55e,stroke:#14532d,color:#052e16,stroke-width:1.5px
  classDef build fill:#a855f7,stroke:#4c1d95,color:#ffffff,stroke-width:1.5px
  classDef doc fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1.2px
  classDef note fill:#fff7ed,stroke:#fb923c,color:#7c2d12,stroke-width:1.2px,stroke-dasharray: 4 3
```
