ZenFG 渲染层解析：基于 WebGPU 的 FrameGraph 管线编排实践

1. 为什么我要写一个“不像引擎”的渲染层

第一次看到 ZenFG 这个项目标题，很多人会下意识把它归类到“又一个 WebGPU 渲染引擎”的赛道里。毕竟这两年 wgpu、WebGPU 相关的开源项目层出不穷，光是叫得上名字的渲染器就有十几个。但我把 ZenFG 的代码拉下来读了两天之后，发现它的定位其实非常克制——它压根没打算跟 Three.js、Babylon.js 或者那些全功能引擎抢饭碗，它做的事情只有一件：把一帧画面里所有渲染任务，用一张可组合的 FrameGraph 串起来。

这个定位听起来有点抽象，我换个说法你就懂了。传统渲染引擎像是一家全包式装修公司，从水电到家具全给你搞定，你只需要拎包入住；而 ZenFG 更像是一套模块化的轨道系统，它不负责生产“家具”（也就是具体的材质、光照、模型加载），它只负责决定“哪个工序先做、哪个后做、哪些可以并行、哪些资源可以复用”。这种设计思路在主机游戏和 3A 大作的自研引擎里其实非常常见，Frostbite、Decima 这些引擎的 FrameGraph 模块都是核心中的核心，但在 WebGPU 生态里，愿意把这一层单独抽出来做成通用库的项目并不多。

我之所以对这个方向感兴趣，是因为过去半年我在做几个 WebGPU 的可视化项目时，反复被同一个问题折磨：渲染管线的依赖关系一旦复杂起来，手动管理纹理和缓冲区的创建、复用、销毁就变成了一场噩梦。比如后处理链里，Bloom 需要先降采样再升采样，SSAO 需要深度图和法线图，TAA 又需要历史帧的颜色和深度。这些 Pass 之间的依赖关系如果用命令式代码硬写，改一个环节就要动一大片，调试的时候根本不知道哪张纹理在哪个时刻被谁写坏了。ZenFG 想解决的，正是这个“管线编排”层面的痛点。

这篇文章我会从实际使用的角度，把 ZenFG 的设计思路、核心概念、实操流程、踩坑经验完整拆一遍。如果你正在用 WebGPU 做中大型渲染项目，或者你已经在用 wgpu 但觉得手动管理 Pass 太累，那这篇内容应该能帮你省下不少试错时间。如果你只是刚接触 WebGPU 的新手，也可以把它当作理解 FrameGraph 这个概念的入门材料，因为 ZenFG 的 API 设计相对干净，没有太多历史包袱。

2. FrameGraph 到底解决了什么问题

2.1 从“命令式渲染”到“声明式编排”的思维转变

要理解 ZenFG 的价值，得先搞清楚传统命令式渲染的痛点在哪里。假设你要做一个带后处理的场景，典型的代码结构大概是这样：先创建一堆纹理资源，然后按顺序写渲染 Pass，每个 Pass 里手动绑定它需要的输入纹理和输出纹理，最后提交命令队列。这个流程在 Pass 数量少的时候没问题，但一旦超过十个 Pass，资源依赖就变成了一张蜘蛛网。

我举个具体的例子。假设你有这样一个管线：几何 Pass 输出颜色和深度，SSAO Pass 读取深度输出 AO 图，模糊 Pass 读取 AO 图输出模糊后的 AO，光照 Pass 读取颜色、深度、模糊 AO 输出光照结果，Bloom 降采样读取光照结果，Bloom 升采样读取降采样链，最后合成 Pass 把光照结果和 Bloom 结果叠加输出到屏幕。这还只是最基础的后处理链，实际项目里 Pass 数量轻松上三十。

命令式写法下，你需要手动追踪每一张中间纹理的生命周期。哪张纹理在哪个 Pass 之后就不再被使用了？能不能提前复用它的内存？如果分辨率变了，哪些纹理需要重建？这些问题全靠开发者自己维护，稍不注意就是内存泄漏或者纹理被提前释放导致的黑屏。更麻烦的是，当你想要调整 Pass 顺序或者插入一个新的后处理效果时，你得手动去改所有相关的绑定代码，牵一发而动全身。

