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.

feat(render): shader feature-variant system (#pragma feature -> #define) — REARCH_RENDER RC7-6 variants

esengine5cd21c7070f2
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index c20acd84c..a901c9663 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -158,6 +158,13 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
continue;
}
+ if (directive == "feature") {
+ // Declares a compile-time variant keyword. Self-documenting; the consumer
+ // chooses which features to enable and assembleStage injects their #defines.
+ if (!argument.empty()) result.features.push_back(argument);
+ continue;
+ }
+
if (directive == "properties") {
if (state != ParseState::Global) {
result.errorMessage = "Unexpected #pragma properties at line " + std::to_string(lineNumber);
@@ -282,8 +289,20 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
std::string ShaderParser::assembleStage(const ParsedShader& parsed,
ShaderStage stage,
- const std::string& platform) {
- return assembleStageEx(parsed, stage, platform).source;
+ const std::string& platform,
+ const std::vector<std::string>& features) {
+ return assembleStageEx(parsed, stage, platform, features).source;
+}
+
+std::string ShaderParser::variantKey(const std::vector<std::string>& features) {
+ std::vector<std::string> sorted(features);
+ std::sort(sorted.begin(), sorted.end());
+ std::string key;
+ for (const auto& f : sorted) {
+ if (!key.empty()) key += '|';
+ key += f;
+ }
+ return key;
}
namespace {
@@ -300,7 +319,8 @@ u32 countNewlines(const std::string& s) {
ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& parsed,
ShaderStage stage,
- const std::string& platform) {
+ const std::string& platform,
+ const std::vector<std::string>& features) {
AssembledStage result;
if (!parsed.valid) return result;
@@ -316,6 +336,14 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
++headerLines;
}
+ // Feature #defines go right after #version (GLSL requires #version first), so the
+ // shader body can #ifdef compile-time variants. Counted into headerLines so the
+ // compile-log line remap stays accurate.
+ for (const auto& f : features) {
+ assembled << "#define " << f << " 1\n";
+ ++headerLines;
+ }
+
if (!platform.empty()) {
auto variantIt = parsed.variants.find(platform);
if (variantIt != parsed.variants.end()) {
diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hpp
index 613aa0232..4965988c9 100644
--- a/src/esengine/resource/ShaderParser.hpp
+++ b/src/esengine/resource/ShaderParser.hpp
@@ -101,6 +101,7 @@ struct ParsedShader {
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)
std::vector<ShaderProperty> properties; ///< Exposed properties
std::string errorMessage; ///< Parse error if any
bool valid = false; ///< True if parsing succeeded
@@ -176,11 +177,20 @@ public:
* @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::string& platform = "",
+ const std::vector<std::string>& features = {});
+
+ /**
+ * @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 Like assembleStage, but also reports the line count of the
@@ -197,7 +207,8 @@ public:
static AssembledStage assembleStageEx(const ParsedShader& parsed,
ShaderStage stage,
- const std::string& platform = "");
+ const std::string& platform = "",
+ const std::vector<std::string>& features = {});
/**
* @brief Rewrites GL compile-log line references back to original files
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index e925aa8d3..c90c5e66c 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -59,6 +59,16 @@ target_include_directories(test_shader_device PRIVATE
)
add_test(NAME test_shader_device COMMAND test_shader_device)
+# Shader variant (feature-permutation) system (RC7-6). Compiles ShaderParser.cpp
+# directly — no GL/engine link — and checks #pragma feature parsing + #define injection.
+add_executable(test_shader_variant
+ renderer/test_shader_variant.cpp
+ ${CMAKE_SOURCE_DIR}/src/esengine/resource/ShaderParser.cpp
+ ${CMAKE_SOURCE_DIR}/src/esengine/core/Log.cpp
+)
+target_include_directories(test_shader_variant PRIVATE ${CMAKE_SOURCE_DIR}/src)
+add_test(NAME test_shader_variant COMMAND test_shader_variant)
+
# Texture + Framebuffer decoupling: compiles the converted classes against a
# MockGfxDevice. The harness stubs the (uncalled) stb file loader.
add_executable(test_texture_fb
diff --git a/tests/renderer/test_shader_variant.cpp b/tests/renderer/test_shader_variant.cpp
new file mode 100644
index 000000000..8260051a0
--- /dev/null
+++ b/tests/renderer/test_shader_variant.cpp
@@ -0,0 +1,68 @@
+// Native harness for the shader variant (feature-permutation) system (RC7-6).
+//
+// Compiles ShaderParser.cpp directly — no GL/engine link, so it runs on any C++20
+// toolchain — and asserts the compile-time variant mechanism: #pragma feature is
+// captured, requested features are injected as #define right after #version (so the
+// shader body can #ifdef them), and variantKey is an order-independent cache key.
+
+#include "esengine/resource/ShaderParser.hpp"
+
+#include <cstdio>
+#include <string>
+
+static int g_failures = 0;
+#define CHECK(cond, msg) \
+ do { \
+ if (!(cond)) { std::printf("FAIL: %s\n", msg); ++g_failures; } \
+ else { std::printf("ok: %s\n", msg); } \
+ } while (0)
+
+using namespace esengine::resource;
+
+static const char* SRC = R"(#pragma shader "VariantTest"
+#pragma version 300 es
+#pragma feature TINT
+
+#pragma vertex
+layout(location = 0) in vec2 a_pos;
+void main() { gl_Position = vec4(a_pos, 0.0, 1.0); }
+#pragma end
+
+#pragma fragment
+precision mediump float;
+out vec4 fragColor;
+void main() {
+#ifdef TINT
+ fragColor = vec4(1.0, 0.0, 0.0, 1.0);
+#else
+ fragColor = vec4(1.0);
+#endif
+}
+#pragma end
+)";
+
+int main() {
+ ParsedShader p = ShaderParser::parse(SRC);
+ CHECK(p.valid, "shader parses");
+ CHECK(p.features.size() == 1 && p.features[0] == "TINT", "#pragma feature TINT captured");
+
+ const std::string withTint = ShaderParser::assembleStage(p, ShaderStage::Fragment, "", {"TINT"});
+ CHECK(withTint.find("#version 300 es") != std::string::npos, "version emitted");
+ CHECK(withTint.find("#define TINT 1") != std::string::npos, "feature define injected when enabled");
+ CHECK(withTint.find("#version") < withTint.find("#define TINT"), "#version precedes the feature #define");
+
+ const std::string noTint = ShaderParser::assembleStage(p, ShaderStage::Fragment, "", {});
+ CHECK(noTint.find("#define TINT") == std::string::npos, "no feature define when disabled");
+
+ CHECK(ShaderParser::variantKey({"B", "A"}) == "A|B", "variantKey is sorted/joined");
+ CHECK(ShaderParser::variantKey({"A", "B"}) == ShaderParser::variantKey({"B", "A"}),
+ "variantKey is order-independent");
+ CHECK(ShaderParser::variantKey({}).empty(), "variantKey of no features is empty");
+
+ if (g_failures == 0) {
+ std::printf("\nALL SHADER-VARIANT TESTS PASSED\n");
+ return 0;
+ }
+ std::printf("\n%d FAILURE(S)\n", g_failures);
+ return 1;
+}