How nazaraengine/shaderlang works
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”).