# diegolix29/shadps4 architecture

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

- Interactive diagram: https://gitdiagram.com/diegolix29/shadps4
- Repository: https://github.com/diegolix29/shadps4

## Overview

##### Main Components
- Emulation Core: Represented mainly within the src/core directory. This includes modules for CPU patches, memory management, loader (ELF, linkers, signaling, threads, and system module management), and device emulation (src/core/devices).
- Libraries and Subsystems: Under src/core/libraries, you have several key subsystems covering audio (audio, audio3d, avplayer), network, video (videodec, videoout), file system, input, system dialogs, and more. Also, modules like np_manager, np_party, and np_trophy handle PlayStation network functionality.
- Shader Recompilation Engine: Found within src/shader_recompiler, this component deals with translating, optimizing and emitting shaders (using both frontend and backend/spirv components).
- Rendering Subsystem: The src/video_core directory and its subdirectories detail components dealing with GPU emulation, including Vulkan rendering (vk_instance, vk_swapchain, vk_shader_util, etc.) and alternative paths like host_shaders.
- User Interface/Frontend: There are multiple UI components:
- Qt-based GUI located in src/qt_gui (with dialogs, settings, and game listing).
- SDL window and imgui based UI layers in src/sdl_window.cpp and src/imgui.
- Input Handling: Modules in src/input and parts of the GUI (controller mapping, keyboard/mouse integration) form the input management system.
- Build System and External Dependencies: The project uses CMake (top-level CMakeLists.txt, cmake directory) and integrates external libraries (see externals directory with modules like MoltenVK, SDL3, and others) for additional functionality.
- Firmware and System Services: Although not part of the hardware abstraction code, the README highlights the firmware modules (user/sys_modules) needed, implying that part of the design deals with interfacing with dumped PS4 firmware libraries.

##### Understand the Relationships and Data Flow
- The Emulator Core (src/emulator.cpp, main.cpp, and related core modules) acts as the central coordinator.
- It interacts with the Graphics (rendering) subsystem to render PS4 output by using both low-level GPU support (src/video_core/renderer_vulkan) and high-level shader compilation (src/shader_recompiler).
- It communicates with audio libraries and input modules to emulate sound and user interaction.
- The UI components (Qt and SDL/ImGui) provide the interface for configuration, debugging (logging and frame graph widgets), and status display.
- The build and dependency management (via CMake and externals) establishes how third-party libraries support features such as RenderDoc integration, FFmpeg for media processing, and others.

##### Architectural Patterns and Design Principles
- Modular Architecture: With directories segmented by functionality (core, native subsystems, libraries, UI, shader recompiler), the design lends itself to a clear modular segmentation.
- Separation of Concerns: For instance, the shader recompilation is separated into front-end (decoding, IR, translation) and its corresponding back-end (SPIR-V generation), while the emulation/hardware abstraction is organized separately.
- Layering: There is a clear layering between low-level emulation (core, libraries) and high-level UI/interaction (qt_gui, imgui).
- Use of CMake Graph: Emphasize how build scripts pull together the library dependencies, external modules, and testing hooks (CI and GitHub workflows).

##### Instructing the Principal Software Engineer
– Include annotations or sub-labels detailing key functions (e.g., “Shader Translation (frontend)” vs. “SPIR-V Emission (backend)”).
– Indicate boundary areas for external dependencies and firmware interfaces.
- Major directories and significant modules mentioned in the file tree (like src/common, src/core, src/shader_recompiler, src/qt_gui, src/video_core, and externals) are represented in context.
- Clarity over clutter—aim to capture every essential architectural element without over-detailed implementation specifics.

