# hrydgard/ppsspp architecture

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

- Interactive diagram: https://gitdiagram.com/hrydgard/ppsspp
- Repository: https://github.com/hrydgard/ppsspp

## Overview

##### Project Type and Purpose
- PPSSPP is a cross-platform PSP emulator written in C++.  It consists of:
- A Core emulation engine (CPU, HLE modules, file systems, audio, input).
- A GPU rendering subsystem with multiple backends (OpenGL, Vulkan, D3D9/11, software).
- UI layers for multiple platforms (SDL, Qt, UWP, Windows native, Android, iOS).
- External libraries (‘ext/’), assets, and tools.

##### File Structure
- Top-level directories:
- Common/  – low-level utilities, threading, math, file I/O, crypto, data structures.
- Core/    – CPU emulation (MIPS interpreter, JITs), HLE PSP modules, file systems, audio/video decoders, debugger, replay.
- GPU/     – abstracted GPU commands + per-API backends (Common, D3D9, D3D11, OpenGL, Vulkan, Software, VR).
- UI/      – common UI components and screens.
- Qt/, SDL/, UWP/, Windows/, macOS/, Android/, iOS/ – platform-specific host wrappers (windowing, input, audio).
- libretro/, headless/ – alternative front-ends.
- ext/     – bundled third-party libraries (zlib, libpng, SPIRV-Cross, ImGui, etc).
- build scripts and CMake toolchains for cross-platform builds.

##### Read README for Context
- Confirms PPSSPP’s purpose: “a fast and portable PSP emulator” using high-level emulation (HLE) without a BIOS.
- Emulation features: CPU JIT, IR interpreter, HLE modules, GPU abstraction, multi-backend rendering, multi-platform UI.

##### Main Components & Their Relationships
A. Emulation Core (blue)
- CPU pipeline – MIPS interpreter & JITs (ARM, ARM64, x86, RISC-V).
- IR subsystem – IR frontend, analysis, passes, interpreter & JIT.
- HLE modules – PSP kernel, audio/video syscalls, networking (sceNet), file I/O.
- File systems – VFS, ISO, Zip, directory…
- Memory management – MemMap, MemArena.
- Audio engine – Atrac3 standalone, OpenSL, XAudio, etc.
- Input handling – gesture, key mapping, controller.

B. GPU Subsystem (green)
- GPU Common – command translation, shader generators, state cache.
- Backends – OpenGL, Vulkan, D3D9, D3D11, Software rasterizer, VR/OpenXR.
- Framebuffer & swapchain – platform-specific surface.

C. UI Layer (yellow)
- Common UI screens – menus, settings, developer tools (ImGui).
- Per-platform UI – SDL host, Qt host, Windows Win32 host, UWP host, Android Activity, iOS UIViewController.

D. Platform Abstraction (orange)
- Window & context management – SDL, Qt, Win32, Cocoa, Android JNI.
- Input device abstraction – SDL joystick, XInput, DInput, Android controllers.
- Audio output – OpenSL ES, CoreAudio, WASAPI, XAudio.
- Thread & timing – std::thread, platform timers.
- File dialogs & storage – portable‐file‐dialogs, Scoped Storage on Android.

E. External Libraries & Tools (gray)
- ext/… – zlib, libpng, rapidjson, ImGui, SPIRV-Cross, mini-upnpc, cityhash, etc.
- Tools – SaveTool, langtool, headless host, libretro core.
- Assets – shaders, fonts, language packs, themes, VFP lookup tables.

##### Architectural Patterns & Principles
- Modular layering:
- Core ←→ GPU ←→ Platform ←→ UI
- Each layer depends only on the layer below + well-defined interfaces.
- Plugin-style GPU backends:
- One API layer (Common) + multiple dynamic backends.
- HLE approach:
- PSP syscalls implemented in Core/HLE modules, no BIOS required.
- Cross-compile toolchain abstraction via CMakePresets / custom toolchain files.

