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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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