# wpmed92/shaderpulse architecture

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

- Interactive diagram: https://gitdiagram.com/wpmed92/shaderpulse
- Repository: https://github.com/wpmed92/shaderpulse

## Overview

##### Project Type and Purpose
- This is a compiler front end for translating GLSL code (with compute shaders and other shader features) into SPIR-V using MLIR as the code generation backend.
- The README clearly defines the role of each major compiler phase (lexing, parsing, analysis, and code generation) and demonstrates an end-to-end example where a compute shader is converted to MLIR SPIR-V code.

##### Key Components and Their Organization
a. Entry Point & Overall Pipeline:
- Compiler’s entry point (e.g., the “compiler/shaderpulse.cpp” file) that likely initializes the overall compilation process.

b. Modular Subsystems:
- Preprocessor: In “include/Preprocessor” and “lib/Preprocessor”, responsible for handling source text modifications (handling #defines, includes, etc.).
- Lexer: In “include/Lexer” and “lib/Lexer”, reads the source GLSL code and produces tokens.
- Parser: Found in “include/Parser” and “lib/Parser”, conducts a recursive descent parsing of tokens into an Abstract Syntax Tree (AST).
- AST & Visitors: The “include/AST” and “lib/AST” directories include definitions for the AST nodes and visitors (like PrinterASTVisitor) that are likely used for traversals.
- Semantic Analysis: In “include/Analysis” and “lib/Analysis”, performs type checking and scope analysis using the visitor pattern.
- Code Generation: In “include/CodeGen” and “lib/CodeGen”, traverses the AST and emits MLIR (which in turn becomes SPIR-V). The MLIRCodeGen module is a key element here.

c. Infrastructure and Testing:
- CMakeLists.txt and related configuration files to build the project.
- “test” directory, which splits tests into subdirectories (Lexer, Parser, Analysis, CodeGen) to verify each component.
- Example shaders in the “example” folder, which serve as demonstrations of the frontend in action.

- From the AST block, branch into two parallel processes (or a sequential pipeline):
- “Semantic Analyzer” – responsible for type-checking and validating constructs (using a visitor pattern).
- “Code Generator” – employing the visitor pattern to generate MLIR/SPIR-V code.
- That Code Generation is based on MLIR (reference “MLIRCodeGen”) and connects to the output module that produces the final SPIR-V dialect.
- Optionally, reference external dependencies (e.g., LLVM / MLIR if relevant, as seen in the “llvm-project” directory).

##### Architectural Patterns and Important Details
- Differentiate between “data transformation” components (lexer, parser, AST) and “analysis/transformation” components (semantic analysis and code generation).
- Clearly label external test frameworks, build configurations (CMake) and example projects that help in verifying each component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("Compiler Entry Point"):::entry
    B("GLSL Source Code"):::input
    C("Preprocessor"):::transform
    D("Lexer (Tokenization)"):::transform
    E("Parser (Recursive Descent Parsing)"):::transform
    F("Abstract Syntax Tree (AST)"):::transform
    G("Semantic Analyzer (VisitorPattern)"):::analysis
    H("Code Generator (MLIR/SPIR-V,VisitorPattern)"):::codegen
    I("SPIR-V MLIR Output"):::output
    J("Test Suites"):::test
    K("Build System & Examples"):::build

    A -->|"initiates"| B
    B -->|"feeds"| C
    C -->|"transforms to"| D
    D -->|"generates tokens for"| E
    E -->|"builds"| F
    F -->|"analyzes"| G
    F -->|"traversed by"| H
    G -->|"produces"| I
    H -->|"emits"| I

    %% Click Events
    click A "https://github.com/wpmed92/shaderpulse/blob/main/compiler/shaderpulse.cpp"
    click C "https://github.com/wpmed92/shaderpulse/tree/main/include/Preprocessor"
    click D "https://github.com/wpmed92/shaderpulse/tree/main/include/Lexer"
    click E "https://github.com/wpmed92/shaderpulse/tree/main/include/Parser"
    click F "https://github.com/wpmed92/shaderpulse/tree/main/include/AST"
    click G "https://github.com/wpmed92/shaderpulse/tree/main/include/Analysis"
    click H "https://github.com/wpmed92/shaderpulse/tree/main/include/CodeGen"
    click J "https://github.com/wpmed92/shaderpulse/tree/main/test"
    click K "https://github.com/wpmed92/shaderpulse/tree/main/example"

    %% Styles
    classDef entry fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef input fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef transform fill:#FFFACD,stroke:#333,stroke-width:1px;
    classDef analysis fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef codegen fill:#FFB6C1,stroke:#333,stroke-width:1px;
    classDef output fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef test fill:#AFEEEE,stroke:#333,stroke-width:1px;
    classDef build fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
