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

Core

Central emulation engine handling GameCube/Wii hardware

PowerPC CPU

CPU emulation with multiple execution backends

Video Backends

Graphics rendering through Vulkan, D3D, OpenGL, and Metal

Audio System

DSP emulation and audio output backends

IOS/HLE

Wii operating system emulation

Disc I/O

Game image loading and disc format support

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:

1. 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
2. CPU Execution

   PowerPC instruction execution via JIT or interpreter

   • Fetch and decode PowerPC instructions
   • Execute through JIT compiler or interpreter
   • Handle exceptions and interrupts
3. 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
4. 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

State Management

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

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)

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

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:

# 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 for details.

Performance Optimizations

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

Texture Cache

Caches decoded textures to avoid redundant uploads:

• Hash-based lookup
• Lazy invalidation
• Arbitrary mipmap detection

Shader Cache

Precompiled shaders stored on disk:

• Reduces stuttering
• Pipeline state objects
• Background compilation

See Also

• Core Emulation Details
• CPU Emulation
• Video Backend Architecture
• Building Dolphin