Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

18.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ShaderParser.hpp
 * @brief   Parser for unified .esshader file format
 * @details Parses single-file shader format containing multiple stages
 *          (vertex, fragment) with optional properties and platform variants.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

// =============================================================================
// Includes
// =============================================================================

#include "../core/Types.hpp"

#include <functional>
#include <optional>
#include <string>
#include <vector>
#include <unordered_map>

namespace esengine::resource {

// =============================================================================
// Include Resolver
// =============================================================================

/**
 * @brief Resolves an #include path to its file contents.
 *
 * Return std::nullopt to signal "not found" — the parser will report a
 * descriptive error. Resolvers are free to cache, normalize paths, or
 * delegate to a virtual filesystem.
 */
using ShaderIncludeResolver = std::function<std::optional<std::string>(const std::string&)>;

// =============================================================================
// Source Line Mapping
// =============================================================================

/**
 * @brief A (file, line) pair identifying an original source location.
 *
 * Empty `file` denotes the primary shader source (the one passed directly
 * to parse()); non-empty names an #included file.
 */
struct SourceLine {
    std::string file;
    u32 line = 0;
};

// =============================================================================
// Shader Stage Enum
// =============================================================================

/**
 * @brief Target language for stage assembly (REARCH_WGSL dual emission).
 * @details Both languages assemble from one ParsedShader: GLSL stages carry the
 *          authored GLSL bodies; WGSL stages carry the file's `#pragma vertex
 *          wgsl` / `#pragma fragment wgsl` twin sections. The injected headers
 *          (TimeConstants/MaterialConstants/texture params/Lit) and the
 *          canonical 2D vertex stage are emitted per language.
 */
enum class ShaderTargetLanguage : u8 {
    GLSL_ES300 = 0,
    WGSL       = 1,
};

enum class ShaderStage : u8 {
    Vertex,
    Fragment
};

// =============================================================================
// Shader Property
// =============================================================================

enum class ShaderPropertyType : u8 {
    Float,
    Vec2,
    Vec3,
    Vec4,
    Color,
    Int,
    Texture,
    Unknown
};

struct ShaderProperty {
    std::string name;                     ///< Uniform name
    ShaderPropertyType type;              ///< Property type
    std::string defaultValue;             ///< Default value as string (comma-separated for vectors)
    std::string displayName;              ///< Display name for editor

    /// True when declared via `#pragma param` (the modern path: ShaderParser owns the GLSL
    /// codegen + std140 layout). False for the legacy `#pragma properties` block, which is
    /// reflection-only — the shader declares those uniforms itself, so they are not codegen'd.
    bool fromParam = false;

    /// Byte offset of this param inside the std140 MaterialConstants block, or -1 for
    /// texture params (which are samplers, not block members).
    i32 std140Offset = -1;
    /// Sampler unit for a texture param (>= MATERIAL_TEXTURE_UNIT_BASE), or -1 otherwise.
    i32 textureUnit = -1;
    /// A texture param declared `textureArray`: a 2D texture array, declared `sampler2DArray` /
    /// `texture_2d_array<f32>` and sampled with a layer index. Everything else is as for `texture`.
    bool layered = false;

