# dfranx/shadered architecture

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

- Interactive diagram: https://gitdiagram.com/dfranx/shadered
- Repository: https://github.com/dfranx/shadered

## Overview

##### Project type and purpose
- SHADERed is a desktop, cross-platform (Windows, Linux, Web) native application for writing, previewing, and debugging GPU shaders.
- It consists of a UI layer (built on SDL2 + ImGui), a core “engine” that drives rendering, debugging and analysis, and plugin & export subsystems.

##### File structure
- src/SHADERed/ contains the heart of the application:
- EditorEngine, GUIManager, InterfaceManager
- Engine subfolder (GLUtils, AudioPlayer, GeometryFactory, RenderEngine)
- Objects subfolder (ShaderCompiler, PipelineManager, ProjectParser, DebugAdapterProtocol, SPIRVParser, WebAPI, PluginAPI)
- UI subfolder (all windows & dockable panels implemented in ImGui)
- libs/ holds external dependencies that are statically linked (ImGui, SPIRV-Cross, SPIRV-VM, glslang, Assimp, pugixml, etc.)
- bin/data & bin/examples/ contain runtime assets: example shaders, models, textures, themes, templates.
- CMakeLists.txt & cmake/ drive the build process and incorporate submodules.

##### Read the README for additional insights
- The README highlights major features: real-time preview, shader debugging (line-by-line + frame analyzer), plugin API, export facilities (C++ templates), and instant recompilation.

##### Main components & interactions
A. User Interface Layer (UI)
- Modules: GUIManager, InterfaceManager, all UI panels under src/SHADERed/UI
- Interaction: Captures user actions (open file, set breakpoint, run debug, change shader code)
B. Editor Core (EditorEngine)
- Coordinates between UI and engine subsystems
- Manages state: current project, open shaders, compile status
C. Render & Compute Engine
- RenderEngine uses GLUtils to call OpenGL via SDL2/GLEW
- GeometryFactory, Model loader (Assimp), AudioPlayer feed data into GPU
D. Shader Pipeline Manager
- PipelineManager constructs GPU pipeline stages (vertex, tessellation, geometry, pixel, compute)
- ShaderCompiler + ShaderFileIncluder compile HLSL/GLSL/SPIR-V through glslang + SPIRV-Cross
E. Debugger & Analyzer
- SPIRVParser + SPIRV-VM simulate or inspect GPU code
- DebugAdapterProtocol + ExpressionCompiler handle breakpoints, watches, immediate expressions
- FrameAnalyzer tracks per-pixel values, undefined behavior heatmap
F. Project & Asset Management
- ProjectParser reads .sprj files, manages asset references
- Resource layer: file I/O, parsing (pugixml for XML, inih for settings), zip_file for imports
G. Plugin System & Export
- PluginManager loads plugins conforming to PluginAPI
- ExportCPP generates C++ shader loading templates
H. External Interfaces
- WebAPI handles online browsing of examples and plugins
- File system and OS integration (SDL2 dialogs via ImFileDialog)

##### Architectural patterns & design principles
- Layered architecture: UI → EditorEngine → Subsystems (Render, Debug, Project) → Hardware/OS
- Plugin-based extensibility: clear PluginAPI interfaces in Objects/PluginAPI
- Separation of concerns: UI code never directly calls OpenGL; it delegates to RenderEngine
- Data-flow loops: code edit → immediate compile → RenderEngine → GPU → UI preview