##### Detail Level & Coverage
- Essential elements without overwhelming:
- Low-level utilities under “Common” rather than listing each file.
- Major sub-systems (CPU, HLE, GPU, UI).
- How assets (shaders, themes, data files) feed into Core/GPU/UI at runtime.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Build System"
        BS["Build System\n(CMake, Gradle, Toolchains)"]:::build
    end

    subgraph "External Libraries & Tools"
        EL["External Libraries & Tools"]:::ext
        Tools["Tools & Utilities"]:::ext
        Assets["Assets\n(Shaders, Themes, Fonts, Lang Packs)"]:::ext
        Frontends["Front-Ends"]:::ext
        Headless["Headless Front-End"]:::ext
        Libretro["libretro Front-End"]:::ext
        EL --> Tools
        EL --> Assets
        Frontends --> Headless
        Frontends --> Libretro
        EL --> Frontends
    end

    subgraph "Platform Abstraction"
        Qt["Qt Host\nWrapper"]:::platform
        SDL["SDL Host\nWrapper"]:::platform
        Win["Windows Host"]:::platform
        UWP["UWP Host"]:::platform
        Mac["macOS Host"]:::platform
        Android["Android Host"]:::platform
        iOS["iOS Host"]:::platform
    end

    subgraph "UI Layer"
        UI["UI Layer\n(Common Screens, ImGui)"]:::ui
    end

    subgraph "Emulation Core"
        Core["Emulation Core"]:::core
        CPU["CPU Pipeline\nMIPS interpreter & JITs"]:::core
        IR["IR Subsystem"]:::core
        HLE["HLE Modules"]:::core
        FS["File Systems\nVFS, ISO, Zip"]:::core
        MM["Memory Mgmt\nMemMap, MemArena"]:::core
        AudioEngine["Audio Engine\nAtrac3, OpenSL, XAudio"]:::core
        Core --> CPU
        Core --> IR
        Core --> HLE
        Core --> FS
        Core --> MM
    end

    subgraph "GPU Subsystem"
        GPUComm["GPU Common"]:::gpu
        Backends["Backends\nOpenGL, Vulkan, D3D9/11, Software, VR"]:::gpu
        FB["Framebuffer & Swapchain"]:::gpu
        GPUComm --> Backends --> FB
    end

    BS --> Core
    BS --> GPUComm
    BS --> UI
    BS --> Qt
    BS --> SDL
    BS --> Win
    BS --> UWP
    BS --> Mac
    BS --> Android
    BS --> iOS

    EL -.-> Core
    EL -.-> GPUComm
    EL -.-> UI
    EL -.-> Qt
    EL -.-> SDL
    EL -.-> Win
    EL -.-> UWP
    EL -.-> Mac
    EL -.-> Android
    EL -.-> iOS

    UI -->|"User Input"| Core
    Core -->|"UI Output"| UI

    Core -->|"Render Cmds"| GPUComm
    AudioEngine -->|"to Audio API"| Qt
    AudioEngine -->|"to Audio API"| SDL
    AudioEngine -->|"to Audio API"| Win
    AudioEngine -->|"to Audio API"| UWP
    AudioEngine -->|"to Audio API"| Mac
    AudioEngine -->|"to Audio API"| Android
    AudioEngine -->|"to Audio API"| iOS

    UI -->|"Depends On"| Qt
    UI -->|"Depends On"| SDL
    UI -->|"Depends On"| Win
    UI -->|"Depends On"| UWP
    UI -->|"Depends On"| Mac
    UI -->|"Depends On"| Android
    UI -->|"Depends On"| iOS

    GPUComm -->|"Depends On"| Qt
    GPUComm -->|"Depends On"| SDL
    GPUComm -->|"Depends On"| Win
    GPUComm -->|"Depends On"| UWP
    GPUComm -->|"Depends On"| Mac
    GPUComm -->|"Depends On"| Android
    GPUComm -->|"Depends On"| iOS

    Assets -->|"Runtime Data"| Core
    Assets -->|"Runtime Data"| GPUComm
    Assets -->|"Runtime Data"| UI

    click Core "https://github.com/hrydgard/ppsspp/tree/master/Core/"
    click GPUComm "https://github.com/hrydgard/ppsspp/tree/master/GPU/"
    click Backends "https://github.com/hrydgard/ppsspp/tree/master/Common/GPU/"
    click UI "https://github.com/hrydgard/ppsspp/tree/master/UI/"
    click Qt "https://github.com/hrydgard/ppsspp/tree/master/Qt/"
    click SDL "https://github.com/hrydgard/ppsspp/tree/master/SDL/"
    click Win "https://github.com/hrydgard/ppsspp/tree/master/Windows/"
    click UWP "https://github.com/hrydgard/ppsspp/tree/master/UWP/"
    click Mac "https://github.com/hrydgard/ppsspp/tree/master/macOS/"
    click Android "https://github.com/hrydgard/ppsspp/tree/master/android/"
    click iOS "https://github.com/hrydgard/ppsspp/tree/master/ios/"
    click EL "https://github.com/hrydgard/ppsspp/tree/master/ext/"
    click Tools "https://github.com/hrydgard/ppsspp/tree/master/Tools/"
    click Assets "https://github.com/hrydgard/ppsspp/tree/master/assets/"
    click Headless "https://github.com/hrydgard/ppsspp/tree/master/headless/"
    click Libretro "https://github.com/hrydgard/ppsspp/tree/master/libretro/"
    click BS "https://github.com/hrydgard/ppsspp/blob/master/CMakeLists.txt"
    click BS "https://github.com/hrydgard/ppsspp/blob/master/CMakePresets.json"
    click BS "https://github.com/hrydgard/ppsspp/tree/master/cmake/Toolchains/"

    classDef core fill:#ADD8E6,stroke:#000;
    classDef gpu fill:#90EE90,stroke:#000;
    classDef ui fill:#FFFFE0,stroke:#000;
    classDef platform fill:#FFA500,stroke:#000;
    classDef ext fill:#D3D3D3,stroke:#000;
    classDef build fill:#E6E6FA,stroke:#000;
```
