# ShadPS4 Source Code Structure Overview: A Deep Dive into the PS4 Emulator Architecture

> Explore the ShadPS4 source code structure. Understand the PS4 emulator architecture, including system emulation, GPU rendering, and input handling. Dive into the C++ codebase.

- Repository: [shadps4-emu/shadPS4](https://github.com/shadps4-emu/shadPS4)
- Tags: architecture
- Published: 2026-03-19

---

**ShadPS4 organizes its C++ codebase into distinct layers—system emulation, GPU/video pipeline, input/UI, and build tooling—with the `src/` directory containing core logic and `src/video_core/` handling Vulkan-based graphics rendering.**

The shadps4-emu repository represents a native C++ implementation of a PlayStation 4 emulator, architected to separate system-level concerns from hardware abstraction. This shadps4-emu source code structure overview examines how the project organizes its emulation core, graphics pipeline, and user interface components across the `src/` directory tree.

## Application Entry Point and CLI Parsing

The emulator boots through [`src/main.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/main.cpp), which implements the `main` function responsible for high-level orchestration. This file creates an `EmulatorState` singleton, loads user configuration, and parses command-line options using **CLI11**.

The parser resolves the game ELF path or CUSA ID, then invokes `Core::Emulator::Run` to begin execution. All initialization logic flows through this single entry point, making it the starting line for understanding the shadps4-emu source code structure.

```cpp
// Simplified flow from main.cpp
auto* emulator = Common::Singleton<Core::Emulator>::Instance();
emulator->Run(ebootPath, gameArgs, overrideRoot);

```

## Emulator Core Architecture

The core emulation logic resides in [`src/emulator.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/emulator.h) and [`src/emulator.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/emulator.cpp), where the `Emulator` class owns and coordinates all subsystems. This architecture separates concerns into distinct managers for memory, modules, threading, and platform abstraction.

### Emulator State and Main Loop

The `Emulator` class maintains the runtime state and drives the main execution loop. It instantiates and manages the core subsystems including the loader, memory manager, GPU interface, and input handler. The main loop processes CPU emulation while coordinating with the Vulkan renderer for graphics submission.

### Module Loading and ELF Parsing

The module system in [`src/core/module.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/module.h) and [`src/core/module.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/module.cpp) handles parsing of PS4 ELF files (including SPRX modules). It maps binaries into the emulated address space, resolves symbols using the **AeroLib** NID table, and manages Thread-Local Storage (TLS) indices and relocations.

```cpp
// Example of manual module loading
u32 maxTlsIdx = 0;
Core::Module my_mod(memory, "/path/to/module.sprx", maxTlsIdx);

// Resolve exported function via NID
using EntryFn = int(*)(int);
auto fn_ptr = reinterpret_cast<EntryFn>(my_mod.FindByName("SomeExportedFunction"));
int result = fn_ptr(42);

```

### Memory Management

The virtual address space implementation lives in [`src/core/memory.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/memory.h) and [`src/core/memory.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/memory.cpp). The `MemoryManager` class provides `MapMemory` functionality, protection flag handling, and page-table management to mirror the PS4's memory architecture.

### Threading and TLS

Thread abstraction resides in [`src/core/thread.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/thread.h) and [`src/core/thread.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/thread.cpp), providing thin wrappers around host threads that expose the PS4 kernel API (`threadCreate`, `threadJoin`, etc.). Thread-Local Storage support is implemented in [`src/core/tls.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/tls.h) and [`src/core/tls.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/tls.cpp) to satisfy the PS4 ABI requirements.

### Signal Handling and Platform Abstraction

POSIX-style signal handling for kernel-layer operations (such as `SIGSEGV` for illegal memory accesses) is implemented in [`src/core/signals.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/signals.h) and [`src/core/signals.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/signals.cpp). Platform detection and OS-specific backend selection occur in [`src/core/platform.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/platform.h), which configures Vulkan, SDL, and other host-specific implementations.

## GPU and Video Core (Vulkan Implementation)

The graphics subsystem in `src/video_core/` implements the PS4's GCN-style pipeline using **Vulkan**. This layer separates renderer orchestration, resource management, and shader compilation.

### Vulkan Renderer Pipeline

The high-level renderer implementation in `src/video_core/renderer_vulkan/` manages command submission, swap-chain handling, and per-frame synchronization. Key components include:
- [`vk_scheduler.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/vk_scheduler.cpp) – Command buffer scheduling and submission
- [`vk_presenter.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/vk_presenter.cpp) – Swap-chain presentation and frame pacing
- [`vk_rasterizer.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/vk_rasterizer.cpp) – Draw command execution and state management

```cpp
// Example draw submission flow
auto* renderer = emulator->GetRenderer();   // Returns Core::RendererVulkan*
renderer->BeginFrame();
renderer->ClearRenderTarget(0, {0.1f, 0.1f, 0.1f, 1.0f});
renderer->EndFrame();   // Presents the swapchain

```

### Resource Management

The resource pool system in [`src/video_core/renderer_vulkan/vk_resource_pool.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/video_core/renderer_vulkan/vk_resource_pool.cpp) manages Vulkan buffers, images, descriptor sets, and a master semaphore for cross-queue work synchronization.

### Pipeline Handling and Caching

Graphics and compute pipeline creation, state caching, and serialization for fast reloads are handled in:
- [`vk_graphics_pipeline.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/vk_graphics_pipeline.cpp)
- [`vk_compute_pipeline.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/vk_compute_pipeline.cpp)
- [`vk_pipeline_cache.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/vk_pipeline_cache.cpp)

### Shader Compilation

The **AeroLib** HLE shader compiler (based on Yuzu's Hades) resides in `src/shader_recompiler/`. It translates PS4 shader binaries into Vulkan SPIR-V, with entry points in [`recompiler.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/recompiler.cpp) and [`recompiler.h`](https://github.com/shadps4-emu/shadPS4/blob/main/recompiler.h).

### Texture and Buffer Caches

PS4-specific memory features including multi-level page tables, tiling, and on-the-fly format conversion are implemented in:
- `src/video_core/texture_cache/`
- `src/video_core/buffer_cache/`

### Host Shaders and Debugging

Compute shaders for texture detiling, color conversion, and **FidelityFX Super Resolution (FSR)** are located in `src/video_core/host_shaders/` (`.comp` and `.frag` files). RenderDoc integration for frame capture debugging is implemented in [`src/video_core/renderdoc.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/video_core/renderdoc.cpp).

## Input Handling and UI Layer

The input abstraction layer in `src/input/` provides unified controller, mouse, and keyboard support. Key files include [`src/input/controller.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/input/controller.cpp) and [`src/input/input_handler.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/input/input_handler.cpp), which expose a consistent API to both the core emulation and the UI.

The ImGui integration layer in `src/imgui/` renders the configuration interface used by the QtLauncher front-end. The main interface definitions reside in [`src/imgui/imgui_layer.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/imgui/imgui_layer.h).

```cpp
// Example controller mapping configuration
auto* km = Core::KeyManager::GetInstance();
km->SetKey("L1", Core::KeyCode::Keyboard_W);
km->SaveToFile();  // Persists to <UserDir>/keys.toml

```

## Build System and Auxiliary Tooling

The project uses **CMake** as its primary build system, configured through the top-level [`CMakeLists.txt`](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt). Platform-specific detection scripts reside in `cmake/`, including `FindxxHash.cmake` and `FindRenderDoc.cmake` for locating optional dependencies.

The build system configures **Vulkan**, **SDL3**, and optional third-party libraries based on the host platform detected in [`src/core/platform.h`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/platform.h).

Python utilities in `scripts/` automate development tasks, notably [`scripts/ps4_names2stubs.py`](https://github.com/shadps4-emu/shadPS4/blob/main/scripts/ps4_names2stubs.py), which generates syscall stubs from the [`ps4_names.txt`](https://github.com/shadps4-emu/shadPS4/blob/main/ps4_names.txt) database. For reproducible Linux builds, the repository includes a `shell.nix` expression.

## Summary

- **ShadPS4** separates concerns into distinct layers: system emulation, GPU/video pipeline, input/UI, and build tooling.
- The entry point in [`src/main.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/main.cpp) orchestrates initialization using CLI11, while [`src/emulator.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/emulator.cpp) manages the runtime state.
- Core emulation logic resides in `src/core/`, handling ELF loading, memory management, threading, TLS, and platform abstraction.
- The Vulkan-based graphics pipeline in `src/video_core/` includes the renderer, resource pools, shader recompiler (AeroLib), and texture/buffer caches.
- Input abstraction and ImGui UI layers bridge the core emulation with user interaction.
- CMake drives the build system, with Python scripts automating syscall stub generation.

## Frequently Asked Questions

### What programming language is ShadPS4 written in?

ShadPS4 is implemented primarily in **C++** as a native systems project. The codebase leverages modern C++ features for performance-critical emulation tasks while maintaining cross-platform compatibility across Windows, Linux, and macOS.

### How does ShadPS4 handle PS4 graphics rendering?

The emulator implements the PS4's GCN-style graphics pipeline using **Vulkan** through the `src/video_core/` directory. It includes a custom shader recompiler (AeroLib) that translates PS4 shader binaries to SPIR-V, along with texture and buffer caches that handle the console's specific memory tiling and format requirements.

### Where is the main entry point for the emulator?

The application entry point resides in [`src/main.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/main.cpp), which creates the `EmulatorState` singleton, parses command-line arguments using CLI11, and invokes `Core::Emulator::Run`. This file serves as the orchestration layer that initializes all subsystems before handing control to the core emulation loop.

### Can the graphics backend be replaced without modifying core emulation logic?

Yes, the modular architecture in `src/video_core/` abstracts the graphics implementation from the core emulation. The renderer interface in `src/video_core/renderer_vulkan/` could theoretically be swapped for a DirectX 12 or Metal backend by implementing the same resource management and pipeline interfaces, without touching the ELF loader or memory management code in `src/core/`.