##### Final checklist
- Clear, distinct labels on every component
- Layered layout reflecting logical separation: UI, core, infra

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction & UI Layer
    subgraph "User Interaction & UI" 
        direction TB
        UI_Panels["UI Panels (ImGui)"]:::inhouse
        GUIManager["GUIManager"]:::inhouse
        InterfaceManager["InterfaceManager"]:::inhouse
        WebAPI["WebAPI"]:::inhouse
    end

    %% Core Engine & Subsystems
    subgraph "Core Engine & Subsystems"
        direction TB
        EditorEngine["EditorEngine"]:::inhouse

        subgraph "Render & Compute Engine"
            direction TB
            RenderEngine["RenderEngine"]:::inhouse
            GLUtils["GLUtils"]:::inhouse
            AudioPlayer["AudioPlayer"]:::inhouse
            GeometryFactory["GeometryFactory"]:::inhouse
            Model["Model"]:::inhouse
        end

        subgraph "Shader Pipeline Manager"
            direction TB
            PipelineManager["PipelineManager"]:::inhouse
            ShaderCompiler["ShaderCompiler"]:::inhouse
            ShaderFileIncluder["ShaderFileIncluder"]:::inhouse
            glslang["glslang"]:::external
            SPIRVCross["SPIR-V Cross"]:::external
        end

        subgraph "Debugger & Analyzer"
            direction TB
            SPIRVParser["SPIRVParser"]:::inhouse
            DebugAdapterProtocol["DebugAdapterProtocol"]:::inhouse
            ExpressionCompiler["ExpressionCompiler"]:::inhouse
            FrameAnalysis["FrameAnalysis"]:::inhouse
            DebugInformation["DebugInformation"]:::inhouse
            SPIRV_VM["SPIRV-VM"]:::external
        end

        subgraph "Project & Asset Management"
            direction TB
            ProjectParser["ProjectParser"]:::inhouse
            Settings["Settings"]:::inhouse
            pugixml["pugixml"]:::external
            INIReader["INIReader"]:::external
            zip_file["zip_file.hpp"]:::external
        end

        subgraph "Plugin System & Export"
            direction TB
            PluginManager["PluginManager"]:::inhouse
            PluginAPI["PluginAPI"]:::inhouse
            ExportCPP["ExportCPP"]:::inhouse
        end
    end

    %% External Dependencies & Hardware
    subgraph "External Dependencies & Hardware"
        direction TB
        SDL2_GLEW["SDL2/GLEW"]:::external
        ImFileDialog["ImFileDialog"]:::external
        GPU_Driver["GPU Driver"]:::hardware
        FileSystem["File System"]:::hardware
        GPU["GPU"]:::hardware
    end

    %% Connections
    UI_Panels -->|"user commands"| EditorEngine
    GUIManager -->|"user commands"| EditorEngine
    InterfaceManager -->|"user commands"| EditorEngine
    WebAPI -->|"fetch examples/plugins"| UI_Panels

    EditorEngine -->|"compile & render"| RenderEngine
    EditorEngine -->|"setup pipeline"| PipelineManager
    EditorEngine -->|"parse project"| ProjectParser
    EditorEngine <-->|"plugin callbacks"| PluginManager

    RenderEngine -->|"OpenGL calls"| GPU_Driver
    RenderEngine -->|"uses"| GLUtils
    RenderEngine -->|"plays audio"| AudioPlayer
    RenderEngine -->|"creates geometry"| GeometryFactory
    RenderEngine -->|"loads models"| Model

    PipelineManager -->|"invoke compiler"| ShaderCompiler
    PipelineManager -->|"include files"| ShaderFileIncluder
    ShaderCompiler -->|"compile HLSL/GLSL"| glslang
    ShaderCompiler -->|"cross-compile"| SPIRVCross

    GPU_Driver -->|"draw calls"| GPU
    GPU -->|"debug data"| SPIRVParser
    SPIRVParser -->|"breakpoint event"| DebugAdapterProtocol
    DebugAdapterProtocol -->|"evaluate expressions"| ExpressionCompiler
    DebugAdapterProtocol -->|"frame analysis"| FrameAnalysis
    DebugAdapterProtocol -->|"gather info"| DebugInformation

    ProjectParser -->|"load .sprj assets"| FileSystem
    ProjectParser -->|"parse XML"| pugixml
    Settings -->|"read ini"| INIReader
    ProjectParser -->|"import zip"| zip_file

    PluginManager -->|"export support"| ExportCPP
    PluginManager -->|"UI dialogs"| ImFileDialog
    PluginManager -->|"system dialogs"| SDL2_GLEW

    %% Click Events
    click UI_Panels "https://github.com/dfranx/shadered/tree/master/src/SHADERed/UI/"
    click GUIManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/GUIManager.cpp"
    click GUIManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/GUIManager.h"
    click InterfaceManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/InterfaceManager.cpp"
    click InterfaceManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/InterfaceManager.h"
    click EditorEngine "https://github.com/dfranx/shadered/blob/master/src/SHADERed/EditorEngine.cpp"
    click EditorEngine "https://github.com/dfranx/shadered/blob/master/src/SHADERed/EditorEngine.h"

    click RenderEngine "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/RenderEngine.cpp"
    click RenderEngine "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/RenderEngine.h"
    click GLUtils "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/GLUtils.cpp"
    click GLUtils "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/GLUtils.h"
    click AudioPlayer "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/AudioPlayer.cpp"
    click AudioPlayer "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/AudioPlayer.h"
    click GeometryFactory "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/GeometryFactory.cpp"
    click GeometryFactory "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/GeometryFactory.h"
    click Model "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/Model.cpp"
    click Model "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Engine/Model.h"

    click PipelineManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/PipelineManager.cpp"
    click PipelineManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/PipelineManager.h"
    click ShaderCompiler "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/ShaderCompiler.cpp"
    click ShaderCompiler "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/ShaderCompiler.h"
    click ShaderFileIncluder "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/ShaderFileIncluder.h"
    click glslang "https://github.com/dfranx/shadered/tree/master/libs/glslang/"
    click SPIRVCross "https://github.com/dfranx/shadered/tree/master/libs/SPIRVCross/"

    click SPIRVParser "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/SPIRVParser.cpp"
    click SPIRVParser "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/SPIRVParser.h"
    click DebugAdapterProtocol "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/DebugAdapterProtocol.cpp"
    click DebugAdapterProtocol "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/DebugAdapterProtocol.h"
    click ExpressionCompiler "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/Debug/ExpressionCompiler.cpp"
    click ExpressionCompiler "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/Debug/ExpressionCompiler.h"
    click FrameAnalysis "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/FrameAnalysis.cpp"
    click FrameAnalysis "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/FrameAnalysis.h"
    click DebugInformation "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/DebugInformation.cpp"
    click DebugInformation "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/DebugInformation.h"
    click SPIRV_VM "https://github.com/dfranx/shadered/tree/master/libs/SPIRV-VM/"

    click ProjectParser "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/ProjectParser.cpp"
    click ProjectParser "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/ProjectParser.h"
    click Settings "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/Settings.cpp"
    click Settings "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/Settings.h"
    click pugixml "https://github.com/dfranx/shadered/tree/master/libs/pugixml/"
    click INIReader "https://github.com/dfranx/shadered/blob/master/libs/misc/INIReader.h"
    click zip_file "https://github.com/dfranx/shadered/blob/master/libs/misc/zip_file.hpp"

    click PluginManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/PluginManager.cpp"
    click PluginManager "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/PluginManager.h"
    click PluginAPI "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/PluginAPI/Plugin.h"
    click PluginAPI "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/PluginAPI/PluginData.h"
    click ExportCPP "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/Export/ExportCPP.cpp"
    click ExportCPP "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/Export/ExportCPP.h"
    click WebAPI "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/WebAPI.cpp"
    click WebAPI "https://github.com/dfranx/shadered/blob/master/src/SHADERed/Objects/WebAPI.h"
    click ImFileDialog "https://github.com/dfranx/shadered/blob/master/libs/misc/ImFileDialog.cpp"
    click ImFileDialog "https://github.com/dfranx/shadered/blob/master/libs/misc/ImFileDialog.h"
    click SDL2_GLEW "https://github.com/dfranx/shadered/tree/master/cmake/"
    
    %% Styles
    classDef inhouse fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef hardware fill:#FFD700,stroke:#333,stroke-width:1px
```
