# libsdl-org/sdl architecture

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

- Interactive diagram: https://gitdiagram.com/libsdl-org/sdl
- Repository: https://github.com/libsdl-org/sdl

## Overview

1. **What this repo is**
   SDL3 is a cross-platform C multimedia runtime, not an app. Its architecture is a library core plus many platform-specific backend implementations, with sample programs and a large test harness around it.

2. **Public API boundary**
   The stable surface is in `include/SDL3`. These headers define the user-facing modules such as audio, video, events, input, rendering, GPU, filesystem, threading, timing, and utility APIs. Applications should mostly stay on this side of the boundary.

3. **Core runtime layer**
   The main implementation lives in `src/`. Common, backend-agnostic logic is concentrated in files like `src/SDL.c`, `src/events`, `src/audio`, `src/video`, `src/render`, etc. This layer coordinates subsystem state, dispatches events, and normalizes behavior before handing work to platform backends.

4. **Platform backend pattern**
   Most subsystems have a shared front-end plus platform-specific implementations beneath it. Examples include `src/video/windows`, `src/video/x11`, `src/video/wayland`, `src/audio/wasapi`, `src/audio/pulseaudio`, `src/joystick/windows`, `src/joystick/linux`, and similar directories for Android, iOS, macOS, Nintendo, PlayStation, DOS, and others. The architecture is “one API, many backends.”

5. **Video and windowing as the central hub**
   The video subsystem is the main integration point for windows, displays, input translation, clipboard, and platform event pumps. Backends such as Cocoa, Win32, X11, Wayland, Android, UIKit, Vulkan/OpenGL/EGL helpers, and offscreen/null drivers all plug into the same higher-level video API.

6. **Rendering stacks**
   SDL has two separate rendering paths:
   - `src/render/software` for CPU-based drawing and blitting.
   - Backend renderers in `src/render/opengl`, `opengles2`, `direct3d`, `direct3d11`, `direct3d12`, `metal`, `vulkan`, `psp`, `vita`, etc.
   The newer GPU API is in `src/gpu` and uses its own backend set and shader assets, independent from the older 2D renderer.

7. **Input and device abstraction**
   Keyboard, mouse, touch, pen, joystick, gamepad, haptic, sensor, and camera support are split into subsystem front-ends plus device-specific adapters. Joysticks/gamepads are especially layered: generic SDL gamepad logic, per-OS device discovery, and HID-based special-case drivers for specific controller families.

8. **HID as a shared device transport**
   `src/hidapi` is vendored as a subproject and used as a hardware access layer for controllers and haptics. SDL’s joystick/haptic code builds on top of it to normalize device descriptors, report parsing, and vendor-specific behaviors across operating systems.

9. **Core OS services**
   Non-graphics system services are also modularized: filesystem, locale, power, dialog/message boxes, process spawning, URL launching, storage, async I/O, threading, timers, and tray integration. Each has a generic API with OS-specific implementations under platform subdirectories.

10. **Application entry and main-function handling**
    SDL owns the app startup boundary through `src/main`. This layer adapts platform launch conventions into SDL’s callback-oriented entry model, with special variants for Windows, iOS, Emscripten, GDK, N-Gage, DOS, and others. It is the bridge between OS entrypoints and user code.

11. **ABI/versioning and dynamic dispatch**
    `src/dynapi` provides SDL’s dynamic API indirection layer, allowing ABI-stable function dispatch and symbol management across versions. This is a key architectural boundary for compatibility, especially when linking applications against different SDL builds.

12. **Build, packaging, and integration targets**
    The repo is heavily multi-build-system oriented: CMake is the main source of truth, with Visual Studio, Xcode, Android/NDK, and platform-specific package support also present. `build-scripts`, `.github/workflows`, `cmake/`, `android-project/`, `VisualC/`, `VisualC-GDK/`, `Xcode/`, and `docs/` collectively define how SDL is configured, built, packaged, and validated across targets.

13. **Tests and examples as first-class architecture consumers**
    `test/` contains the integration test suite and many subsystem exercisers, while `examples/` provides focused sample programs grouped by feature area. These are not separate products; they are architectural verification that each subsystem/backend combination behaves correctly across platforms.

