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(water): the surface asks whether it is water before it works out the waves and the light

yhh10dc71b6cba7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 90b036d15..346cf2276 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,7 @@ published separately; it ships inside the editor.
### Changed
+- **The water surface leaves early where it is not water.** A shader that may discard late is not let test depth early, so the water behind a hill ran all of it; the test that decides whether a pixel is water now comes before the waves and the light are worked out. The picture is the same, a frame of the Terrain & Water example about a millisecond shorter or more on an RTX 3060. The WebGL2 shader only.
- **A lit surface takes its shadow in fewer operations.** The shadow lookup of a light with a size (the sun's penumbra) worked a `sin`, a `cos` and a `sqrt` for each of its forty-eight taps and a whole matrix for each of the sixteen that look for a blocker; the taps are a table now, turned once a pixel, and the matrix is applied to the light's direction once. Inside a shadow, where every blocker tap hits, it returns at once, and a penumbra a texel or two wide is averaged over 8 or 16 taps, not 32. The picture is the same to the pixel gates on WebGL2 and WebGPU; a frame of the Terrain & Water example is 3 to 10 ms shorter on an RTX 3060.
### Fixed
diff --git a/docs/GPU_PERFORMANCE_OPTIONS.md b/docs/GPU_PERFORMANCE_OPTIONS.md
new file mode 100644
index 000000000..7221673e2
--- /dev/null
+++ b/docs/GPU_PERFORMANCE_OPTIONS.md
@@ -0,0 +1,103 @@
+# GPU 性能:现代引擎技术对照我们的渲染器(2026-10-26)
+
+依据是 `docs/TERRAIN_WATER_GPU_COST.md` 里在 RTX 3060、1080p、WebGL2 上量过的数,和读过的代码。每一项写:它是什么、我们现在有什么、量到的证据、估计的收益、风险。**收益是估计,不是承诺**;没有量过的我标了。
+
+## 先放一个前提:我们是怎么量的,以及缺什么
+
+引擎只有**整个渲染图一个** GPU 计时器(`render.graph`),场景的网格绘制还在图外。所以这一轮每个数都是“拿掉一样东西,看整帧差多少”(消融),有的还要为了量一个着色器阶段重新编一个引擎。这能用,但慢,而且各部分不能相加。
+
+- **0. 逐 pass 的 GPU 计时(基础设施)。** 渲染图的每个 pass 已经有名字(`gtao_ao`、`bloom_kawase_0`、`scene-grab`、阴影的每张图…)。WebGPU 有时间戳查询(`timestamp-query`),WebGL2 有 `EXT_disjoint_timer_query_webgl2`,每个 pass 两个时间戳、几帧环形读回即可。有了它,后面每一项的取舍是一次读数,不是一次构建。这是下面所有项里投入最小、回报最直接的一项。引擎里 `GpuTimer` 和 WebGPU 的时间戳环已经在,缺的是按 pass 分。
+
+## 按证据排序
+
+### 1. 天空大气和高度雾:LUT 化、低分辨率、跨帧复用 —— 现在最大的一块
+
+**证据:**所有优化之后,默认机位 24.8 ms 的帧里,后处理链占 12.4 ms,其中天空大气 7.9 ms、高度雾 5.1 ms(沿河机位:7.2 与 5.1);两者不是相加的关系,但合起来是帧的一半以上。它们各是一个全分辨率的单 pass。
+
+**现代做法**(Hillaire 2020,UE5 / Frostbite 的天空大气):
+- *Transmittance LUT*(只随高度和太阳角变,几乎不用重算)、*multi-scattering LUT*、*sky-view LUT*(小图,天空的颜色只随方向变,屏幕上每个天空像素只采一次)。
+- *Aerial perspective*:把雾和大气的散射做成一个相机对齐的小体积纹理(froxel,例如 32×32×16),每个像素按深度采一次,取代每像素的步进。
+- 云:低分辨率(1/4)加时间重投影累积,每帧只算像素的一部分,其余用历史。
+
+**我们现在有:**`skyAtmosphere` 每个天空像素 16 步云步进;`heightFog` 每像素一个解析式,打开 `u_volumetric` 时每像素 24 个阴影采样(这个示例里体积光只占 −0.3 到 −0.6 ms,在噪声里)。`gtao` 已经是半分辨率加双向模糊,说明引擎里有“半分辨率 pass 加上采样”的现成做法(`scale: 0.5` 的 `multiPass`)。
+
+**估计:**天空 LUT 加 aerial perspective 能把这两项合起来从 13 ms 降到 2 到 4 ms(帧的 30% 到 40%)。**风险:**画面要重新对齐(太阳、云影、雾的颜色),这是渲染器里最容易出现“看起来不对但没有一个像素验收能说清”的部分;需要截图对比。**工作量:**大(一到两周)。比它便宜的第一步:**把天空和雾各自放到半分辨率,用深度感知的上采样**,这是现有 `gtao` 的做法,一两天。
+
+### 2. 用 TAA 加时间上采样换掉 4× MSAA,再加动态分辨率
+
+**证据:**4× MSAA 在预通道之后还是 5 到 8 ms(帧的 16% 到 18%),集中在接收阴影的叶片边缘像素的着色次数上,不在解析;渲染比例 0.75 省 15 到 44 ms(帧是片元受限)。
+
+**现代做法:**1× 渲染加抖动、运动向量、历史累积(TAA),需要时再用时间上采样(TAAU/FSR2 类)从 0.67 倍分辨率放回。
+
+**我们现在有:**`taa` 是一个后处理效果(这个示例的链里没有开,所以没有量它的成本),`motion` pass(`RenderPurpose::Motion`)已经为它写运动向量,`QualityController` 有 `dynamicResolution` 和 `renderScale` 的上下限。**缺:**把它们接成一条默认的“高画质 = 1× + TAAU”的路径,以及对叶片的抗锯齿质量(镂空卡片的 TAA 鬼影)的验收。
+
+**估计:**5 到 8 ms(MSAA)加上动态分辨率的余量。**风险:**画面特性变了(时间稳定性换空间锐度),镂空叶片和细线容易鬼影;**用户已经决定 high 档的 4× MSAA 不动**,所以这一项只能作为新的档位或选项。
+
+### 3. 阴影:缓存与更新率,而不是更便宜的查找
+
+**证据:**阴影整个是 3.6 ms(默认)到 9.8 ms(沿河)。接收端只有 3 到 4 ms,而且试过的减采样、背面跳过、硬边都没有收益;**投射**才是随场景变的那一块。级联模式下投射体的绘制数是一张图的 2 到 4 倍(因为默认范围太大,不是剔除缺失)。
+
+**现代做法:**
+- *静态投射体缓存*:地形、不动的树不是每帧画进阴影图;只重画动的东西,太阳动得慢时远处的级联隔几帧才更新(我们的 TimeOfDay 很慢)。
+- *虚拟阴影图 / 稀疏分页*(UE5 的 VSM):只画屏幕上有像素用到的页。浏览器里没有稀疏纹理,代价高,不建议。
+- *接触阴影*(屏幕空间短射线)补细节,让主阴影图可以更粗。
+
+**我们现在有:**每帧全量重画每一张阴影图;没有缓存也没有隔帧更新。**估计:**缓存 + 隔帧更新能把投射部分的大半拿掉(这个示例里 3 到 8 ms,远处级联更多)。**风险:**视角移动时缓存要按纹素网格对齐,太阳动时要失效。**工作量:**中。
+
+### 4. GPU 驱动的绘制:间接绘制、计算剔除、Hi-Z 遮挡
+
+**证据:**CPU 帧耗时在 9 到 14 ms(含剖析开销),绘制 600 到 700 个,阴影绘制 400 到 5000 个(级联模式)。GPU 受限的这个场景里 CPU 不是瓶颈;但手机和小游戏上它会是。
+
+**现代做法:**把每个单元里的实例位置放在一块 GPU 缓冲里,用计算着色器做视锥和 Hi-Z 遮挡剔除,把幸存者写进间接绘制参数,一次 `multiDrawIndirect` 画完整个场景。
+
+**我们现在有:**实例化的植物绘制(按单元和种类合并成一个绘制)、一个 CPU 的软件遮挡盒(`occlusion_`);RHI 里没有间接绘制,也没有计算分发的统一接口(WebGPU 后端有计算 pass,GPU 粒子在用)。**WebGL2 没有间接绘制**,所以这一项只对 WebGPU 路径有意义。**估计:**对这个场景的 GPU 时间几乎没有收益(叶片的着色次数不会因此少),CPU 时间和绘制提交会少。**优先级低**,等 WebGPU 成为主路径再做。
+
+### 5. 可见性缓冲 / 延迟纹理(visibility buffer)
+
+**证据:**植物是帧里最贵的一块(默认 4.3 ms,沿河 12.1 ms,没有预通道时是 22 到 68 ms),预通道已经拿掉了被遮住的着色。剩下的是多重采样下边缘像素的着色次数和小三角形的四元组过度着色。
+
+**现代做法:**先把“哪个三角形、哪个实例”写进一张小图(便宜,深度加 id),再在一个屏幕空间 pass 里,每个像素只着色一次,按材质分批。对叶片这种几何密、材质少的场景尤其合适。
+
+**我们现在有:**前向着色加预通道;已有 G-buffer 路径(给 SSR/SSGI 用)。**风险:**大改动,透明与镂空的处理,WebGL2 上的带宽;镂空(alpha-to-coverage)在 visibility buffer 里需要自己的做法。**估计:**如果 MSAA 换成 TAA(第 2 项)就不再需要它;两者择一。**优先级:**第 2 项之后再看。
+
+### 6. 远处的树:贴图替身(impostor)
+
+**证据:**树在 60 到 170 米之间曾是最贵的(lod1 一棵 1 万个三角形盖几百个像素);我们加了第三级网格(约 1/10 三角形)。再往远已经是两张交叉的卡片。
+
+**现代做法:**八面体替身(octahedral impostor):把树从 N 个方向预烘成图集,远处按视角在几张图之间插值,几百个三角形的成本降到两个。
+
+**我们现在有:**第三级网格加两张卡片的远景。**估计:**在 100 到 400 米这一段还有余量,但这个示例里树现在不是主要成本,**除非场景树更多,否则不做**。
+
+### 7. 后处理的 pass 合并与半分辨率
+
+**证据:**颜色分级、显示 LUT、FXAA、自动曝光、bloom 的五次下采样各是全屏 pass,逐个看都是 0.2 到 2 ms(bloom 在沿河 1.4 ms,颜色分级加 LUT 1.5 到 2.3 ms,FXAA 在噪声里)。
+
+**现代做法:**把末尾的几次 LDR 全屏 pass(分级、LUT、FXAA、色调映射)合成一个;bloom 用计算着色器一次做完一条下采样链(WebGPU)。**估计:**1 到 2 ms。**风险:**小;`displayLut` 的“在输出变换之后”的次序要保持。
+
+### 8. 移动端和小游戏上的取舍(没有量过)
+
+- 分块 GPU 上深度预通道是几何画两次,所以 low 档默认关;**没有在任何手机上量过**,预通道的收益和代价应该在真机上各量一次再定 medium 档要不要开。
+- 分块 GPU 对“把场景拷出来再折射”(水)特别贵(要把片上内存刷出去),所以水在 low 档应该走平面折射或假折射;这个示例的 low 档已经是“平水面”。
+
+## 这一轮已经量过、**不是**杠杆的(别再花时间)
+
+| 想法 | 结果 |
+|---|---|
+| 折射的两次场景拷贝 | 0 到 1 ms,在噪声里 |
+| 水面反射步进(20 步) | 关掉不变 |
+| 水着色器的数学(波浪、区域、涟漪、折射、焦散、泡沫、光照) | 每一段在噪声里;成本是末尾的 `discard`(已改) |
+| 阴影采样数、硬边阴影、背面跳过、4 采样提前退出 | 没有收益或更慢 |
+| MSAA 解析和后处理对 MSAA 的敏感 | 解析 ≤ 0.7 ms |
+| FXAA | 噪声 |
+| 近处树提前换 LOD | 预通道之后 0 到 2 ms,树冠变疏 |
+| 水的质量档位 | 都在噪声里 |
+
+## 建议的顺序
+
+1. **逐 pass GPU 计时**(第 0 项):投入最小,让后面每一步可以直接读数。
+2. **天空与雾半分辨率加上采样**(第 1 项的第一步),再看要不要做 LUT。
+3. **阴影缓存与远处级联隔帧更新**(第 3 项)。
+4. **TAA 加时间上采样作为新档位**(第 2 项),要用户拍板。
+5. 后处理 pass 合并(第 7 项)。
+
+GPU 驱动绘制、可见性缓冲、替身这三项,在这个示例的瓶颈上收益都不大,不在前面。
diff --git a/docs/TERRAIN_WATER_GPU_COST.md b/docs/TERRAIN_WATER_GPU_COST.md
index 27529d342..40bc0e054 100644
--- a/docs/TERRAIN_WATER_GPU_COST.md
+++ b/docs/TERRAIN_WATER_GPU_COST.md
@@ -303,3 +303,46 @@
**画面:**花海近处树冠的截图(左基准,右 40/80 米):树冠明显变疏——叶片的数量少了、单片变大,枝干的粗细和分叉也不一样,天空从叶隙漏得更多;30/60 米与 40/80 米在这棵树上一样(它在 40 到 60 米之间,两者都已经是 lod1)。用两次基准里都不变的像素数差别:40/80 米的平均差 2.5 到 4.5,差大于 24 的像素 1.7% 到 4.2%;30/60 米 3.5 到 7.1,4.1% 到 8.9%;同一个包什么也不改的对照在 0.3 到 2.0,0%。
**决定:不落地。**为了 0 到 2 ms(1% 到 5%)换近处树冠的外观,不值得;这个外观的变化来自美术给的 lod1 网格本身(它的叶片更大更少),不是距离的问题,所以把它再往近处拉,近处就是一棵不同的树。要省这一块,方向是更好的 lod1(叶片数量与 lod0 一致、只合并三角形)或者用不同的叶片替代,不是移动阈值。
+
+## 水:折射用的场景拷贝与反射步进(2026-10-26)
+
+先量,两个都不是杠杆,真正的成本在别处。
+
+| 量什么 | 做法 | 结果 |
+|---|---|---|
+| 场景拷贝(颜色与深度两次全屏) | 引擎里把两次拷贝拿掉,留下分遍(变体 E1) | 水的成本 0.4 到 3.1 ms,和不拿掉(1.5 到 3.3)在噪声里 |
+| 分遍加拷贝都拿掉 | 水不再折射,和别的一起画(E2) | 水的成本 1.3 到 4.9 ms,没有更便宜 |
+| 反射步进(20 步) | 着色器里关掉那一段(C6) | 和完整一样(3.7 对 3.0,3.0 对 2.8,1.3 对 1.5) |
+| 波浪、区域、涟漪(C1) | 算完法线就返回 | 水的成本 ≈ 0 |
+| 折射、焦散、泡沫、光照(C2 到 C4) | 依次在每段后面返回 | 每一档都 ≈ 0 |
+
+(都是“基准减去没有水面”的差,同一个包里算,抵消机器的漂移。)所以水着色器的数学几乎不花钱;**成本在着色器末尾那条 `discard`**:去掉它水的成本从 2.4、2.1、2.0 降到 0.9、1.0、0.6 ms(变体 C7,画面不对,只为量它)。
+
+**原因(推断):**着色器里有 `discard`,就不能让深度测试先于着色器做完,被地形或树挡住的水面像素(一整块 28 公里的海面在山后面)也要把整段着色器跑完才被深度测试丢掉。那条 `discard` 只在海岸之外(`shoreDist < 0`)才会真的丢,所以把判断挪到前面、先算它再算波浪和光照也行(变体 C8:1.9、1.0、0.8 ms)。
+
+**做了什么:**把这三条语句(`film`、`under`、`discard`)原样移到场景深度读出之后、算波浪之前。它们用到的值都不依赖波浪和光照,所以结果相同,只是不是水的像素早早离开。只改了 WebGL2 的 GLSL;WGSL 孪生没动(没有引擎侧的水夹具能验它,编辑器的水检查在 CI 里)。
+
+交替 A/B(同一个引擎,只有水着色器不同,每个机位两轮):
+
+| 机位 | 之前 帧 / 水 ms | 之后 帧 / 水 ms |
+|---|---|---|
+| 默认 | 26.5 / 2.8,25.8 / 2.6 | 24.9 / 1.6,24.8 / −0.2 |
+| 花海 | 38.9 / 1.0,41.5 / 5.4 | 34.9 / 0.7,35.5 / 0.1 |
+
+整帧省 1 到 5 ms(这一对包的机器漂移比水本身大,保守地读成 1 ms 左右)。像素:沿河机位里两次基准都不变的 84% 的像素,新旧平均差 0.36,差大于 24 的 0.23%(对照一般 0.3 到 0.6)。
+
+## 现在整帧在哪(同一天,所有改动之后)
+
+| | 默认机位 | 沿河 |
+|---|---|---|
+| 帧 | 24.8 ms | 32.0 ms |
+| 后处理链整个 | 12.4 | 12.7 |
+| 其中天空大气 | 7.9 | 7.2 |
+| 其中高度雾 | 5.1 | 5.1 |
+| 其中 GTAO | −0.2(噪声) | 2.8 |
+| 其中体积光 | −0.3(噪声) | −0.6(噪声) |
+| 其中 bloom | 0 | 1.4 |
+| 植物 | 4.3 | 12.1 |
+| 阴影 | 3.6 | 9.8 |
+
+**最大的一块已经变成天空大气加高度雾**:默认机位上这两个就占了帧的一半以上(不是互相独立的,去掉一个另一个的成本会变,所以不能相加)。这是下一步最值的方向,见 `docs/GPU_PERFORMANCE_OPTIONS.md`。
diff --git a/sdk/src/water/waterShader.ts b/sdk/src/water/waterShader.ts
index f60159be5..2a90d7680 100644
--- a/sdk/src/water/waterShader.ts
+++ b/sdk/src/water/waterShader.ts
@@ -668,6 +668,14 @@ void main() {
vec2 uv0 = clip0.xy / max(clip0.w, 1e-4) * 0.5 + 0.5;
float behindDist = haveDepth ? texture(u_sceneDepthMap, clamp(uv0, vec2(0.001), vec2(0.999))).r : waterDist + u_fallbackDepth;
float column0 = max(behindDist - waterDist, 0.0);
+ // Past the shore only the surf's film is water: over ground no lower than the water, within its height of the rest level (further off
+ // it is the mesh stretched between two waters' heights); the depth test cuts it where the ground rises above it. Asked here, before the
+ // waves and the light are worked out for it: a shader that may discard late is not let test depth early, and what leaves here does not pay for them.
+ bool film = abs(P.y + u_renderOrigin.y - zone.x) <= surf.x + u_waveHeight * zone.z + 1e-3;
+ // Ground lower than the water there (a dry basin) takes no film. The picture's depth says it of this very pixel; the baked depth only
+ // of whole texels (dry is 0 and any wet one beside it raises the blend), which would cut the film in the texels' steps.
+ float under = haveDepth ? column0 * abs(viewDir.y) - 2.0 * (surf.x + u_waveHeight * zone.z) - 1.0 : shoreDepth - 1e-3;
+ if (shoreDist < 0.0 && (surf.x <= 0.0 || under > 0.0 || !film)) discard;
// Bent by the waves: the ray through the tilted surface against the ray through a flat one, over as much water as there is.
float RATIO = below ? 1.333 : 1.0 / 1.333;
@@ -770,13 +778,6 @@ void main() {
float thin = max(smoothstep(0.0, u_edgeSoftness, column0 * max(abs(viewDir.y), 0.15)), surfFoam);
color = mix(textureLod(u_sceneColor, clamp(uv0, vec2(0.001), vec2(0.999)), 0.0).rgb, color, thin);
}
- // Past the shore only the surf's film is water: over ground no lower than the water, within its height of the rest level (further off
- // it is the mesh stretched between two waters' heights); the depth test cuts it where the ground rises above it.
- bool film = abs(P.y + u_renderOrigin.y - zone.x) <= surf.x + u_waveHeight * zone.z + 1e-3;
- // Ground lower than the water there (a dry basin) takes no film. The picture's depth says it of this very pixel; the baked depth only
- // of whole texels (dry is 0 and any wet one beside it raises the blend), which would cut the film in the texels' steps.
- float under = haveDepth ? column0 * abs(viewDir.y) - 2.0 * (surf.x + u_waveHeight * zone.z) - 1.0 : shoreDepth - 1e-3;
- if (shoreDist < 0.0 && (surf.x <= 0.0 || under > 0.0 || !film)) discard;
fragColor = vec4(color, haveColor ? 1.0 : 0.85);
#ifdef ES_GBUFFER
// 0.72: a surface, and water (see readSurface): what lands on it is the water's, not a wet floor's.
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 8b74d32f5..76d0ce34d 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2984,4 +2984,6 @@ export const NOTED = {
{"note":"A depth prepass for the opaque scene."},
"fix(render): a depth program seeds the samplers a vertex hook reads, so the terrain takes part in the depth prepass with its own heights":
{"note":"A material's vertex hook reads its own textures when it casts a shadow."},
+ "perf(water): the surface asks whether it is water before it works out the waves and the light":
+ {"note":"The water surface leaves early where it is not water."},
};