How libsdl-org/sdl works
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: SDL.c Core runtime · examples Examples & tests · video Video core · joystick Input stack
Components 18
Public API
Stable headers and user-facing modules.
- SDL3 headers · Public entry point and stable module headers under include/SDL3.
include/SDL3
Runtime
Core SDL implementation and subsystem coordination.
- Core runtime · Shared implementation glue and low-level utilities.
src/SDL.c - Events · Event queue, translation, and input event dispatch.
src/events - Video core · Windowing, displays, clipboard, surfaces, and platform video coordination.
src/video - 2D renderer · Legacy renderer front-end plus software and backend renderers.
src/render - GPU API · New GPU abstraction and graphics backend coordination.
src/gpu - Input stack · Keyboard, mouse, touch, pen, joystick, gamepad, haptic, sensor, and camera front-ends.
src/joystick - Audio core · Audio device management, mixing, resampling, and codec support.
src/audio - OS services · Filesystem, locale, power, dialogs, processes, URL handling, storage, async I/O, threading, timers, and tray support.
src/filesystem - App entry · Main-function adaptation layer that bridges platform entrypoints to SDL app callbacks.
src/main - Dynapi · Dynamic API indirection and symbol management for compatibility.
src/dynapi
Backends
Platform-specific implementations behind shared subsystem front-ends.
- Video backends · Platform-specific window, event, and graphics integrations.
src/video/windows - Audio backends · Backend drivers for native audio systems.
src/audio/wasapi - Input backends · OS-specific device discovery and controller adapters, including HID-based drivers.
src/joystick/windows - OS backends · Per-platform implementations for filesystem, process, locale, power, and related services.
src/core/windows
Tooling
Build, packaging, examples, and validation targets.
- Build & pkg · CMake, IDE projects, Android packaging, release scripts, and CI workflows.
CMakeLists.txt - Examples & tests · Sample programs and integration tests that exercise subsystem/backend combinations.
examples
Vendored
Third-party code embedded in the tree.
- HIDAPI · Vendored HID access layer used by joystick and haptic subsystems.
src/hidapi
Connections 24
- 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.