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.

perf(lighting): a lit sprite is lit by its own short function - the general model's sums term for term, the two 2D masks read once for the pixel where each light read them again, and none of the highlight carried along; 32 screen-filling lit layers under four lamps go from 5.4 ms to 4.7 on WebGL2 and from 8.8 to 6.5 on WebGPU, and the note prices what is left

yhh881e3f62091a
diff --git a/docs/GPU_PERFORMANCE_OPTIONS.md b/docs/GPU_PERFORMANCE_OPTIONS.md
index 4160a59c8..78405ee14 100644
--- a/docs/GPU_PERFORMANCE_OPTIONS.md
+++ b/docs/GPU_PERFORMANCE_OPTIONS.md
@@ -109,7 +109,35 @@ ESTELLA_VERIFY_GPU_PASSES=print node tools/run-electron.mjs tools/render-host/ru
- **镜面为 0 时跳过环境镜面那一段(DFG 拟合加反射查找)没有收益**:5.40 对 5.40 ms。镜面是编译期常数 0,驱动的编译器已经把那一段折掉了。改动已撤回。
- WebGPU 比 WebGL2 慢约 1.5 倍,受光与不受光一样,所以是后端(混合/光栅)的差别,不是光照代码的。
- **读数陷阱(已修):**`ESTELLA_VERIFY_GPU_PASSES=print` 原来取第一个有读数的帧,这一帧在这个场景上读成 50 ms(着色器第一次被用到的一次性开销),稳态是 5.4 ms。现在取第八个有读数的帧。那 50 ms 本身是真的首帧卡顿,属于"着色器首次编译"那一类(见 `docs/TERRAIN_WATER_GPU_COST.md` 的 Web 一节)。
-- **没有量的:**手机。移动端的编译器不一定折掉常数分支(水着色器上量到过没走的分支也花时间),这条路径在分块 GPU 上值得单独量一次再决定要不要给 2D 一条更短的光照函数。
+- **没有量的:**手机。移动端的编译器不一定折掉常数分支(水着色器上量到过没走的分支也花时间)。
+
+**这个数是什么:**32 层全屏 = 6600 万个受光片元,每个算四盏灯,共 2.6 亿次"一盏灯照一个像素"。一层全屏受光是 0.15 ms;一个真实的 2D 画面是两到四层重叠。
+
+**逐段定价(同一天,稳态读数,WebGL2,每刀一个构建):**
+
+| 剪掉 | 32 层 ms | 这一段 |
+|---|---|---|
+| 原样 | 5.40 | |
+| 整个光照调用(下限) | 0.84 | 光照 4.56 |
+| 灯循环 | 0.91 | **全部在灯循环里**;间接光、探针、分块灯、环境镜面合起来 0.07 |
+| 每盏灯的两次 2D 遮罩读取(形状、阴影) | 4.39 | 1.0 |
+| 再加每盏灯的三维阴影查找 | 4.40 | 0 |
+| 衰减换成一条线性斜坡 | 少 1.0 | `distanceFalloff`(`pow` 加三次除法)1.0 |
+| 图层范围判断(`lightReachesLayer`) | 少 0.7 | 0.7;把里面的除法和取模换成乘法**没有**变化(4.68 对 4.72),所以不是那几次运算 |
+| 循环展开成常数下标 | 少 0.25 | 动态下标读灯块不是成本 |
+
+**落地(2026-11-12):**受光精灵和 2D 受光材质(`applyLighting2D*`)不再绕三维的 `applyLightingPBR`,走自己的 `shadeLight2D`:同样的求和,逐项相同,两张 2D 遮罩每个像素读一次而不是每盏灯读一次,不带高光的任何部分。
+
+| 32 层全屏,四盏点光 | 之前 | 之后 |
+|---|---|---|
+| WebGL2 | 5.40 ms | 4.70 ms |
+| WebGPU | 8.78 ms | 6.51 ms |
+
+两个后端各 29 个 2D/3D 光照像素场景通过(光形、衰减、2D 阴影、受光材质、受光精灵、线性)。
+
+**试了反而慢的(D3D):**把点光和聚光合成一个分支、聚光锥再判一次(5.7 ms);照不到的灯提前返回(同上)。保留了和通用函数一样的三个分支。
+
+**剩下的 3.9 ms 是每盏灯的算术**(2.6 亿次,每次约 15 皮秒),再改着色器文本只有零头。真正的杠杆是**少算灯**:现在每个受光像素对场景里的每一盏灯都算一遍,不管照不照得到。按精灵(或按屏幕分块,分块灯已经有这套掩码)在 CPU 上剔掉照不到的灯,像素只算照得到它的那几盏——真实的 2D 场景里灯是局部的,这才是数量级的差别。没有做。
## 这一轮已经量过、**不是**杠杆的(别再花时间)
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 0860a12f9..ac1c171a8 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -2449,9 +2449,97 @@ fn shadeLight(pd : vec4f, col : vec4f, sp : vec4f, sh : vec4f, sm : vec4f, fo :
}
return LightTerm(lit, gloss, extra);
}
+)"
+// Split for MSVC's cap on one string literal, as above.
+R"(// A lit sprite's light, written out as only what it is (see the GLSL twin): the general model's sums term for term, with the two 2D masks
+// read once for the pixel and nothing of the highlight carried along.
+fn shadeLight2D(pd : vec4f, col : vec4f, sp : vec4f, sh : vec4f, sm : vec4f, fo : vec4f, N : vec3f, worldPos : vec3f,
+ masked : bool, shadowMask : vec4f, shapeMask : vec4f, shadow3D : bool) -> vec3f {
+ if (col.a == 0.0 || !lightReachesLayer(sm.y)) { return vec3f(0.0); }
+ var L : vec3f;
+ var atten = 1.0;
+ var castShadow = true;
+ if (pd.z < 0.5) {
+ let toL = lightVector(pd, sh, worldPos);
+ let dist = lightDistance(toL);
+ atten = distanceFalloff(dist, max(pd.w, 0.0001), fo);
+ L = towardLight(toL, N);
+ } else if (pd.z < 1.5) {
+ L = normalize(-vec3f(pd.xy, pd.w));
+ var toLight = vec2f(0.0, 0.0);
+ if (dot(pd.xy, pd.xy) > 1e-8) { toLight = normalize(-pd.xy); }
+ castShadow = sh.y > 0.0 && dot(toLight, toLight) > 0.5;
+ } else {
+ let toL = lightVector(pd, sh, worldPos);
+ let dist = lightDistance(toL);
+ atten = distanceFalloff(dist, max(pd.w, 0.0001), fo);
+ L = towardLight(toL, N);
+ atten *= spotCone(sp, sh, toL, dist);
+ }
+#ifndef ES_LIGHT_DIRECT
+ if (masked && col.a > 0.0 && atten > 0.0) {
+ if (fo.w >= 0.0) { atten *= min(mask2DChannel(shapeMask, fo.w), 1.0); }
+ if (castShadow && sm.w >= 0.0 && atten > 0.0) {
+ var hidden = 0.0;
+ if (sm.w < 3.5) { hidden = mask2DChannel(shadowMask, sm.w); }
+ else { hidden = mask2DChannel(shapeMask, sm.w - 4.0); }
+ atten *= mix(1.0, 1.0 - min(hidden, 1.0), fo.z);
+ }
+ }
+#endif
+ if (shadow3D && sm.y % 8.0 > 0.0 && atten > 0.0) {
+ atten *= mix(1.0,
+ shadowFactor3D(worldPos, N, L, vec2f(sh.x, sm.z), i32(sm.x), i32(sm.y % 8.0)),
+ fo.z);
+ }
+ return col.rgb * (col.a * max(dot(N, L), 0.0) * atten);
+}
fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> vec3f {
let P = vec3f(worldPos, 0.0);
- return applyLightingPBR(albedo, N, P, viewDirection(P), 0.0, 1.0, 0.0, ao);
+ g_probePos = P;
+ var lit = indirectIrradiance(N) * ao;
+ var masked = false;
+ var shadowMask = vec4f(0.0);
+ var shapeMask = vec4f(0.0);
+#ifndef ES_LIGHT_DIRECT
+ if (lc.u_mask2DRect.z > 0.0) {
+ let maskUv = mask2DUv(worldPos);
+ if (!(maskUv.x < 0.0)) {
+ masked = true;
+ shadowMask = textureSampleLevel(t7, s7, maskUv, 0.0);
+ shapeMask = textureSampleLevel(t6, s6, maskUv, 0.0);
+ }
+ }
+#endif
+ let lightCount = i32(lc.u_ambient.a);
+ for (var i = 0; i < lightCount; i++) {
+ lit += shadeLight2D(lc.u_lights[i].posDir, lc.u_lights[i].color, lc.u_lights[i].spot, lc.u_lights[i].shadow,
+ lc.u_lights[i].shadowMap, lc.u_lights[i].falloff, N, P, masked, shadowMask, shapeMask, true);
+ }
+#ifndef ES_LIGHT_DIRECT
+ let tiledCount = i32(lc.tileInfo.x);
+ if (tiledCount > 0) {
+ let tileClip = frame.projection * vec4f(P, 1.0);
+ let tileNdc = tileClip.xy / max(tileClip.w, 1e-4);
+ let tileCount = vec2i(i32(lc.tileInfo.y), i32(lc.tileInfo.z));
+ let tile = clamp(vec2i(floor((tileNdc * 0.5 + 0.5) * vec2f(tileCount))), vec2i(0), tileCount - vec2i(1));
+ let mask = lc.tileMask[tile.y * tileCount.x + tile.x];
+ for (var w = 0; w < 3; w++) {
+ var bits = mask.x;
+ if (w == 1) { bits = mask.y; } else if (w == 2) { bits = mask.z; }
+ if (bits == 0u) { continue; }
+ for (var b = 0; b < 32; b++) {
+ if ((bits & (1u << u32(b))) == 0u) { continue; }
+ let k = w * 32 + b;
+ if (k >= tiledCount) { break; }
+ lit += shadeLight2D(lc.tiledLights[k].posDir, lc.tiledLights[k].color, lc.tiledLights[k].spot,
+ lc.tiledLights[k].shadow, lc.tiledLights[k].shadowMap, lc.tiledLights[k].falloff,
+ N, P, masked, shadowMask, shapeMask, false);
+ }
+ }
+ }
+#endif
+ return albedo * lit;
}
fn applyLighting2D(albedo : vec3f, N : vec3f, worldPos : vec2f) -> vec3f {
return applyLighting2DAO(albedo, N, worldPos, 1.0);
@@ -4000,10 +4088,96 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" }\n"
" }\n"
"}\n"
+ // A lit sprite's light: the general model at metallic 0, roughness 1, specular 0, which is albedo times what arrives, written
+ // out as only that. The sums are the general ones term for term, so the picture is the same; what differs is what a pixel
+ // pays: the two 2D masks are read once for the pixel and not once per light, and nothing of the highlight is carried along.
+ // The three kinds of light keep a branch each, as the general function has them: folding point and spot into one, or
+ // leaving early when a light does not reach, measured SLOWER on D3D (5.7 ms against 4.7). 32 screen-filling lit layers
+ // under four lamps: 5.4 ms to 4.7 on WebGL2, 8.8 to 6.5 on WebGPU (docs/GPU_PERFORMANCE_OPTIONS.md, section 9).
+ "void shadeLight2D(in highp vec4 pd, in highp vec4 col, in highp vec4 sp, in highp vec4 sh, in highp vec4 sm,\n"
+ " in highp vec4 fo, in highp vec3 N, in highp vec3 worldPos, in bool masked,\n"
+ " in highp vec4 shadowMask, in highp vec4 shapeMask, inout highp vec3 lit, in bool shadow3D) {\n"
+ " if (col.a == 0.0 || !lightReachesLayer(sm.y)) return;\n"
+ " highp vec3 L;\n"
+ " highp float atten = 1.0;\n"
+ " bool castShadow = true;\n"
+ " if (pd.z < 0.5) {\n"
+ " highp vec3 toL = lightVector(pd, sh, worldPos);\n"
+ " highp float dist = lightDistance(toL);\n"
+ " atten = distanceFalloff(dist, max(pd.w, 0.0001), fo);\n"
+ " L = towardLight(toL, N);\n"
+ " } else if (pd.z < 1.5) {\n"
+ " L = normalize(-vec3(pd.xy, pd.w));\n"
+ " highp vec2 toLight = (dot(pd.xy, pd.xy) > 1e-8) ? normalize(-pd.xy) : vec2(0.0);\n"
+ " castShadow = sh.y > 0.0 && dot(toLight, toLight) > 0.5;\n"
+ " } else {\n"
+ " highp vec3 toL = lightVector(pd, sh, worldPos);\n"
+ " highp float dist = lightDistance(toL);\n"
+ " atten = distanceFalloff(dist, max(pd.w, 0.0001), fo);\n"
+ " L = towardLight(toL, N);\n"
+ " atten *= spotCone(sp, sh, toL, dist);\n"
+ " }\n"
+ "#ifndef ES_LIGHT_DIRECT\n"
+ " if (masked && col.a > 0.0 && atten > 0.0) {\n"
+ " if (fo.w >= 0.0) atten *= min(mask2DChannel(shapeMask, fo.w), 1.0);\n"
+ " if (castShadow && sm.w >= 0.0 && atten > 0.0) {\n"
+ " highp float hidden = (sm.w < 3.5) ? mask2DChannel(shadowMask, sm.w) : mask2DChannel(shapeMask, sm.w - 4.0);\n"
+ " atten *= mix(1.0, 1.0 - min(hidden, 1.0), fo.z);\n"
+ " }\n"
+ " }\n"
+ "#endif\n"
+ " if (shadow3D && mod(sm.y, 8.0) > 0.0 && atten > 0.0) {\n"
+ " atten *= mix(1.0, shadowFactor3D(worldPos, N, L, vec2(sh.x, sm.z),\n"
+ " int(sm.x), int(mod(sm.y, 8.0))), fo.z);\n"
+ " }\n"
+ " lit += col.rgb * (col.a * max(dot(N, L), 0.0) * atten);\n"
+ "}\n"
"highp vec3 applyLighting2DAO(highp vec3 albedo, highp vec3 N, highp vec2 worldPos,\n"
" highp float ao) {\n"
" highp vec3 P = vec3(worldPos, 0.0);\n"
- " return applyLightingPBR(albedo, N, P, viewDirection(P), 0.0, 1.0, 0.0, ao);\n"
+ " g_probePos = P;\n"
+ " highp vec3 lit = indirectIrradiance(N) * ao;\n"
+ " bool masked = false;\n"
+ " highp vec4 shadowMask = vec4(0.0);\n"
+ " highp vec4 shapeMask = vec4(0.0);\n"
+ "#ifndef ES_LIGHT_DIRECT\n"
+ " if (u_mask2DRect.z > 0.0) {\n"
+ " highp vec2 maskUv = mask2DUv(worldPos);\n"
+ " if (!(maskUv.x < 0.0)) {\n"
+ " masked = true;\n"
+ " shadowMask = textureLod(u_shadow2D, maskUv, 0.0);\n"
+ " shapeMask = textureLod(u_lightShape2D, maskUv, 0.0);\n"
+ " }\n"
+ " }\n"
+ "#endif\n"
+ " int lightCount = int(u_ambient.a);\n"
+ " for (int i = 0; i < lightCount; ++i) {\n"
+ " shadeLight2D(u_lights[i].posDir, u_lights[i].color, u_lights[i].spot, u_lights[i].shadow,\n"
+ " u_lights[i].shadowMap, u_lights[i].falloff, N, P, masked, shadowMask, shapeMask, lit, true);\n"
+ " }\n"
+ "#ifndef ES_LIGHT_DIRECT\n"
+ " int tiledCount = int(u_tileInfo.x);\n"
+ " if (tiledCount > 0) {\n"
+ " highp vec4 tileClip = u_projection * vec4(P, 1.0);\n"
+ " highp vec2 tileNdc = tileClip.xy / max(tileClip.w, 1e-4);\n"
+ " ivec2 tileCount = ivec2(int(u_tileInfo.y), int(u_tileInfo.z));\n"
+ " ivec2 tile = clamp(ivec2(floor((tileNdc * 0.5 + 0.5) * vec2(tileCount))), ivec2(0), tileCount - ivec2(1));\n"
+ " highp uvec4 mask = u_tileMask[tile.y * tileCount.x + tile.x];\n"
+ " for (int w = 0; w < 3; ++w) {\n"
+ " highp uint bits = w == 0 ? mask.x : (w == 1 ? mask.y : mask.z);\n"
+ " if (bits == 0u) continue;\n"
+ " for (int b = 0; b < 32; ++b) {\n"
+ " if ((bits & (1u << uint(b))) == 0u) continue;\n"
+ " int k = w * 32 + b;\n"
+ " if (k >= tiledCount) break;\n"
+ " shadeLight2D(u_tiledLights[k].posDir, u_tiledLights[k].color, u_tiledLights[k].spot,\n"
+ " u_tiledLights[k].shadow, u_tiledLights[k].shadowMap, u_tiledLights[k].falloff,\n"
+ " N, P, masked, shadowMask, shapeMask, lit, false);\n"
+ " }\n"
+ " }\n"
+ " }\n"
+ "#endif\n"
+ " return albedo * lit;\n"
"}\n"
"highp vec3 applyLighting2D(highp vec3 albedo, highp vec3 N, highp vec2 worldPos) {\n"
" return applyLighting2DAO(albedo, N, worldPos, 1.0);\n"