# nazaraengine/shaderlang architecture

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

- Interactive diagram: https://gitdiagram.com/nazaraengine/shaderlang
- Repository: https://github.com/nazaraengine/shaderlang

## Overview

##### Project type and purpose
- This is a **language compiler library** (NZSL) and related C‐API wrapper (CNZSL) for a custom shading language.
- It is designed to be embedded in host applications via a direct API rather than as a standalone CLI tool.

##### File structure (focused on direct API path, excluding examples, tests, CLI)
- Top‐level “include/NZSL” and “src/NZSL” – the core C++ implementation (lexer, parser, AST, passes, writers).
- “include/CNZSL” and “src/CNZSL” – a thin C API wrapper around the C++ library.
- “src/ShaderCompiler” and “src/ShaderArchiver” – CLI executables (to be ignored per instructions).
- Configuration: “xmake.lua” – build script (not part of runtime architecture).

##### README for additional insights
- The library exposes a C++ API: `nzsl::ParseFromFile`, `nzsl::GlslWriter`, `nzsl::SpirvWriter`.
- Processing stages: parse into AST, then generate GLSL or SPIR-V.
- Optional C API via CNZSL for C applications.

##### Main components
a. Application (host engine or tool)
b. C++ API façade (`nzsl::Parser`, `nzsl::GlslWriter`, `nzsl::SpirvWriter`)
c. C API wrapper (CNZSL) – optional, if the application is C-based
d. Core language front-end
- Lexer & Tokenizer
- Parser → AST
- ModuleResolver (filesystem-based)
e. AST transformation & analysis passes
- DependencyChecker
- ConstantPropagation
- EliminateUnused
- SanitizeVisitor
- (other visitors: ReflectVisitor, IndexRemapper, etc.)
f. Writers (back-ends)
- `GlslWriter` → GLSL source code
- `SpirvWriter` → SPIR-V bytecode vector<uint32_t>
g. Outputs
- Textual GLSL code (string or file)
- SPIR-V binary blob

##### Relationships and interactions
- **Application** calls the **Parser** API (or via C wrapper) to load/parse a .nzsl file.
- Parser uses **Lexer** → produces tokens → **Parser** → builds raw AST.
- After parsing, the AST is handed off to a sequence of **visitors/passes**, each mutating or validating the AST.
- The final AST is then fed to a **Writer** (GLSL or SPIR-V), which may traverse the AST again with specialized visitors (e.g., SpirvAstVisitor).
- The **Writer** returns its output to the application (string or binary).

##### Architectural patterns and design principles
- **Modular front-end/back-end** separation: parsing & analysis vs. code generation.
- **Visitor pattern** for AST transformations and back-end traversal.
- **Facade/API façade** (nzsl namespace) exposing simple entry points.
- **Wrapper layer** (CNZSL) to expose C ABI while reusing C++ core.

##### Technologies, frameworks, or libraries
- C++17 (core library)
- CNZSL (C wrapper)
- No external dependencies for parsing or codegen

7. Major component with the corresponding source folder (e.g., “include/NZSL/Parser.hpp & src/NZSL/Parser.cpp”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    HostApp["Host Application"]:::external

    subgraph "API Layer"
        Parser["nzsl::Parser"]:::api
        GlslAPI["nzsl::GlslWriter"]:::api
        SpirvAPI["nzsl::SpirvWriter"]:::api
    end

    subgraph "C API (optional)"
        CNZSL["CNZSL"]:::api
    end

    subgraph "Front-End"
        Lexer["Lexer & Tokenizer"]:::frontend
        RawParser["Parser (raw AST)"]:::frontend
        ModuleResolver["ModuleResolver"]:::frontend
    end

    subgraph "AST Analysis Passes"
        Dep["DependencyChecker"]:::passes
        Const["ConstantPropagation"]:::passes
        Elim["EliminateUnused"]:::passes
        San["SanitizeVisitor"]:::passes
        Ref["ReflectVisitor"]:::passes
        Index["IndexRemapper"]:::passes
    end

    subgraph "Writers"
        Glsl["GlslWriter"]:::backend
        Spirv["SpirvWriter"]:::backend
    end

    HostApp -->|"calls C++ API"| Parser
    HostApp -.->|"calls C API"| CNZSL
    CNZSL -->|"wraps to C++"| Parser

    Parser -->|"TokenList"| Lexer
    Lexer -->|"tokens"| RawParser
    RawParser -->|"Ast::ModulePtr"| ModuleResolver
    ModuleResolver -->|"resolved modules"| RawParser

    RawParser --> Dep
    Dep --> Const
    Const --> Elim
    Elim --> San
    San --> Ref
    Ref --> Index

    Index --> Glsl
    Index --> Spirv

    Glsl -->|"string/GLSL"| GLSLOut["GLSL Code (string/file)"]
    Spirv -->|"vector<uint32_t>"| SPVOut["SPIR-V Binary"]

    click Parser "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Parser.hpp"
    click GlslAPI "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/GlslWriter.hpp"
    click SpirvAPI "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/SpirvWriter.hpp"
    click CNZSL "https://github.com/nazaraengine/shaderlang/tree/main/include/CNZSL/"
    click Lexer "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Lexer.hpp"
    click ModuleResolver "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/FilesystemModuleResolver.hpp"
    click Dep "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Ast/DependencyCheckerVisitor.hpp"
    click Const "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Ast/ConstantPropagationVisitor.hpp"
    click Elim "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Ast/EliminateUnusedPassVisitor.hpp"
    click San "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Ast/SanitizeVisitor.hpp"
    click Ref "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Ast/ReflectVisitor.hpp"
    click Index "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/Ast/IndexRemapperVisitor.hpp"
    click Glsl "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/GlslWriter.hpp"
    click Spirv "https://github.com/nazaraengine/shaderlang/blob/main/include/NZSL/SpirvWriter.hpp"

    classDef frontend fill:#D0E4F5,stroke:#333
    classDef passes fill:#F9E79F,stroke:#333
    classDef backend fill:#ABEBC6,stroke:#333
    classDef api fill:#D2B4DE,stroke:#333
    classDef external fill:#BBBDC1,stroke:#333
```