    /// Optional editor metadata (range slider bounds, UI hint). Drives the inspector panel;
    /// not used in codegen. hasRange == false leaves the field a plain numeric input.
    bool hasRange = false;
    f32 rangeMin = 0.0f;
    f32 rangeMax = 1.0f;
    std::string ui;                       ///< UI hint, e.g. "slider", "color" (free-form).
    /// `unit(length)` (1) or `unit(perLength)` (-1): the default and range are written at 100 world units a metre and
    /// follow the project's units per metre where a material leaves the param unset. 0 is a plain number.
    i8 worldUnits = 0;
};

/**
 * @brief A material-controlled static switch (#pragma switch): a boolean the material sets,
 *        selecting a compile-time shader permutation via a #define. Distinct from #pragma
 *        feature (an engine-chosen variant keyword) only in being material-facing + defaulted.
 */
struct ShaderSwitch {
    std::string name;
    bool defaultOn = false;
};

// =============================================================================
// Parsed Shader
// =============================================================================

/**
 * @brief Result of parsing an .esshader file
 *
 * @details Contains all extracted information from a unified shader file
 *          including stages, properties, and platform variants.
 */
struct ParsedShader {
    std::string name;                                         ///< Shader name
    std::string version;                                      ///< GLSL version
    std::string sharedCode;                                   ///< Code shared by all stages
    std::unordered_map<ShaderStage, std::string> stages;      ///< Stage source code
    std::unordered_map<std::string, std::string> variants;    ///< Platform variants
    std::vector<std::string> features;                        ///< Declared #pragma feature keywords (compile-time variants)
    /// `#pragma lighting direct`: compiled with ES_LIGHT_DIRECT. Lit by the sixteen lights of the block and hard-edged shadows only, without what most scenes never
    /// reach and every pixel pays for regardless (on a phone, a third of a water's frame): the tiled lights, the 2D light masks, the soft and hair shadows.
    bool lightingDirect = false;
    std::vector<ShaderSwitch> switches;                       ///< Material-controlled #pragma switch toggles (name + default)
    std::vector<ShaderProperty> properties;                   ///< Exposed material params (#pragma param / properties block)
    std::string domain = "Unlit";                           ///< #pragma domain (Unlit/Lit/PostProcess/UI)
    /// `#pragma coverage <param>`: while that float param is above zero, the shader's
    /// output alpha is coverage (a cutout sharpened to one texel), so an opaque draw
    /// may turn it into multisample coverage instead of a hard edge.
    std::string coverageParam;
    /// `#pragma tips <param>`: while that float param is above zero, the shader draws a second, blended
    /// pass (compiled with ES_TIP_PASS) over the opaque one: the soft outer band of a cutout that
    /// coverage alone would stair-step.
    std::string tipParam;
    /// `#pragma hairshadow <param>`: while that float param is above zero, meshes drawn with the material are hair —
    /// the frame fits a shadow cascade to them alone (so their layers are not lost in a texel of the view's own
    /// cascades), and the shader reads the shadow as a density along the light (a strand layer lets part of the
    /// light through) in place of a hard compare. The value is the density, in opacity per world unit.
    std::string hairShadowParam;
    /// `#pragma gbuffer`: a post-process shader reads the scene's surface record (normal, roughness,
    /// metalness) at unit kGBufferUnit, so the frame must draw one for it.
    bool usesGBuffer = false;
    /// `#pragma lights`: a post-process shader reads the frame's light block — which light is the sun, where it
    /// stands, and (through `sunVisibility`) whether the shadow map says a point of air is lit — so the pipeline
    /// binds the block and the shadow atlas for it.
    bool usesLights = false;
    /// `#pragma highprecision`: what this post-process shader writes is a measurement, not a picture, so its target is
    /// a float one whenever the device can render to one — even in a chain of 8-bit pictures.
    bool highPrecision = false;
    /// `#pragma vertexoffset`: the body of `esMaterialVertex(inout local, inout localNormal, uv)`,
    /// run on a resident mesh's local-space vertex before it is posed and placed. It is the
    /// material's own, so the canonical mesh vertex stage calls it and a material without one
    /// assembles exactly as before. The WGSL twin takes pointers instead of `inout`.
    std::string vertexHook;
    std::string wgslVertexHook;
    /// `#pragma vertexbounds <units>`: how far the hook can move a vertex from the mesh's own
    /// bounds, in the mesh's local units — what culling must grow its box by so a bent mesh is not
    /// dropped while still visible. Zero when the material has no hook.
    float vertexBounds = 0.0f;
    /// std140 byte size of the generated MaterialConstants block (16-aligned), 0 if no
    /// non-texture params. The render path sizes the per-material UBO to this.
    u32 materialBlockSize = 0;
    std::string errorMessage;                                 ///< Parse error if any
    bool valid = false;                                       ///< True if parsing succeeded

    /**
     * @brief Line map for the expanded pre-parse source.
     *
     * expandedLineMap[i] is the original SourceLine that produced line
     * (i + 1) of the post-#include-expansion source. Callers that know
     * the expanded-source line of a compile error can resolve it back
     * to the original file.
     */
    std::vector<SourceLine> expandedLineMap;