Main entry points: [`src/SDL.c`](https://github.com/libsdl-org/sdl/blob/main/src/SDL.c) (Core runtime), [`examples`](https://github.com/libsdl-org/sdl/tree/main/examples) (Examples & tests), [`src/video`](https://github.com/libsdl-org/sdl/tree/main/src/video) (Video core), [`src/joystick`](https://github.com/libsdl-org/sdl/tree/main/src/joystick) (Input stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_include_sdl3["SDL3 headers<br/>API surface"]
end

subgraph group_runtime["Runtime"]
  node_src_core["Core runtime<br/>common runtime<br/>[SDL.c]"]
  node_src_events["Events<br/>event system"]
  node_src_video["Video core<br/>window/display core"]
  node_src_render["2D renderer<br/>rendering core"]
  node_src_gpu["GPU API<br/>modern graphics API"]
  node_src_input["Input stack<br/>device input"]
  node_src_audio["Audio core<br/>audio system"]
  node_src_os["OS services<br/>system services"]
  node_src_main["App entry<br/>startup bridge"]
  node_src_dynapi["Dynapi<br/>ABI dispatch"]
end

subgraph group_platform_backends["Backends"]
  node_video_backends["Video backends<br/>platform video"]
  node_audio_backends["Audio backends<br/>platform audio"]
  node_input_backends["Input backends<br/>platform input"]
  node_os_backends["OS backends<br/>platform services"]
end

subgraph group_tooling["Tooling"]
  node_build_pkg["Build & pkg<br/>build integration<br/>[CMakeLists.txt]"]
  node_examples_tests["Examples & tests<br/>validation apps"]
end

subgraph group_vendor["Vendored"]
  node_hidapi["HIDAPI<br/>vendored transport"]
end

node_include_sdl3 -->|"declares API for"| node_src_core
node_src_core -->|"routes events"| node_src_events
node_src_core -->|"coordinates video"| node_src_video
node_src_core -->|"coordinates audio"| node_src_audio
node_src_core -->|"coordinates input"| node_src_input
node_src_core -->|"uses services"| node_src_os
node_src_core -->|"boots app"| node_src_main
node_src_core -->|"exports ABI"| node_src_dynapi
node_src_video -->|"plugs into"| node_video_backends
node_src_audio -->|"plugs into"| node_audio_backends
node_src_input -->|"plugs into"| node_input_backends
node_src_os -->|"plugs into"| node_os_backends
node_src_video -->|"feeds surfaces"| node_src_render
node_src_video -->|"feeds graphics"| node_src_gpu
node_src_input -->|"uses HID"| node_hidapi
node_hidapi -->|"supports devices"| node_input_backends
node_build_pkg -->|"packages headers"| node_include_sdl3
node_build_pkg -->|"builds library"| node_src_core
node_build_pkg -->|"drives validation"| node_examples_tests
node_examples_tests -->|"consumes API"| node_include_sdl3
node_examples_tests -->|"exercises video"| node_src_video
node_examples_tests -->|"exercises input"| node_src_input
node_examples_tests -->|"exercises audio"| node_src_audio
node_src_dynapi -->|"stabilizes ABI"| node_include_sdl3

click node_include_sdl3 "https://github.com/libsdl-org/sdl/tree/main/include/SDL3"
click node_src_core "https://github.com/libsdl-org/sdl/blob/main/src/SDL.c"
click node_src_events "https://github.com/libsdl-org/sdl/tree/main/src/events"
click node_src_video "https://github.com/libsdl-org/sdl/tree/main/src/video"
click node_src_render "https://github.com/libsdl-org/sdl/tree/main/src/render"
click node_src_gpu "https://github.com/libsdl-org/sdl/tree/main/src/gpu"
click node_src_input "https://github.com/libsdl-org/sdl/tree/main/src/joystick"
click node_src_audio "https://github.com/libsdl-org/sdl/tree/main/src/audio"
click node_src_os "https://github.com/libsdl-org/sdl/tree/main/src/filesystem"
click node_src_main "https://github.com/libsdl-org/sdl/tree/main/src/main"
click node_src_dynapi "https://github.com/libsdl-org/sdl/tree/main/src/dynapi"
click node_video_backends "https://github.com/libsdl-org/sdl/tree/main/src/video/windows"
click node_audio_backends "https://github.com/libsdl-org/sdl/tree/main/src/audio/wasapi"
click node_input_backends "https://github.com/libsdl-org/sdl/tree/main/src/joystick/windows"
click node_os_backends "https://github.com/libsdl-org/sdl/tree/main/src/core/windows"
click node_build_pkg "https://github.com/libsdl-org/sdl/blob/main/CMakeLists.txt"
click node_examples_tests "https://github.com/libsdl-org/sdl/tree/main/examples"
click node_hidapi "https://github.com/libsdl-org/sdl/tree/main/src/hidapi"

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_include_sdl3 toneBlue
class node_src_core,node_src_events,node_src_video,node_src_render,node_src_gpu,node_src_input,node_src_audio,node_src_os,node_src_main,node_src_dynapi toneAmber
class node_video_backends,node_audio_backends,node_input_backends,node_os_backends toneMint
class node_build_pkg,node_examples_tests toneRose
class node_hidapi toneIndigo
```

## Components

### Public API

Stable headers and user-facing modules.

- [SDL3 headers](https://github.com/libsdl-org/sdl/tree/main/include/SDL3): API surface · Public entry point and stable module headers under include/SDL3. · `include/SDL3`

### Runtime

Core SDL implementation and subsystem coordination.

- [Core runtime](https://github.com/libsdl-org/sdl/blob/main/src/SDL.c): common runtime · Shared implementation glue and low-level utilities. · `src/SDL.c`
- [Events](https://github.com/libsdl-org/sdl/tree/main/src/events): event system · Event queue, translation, and input event dispatch. · `src/events`
- [Video core](https://github.com/libsdl-org/sdl/tree/main/src/video): window/display core · Windowing, displays, clipboard, surfaces, and platform video coordination. · `src/video`
- [2D renderer](https://github.com/libsdl-org/sdl/tree/main/src/render): rendering core · Legacy renderer front-end plus software and backend renderers. · `src/render`
- [GPU API](https://github.com/libsdl-org/sdl/tree/main/src/gpu): modern graphics API · New GPU abstraction and graphics backend coordination. · `src/gpu`
- [Input stack](https://github.com/libsdl-org/sdl/tree/main/src/joystick): device input · Keyboard, mouse, touch, pen, joystick, gamepad, haptic, sensor, and camera front-ends. · `src/joystick`
- [Audio core](https://github.com/libsdl-org/sdl/tree/main/src/audio): audio system · Audio device management, mixing, resampling, and codec support. · `src/audio`
- [OS services](https://github.com/libsdl-org/sdl/tree/main/src/filesystem): system services · Filesystem, locale, power, dialogs, processes, URL handling, storage, async I/O, threading, timers, and tray support. · `src/filesystem`
- [App entry](https://github.com/libsdl-org/sdl/tree/main/src/main): startup bridge · Main-function adaptation layer that bridges platform entrypoints to SDL app callbacks. · `src/main`
- [Dynapi](https://github.com/libsdl-org/sdl/tree/main/src/dynapi): ABI dispatch · Dynamic API indirection and symbol management for compatibility. · `src/dynapi`

### Backends

Platform-specific implementations behind shared subsystem front-ends.

- [Video backends](https://github.com/libsdl-org/sdl/tree/main/src/video/windows): platform video · Platform-specific window, event, and graphics integrations. · `src/video/windows`
- [Audio backends](https://github.com/libsdl-org/sdl/tree/main/src/audio/wasapi): platform audio · Backend drivers for native audio systems. · `src/audio/wasapi`
- [Input backends](https://github.com/libsdl-org/sdl/tree/main/src/joystick/windows): platform input · OS-specific device discovery and controller adapters, including HID-based drivers. · `src/joystick/windows`
- [OS backends](https://github.com/libsdl-org/sdl/tree/main/src/core/windows): platform services · Per-platform implementations for filesystem, process, locale, power, and related services. · `src/core/windows`

### Tooling

Build, packaging, examples, and validation targets.

- [Build & pkg](https://github.com/libsdl-org/sdl/blob/main/CMakeLists.txt): build integration · CMake, IDE projects, Android packaging, release scripts, and CI workflows. · `CMakeLists.txt`
- [Examples & tests](https://github.com/libsdl-org/sdl/tree/main/examples): validation apps · Sample programs and integration tests that exercise subsystem/backend combinations. · `examples`

### Vendored

Third-party code embedded in the tree.

- [HIDAPI](https://github.com/libsdl-org/sdl/tree/main/src/hidapi): vendored transport · Vendored HID access layer used by joystick and haptic subsystems. · `src/hidapi`

## Connections

- SDL3 headers → Core runtime: declares API for · Public headers define the user-facing contract implemented by core runtime.
- Core runtime → Events: routes events · Core runtime depends on event processing and dispatch.
- Core runtime → Video core: coordinates video · Core runtime initializes and manages the video subsystem.
- Core runtime → Audio core: coordinates audio · Core runtime initializes and manages the audio subsystem.
- Core runtime → Input stack: coordinates input · Core runtime exposes generic device abstraction and lifecycle.
- Core runtime → OS services: uses services · Core runtime relies on OS services such as filesystem, threading, and timers.
- Core runtime → App entry: boots app · Core runtime hands control through SDL's application entry bridge.
- Core runtime → Dynapi: exports ABI · Core runtime participates in dynamic API dispatch and compatibility layers.
- Video core → Video backends: plugs into · Video core is implemented by platform drivers and window system adapters.
- Audio core → Audio backends: plugs into · Audio core is implemented by platform drivers.
- Input stack → Input backends: plugs into · Input stack is extended by OS-specific discovery and controller backends.
- OS services → OS backends: plugs into · OS services are specialized per platform.
- Video core → 2D renderer: feeds surfaces · Video and windowing underpin the legacy renderer and presentation path.
- Video core → GPU API: feeds graphics · Video subsystem supports GPU and window surface integration.
- Input stack → HIDAPI: uses HID · Joystick and haptic layers build on the vendored HID transport.
- HIDAPI → Input backends: supports devices · HID access is used by OS-specific controller adapters and special-case device drivers.
- Build & pkg → SDL3 headers: packages headers · Build and packaging systems install and configure the public API surface.
- Build & pkg → Core runtime: builds library · Build systems compile the SDL runtime and platform backends.
- Build & pkg → Examples & tests: drives validation · Examples and tests are built and run across targets and CI.
- Examples & tests → SDL3 headers: consumes API · Examples and tests exercise the public API like applications do.
- Examples & tests → Video core: exercises video · Many samples and tests validate windowing and rendering paths.
- Examples & tests → Input stack: exercises input · Tests and samples cover joysticks, gamepads, pens, and sensors.
- Examples & tests → Audio core: exercises audio · Audio samples and tests validate device and streaming behavior.
- Dynapi → SDL3 headers: stabilizes ABI · Dynamic dispatch preserves compatibility for the public function set.
