> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dolphin-emu/dolphin/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture overview

> High-level overview of Dolphin's modular architecture and core components

Dolphin is built with a modular architecture that separates concerns and allows different backends to be swapped based on platform and user preferences.

## Core Components

<CardGroup cols={2}>
  <Card title="Core" icon="microchip" href="/architecture/core-emulation">
    Central emulation engine handling GameCube/Wii hardware
  </Card>

  <Card title="PowerPC CPU" icon="cpu" href="/architecture/cpu-emulation">
    CPU emulation with multiple execution backends
  </Card>

  <Card title="Video Backends" icon="display" href="/architecture/video-backends">
    Graphics rendering through Vulkan, D3D, OpenGL, and Metal
  </Card>

  <Card title="Audio System" icon="volume" href="/architecture/audio-system">
    DSP emulation and audio output backends
  </Card>

  <Card title="IOS/HLE" icon="server" href="/architecture/ios-emulation">
    Wii operating system emulation
  </Card>

  <Card title="Disc I/O" icon="disc-drive" href="/architecture/disc-io">
    Game image loading and disc format support
  </Card>
</CardGroup>

## Directory Structure

Dolphin's source code is organized in `Source/Core/` with these major components:

```
Source/Core/
├── Common/          # Shared utilities, logging, threading
├── Core/            # Main emulation engine
│   ├── HW/         # Hardware emulation (CPU, GPU, memory, peripherals)
│   ├── PowerPC/    # PowerPC CPU emulation
│   ├── IOS/        # Wii IOS high-level emulation
│   ├── DSP/        # DSP audio processor
│   ├── Boot/       # Game boot and initialization
│   └── Config/     # Configuration system
├── VideoCommon/     # Shared video code
├── VideoBackends/   # Platform-specific rendering
│   ├── Vulkan/
│   ├── D3D/
│   ├── D3D12/
│   ├── OGL/
│   ├── Metal/
│   └── Software/
├── AudioCommon/     # Audio processing
├── InputCommon/     # Controller input handling
├── DiscIO/          # Disc image formats
├── UICommon/        # Shared UI code
├── DolphinQt/       # Qt-based GUI
├── DolphinNoGUI/    # Headless frontend
└── DolphinTool/     # CLI tool for disc operations
```

## Emulation Pipeline

The emulation process flows through these stages:

<Steps>
  <Step title="Boot">
    Game loading and system initialization from `Core/Boot/`

    * Parse disc image format (ISO, RVZ, GCZ, WIA)
    * Load system files (BIOS, IPL)
    * Initialize hardware state
  </Step>

  <Step title="CPU Execution">
    PowerPC instruction execution via JIT or interpreter

    * Fetch and decode PowerPC instructions
    * Execute through JIT compiler or interpreter
    * Handle exceptions and interrupts
  </Step>

  <Step title="Hardware Emulation">
    Emulate GameCube/Wii hardware components

    * **GPU**: Graphics FIFO, texture cache, shader generation
    * **DSP**: Audio processing (HLE or LLE)
    * **Memory**: Main RAM, embedded framebuffer, texture memory
    * **Peripherals**: Controllers, memory cards, sensors
  </Step>

  <Step title="Rendering">
    Video backend translates graphics commands to modern APIs

    * Convert GX commands to Vulkan/D3D/OpenGL
    * Apply enhancements (HD rendering, anti-aliasing)
    * Output to display
  </Step>
</Steps>

## State Management

Dolphin manages emulation state through the `Core::State` enum:

```cpp theme={null}
enum class State
{
  Uninitialized,  // Not running
  Paused,         // Paused, state preserved
  Running,        // Actively emulating
  Stopping,       // Shutdown in progress
  Starting,       // Initialization in progress
};
```

State transitions are handled in `Source/Core/Core/Core.cpp`.

## System Class

The `Core::System` class (defined in `Core/System.h`) serves as the central coordination point:

* Owns all hardware component instances
* Manages component lifecycle
* Provides access to memory, CPU, GPU subsystems
* Coordinates save states and serialization

## Thread Model

Dolphin uses multiple threads for performance:

| Thread                   | Purpose                                       |
| ------------------------ | --------------------------------------------- |
| **CPU Thread**           | PowerPC emulation, main game logic            |
| **GPU Thread**           | Graphics command processing                   |
| **Audio Thread**         | DSP emulation and audio output                |
| **Video Backend Thread** | API-specific rendering                        |
| **EXI Thread**           | GameCube peripherals (memory cards, GBA link) |

<Note>
  The CPU thread is the authoritative thread. All other threads synchronize with it to maintain determinism.
</Note>

## Platform Abstraction

Platform-specific code is isolated in:

* **Video backends**: Vulkan (cross-platform), D3D11/D3D12 (Windows), OpenGL (cross-platform), Metal (macOS/iOS)
* **Audio backends**: Cubeb (cross-platform), WASAPI (Windows), PulseAudio/ALSA (Linux), AudioUnit (macOS)
* **UI frontends**: DolphinQt (Qt, cross-platform), DolphinNoGUI (headless)
* **Input backends**: SDL, DInput, XInput, evdev

## Build System

Dolphin uses CMake for cross-platform builds:

```cmake theme={null}
# From CMakeLists.txt
project(dolphin-emu)
set(CMAKE_CXX_STANDARD 23)
```

Key build options include:

* `ENABLE_QT`: Build Qt GUI (default ON)
* `ENABLE_NOGUI`: Build headless frontend (default ON)
* `ENABLE_VULKAN`: Vulkan backend support (default ON)
* `ENABLE_LTO`: Link-time optimization (default OFF)

See the [Building guide](/building/overview) for details.

## Performance Optimizations

<Accordion title="JIT Compilation">
  PowerPC code is compiled to native x86-64 or ARM64 for speed. The JIT supports:

  * Block compilation with register allocation
  * Paired-single SIMD optimization
  * MMU fastmem for direct memory access
</Accordion>

<Accordion title="Texture Cache">
  Caches decoded textures to avoid redundant uploads:

  * Hash-based lookup
  * Lazy invalidation
  * Arbitrary mipmap detection
</Accordion>

<Accordion title="Shader Cache">
  Precompiled shaders stored on disk:

  * Reduces stuttering
  * Pipeline state objects
  * Background compilation
</Accordion>

## See Also

* [Core Emulation Details](/architecture/core-emulation)
* [CPU Emulation](/architecture/cpu-emulation)
* [Video Backend Architecture](/architecture/video-backends)
* [Building Dolphin](/building/overview)