    /**
     * @brief Per-stage line maps, parallel to stages[].
     *
     * Entry N is the SourceLine for line (N + 1) of the stage body (the
     * code between `#pragma vertex`/`#pragma fragment` and `#pragma end`,
     * not including the assembled `#version`/sharedCode prefix).
     */
    std::unordered_map<ShaderStage, std::vector<SourceLine>> stageLineMaps;

    /**
     * @brief WGSL twin stage bodies (`#pragma vertex wgsl` / `#pragma fragment
     *        wgsl` sections), keyed like stages[].
     *
     * A 2D-domain shader with a WGSL fragment but no WGSL vertex gets the
     * canonical 2D vertex injected here at parse (wgslVertexIsCanonical).
     * An empty map means the shader has no WGSL twin: assembling for the WGSL
     * target reports a descriptive error.
     */
    std::unordered_map<ShaderStage, std::string> wgslStages;

    /** @brief Line maps for wgslStages, same convention as stageLineMaps. */
    std::unordered_map<ShaderStage, std::vector<SourceLine>> wgslStageLineMaps;

    /**
     * @brief Stages whose WGSL twin is a SELF-CONTAINED program (`#pragma vertex
     *        wgsl full` / `#pragma fragment wgsl full`): assembly skips every
     *        injected header — the body carries its own declarations at the
     *        engine's binding conventions (group 0 UBO slots, group-1
     *        texture/sampler unit map). The shape a cook-time GLSL→WGSL
     *        conversion emits, since a translator returns whole programs.
     */
    std::unordered_map<ShaderStage, bool> wgslStageFull;

    /**
     * @brief True when the WGSL vertex stage is the injected canonical one.
     *        The WGSL fragment assembly then also injects the matching VSOut
     *        struct, so fragment-only twins write `fs_main(v : VSOut)` against
     *        an engine-owned interface. Authored twin pairs declare their own.
     */
    bool wgslVertexIsCanonical = false;

    /**
     * @brief True when the GLSL vertex stage is the injected canonical one.
     * @details Only then does the engine decide how a vertex reaches clip space,
     *          which is what lets a material be compiled for a second vertex
     *          source (MESH). A shader that writes its own vertex stage owns
     *          that decision and cannot be retargeted behind its back.
     */
    bool vertexIsCanonical = false;
};

// =============================================================================
// ShaderParser Class
// =============================================================================

/**
 * @brief Parser for .esshader unified shader format
 *
 * @details Parses shader files that contain multiple stages in a single file.
 *          Uses #pragma directives to separate sections.
 *
 * File format:
 * @code
 * #pragma shader "MyShader"
 * #pragma version 300 es
 *
 * #pragma properties
 * uniform sampler2D u_texture;  // @property(type=texture)
 * #pragma end
 *
 * #pragma vertex
 * // vertex shader code (GLSL)
 * #pragma end
 *
 * #pragma fragment
 * // fragment shader code (GLSL)
 * #pragma end
 *
 * #pragma fragment wgsl
 * // WGSL twin of the fragment stage (assembled for the WGSL target;
 * // fragment-only 2D shaders get the canonical WGSL vertex + VSOut injected)
 * #pragma end
 * @endcode
 */
class ShaderParser {
public:
    /**
     * @brief Parses shader source into structured format (no include support)
     * @param source The complete .esshader file content
     * @return Parsed shader data with valid flag indicating success
     */
    static ParsedShader parse(const std::string& source);

    /**
     * @brief Parses shader source with #include "path" expansion
     * @param source The complete .esshader file content
     * @param resolver Callback used to fetch included file contents
     * @return Parsed shader data with valid flag indicating success
     */
    static ParsedShader parse(const std::string& source,
                              const ShaderIncludeResolver& resolver);

    /**
     * @brief Assembles final GLSL source for a specific stage
     * @param parsed The parsed shader data
     * @param stage The shader stage to assemble
     * @param platform Platform variant name (empty for default)
     * @param features Feature keywords to enable; each is injected as `#define <name> 1`
     *                 right after `#version`, so shaders can `#ifdef` compile-time variants.
     * @return Complete GLSL source ready for compilation
     */
    static std::string assembleStage(const ParsedShader& parsed,
                                     ShaderStage stage,
                                     const std::string& platform = "",
                                     const std::vector<std::string>& features = {},
                                     ShaderTargetLanguage target = ShaderTargetLanguage::GLSL_ES300);