ZenFG 的思路是把这套流程反过来：你不再命令式地写“先做 A 再做 B”，而是声明式地描述“B 需要 A 的输出”。至于 A 和 B 之间怎么调度、中间资源怎么分配和复用，交给 FrameGraph 去算。这就像从“手动挡”换成了“自动挡”，你只需要告诉系统目的地，路线规划它自己搞定。

2.2 ZenFG 的核心抽象：Pass、Resource、Builder

ZenFG 的 API 表面上看很简洁，核心概念就三个：Pass、Resource 和 Builder。但这三个概念背后的设计取舍值得细说。

Pass 代表一个渲染阶段，但它不是直接执行渲染命令的地方，而是一个“声明”。你在 Pass 里声明它需要读取哪些资源、写入哪些资源，以及具体的渲染逻辑。这个声明过程发生在“构建阶段”，而不是“执行阶段”。这个区分非常关键，因为只有把声明和执行分开，FrameGraph 才有机会在中间做优化。

Resource 代表渲染过程中用到的各种资源，主要是纹理和缓冲区。在 ZenFG 里，资源也是声明出来的，你描述它的格式、尺寸、用途，但不直接创建它。真正的创建时机由 FrameGraph 根据依赖关系决定。这里有个很妙的设计：资源可以被“别名化”，也就是说，如果两张纹理的生命周期不重叠，FrameGraph 可以让它们共享同一块内存。这个优化在移动端或者显存受限的场景下价值巨大。

Builder 是连接 Pass 和 Resource 的桥梁。你通过 Builder 来声明依赖关系，比如builder.read(texture)表示当前 Pass 要读取这张纹理，builder.write(texture)表示要写入。Builder 还负责处理资源的版本管理，同一个资源在不同 Pass 里可能有不同的状态，Builder 会帮你追踪这些状态变化。

我实测下来，这套抽象的学习曲线大概在两到三天。第一天你会觉得概念有点绕，第二天开始能写出简单的管线，第三天就能体会到声明式编排的爽点了。相比直接手写 wgpu 的命令编码，ZenFG 让你少写大概百分之四十的样板代码，而且改管线的时候心理负担小很多。

2.3 和 impeller 渲染引擎原理的异同

最近 impeller 渲染引擎原理是个热词，我顺便聊一下 ZenFG 和 impeller 在思路上的一些异同。impeller 是 Flutter 的新一代渲染引擎，它的核心改进之一就是预编译着色器，避免运行时着色器编译导致的卡顿。而 ZenFG 关注的是另一个维度：管线编排。

两者其实不在一个层面上。impeller 更像是一个完整的渲染后端，它关心的是“怎么把这一帧画出来”，包括着色器管理、图层合成、光栅化策略。ZenFG 关心的是“这一帧里各个渲染任务怎么组织”，它不碰着色器编译，也不管具体的绘制命令，它只负责调度。

但有意思的是，impeller 内部其实也有类似 FrameGraph 的调度逻辑，只是它没有把这层单独暴露出来。ZenFG 的做法是把这层抽出来做成通用库，让你可以在 WebGPU 之上自由组合。如果你做过 Flutter 的自定义绘制，你会发现 impeller 的 Layer 树和 ZenFG 的 Pass 图在思路上有相通之处，都是把渲染任务组织成有向无环图，然后做拓扑排序和资源调度。

3. ZenFG 的核心细节与实操要点

3.1 资源声明：格式、尺寸与用途的取舍

在 ZenFG 里声明一个资源，你需要提供三个关键信息：格式、尺寸和用途。这三个参数看起来简单，但每一个都有坑。

格式方面，WebGPU 支持的纹理格式有几十种，选错了要么性能差，要么直接报错。比如后处理链里的中间纹理，很多人习惯用rgba8unorm，但实际上如果你的中间结果需要保留 HDR 信息，就得用rgba16float。我踩过一次坑：Bloom 的降采样链用了rgba8unorm，结果高光部分全部被截断，Bloom 效果看起来像一团灰雾。后来改成rgba16float才正常。

尺寸方面，ZenFG 支持相对尺寸和绝对尺寸。相对尺寸就是按屏幕比例来，比如0.5表示半分辨率。这个在 Bloom 和 SSAO 里特别有用，因为这两个效果本来就不需要全分辨率。但要注意，相对尺寸在窗口大小变化时需要重建资源，ZenFG 会自动处理这个，但你得确保你的 Pass 逻辑能适应尺寸变化。