- Emulator Core and Subsystems (CPU, memory, loader, device and system emulation)
- Rendering and Shader Processing (video core, renderer, shader recompilation)
- Audio, Input, and Peripheral Emulation (audio libraries, input handling)
- User Interfaces (Qt GUI, SDL/ImGui)
- Build Infrastructure and External Dependencies (CMake and externals)

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Build & External"
        BUILD_CMAKE["Build System: CMakeLists.txt"]:::build
        BUILD_DIR["CMake Modules: cmake"]:::build
        BUILD_EXT["Externals: externals"]:::build
    end

    subgraph "Emulator Core"
        CORE["Emulator Core"]:::core
    end

    subgraph "Libraries & Subsystems"
        LIB["Libraries & Subsystems\n(src/core/libraries)"]:::libraries
    end

    subgraph "Shader Recompiler"
        SHADER["Shader Recompiler Engine\n(src/shader_recompiler)"]:::shader
    end

    subgraph "Rendering Subsystem"
        RENDER["Video Core\n(src/video_core)"]:::rendering
        RENDER2["Renderer Vulkan\n(src/video_core/renderer_vulkan)"]:::rendering
        RENDER_HOST["Host Shaders\n(src/video_core/host_shaders)"]:::rendering
        RENDER_BUFFER["Buffer Cache\n(src/video_core/buffer_cache)"]:::rendering
        RENDER_TEXTURE["Texture Cache\n(src/video_core/texture_cache)"]:::rendering
    end

    subgraph "User Interface"
        UI_QT["Qt GUI\n(src/qt_gui)"]:::ui
        UI_SDL["SDL/ImGui UI\n(src/sdl_window & src/imgui)"]:::ui
    end

    subgraph "Input Handling"
        INPUT["Input Handler\n(src/input)"]:::input
    end

    subgraph "System Services"
        FIRM["Firmware Modules\n(user/sys_modules)"]:::external
    end

    %% Build & External connections
    BUILD_CMAKE --> CORE
    BUILD_DIR --> CORE
    BUILD_EXT --> CORE
    BUILD_EXT --> LIB
    BUILD_EXT --> SHADER
    BUILD_EXT --> RENDER
    BUILD_EXT --> UI_QT
    BUILD_EXT --> INPUT

    %% Core interactions
    CORE -->|"uses"| LIB
    CORE -->|"shaderCompilation"| SHADER
    CORE -->|"renderCommands"| RENDER
    CORE -->|"inputEvents"| INPUT
    CORE -->|"uiUpdates"| UI_QT
    CORE -->|"uiUpdates"| UI_SDL
    CORE -->|"firmwareAccess"| FIRM

    %% Shader to Rendering
    SHADER -->|"shaderEmission"| RENDER2

    %% Internal Rendering flow
    RENDER --> RENDER2
    RENDER2 --> RENDER_HOST
    RENDER_HOST --> RENDER_BUFFER
    RENDER_BUFFER --> RENDER_TEXTURE

    %% UI feedback to Core
    UI_QT --> CORE
    UI_SDL --> CORE

    %% Click Events for Emulator Core
    click CORE "https://github.com/diegolix29/shadps4/tree/main/src/core"
    click CORE "https://github.com/diegolix29/shadps4/blob/main/src/emulator.cpp"
    click CORE "https://github.com/diegolix29/shadps4/blob/main/src/emulator.h"
    click CORE "https://github.com/diegolix29/shadps4/blob/main/src/main.cpp"

    %% Click Events for Libraries & Subsystems
    click LIB "https://github.com/diegolix29/shadps4/tree/main/src/core/libraries"
    click LIB "https://github.com/diegolix29/shadps4/tree/main/src/core/libraries/audio"
    click LIB "https://github.com/diegolix29/shadps4/tree/main/src/core/libraries/avplayer"
    click LIB "https://github.com/diegolix29/shadps4/tree/main/src/core/libraries/network"
    click LIB "https://github.com/diegolix29/shadps4/tree/main/src/core/libraries/videodec"
    click LIB "https://github.com/diegolix29/shadps4/tree/main/src/core/libraries/videoout"

    %% Click Events for Shader Recompiler
    click SHADER "https://github.com/diegolix29/shadps4/tree/main/src/shader_recompiler"

    %% Click Events for Rendering Subsystem
    click RENDER "https://github.com/diegolix29/shadps4/tree/main/src/video_core"
    click RENDER2 "https://github.com/diegolix29/shadps4/tree/main/src/video_core/renderer_vulkan"
    click RENDER_HOST "https://github.com/diegolix29/shadps4/tree/main/src/video_core/host_shaders"
    click RENDER_BUFFER "https://github.com/diegolix29/shadps4/tree/main/src/video_core/buffer_cache"
    click RENDER_TEXTURE "https://github.com/diegolix29/shadps4/tree/main/src/video_core/texture_cache"

    %% Click Events for User Interface
    click UI_QT "https://github.com/diegolix29/shadps4/tree/main/src/qt_gui"
    click UI_SDL "https://github.com/diegolix29/shadps4/blob/main/src/sdl_window.cpp"
    click UI_SDL "https://github.com/diegolix29/shadps4/blob/main/src/sdl_window.h"
    click UI_SDL "https://github.com/diegolix29/shadps4/tree/main/src/imgui"

    %% Click Event for Input Handling
    click INPUT "https://github.com/diegolix29/shadps4/tree/main/src/input"

    %% Click Events for Build System and External Dependencies
    click BUILD_CMAKE "https://github.com/diegolix29/shadps4/blob/main/CMakeLists.txt"
    click BUILD_DIR "https://github.com/diegolix29/shadps4/tree/main/cmake"
    click BUILD_EXT "https://github.com/diegolix29/shadps4/tree/main/externals"

    %% Styles
    classDef core fill:#e0bbe4,stroke:#6a1b9a,stroke-width:2px;
    classDef libraries fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef shader fill:#dcedc1,stroke:#558b2f,stroke-width:2px;
    classDef rendering fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef ui fill:#b3e5fc,stroke:#0277bd,stroke-width:2px;
    classDef input fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef build fill:#f8bbd0,stroke:#ad1457,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
```
