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.

refactor(render): one declaration of the frame block

esengine9f65ec567e80
diff --git a/desktop/public/scenes/mat-graph/graph-tint.esshader b/desktop/public/scenes/mat-graph/graph-tint.esshader
index d6bccf5db..ef852a3ce 100644
--- a/desktop/public/scenes/mat-graph/graph-tint.esshader
+++ b/desktop/public/scenes/mat-graph/graph-tint.esshader
@@ -10,10 +10,6 @@ layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
layout(location = 3) in float a_texIndex;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
out vec2 v_texCoord;
diff --git a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader
index 278e11436..e0c5a7a58 100644
--- a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader
+++ b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader
@@ -9,10 +9,6 @@ layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
layout(location = 3) in float a_texIndex;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
out vec2 v_texCoord;
out highp vec2 v_worldPos;
diff --git a/desktop/public/scenes/mat-lit-normal/lit-normal.esshader b/desktop/public/scenes/mat-lit-normal/lit-normal.esshader
index d91de9439..2e9b043ad 100644
--- a/desktop/public/scenes/mat-lit-normal/lit-normal.esshader
+++ b/desktop/public/scenes/mat-lit-normal/lit-normal.esshader
@@ -9,10 +9,6 @@ layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
layout(location = 3) in float a_texIndex;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
out vec2 v_texCoord;
out highp vec2 v_worldPos;
diff --git a/desktop/public/scenes/mat-lit/lit.esshader b/desktop/public/scenes/mat-lit/lit.esshader
index 85b028225..2aa32dc2b 100644
--- a/desktop/public/scenes/mat-lit/lit.esshader
+++ b/desktop/public/scenes/mat-lit/lit.esshader
@@ -8,6 +8,9 @@ layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
layout(location = 3) in float a_texIndex;
+// Deliberately still declared by hand, though the engine now injects this block:
+// a shader written before that keeps compiling, and the pixel criteria this
+// fixture backs are what proves it.
layout(std140) uniform FrameConstants {
mat4 u_projection;
};
diff --git a/desktop/public/scenes/mat-sw/switched.esshader b/desktop/public/scenes/mat-sw/switched.esshader
index 403d8d68c..c665ed7ba 100644
--- a/desktop/public/scenes/mat-sw/switched.esshader
+++ b/desktop/public/scenes/mat-sw/switched.esshader
@@ -9,10 +9,6 @@ layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
layout(location = 3) in float a_texIndex;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
void main() {
diff --git a/desktop/public/scenes/mat-tex/masked.esshader b/desktop/public/scenes/mat-tex/masked.esshader
index f7562f88f..1b78dc9b4 100644
--- a/desktop/public/scenes/mat-tex/masked.esshader
+++ b/desktop/public/scenes/mat-tex/masked.esshader
@@ -9,10 +9,6 @@ layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
layout(location = 3) in float a_texIndex;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
out vec2 v_texCoord;
diff --git a/desktop/public/scenes/mat-tint/tint.esshader b/desktop/public/scenes/mat-tint/tint.esshader
index a44463eb8..a26150205 100644
--- a/desktop/public/scenes/mat-tint/tint.esshader
+++ b/desktop/public/scenes/mat-tint/tint.esshader
@@ -9,10 +9,6 @@ layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
layout(location = 3) in float a_texIndex;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
out vec2 v_texCoord;
@@ -41,9 +37,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn {
@location(0) a_position : vec3f,
@location(1) a_color : vec4f,
diff --git a/sdk/src/camera/editorGridRenderer.ts b/sdk/src/camera/editorGridRenderer.ts
index 0233808d8..211d76dc3 100644
--- a/sdk/src/camera/editorGridRenderer.ts
+++ b/sdk/src/camera/editorGridRenderer.ts
@@ -49,10 +49,6 @@ export const GRID_ESSHADER = `#pragma shader "EditorGrid"
#pragma vertex
layout(location = 0) in vec2 a_position;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec2 v_world;
void main() {
@@ -106,9 +102,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn { @location(0) a_position : vec2f };
struct VSOut {
@builtin(position) pos : vec4f,
diff --git a/src/esengine/data/shaders/batch.esshader b/src/esengine/data/shaders/batch.esshader
index fb6dc84dc..d00909dca 100644
--- a/src/esengine/data/shaders/batch.esshader
+++ b/src/esengine/data/shaders/batch.esshader
@@ -26,10 +26,6 @@ layout(location = 3) in float a_texIndex;
layout(location = 4) in float a_sdfBias;
#endif
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
out vec2 v_texCoord;
flat out int v_texIndex;
@@ -121,9 +117,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn {
@location(0) a_position : vec3f,
@location(1) a_color : vec4f,
diff --git a/src/esengine/data/shaders/mesh.esshader b/src/esengine/data/shaders/mesh.esshader
index 99d56fccf..8d356b0dc 100644
--- a/src/esengine/data/shaders/mesh.esshader
+++ b/src/esengine/data/shaders/mesh.esshader
@@ -62,10 +62,6 @@ layout(location = 14) in vec3 a_nrm1;
layout(location = 15) in vec3 a_nrm2;
#endif
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
#ifdef SKINNED
// This draw's pose, rewritten immediately before it (SkinConstants, binding 5).
layout(std140) uniform SkinConstants {
@@ -144,9 +140,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
#ifdef SKINNED
struct SkinConstants { bones : array<mat4x4f, 64> };
@group(0) @binding(5) var<uniform> skin : SkinConstants;
diff --git a/src/esengine/data/shaders/particle.esshader b/src/esengine/data/shaders/particle.esshader
index f79aa1bac..992f6a00f 100644
--- a/src/esengine/data/shaders/particle.esshader
+++ b/src/esengine/data/shaders/particle.esshader
@@ -12,10 +12,6 @@ layout(location = 5) in vec4 a_inst_color;
layout(location = 6) in vec2 a_inst_uv_offset;
layout(location = 7) in vec2 a_inst_uv_scale;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec2 v_texCoord;
out vec4 v_color;
@@ -54,9 +50,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn {
@location(0) a_position : vec2f,
@location(1) a_texCoord : vec2f,
diff --git a/src/esengine/data/shaders/shape.esshader b/src/esengine/data/shaders/shape.esshader
index 82ff145c9..a81b8e4b8 100644
--- a/src/esengine/data/shaders/shape.esshader
+++ b/src/esengine/data/shaders/shape.esshader
@@ -7,10 +7,6 @@ layout(location = 1) in vec2 a_texCoord;
layout(location = 2) in vec4 a_color;
layout(location = 3) in vec4 a_shapeInfo;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec2 v_uv;
out vec4 v_color;
out vec4 v_shapeInfo;
@@ -62,9 +58,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn {
@location(0) a_position : vec2f,
@location(1) a_texCoord : vec2f,
diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
index 98e6da132..fefb4a094 100644
--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
@@ -30,10 +30,6 @@ layout(location = 3) in float a_texIndex;
layout(location = 4) in float a_sdfBias;
#endif
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec4 v_color;
out vec2 v_texCoord;
flat out int v_texIndex;
@@ -125,9 +121,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn {
@location(0) a_position : vec3f,
@location(1) a_color : vec4f,
@@ -335,10 +328,6 @@ layout(location = 14) in vec3 a_nrm1;
layout(location = 15) in vec3 a_nrm2;
#endif
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
#ifdef SKINNED
// This draw's pose, rewritten immediately before it (SkinConstants, binding 5).
layout(std140) uniform SkinConstants {
@@ -417,9 +406,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
#ifdef SKINNED
struct SkinConstants { bones : array<mat4x4f, 64> };
@group(0) @binding(5) var<uniform> skin : SkinConstants;
@@ -542,10 +528,6 @@ layout(location = 5) in vec4 a_inst_color;
layout(location = 6) in vec2 a_inst_uv_offset;
layout(location = 7) in vec2 a_inst_uv_scale;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec2 v_texCoord;
out vec4 v_color;
@@ -584,9 +566,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn {
@location(0) a_position : vec2f,
@location(1) a_texCoord : vec2f,
@@ -649,10 +628,6 @@ layout(location = 1) in vec2 a_texCoord;
layout(location = 2) in vec4 a_color;
layout(location = 3) in vec4 a_shapeInfo;
-layout(std140) uniform FrameConstants {
- mat4 u_projection;
-};
-
out vec2 v_uv;
out vec4 v_color;
out vec4 v_shapeInfo;
@@ -704,9 +679,6 @@ void main() {
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
-
struct VSIn {
@location(0) a_position : vec2f,
@location(1) a_texCoord : vec2f,
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 9950fc40e..b47ee2db4 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -117,15 +117,11 @@ std::string wgslCanonicalVSOut(bool lit) {
return src;
}
-// WGSL twin of canonical2DVertexStage: same attribute locations, FrameConstants
-// at group 0 binding 0, GLSL names kept behind struct fields (a_position ->
-// v.a_position) so the two stages diff cleanly.
+// WGSL twin of canonical2DVertexStage: same attribute locations, GLSL names
+// kept behind struct fields (a_position -> v.a_position) so the two stages diff
+// cleanly. FrameConstants arrives with the injected headers.
std::string canonical2DVertexStageWGSL(bool lit) {
- std::string src =
- "struct FrameConstants { projection : mat4x4f };\n"
- "@group(0) @binding(0) var<uniform> frame : FrameConstants;\n"
- "\n";
- src += wgslCanonicalVSOut(lit);
+ std::string src = wgslCanonicalVSOut(lit);
src +=
"\n"
"struct VSIn {\n"
@@ -244,10 +240,6 @@ std::string canonical2DVertexStage(bool lit) {
"layout(location = 15) in vec3 a_nrm2;\n"
"#endif\n"
"\n"
- "layout(std140) uniform FrameConstants {\n"
- " mat4 u_projection;\n"
- "};\n"
- "\n"
"out vec4 v_color;\n"
"out vec2 v_texCoord;\n"
"#ifdef MESH_NORMALS\n"
@@ -631,6 +623,10 @@ const char* wgslTypeName(ShaderPropertyType t) {
// Engine-owned frame block (u_time / u_viewport), binding 3 — the GLSL
// kTimeHeader's twin. Injected into every WGSL stage; the device's explicit
// layouts make a declared-but-unused block legal, same as GL.
+const char* kFrameHeaderWGSL =
+ "struct FrameConstants { projection : mat4x4f };\n"
+ "@group(0) @binding(0) var<uniform> frame : FrameConstants;\n";
+
const char* kTimeHeaderWGSL =
"struct TimeConstants { u_time : vec4f, u_viewport : vec4f };\n"
"@group(0) @binding(3) var<uniform> tc : TimeConstants;\n";
@@ -800,6 +796,33 @@ fn applyLighting2D(albedo : vec3f, N : vec3f, worldPos : vec2f) -> vec3f {
}
)";
+// Blanks a hand-written `layout(std140) uniform <block> {...};` out of a GLSL
+// stage: shaders predating the injected block still carry their own, and one
+// block declared twice never links. Blanked (not cut) so line remapping lands.
+std::string blankUniformBlock(const std::string& src, const std::string& blockName) {
+ const std::string needle = "uniform " + blockName;
+ const usize at = src.find(needle);
+ if (at == std::string::npos) return src;
+
+ const usize lineStart = src.rfind('\n', at) == std::string::npos ? 0 : src.rfind('\n', at) + 1;
+ // Only a declaration counts: the same words inside a comment must survive.
+ const std::string prefix = src.substr(lineStart, at - lineStart);
+ if (prefix.find_first_not_of(" \t") != std::string::npos
+ && prefix.find("layout") == std::string::npos) {
+ return src;
+ }
+ const usize open = src.find('{', at);
+ if (open == std::string::npos) return src;
+ const usize close = src.find("};", open);
+ if (close == std::string::npos) return src;
+
+ std::string out = src;
+ for (usize i = lineStart; i < close + 2; ++i) {
+ if (out[i] != '\n') out[i] = ' ';
+ }
+ return out;
+}
+
std::string trimWs(const std::string& s) {
const usize a = s.find_first_not_of(" \t\r\n");
if (a == std::string::npos) return {};
@@ -914,6 +937,7 @@ ShaderParser::AssembledStage assembleWGSLStage(const ParsedShader& parsed,
inject(parsed.domain == "PostProcess" ? wgslPPVSOut() : wgslCanonicalVSOut(lit));
inject(wgslBatchTextureDecls());
}
+ inject(kFrameHeaderWGSL);
inject(kTimeHeaderWGSL);
if (parsed.materialBlockSize > 0) {
std::string block = "struct MaterialConstants {\n";
@@ -1000,6 +1024,16 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
headerLines += countNewlines(kColorHelpers);
}
+ // The per-frame view-projection, injected identically into every stage (a block
+ // declared two ways does not link) and engine-owned, so it cannot drift from the
+ // std140 mirror in FrameConstants.hpp. highp: fragment has no default this early.
+ static const char* kFrameHeader =
+ "layout(std140) uniform FrameConstants {\n"
+ " highp mat4 u_projection;\n"
+ "};\n";
+ assembled << kFrameHeader;
+ headerLines += countNewlines(kFrameHeader);
+
// Engine-owned frame block, injected into every stage (identical in both, so the
// program links). u_time = (elapsed s, delta s, 0, 0); u_viewport = canvas
// (w, h, 1/w, 1/h) in pixels; binding 3 (Shader::compile).
@@ -1199,7 +1233,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
headerLines += countNewlines(parsed.sharedCode);
}
- assembled << stageIt->second;
+ assembled << blankUniformBlock(stageIt->second, "FrameConstants");
result.source = assembled.str();
result.headerLineCount = headerLines;
diff --git a/tests/renderer/test_shader_variant.cpp b/tests/renderer/test_shader_variant.cpp
index 54ef19c1c..aa7840679 100644
--- a/tests/renderer/test_shader_variant.cpp
+++ b/tests/renderer/test_shader_variant.cpp
@@ -7,6 +7,7 @@
#include "esengine/resource/ShaderParser.hpp"
+#include <algorithm>
#include <cstdio>
#include <string>
@@ -169,8 +170,6 @@ void main() { fragColor = vec4(1.0); }
#pragma end
#pragma vertex wgsl
-struct FrameConstants { projection : mat4x4f };
-@group(0) @binding(0) var<uniform> frame : FrameConstants;
@vertex fn vs_main(@location(0) pos : vec2f) -> @builtin(position) vec4f {
#ifdef LIT
return frame.projection * vec4f(pos, 1.0, 1.0);
@@ -370,7 +369,7 @@ static void testFragmentOnly() {
CHECK(pp.valid, "fragment-only PostProcess shader parses");
const std::string ppv = ShaderParser::assembleStage(pp, ShaderStage::Vertex);
CHECK(ppv.find("gl_Position = vec4(a_position, 0.0, 1.0);") != std::string::npos &&
- ppv.find("FrameConstants") == std::string::npos,
+ ppv.find("u_projection *") == std::string::npos,
"PostProcess canonical vertex is the clip-space pass-through (no projection)");
ParsedShader unknownDomain = ShaderParser::parse(FRAG_ONLY_UNKNOWN_DOMAIN);
@@ -392,6 +391,44 @@ static void testFragmentOnly() {
"#pragma fragment\nvoid main() {}\n#pragma end\n");
CHECK(!reserved.valid && reserved.errorMessage.find("reserved") != std::string::npos,
"a param named after an injected uniform is rejected with a clear error");
+
+ CHECK(av.find("uniform FrameConstants") != std::string::npos &&
+ af.find("uniform FrameConstants") != std::string::npos,
+ "the view-projection block is injected into both stages");
+}
+
+// A shader written before the engine injected FrameConstants declares its own.
+// Two declarations of one block name never link, so the authored copy is blanked
+// out — with its line count kept, or every compile-log line number after it moves.
+static void testHandWrittenFrameBlock() {
+ ParsedShader p = ShaderParser::parse(
+ "#pragma shader \"Legacy\"\n#pragma version 300 es\n"
+ "#pragma vertex\n"
+ "layout(location = 0) in vec2 a_pos;\n"
+ "layout(std140) uniform FrameConstants {\n"
+ " mat4 u_projection;\n"
+ "};\n"
+ "// uniform FrameConstants named in a comment stays put\n"
+ "void main() { gl_Position = u_projection * vec4(a_pos, 0.0, 1.0); }\n"
+ "#pragma end\n"
+ "#pragma fragment\nvoid main() {}\n#pragma end\n");
+ CHECK(p.valid, "a shader carrying its own frame block still parses");
+ if (!p.valid) return;
+
+ const std::string vs = ShaderParser::assembleStage(p, ShaderStage::Vertex);
+ CHECK(vs.find(" mat4 u_projection;") == std::string::npos,
+ "the authored member is blanked, so only the injected block declares the layout");
+ CHECK(vs.find("// uniform FrameConstants named in a comment stays put") != std::string::npos,
+ "a comment naming the block is not a declaration and survives");
+
+ const std::string::size_type decl = vs.find("layout(location = 0) in vec2 a_pos;");
+ const std::string::size_type note = vs.find("// uniform FrameConstants named");
+ CHECK(decl != std::string::npos && note != std::string::npos && decl < note,
+ "the authored body survives around the blanked block");
+ if (decl == std::string::npos || note == std::string::npos || decl >= note) return;
+ CHECK(std::count(vs.begin() + static_cast<long>(decl), vs.begin() + static_cast<long>(note),
+ '\n') == 4,
+ "blanking keeps the line count, so compile-log remapping still lands");
}
int main() {
@@ -413,6 +450,7 @@ int main() {
CHECK(ShaderParser::variantKey({}).empty(), "variantKey of no features is empty");
testFragmentOnly();
+ testHandWrittenFrameBlock();
testWGSLEmission();
if (g_failures == 0) {