用途方面，WebGPU 的纹理用途标志位包括TEXTURE_BINDING、STORAGE_BINDING、RENDER_ATTACHMENT、COPY_SRC、COPY_DST等。ZenFG 会根据你在 Pass 里的读写声明自动推断用途，但有时候推断不准，你就得手动指定。比如一张纹理既要作为渲染目标又要作为采样输入，你就得同时声明RENDER_ATTACHMENT和TEXTURE_BINDING。

提示：资源格式一旦确定就不要轻易改，因为改格式意味着改内存布局，可能会影响整个管线的性能。建议在项目初期就把所有中间纹理的格式定好，写进文档里。

3.2 Pass 的读写声明与依赖推导

Pass 的读写声明是 ZenFG 最核心的机制。你写builder.read(tex)的时候，FrameGraph 会记录“这个 Pass 依赖 tex 的当前版本”。你写builder.write(tex)的时候，FrameGraph 会创建一个新版本，后续的读取都会指向这个新版本。

这个版本管理机制解决了一个很常见的 bug：同一个资源被多个 Pass 读写时，顺序错乱导致读到旧数据。在命令式写法里，这种 bug 往往要调试半天才能定位；在 ZenFG 里，FrameGraph 会在构建阶段就检测出循环依赖或者版本冲突，直接报错。

但这里有个注意事项：读写声明必须和实际使用一致。如果你声明了builder.read(tex)但实际在渲染时没有绑定这张纹理，FrameGraph 可能会做出错误的资源复用决策。反过来，如果你实际用了某张纹理但没声明，FrameGraph 不会知道这个依赖，可能会导致资源被提前释放。我建议在开发阶段开启 ZenFG 的严格模式，它会校验声明和实际使用是否匹配。

3.3 资源别名与内存复用策略

资源别名是 ZenFG 最让我惊喜的功能。它的原理不复杂：如果两张纹理的生命周期没有重叠，就让它们共享同一块 GPU 内存。但实现起来需要考虑很多细节，比如内存对齐、格式兼容性、用途兼容性。

我实测了一个场景：一个包含 SSAO、Bloom、TAA 的后处理链，中间纹理大概有十二张。开启资源别名之后，实际分配的内存块只有五块。在移动端 GPU 上，这个优化直接让显存占用降了将近一半，帧率从 45 提到了 58。

但资源别名不是万能的。如果两张纹理的格式不同，比如一张是rgba16float一张是rgba8unorm，它们就不能共享内存。如果一张纹理需要COPY_SRC用途而另一张不需要，也可能影响复用。所以如果你发现别名效果不理想，先检查一下纹理的格式和用途是否一致。

注意：资源别名在调试阶段可能会让问题更难定位，因为你在 RenderDoc 里看到的纹理内容可能是被复用过的。建议在调试时关闭别名，等管线稳定后再开启。

4. 从零搭建一个 ZenFG 后处理管线

4.1 环境准备与项目初始化

我假设你已经有一个能跑 WebGPU 的环境，浏览器用 Chrome 113+ 或者 Edge 113+，Node.js 用 18 以上。ZenFG 本身是一个 npm 包，安装很简单：

npm install zenfg

如果你用的是原生 WebGPU 而不是 wgpu，需要确保你的浏览器支持navigator.gpu。我实测下来，Chrome 在 Windows 和 macOS 上的 WebGPU 支持已经比较稳定了，Linux 上还需要一些 flag。

项目初始化方面，我建议用 Vite 而不是 Webpack，因为 Vite 对 WebGPU 的 HMR 支持更好，改着色器代码的时候不用刷新页面。我的vite.config.js大概是这样：

import { defineConfig } from 'vite'; export default defineConfig({ server: { port: 5173, open: true, }, build: { target: 'esnext', }, });

初始化 ZenFG 的代码很简洁：

import { FrameGraph } from 'zenfg'; const adapter = await navigator.gpu.requestAdapter(); const device = await adapter.requestDevice(); const context = canvas.getContext('webgpu'); const format = navigator.gpu.getPreferredCanvasFormat(); context.configure({ device, format, alphaMode: 'premultiplied', }); const fg = new FrameGraph(device);

这里有个细节：alphaMode我建议用premultiplied而不是opaque，因为后处理链里经常需要做透明混合，premultiplied能避免边缘出现黑边。