    /**
     * @brief The WGSL varying struct the engine's vertex stage emits for @p parsed,
     *        or empty when the shader writes its own vertex stage.
     * @details A fragment twin generated for a shader on the engine's vertex stage
     *          reads its inputs at these locations, so every vertex source the
     *          engine retargets the material to feeds the same fragment.
     */
    static std::string canonicalVaryingsWGSL(const ParsedShader& parsed);

    /**
     * @brief Stable cache key for a feature set (order-independent), e.g. "GRAYSCALE|TINT".
     *        Consumers key their compiled-variant cache on (shader, variantKey(features)).
     */
    static std::string variantKey(const std::vector<std::string>& features);

    /**
     * @brief Split a comma-separated feature/switch list into trimmed, non-empty
     *        entries — the form the boundary carries a permutation in.
     */
    static std::vector<std::string> splitFeatures(const std::string& csv);

    /**
     * @brief Process-global color-space mode. When linear, every assembled
     *        stage compiles with ES_LINEAR defined (GLSL #define / WGSL
     *        assembly-time preprocessor). Set BEFORE the renderer compiles
     *        shaders; flipping later requires a reload. Variant caches must
     *        fold linearColorSpace() into their keys if they can outlive a flip.
     */
    static void setLinearColorSpace(bool linear);
    static bool linearColorSpace();

    /**
     * @brief Like assembleStage, but also reports the line count of the
     *        assembled prefix (version + variant + sharedCode).
     *
     * Stage body starts at output line (headerLineCount + 1); pass
     * headerLineCount to remapCompilerLog as its `headerLineOffset`
     * so GL log line numbers can be translated back to the original file.
     */
    struct AssembledStage {
        std::string source;
        u32 headerLineCount = 0;
    };

    static AssembledStage assembleStageEx(const ParsedShader& parsed,
                                          ShaderStage stage,
                                          const std::string& platform = "",
                                          const std::vector<std::string>& features = {},
                                          ShaderTargetLanguage target = ShaderTargetLanguage::GLSL_ES300);

    /**
     * @brief Rewrites GL compile-log line references back to original files
     *
     * Scans @p log for `0:N:` and `0(N)` patterns (the two common vendor
     * prefixes) and rewrites each occurrence to `file:origLine:`. Lines
     * before @p headerLineOffset are treated as synthetic header (e.g.
     * `#version`, sharedCode) and left unchanged.
     *
     * @param log GL driver log (from glGetShaderInfoLog / glGetProgramInfoLog)
     * @param stageMap Per-stage line map from ParsedShader::stageLineMaps
     * @param headerLineOffset Line count prepended by assembleStage before
     *        the stage body (typically 1 for `#version` + sharedCode line
     *        count)
     * @return Log with line references rewritten to original locations
     */
    static std::string remapCompilerLog(const std::string& log,
                                        const std::vector<SourceLine>& stageMap,
                                        u32 headerLineOffset);

private:
    static void parseDirective(const std::string& line,
                              std::string& directive,
                              std::string& argument);

    /// Parses a `#pragma param <name> <type> [default(..)] [range(min,max)] [ui(..)]` line.
    static ShaderProperty parseParamDirective(const std::string& argument);

    /// Assigns std140 offsets to non-texture params and sampler units to texture params,
    /// and sets ParsedShader::materialBlockSize. Run once after all params are collected.
    static void computeMaterialLayout(ParsedShader& shader);

public:
    /// The units below the material base a texture param may take on @p shader (a mask): the ones it never reads from the engine.
    static u32 materialOverflowUnits(const ParsedShader& shader);

private:
    /// Takes the highest unit left in @p free, or -1.
    static i32 takeOverflowUnit(u32& free);

    static ShaderProperty parsePropertyAnnotation(const std::string& line);

    static ShaderPropertyType stringToPropertyType(const std::string& typeStr);

    static std::string trim(const std::string& str);

private:
    static bool s_linearColor;

};

}  // namespace esengine::resource