4.2 声明几何 Pass 与深度纹理

几何 Pass 是整个管线的起点，它负责把场景里的模型画到颜色纹理和深度纹理上。在 ZenFG 里，你需要先声明这两张纹理：

const colorTex = fg.createTexture({ name: 'sceneColor', format: 'rgba16float', size: { relative: 1.0 }, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING, }); const depthTex = fg.createTexture({ name: 'sceneDepth', format: 'depth24plus', size: { relative: 1.0 }, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING, });

然后声明几何 Pass：

fg.addPass({ name: 'geometry', reads: [], writes: [colorTex, depthTex], execute: (builder, encoder) => { const colorView = builder.getView(colorTex); const depthView = builder.getView(depthTex); const renderPass = encoder.beginRenderPass({ colorAttachments: [{ view: colorView, clearValue: { r: 0.1, g: 0.1, b: 0.1, a: 1.0 }, loadOp: 'clear', storeOp: 'store', }], depthStencilAttachment: { view: depthView, depthClearValue: 1.0, depthLoadOp: 'clear', depthStoreOp: 'store', }, }); // 这里写你的绘制命令 renderPass.end(); }, });

这里有个经验：clearValue不要用纯黑，用深灰色。因为纯黑在后续的 Bloom 和色调映射里容易产生奇怪的伪影，深灰色更安全。

4.3 插入 SSAO 与模糊 Pass

SSAO Pass 需要读取深度纹理，输出一张 AO 纹理。在 ZenFG 里，你需要先声明 AO 纹理，然后声明 Pass：

const aoTex = fg.createTexture({ name: 'ssao', format: 'r8unorm', size: { relative: 0.5 }, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING, }); fg.addPass({ name: 'ssao', reads: [depthTex], writes: [aoTex], execute: (builder, encoder) => { const depthView = builder.getView(depthTex); const aoView = builder.getView(aoTex); // SSAO 渲染逻辑 }, });

模糊 Pass 读取 AO 纹理，输出模糊后的 AO。这里我建议用两次 Pass 做水平模糊和垂直模糊，而不是一次做二维模糊，因为分离式模糊的采样次数更少，性能更好：

const aoBlurTex = fg.createTexture({ name: 'ssaoBlur', format: 'r8unorm', size: { relative: 0.5 }, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING, }); fg.addPass({ name: 'ssaoBlurH', reads: [aoTex], writes: [aoBlurTex], execute: (builder, encoder) => { // 水平模糊 }, }); fg.addPass({ name: 'ssaoBlurV', reads: [aoBlurTex], writes: [aoTex], execute: (builder, encoder) => { // 垂直模糊，注意这里写回 aoTex }, });

注意最后一个 Pass 写回了aoTex，这在 ZenFG 里是允许的，FrameGraph 会创建一个新版本。但你要确保后续的读取都指向新版本，否则会读到旧数据。

4.4 光照 Pass 与 Bloom 链的衔接

光照 Pass 读取颜色、深度和模糊后的 AO，输出光照结果。这里的关键是资源版本管理：光照 Pass 读取的aoTex必须是模糊后的版本，而不是原始版本。ZenFG 会自动处理这个，因为你在模糊 Pass 里写了aoTex，后续读取都会指向新版本。

Bloom 链稍微复杂一点，它需要多次降采样和升采样。我通常用五级降采样，每级分辨率减半：

const bloomLevels = 5; const bloomTexs = []; for (let i = 0; i < bloomLevels; i++) { bloomTexs.push(fg.createTexture({ name: `bloom${i}`, format: 'rgba16float', size: { relative: 1.0 / Math.pow(2, i + 1) }, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING, })); }

降采样 Pass 读取上一级，写入下一级；升采样 Pass 反过来。这里有个性能技巧：降采样用双线性过滤，升采样用 tent 过滤，这样能在保证质量的同时减少采样次数。

4.5 合成 Pass 与最终输出

合成 Pass 把光照结果和 Bloom 结果叠加，然后做色调映射，最后输出到屏幕。这个 Pass 的写入目标是交换链纹理，不是 FrameGraph 管理的资源：

fg.addPass({ name: 'composite', reads: [lightingTex, bloomTexs[0]], writes: [], execute: (builder, encoder) => { const lightingView = builder.getView(lightingTex); const bloomView = builder.getView(bloomTexs[0]); const swapChainView = context.getCurrentTexture().createView(); const renderPass = encoder.beginRenderPass({ colorAttachments: [{ view: swapChainView, clearValue: { r: 0, g: 0, b: 0, a: 1 }, loadOp: 'clear', storeOp: 'store', }], }); // 合成逻辑 renderPass.end(); }, });

最后调用fg.execute()执行整个管线。ZenFG 会自动做拓扑排序，确保 Pass 按正确顺序执行。

5. 常见问题与排查技巧实录

5.1 黑屏与纹理未初始化问题

黑屏是 WebGPU 开发里最常见的问题，原因可能有很多。在 ZenFG 里，我遇到的黑屏问题大概分三类。

第一类是资源声明了但没写入。比如你声明了一张纹理，但没有任何 Pass 写入它，FrameGraph 可能会把它优化掉，导致后续读取时拿到空数据。解决方法是检查每个 Pass 的writes声明，确保所有被读取的资源都有 Pass 写入过。

第二类是读写顺序错误。比如你在光照 Pass 里读取了aoTex，但模糊 Pass 还没执行。ZenFG 的拓扑排序通常能避免这个问题，但如果你手动指定了 Pass 顺序，就可能出错。我建议不要手动指定顺序，让 FrameGraph 自己算。

第三类是格式不匹配。比如你把rgba16float的纹理绑定到了期望rgba8unorm的着色器上，WebGPU 会直接报错或者输出黑屏。检查方法是看控制台有没有格式相关的警告。

5.2 资源别名导致的调试困难

资源别名在提升性能的同时，确实会让调试变难。我遇到过一次诡异的问题：在 RenderDoc 里看某张纹理的内容，发现它和另一张完全不相关的纹理内容一样。排查了半天才发现是资源别名导致的，两张纹理共享了内存，RenderDoc 显示的是同一块内存的内容。

解决方法是在调试时关闭别名。ZenFG 提供了一个配置项：

const fg = new FrameGraph(device, { enableAliasing: false, });

等管线稳定后再开启别名，这样既能享受性能优化，又不会在调试时被误导。

5.3 性能瓶颈定位与优化

ZenFG 本身不提供性能分析工具，但你可以结合浏览器的 WebGPU 调试工具来做。我常用的方法是给每个 Pass 加时间戳查询：

const querySet = device.createQuerySet({ type: 'timestamp', count: 2, }); fg.addPass({ name: 'ssao', reads: [depthTex], writes: [aoTex], execute: (builder, encoder) => { encoder.writeTimestamp(querySet, 0); // 渲染逻辑 encoder.writeTimestamp(querySet, 1); }, });

然后读取查询结果，算出每个 Pass 的耗时。我实测下来，后处理链里最耗时的通常是 SSAO 和 Bloom 的降采样，这两个环节可以考虑降分辨率或者减少采样次数。

5.4 常见问题速查表

提示：ZenFG 的错误信息通常比较清晰，遇到问题时先看控制台，大部分问题都能从错误信息里找到线索。

6. 我个人的一些使用体会

用了 ZenFG 大概三个月，最大的感受是它把“管线编排”这件事从“手工活”变成了“声明式配置”。以前改一个后处理效果，我得小心翼翼地改绑定代码，生怕漏了哪张纹理；现在只需要改 Pass 的读写声明，FrameGraph 会自动处理资源分配和调度。

但 ZenFG 也不是银弹。它的抽象层确实带来了一些性能开销，尤其是在 Pass 数量少的时候，FrameGraph 的调度开销可能比手动写还大。我的经验是，Pass 数量少于五个的时候，直接手写更划算；超过十个 Pass，ZenFG 的优势就体现出来了。

另外，ZenFG 的文档目前还比较简略，很多细节需要读源码才能搞清楚。我建议新手先从官方示例入手，跑通一个最简单的后处理链，然后再逐步加 Pass。遇到问题可以去项目的讨论区搜一下，大部分常见问题都有人问过。

最后分享一个小技巧：在开发阶段，我会给每个 Pass 加一个debugName，然后在 RenderDoc 里就能看到清晰的 Pass 名称，而不是一堆匿名渲染通道。这个习惯帮我省了很多调试时间。