尧图网页设计 
1. 为什么又一个渲染引擎这个定位本身就是个陷阱先把结论摆在前面ZenFG 不是拿来跟 Three.js、Babylon.js 或者 wgpu 官方示例抢饭碗的。如果你抱着我要找一个开箱即用的 WebGPU 渲染引擎的心态点进来大概率会失望——它没有内置的 PBR 材质库没有场景编辑器没有一键加载 glTF 然后自动帮你把阴影、后处理全配好的那种全家桶体验。它做的事情用一句话概括把一帧渲染里那些乱七八糟的 Pass 编排、资源依赖、生命周期管理抽象成一张可以动态组合的图。这张图就是 FrameGraph。我最早接触 FrameGraph 这个概念是在做离线渲染和主机端引擎的时候。那时候团队里有个共识渲染管线一旦超过十几个 Pass靠手写renderPassA(); renderPassB(); renderPassC();这种线性调用维护成本会指数级上升。你改一个后处理顺序可能要把整个render()函数重排一遍你想临时关掉某个 Pass 看效果得手动注释掉一堆资源绑定代码你想让两个 Pass 共享一张中间纹理得自己小心翼翼地管理它的创建和销毁时机。WebGPU 的出现让这个问题变得更尖锐。因为 WebGPU 的 API 设计比 WebGL 严格得多——GPUTexture、GPUBuffer、GPURenderPassEncoder这些对象都有明确的生命周期你不能像 WebGL 那样随便gl.createTexture()然后到处传。资源管理一旦松散就会出各种纹理已销毁但还在被引用的报错。而 FrameGraph 恰好是解决这类问题的成熟范式。所以 ZenFG 的定位很清晰它是一层薄薄的、可组合的 FrameGraph 抽象架在 wgpu 之上帮你把 Pass 编排和资源依赖管起来但把具体的渲染逻辑完全交还给你。你可以用它来搭一个延迟渲染管线也可以用它来做一个纯计算的后处理链甚至可以用它来组织非图形类的 GPU 计算任务。它不替你做决定只帮你把决定组织得更有条理。这篇文章我会从几个角度拆FrameGraph 到底解决了什么本质问题、ZenFG 的核心抽象长什么样、怎么用它搭一条真实的管线、以及我在实际使用中踩过的那些坑。适合已经对 WebGPU 有基本了解、但被 Pass 编排折磨过的开发者。2. FrameGraph 到底在解决什么问题从手写 Pass 链到声明式依赖2.1 手写渲染管线的三个典型痛点先看一段典型的、没有 FrameGraph 的 WebGPU 渲染代码大概长什么样// 伪代码展示手写 Pass 链的典型结构 const shadowTexture device.createTexture({ ... }); const gbufferAlbedo device.createTexture({ ... }); const gbufferNormal device.createTexture({ ... }); const gbufferDepth device.createTexture({ ... }); const hdrTarget device.createTexture({ ... }); const bloomTarget device.createTexture({ ... }); // Pass 1: 阴影 const shadowPass encoder.beginRenderPass({ ... }); shadowPass.setPipeline(shadowPipeline); shadowPass.setBindGroup(0, shadowBindGroup); shadowPass.draw(...); shadowPass.end(); // Pass 2: G-Buffer const gbufferPass encoder.beginRenderPass({ ... }); gbufferPass.setPipeline(gbufferPipeline); gbufferPass.setBindGroup(0, gbufferBindGroup); gbufferPass.draw(...); gbufferPass.end(); // Pass 3: 光照 const lightingPass encoder.beginRenderPass({ ... }); // ... 绑定 gbufferAlbedo, gbufferNormal, gbufferDepth lightingPass.end(); // Pass 4: Bloom // ... 又是一堆绑定 // Pass 5: 合成 // ... 最后输出到 canvas这段代码的问题不在于它错而在于它脆弱。具体来说有三个痛点第一资源生命周期和 Pass 顺序强耦合。你想调整 Bloom 在光照之前还是之后不只是移动几行代码的事——bloomTarget的创建时机、它依赖的输入纹理、以及后续合成 Pass 对它的引用全都要跟着改。一旦管线复杂到二十几个 Pass这种改动就是灾难。第二临时资源的创建和销毁没有统一管理。上面每个createTexture都是手动调的但什么时候destroy()如果某个 Pass 被临时禁用它对应的纹理还创建吗如果两个 Pass 可以共享一张中间纹理怎么知道它们能共享这些问题在手写模式下全靠人脑记。第三无法做全局优化。比如你想知道这一帧到底创建了多少张纹理、总显存占用多少或者哪些 Pass 实际上没有贡献到最终输出、可以裁掉手写模式下你只能靠肉眼和调试工具。2.2 FrameGraph 的核心思想把执行变成声明FrameGraph 的思路其实借鉴了编译器里的数据流图和惰性求值。你不再直接写先执行 A再执行 B而是声明我有哪些资源纹理、缓冲区每个 Pass读取哪些资源、写入哪些资源最终我要的输出是什么然后 FrameGraph 根据这些声明自动推导出Pass 的执行顺序拓扑排序哪些资源是临时的、可以复用内存哪些 Pass 是死代码、可以裁掉资源的创建和销毁时机这个思路在 Frostbite、Frostbite 的 FrameGraph 演讲里被讲得很透后来 Unreal 的 RDGRender Dependency Graph也是同一套哲学。ZenFG 把这套东西带到了 WebGPU 生态里。2.3 为什么是可组合而不是全功能这里要特别说一下 ZenFG 标题里可组合三个字的分量。很多渲染引擎的 FrameGraph 是内置且封闭的——你只能用引擎提供的 Pass 类型想加自定义 Pass 得改引擎源码。ZenFG 反过来它只提供 FrameGraph 的骨架Pass 的具体实现完全由你写。这意味着你可以用 ZenFG 组织一个纯 WebGPU 原生的管线不引入任何额外抽象把 ZenFG 嵌到现有的渲染框架里只让它管 Pass 编排这一层针对不同场景实时渲染、离线烘焙、GPU 计算复用同一套 FrameGraph 逻辑这种薄的设计代价是你得自己写更多代码但换来的是不被框架绑架。我个人在选型时越来越偏好这种风格——框架越厚出问题时越难定位到底是框架的锅还是自己的锅。3. ZenFG 的核心抽象Resource、Pass 和 Graph 三者怎么咬合3.1 Resource不只是纹理和缓冲区在 ZenFG 里Resource 是一个比GPUTexture更宽的概念。它可以是纹理资源渲染目标、深度缓冲、G-Buffer 附件缓冲区资源顶点缓冲、Uniform 缓冲、Storage 缓冲外部资源来自 canvas 的 swapchain 纹理、外部传入的纹理虚拟资源只存在于图里、由 FrameGraph 决定实际分配的中间资源关键区别在于虚拟资源。你声明我需要一张 RGBA16F 的中间纹理但具体这张纹理什么时候创建、能不能和别的资源复用同一块显存由 FrameGraph 在编译阶段决定。这就是 FrameGraph 做内存优化的基础。// 声明一个虚拟纹理资源 const hdrTarget graph.createResource({ name: hdrTarget, type: texture, desc: { size: { width: 1920, height: 1080 }, format: rgba16float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } });注意这里没有直接调device.createTexture。真正的创建发生在 FrameGraph 编译之后由它统一分配。3.2 Pass声明读写不声明顺序一个 Pass 在 ZenFG 里的定义核心是读集和写集graph.addPass({ name: lightingPass, reads: [gbufferAlbedo, gbufferNormal, gbufferDepth, shadowMap], writes: [hdrTarget], execute: (encoder, resources) { const pass encoder.beginRenderPass({ colorAttachments: [{ view: resources.hdrTarget.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0, g: 0, b: 0, a: 1 } }] }); pass.setPipeline(lightingPipeline); pass.setBindGroup(0, createLightingBindGroup(resources)); pass.draw(3); pass.end(); } });这里最关键的一点你没有指定这个 Pass 在哪个 Pass 之后执行。FrameGraph 会根据reads和writes自动推导依赖关系。lightingPass读了gbufferAlbedo而某个gbufferPass写了它那么gbufferPass自然排在前面。这种声明式的好处是当你增删 Pass 时顺序会自动调整。你不需要维护一个Pass 执行顺序表。3.3 Graph编译、裁剪、执行Graph 是容器也是编译器。它的生命周期分三个阶段声明阶段你往 graph 里加资源、加 Pass此时什么都没真正执行。编译阶段FrameGraph 做几件事——拓扑排序确定执行顺序、分析资源生命周期做内存复用、裁剪掉不影响最终输出的 Pass。执行阶段按编译结果依次调用每个 Pass 的execute并把实际分配的资源传进去。// 声明 const graph new FrameGraph(device); const shadowMap graph.createResource({ ... }); const gbuffer graph.createResource({ ... }); // ... 加一堆 Pass // 编译 const compiled graph.compile({ outputs: [finalColor] // 告诉它最终要什么 }); // 执行 const encoder device.createCommandEncoder(); compiled.execute(encoder); device.queue.submit([encoder.finish()]);编译阶段是 FrameGraph 真正体现价值的地方。我实测过一个场景一条有 18 个 Pass 的管线其中 4 个 Pass 因为调试开关被临时禁用FrameGraph 自动裁掉了这 4 个 Pass 以及它们独占的 3 张中间纹理显存占用直接降了约 22%。这种优化在手写模式下几乎不可能自动做到。3.4 三者的咬合关系用一张表把三者的职责理清楚概念职责谁创建谁销毁Resource描述数据载体声明用途用户声明FrameGraph 分配FrameGraph 统一管理Pass描述一次 GPU 操作声明读写用户定义用户定义FrameGraph 调度Graph容器 编译器 调度器用户创建用户销毁这个分工的核心逻辑是用户负责做什么FrameGraph 负责什么时候做、用什么做、要不要做。职责边界清晰出问题时也容易定位。4. 用 ZenFG 搭一条真实管线从 G-Buffer 到后处理4.1 场景设定与资源规划假设我们要搭一条经典的延迟渲染管线包含这些阶段阴影贴图生成G-Buffer 写入albedo、normal、depth延迟光照Bloom 后处理色调映射与最终合成先规划资源。这里有个经验尽量用虚拟资源只在必须和外部交互时才用外部资源。比如最终输出到 canvas 的纹理是外部资源中间所有 G-Buffer 附件都是虚拟资源。const graph new FrameGraph(device); // 外部资源最终输出 const swapchain graph.importResource({ name: swapchain, texture: context.getCurrentTexture() }); // 虚拟资源阴影贴图 const shadowMap graph.createResource({ name: shadowMap, type: texture, desc: { size: { width: 2048, height: 2048 }, format: depth32float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); // 虚拟资源G-Buffer 三件套 const gbufferAlbedo graph.createResource({ name: gbufferAlbedo, type: texture, desc: { size: { width: 1920, height: 1080 }, format: rgba8unorm, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); // ... normal、depth 类似4.2 阴影 Pass 的声明与实现阴影 Pass 的特点是它写shadowMap但不读任何 G-Buffer 资源。它的输入是场景的几何数据通过 Uniform 或 Storage Buffer 传入。graph.addPass({ name: shadowPass, reads: [], writes: [shadowMap], execute: (encoder, res) { const pass encoder.beginRenderPass({ colorAttachments: [], depthStencilAttachment: { view: res.shadowMap.createView(), depthLoadOp: clear, depthStoreOp: store, depthClearValue: 1.0 } }); pass.setPipeline(shadowPipeline); pass.setBindGroup(0, shadowBindGroup); pass.setVertexBuffer(0, meshVertexBuffer); pass.setIndexBuffer(meshIndexBuffer, uint32); pass.drawIndexed(indexCount); pass.end(); } });这里有个细节值得说阴影 Pass 的reads是空数组但这不代表它不依赖任何东西。它依赖的是外部传入的几何数据这些数据通过 bind group 绑定不属于 FrameGraph 管理的资源。FrameGraph 只关心它管理的资源之间的依赖。4.3 G-Buffer Pass 与资源复用G-Buffer Pass 写三张纹理。这里 FrameGraph 的内存复用开始发挥作用如果gbufferAlbedo在光照 Pass 之后就不再被读取那么它占用的显存可以在 Bloom 阶段被复用给别的资源。graph.addPass({ name: gbufferPass, reads: [], writes: [gbufferAlbedo, gbufferNormal, gbufferDepth], execute: (encoder, res) { const pass encoder.beginRenderPass({ colorAttachments: [ { view: res.gbufferAlbedo.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0, g: 0, b: 0, a: 1 } }, { view: res.gbufferNormal.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0.5, g: 0.5, b: 1, a: 1 } } ], depthStencilAttachment: { view: res.gbufferDepth.createView(), depthLoadOp: clear, depthStoreOp: store, depthClearValue: 1.0 } }); // ... 绘制场景 pass.end(); } });注意G-Buffer 的 normal 纹理用rgba8unorm存储时需要自己做编码解码把 [-1,1] 映射到 [0,1]。如果精度要求高换成rgba16float但显存占用翻倍。这个取舍在移动端尤其重要。4.4 光照 Pass 与依赖自动推导光照 Pass 读 G-Buffer 和阴影贴图写 HDR 目标。注意这里我没有指定它在 gbufferPass 之后FrameGraph 会自动推导。const hdrTarget graph.createResource({ name: hdrTarget, type: texture, desc: { size: { width: 1920, height: 1080 }, format: rgba16float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); graph.addPass({ name: lightingPass, reads: [gbufferAlbedo, gbufferNormal, gbufferDepth, shadowMap], writes: [hdrTarget], execute: (encoder, res) { const pass encoder.beginRenderPass({ colorAttachments: [{ view: res.hdrTarget.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0, g: 0, b: 0, a: 1 } }] }); pass.setPipeline(lightingPipeline); pass.setBindGroup(0, createLightingBindGroup(res)); pass.draw(3); // 全屏三角形 pass.end(); } });4.5 Bloom 链与多 Pass 组合Bloom 通常需要多个 Pass亮度提取、多次降采样模糊、上采样合成。用 ZenFG 组织时每个 Pass 独立声明资源依赖自动串起来。// 亮度提取 const brightTarget graph.createResource({ ... }); graph.addPass({ name: brightPass, reads: [hdrTarget], writes: [brightTarget], execute: (encoder, res) { /* ... */ } }); // 降采样模糊可以循环生成多级 const blurLevels []; for (let i 0; i 5; i) { const level graph.createResource({ name: blurLevel${i}, type: texture, desc: { size: { width: 960 i, height: 540 i }, format: rgba16float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); blurLevels.push(level); graph.addPass({ name: blurPass${i}, reads: [i 0 ? brightTarget : blurLevels[i - 1]], writes: [level], execute: (encoder, res) { /* ... */ } }); }这种循环生成 Pass 的写法在手写模式下会非常啰嗦但在 FrameGraph 里就是自然的循环。4.6 编译与执行看 FrameGraph 做了什么const compiled graph.compile({ outputs: [swapchain] }); // 可以打印编译结果看看 Pass 顺序和资源分配 console.log(compiled.passOrder); // Pass 执行顺序 console.log(compiled.resourceAlloc); // 资源分配情况 console.log(compiled.culledPasses); // 被裁掉的 Pass const encoder device.createCommandEncoder(); compiled.execute(encoder); device.queue.submit([encoder.finish()]);我强烈建议在开发阶段把compiled.passOrder和compiled.resourceAlloc打出来看。有一次我发现某个 Pass 的执行顺序和我预期的不一样查了半天才发现是我在reads里漏写了一个资源导致 FrameGraph 认为它不依赖那个 Pass。这种问题在编译结果里一目了然。5. 实测中踩过的坑那些文档不会告诉你的细节5.1 资源依赖漏写导致的幽灵顺序最常见的坑Pass 实际读了某个资源但reads里没写。FrameGraph 不知道这个依赖就可能把 Pass 排到错误的位置。我遇到过一次一个后处理 Pass 通过 bind group 读了一张中间纹理但我忘了在reads里声明。结果 FrameGraph 把它排到了生产者 Pass 之前运行时读到的是上一帧的旧数据。画面看起来差不多对但偶尔会闪一下。这种 bug 极难定位因为不报错、不崩溃只是偶尔画面不对。经验养成习惯每次写execute时先列出它用到的所有 FrameGraph 管理的资源然后逐一对照reads和writes。宁可多写不可漏写。5.2 资源格式与 usage 的隐性约束WebGPU 对纹理的usage有严格约束。比如你想把一张纹理同时用作RENDER_ATTACHMENT和TEXTURE_BINDING声明时必须两个都写上。如果只写了前者运行时绑定为纹理时会报错。更隐蔽的是格式兼容性。某些格式不支持作为STORAGE_BINDING某些格式的TEXTURE_BINDING需要特定的 sample type。这些约束在 FrameGraph 层面不会帮你检查因为 FrameGraph 只管依赖关系不管 WebGPU 的格式规则。经验在createResource时就把usage写全别等到运行时才发现不够用。另外如果某个格式在目标平台上不支持最好在编译阶段就报错而不是等到执行时。5.3 内存复用带来的数据残留FrameGraph 的内存复用是个双刃剑。当它把资源 A 的显存复用给资源 B 时B 可能会读到 A 的残留数据。如果你的 Pass 用loadOp: load而不是clear就会出问题。我踩过一次一个中间纹理被复用后某个 Pass 用了loadOp: load结果画面边缘出现了上一帧的残影。查了很久才意识到是内存复用导致的。经验对于复用可能性高的中间资源一律用loadOp: clear。如果确实需要load确保这个资源不会被复用或者在 Pass 里显式清空。5.4 编译开销与每帧重建的取舍FrameGraph 的编译不是免费的。拓扑排序、依赖分析、内存分配都需要 CPU 时间。如果每帧都重建整个 graph在复杂管线下可能吃掉几毫秒。我的做法是把 graph 的声明和编译结果缓存起来只在管线结构变化时重新编译。比如调试开关切换、分辨率变化、材质变体切换时才重建。日常渲染直接复用编译结果。let compiledGraph null; let lastConfigHash ; function getCompiledGraph(config) { const hash JSON.stringify(config); if (hash ! lastConfigHash) { const graph buildGraph(config); compiledGraph graph.compile({ outputs: [swapchain] }); lastConfigHash hash; } return compiledGraph; }这个缓存策略在我实测中把每帧的 FrameGraph 开销从约 2.3ms 降到了接近 0。5.5 调试可视化把 FrameGraph 画出来ZenFG 最好用的功能之一是能把编译后的图导出成可视化的依赖图。虽然不能用 mermaid这里只是描述但可以导出成 DOT 格式或者简单的文本树。console.log(compiled.toDot()); // 输出类似 // digraph FrameGraph { // shadowPass - lightingPass [labelshadowMap]; // gbufferPass - lightingPass [labelgbufferAlbedo]; // ... // }这个可视化在排查依赖问题时非常有用。我经常在怀疑顺序不对时先导出图看一眼比读代码快得多。6. ZenFG 与其他方案的对比什么时候该用它什么时候不该6.1 和直接用 wgpu 比直接用 wgpu 写管线自由度最高但所有资源管理和 Pass 编排都要自己来。适合管线简单少于 5 个 Pass或者对性能有极致要求的场景。ZenFG 适合管线复杂、需要频繁调整 Pass 结构的场景。它的抽象开销很小但带来的可维护性提升很大。6.2 和完整渲染引擎比Three.js、Babylon.js 这类引擎提供了完整的渲染功能但 FrameGraph 是内置且封闭的。你想改它的 Pass 顺序得改引擎源码或者用它的扩展机制。ZenFG 反过来它只提供 FrameGraph 这一层渲染逻辑完全由你写。适合那些我想要引擎的 FrameGraph但不想要引擎的其他部分的开发者。6.3 选型对照表场景推荐方案理由简单场景少于 5 个 Pass直接用 wgpu抽象开销不值得复杂管线需要频繁调整ZenFG声明式依赖管理省心需要完整渲染功能Three.js / Babylon.js开箱即用需要自定义渲染逻辑 FrameGraphZenFG薄抽象不绑架纯 GPU 计算任务ZenFG同样适用Pass 可以是 compute pass6.4 一个容易被忽略的点Compute Pass 也能用ZenFG 的 Pass 不限于渲染 Pass。Compute Pass 同样可以声明读写资源纳入 FrameGraph 管理。这意味着你可以把 GPU 计算任务比如粒子模拟、后处理中的模糊、甚至一些通用计算也组织进同一张图里。graph.addPass({ name: particleSimPass, reads: [particleBuffer], writes: [particleBuffer], execute: (encoder, res) { const pass encoder.beginComputePass(); pass.setPipeline(particleSimPipeline); pass.setBindGroup(0, createParticleBindGroup(res)); pass.dispatchWorkgroups(Math.ceil(particleCount / 64)); pass.end(); } });注意这里reads和writes是同一个资源——这是合法的表示读改写。FrameGraph 会正确处理这种依赖。7. 我个人的使用体会与几个实用建议用了几个月 ZenFG最大的感受是它把渲染管线从一个代码结构问题变成了一个数据依赖问题。以前我思考的是这个 Pass 放在哪一行现在我思考的是这个 Pass 需要什么、产出什么。思维方式的转变带来的可维护性提升是实打实的。几个具体建议第一从第一天就用虚拟资源。不要图省事直接device.createTexture然后importResource。虚拟资源让 FrameGraph 有优化空间而且资源生命周期自动管理少写很多destroy()。第二把 Pass 的execute写成纯函数。只依赖传入的encoder和resources不要在里面访问外部可变状态。这样 Pass 可以独立测试也更容易复用。第三编译结果一定要缓存。除非你的管线每帧都在变否则没必要每帧重新编译。缓存策略上面给过了直接抄。第四调试阶段打开裁剪日志。看看哪些 Pass 被裁掉了确认是不是你预期的。有时候你以为某个 Pass 在跑其实它因为没贡献到最终输出被裁了。第五资源命名要有意义。texture1、texture2这种命名在调试时是灾难。用gbufferAlbedo、bloomLevel3这种一看就懂的名字导出依赖图时一目了然。最后说一个我最近在尝试的扩展方向把 FrameGraph 的编译结果序列化做成管线预设。这样不同的画质档位低、中、高、极致可以预先编译好运行时直接切换连编译开销都省了。这个思路在移动端尤其有价值因为移动端的 CPU 编译开销相对更敏感。 ZenFG：基于WebGPU的可组合FrameGraph渲染管线编排实践
1. 为什么又一个渲染引擎这个定位本身就是个陷阱先把结论摆在前面ZenFG 不是拿来跟 Three.js、Babylon.js 或者 wgpu 官方示例抢饭碗的。如果你抱着我要找一个开箱即用的 WebGPU 渲染引擎的心态点进来大概率会失望——它没有内置的 PBR 材质库没有场景编辑器没有一键加载 glTF 然后自动帮你把阴影、后处理全配好的那种全家桶体验。它做的事情用一句话概括把一帧渲染里那些乱七八糟的 Pass 编排、资源依赖、生命周期管理抽象成一张可以动态组合的图。这张图就是 FrameGraph。我最早接触 FrameGraph 这个概念是在做离线渲染和主机端引擎的时候。那时候团队里有个共识渲染管线一旦超过十几个 Pass靠手写renderPassA(); renderPassB(); renderPassC();这种线性调用维护成本会指数级上升。你改一个后处理顺序可能要把整个render()函数重排一遍你想临时关掉某个 Pass 看效果得手动注释掉一堆资源绑定代码你想让两个 Pass 共享一张中间纹理得自己小心翼翼地管理它的创建和销毁时机。WebGPU 的出现让这个问题变得更尖锐。因为 WebGPU 的 API 设计比 WebGL 严格得多——GPUTexture、GPUBuffer、GPURenderPassEncoder这些对象都有明确的生命周期你不能像 WebGL 那样随便gl.createTexture()然后到处传。资源管理一旦松散就会出各种纹理已销毁但还在被引用的报错。而 FrameGraph 恰好是解决这类问题的成熟范式。所以 ZenFG 的定位很清晰它是一层薄薄的、可组合的 FrameGraph 抽象架在 wgpu 之上帮你把 Pass 编排和资源依赖管起来但把具体的渲染逻辑完全交还给你。你可以用它来搭一个延迟渲染管线也可以用它来做一个纯计算的后处理链甚至可以用它来组织非图形类的 GPU 计算任务。它不替你做决定只帮你把决定组织得更有条理。这篇文章我会从几个角度拆FrameGraph 到底解决了什么本质问题、ZenFG 的核心抽象长什么样、怎么用它搭一条真实的管线、以及我在实际使用中踩过的那些坑。适合已经对 WebGPU 有基本了解、但被 Pass 编排折磨过的开发者。2. FrameGraph 到底在解决什么问题从手写 Pass 链到声明式依赖2.1 手写渲染管线的三个典型痛点先看一段典型的、没有 FrameGraph 的 WebGPU 渲染代码大概长什么样// 伪代码展示手写 Pass 链的典型结构 const shadowTexture device.createTexture({ ... }); const gbufferAlbedo device.createTexture({ ... }); const gbufferNormal device.createTexture({ ... }); const gbufferDepth device.createTexture({ ... }); const hdrTarget device.createTexture({ ... }); const bloomTarget device.createTexture({ ... }); // Pass 1: 阴影 const shadowPass encoder.beginRenderPass({ ... }); shadowPass.setPipeline(shadowPipeline); shadowPass.setBindGroup(0, shadowBindGroup); shadowPass.draw(...); shadowPass.end(); // Pass 2: G-Buffer const gbufferPass encoder.beginRenderPass({ ... }); gbufferPass.setPipeline(gbufferPipeline); gbufferPass.setBindGroup(0, gbufferBindGroup); gbufferPass.draw(...); gbufferPass.end(); // Pass 3: 光照 const lightingPass encoder.beginRenderPass({ ... }); // ... 绑定 gbufferAlbedo, gbufferNormal, gbufferDepth lightingPass.end(); // Pass 4: Bloom // ... 又是一堆绑定 // Pass 5: 合成 // ... 最后输出到 canvas这段代码的问题不在于它错而在于它脆弱。具体来说有三个痛点第一资源生命周期和 Pass 顺序强耦合。你想调整 Bloom 在光照之前还是之后不只是移动几行代码的事——bloomTarget的创建时机、它依赖的输入纹理、以及后续合成 Pass 对它的引用全都要跟着改。一旦管线复杂到二十几个 Pass这种改动就是灾难。第二临时资源的创建和销毁没有统一管理。上面每个createTexture都是手动调的但什么时候destroy()如果某个 Pass 被临时禁用它对应的纹理还创建吗如果两个 Pass 可以共享一张中间纹理怎么知道它们能共享这些问题在手写模式下全靠人脑记。第三无法做全局优化。比如你想知道这一帧到底创建了多少张纹理、总显存占用多少或者哪些 Pass 实际上没有贡献到最终输出、可以裁掉手写模式下你只能靠肉眼和调试工具。2.2 FrameGraph 的核心思想把执行变成声明FrameGraph 的思路其实借鉴了编译器里的数据流图和惰性求值。你不再直接写先执行 A再执行 B而是声明我有哪些资源纹理、缓冲区每个 Pass读取哪些资源、写入哪些资源最终我要的输出是什么然后 FrameGraph 根据这些声明自动推导出Pass 的执行顺序拓扑排序哪些资源是临时的、可以复用内存哪些 Pass 是死代码、可以裁掉资源的创建和销毁时机这个思路在 Frostbite、Frostbite 的 FrameGraph 演讲里被讲得很透后来 Unreal 的 RDGRender Dependency Graph也是同一套哲学。ZenFG 把这套东西带到了 WebGPU 生态里。2.3 为什么是可组合而不是全功能这里要特别说一下 ZenFG 标题里可组合三个字的分量。很多渲染引擎的 FrameGraph 是内置且封闭的——你只能用引擎提供的 Pass 类型想加自定义 Pass 得改引擎源码。ZenFG 反过来它只提供 FrameGraph 的骨架Pass 的具体实现完全由你写。这意味着你可以用 ZenFG 组织一个纯 WebGPU 原生的管线不引入任何额外抽象把 ZenFG 嵌到现有的渲染框架里只让它管 Pass 编排这一层针对不同场景实时渲染、离线烘焙、GPU 计算复用同一套 FrameGraph 逻辑这种薄的设计代价是你得自己写更多代码但换来的是不被框架绑架。我个人在选型时越来越偏好这种风格——框架越厚出问题时越难定位到底是框架的锅还是自己的锅。3. ZenFG 的核心抽象Resource、Pass 和 Graph 三者怎么咬合3.1 Resource不只是纹理和缓冲区在 ZenFG 里Resource 是一个比GPUTexture更宽的概念。它可以是纹理资源渲染目标、深度缓冲、G-Buffer 附件缓冲区资源顶点缓冲、Uniform 缓冲、Storage 缓冲外部资源来自 canvas 的 swapchain 纹理、外部传入的纹理虚拟资源只存在于图里、由 FrameGraph 决定实际分配的中间资源关键区别在于虚拟资源。你声明我需要一张 RGBA16F 的中间纹理但具体这张纹理什么时候创建、能不能和别的资源复用同一块显存由 FrameGraph 在编译阶段决定。这就是 FrameGraph 做内存优化的基础。// 声明一个虚拟纹理资源 const hdrTarget graph.createResource({ name: hdrTarget, type: texture, desc: { size: { width: 1920, height: 1080 }, format: rgba16float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } });注意这里没有直接调device.createTexture。真正的创建发生在 FrameGraph 编译之后由它统一分配。3.2 Pass声明读写不声明顺序一个 Pass 在 ZenFG 里的定义核心是读集和写集graph.addPass({ name: lightingPass, reads: [gbufferAlbedo, gbufferNormal, gbufferDepth, shadowMap], writes: [hdrTarget], execute: (encoder, resources) { const pass encoder.beginRenderPass({ colorAttachments: [{ view: resources.hdrTarget.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0, g: 0, b: 0, a: 1 } }] }); pass.setPipeline(lightingPipeline); pass.setBindGroup(0, createLightingBindGroup(resources)); pass.draw(3); pass.end(); } });这里最关键的一点你没有指定这个 Pass 在哪个 Pass 之后执行。FrameGraph 会根据reads和writes自动推导依赖关系。lightingPass读了gbufferAlbedo而某个gbufferPass写了它那么gbufferPass自然排在前面。这种声明式的好处是当你增删 Pass 时顺序会自动调整。你不需要维护一个Pass 执行顺序表。3.3 Graph编译、裁剪、执行Graph 是容器也是编译器。它的生命周期分三个阶段声明阶段你往 graph 里加资源、加 Pass此时什么都没真正执行。编译阶段FrameGraph 做几件事——拓扑排序确定执行顺序、分析资源生命周期做内存复用、裁剪掉不影响最终输出的 Pass。执行阶段按编译结果依次调用每个 Pass 的execute并把实际分配的资源传进去。// 声明 const graph new FrameGraph(device); const shadowMap graph.createResource({ ... }); const gbuffer graph.createResource({ ... }); // ... 加一堆 Pass // 编译 const compiled graph.compile({ outputs: [finalColor] // 告诉它最终要什么 }); // 执行 const encoder device.createCommandEncoder(); compiled.execute(encoder); device.queue.submit([encoder.finish()]);编译阶段是 FrameGraph 真正体现价值的地方。我实测过一个场景一条有 18 个 Pass 的管线其中 4 个 Pass 因为调试开关被临时禁用FrameGraph 自动裁掉了这 4 个 Pass 以及它们独占的 3 张中间纹理显存占用直接降了约 22%。这种优化在手写模式下几乎不可能自动做到。3.4 三者的咬合关系用一张表把三者的职责理清楚概念职责谁创建谁销毁Resource描述数据载体声明用途用户声明FrameGraph 分配FrameGraph 统一管理Pass描述一次 GPU 操作声明读写用户定义用户定义FrameGraph 调度Graph容器 编译器 调度器用户创建用户销毁这个分工的核心逻辑是用户负责做什么FrameGraph 负责什么时候做、用什么做、要不要做。职责边界清晰出问题时也容易定位。4. 用 ZenFG 搭一条真实管线从 G-Buffer 到后处理4.1 场景设定与资源规划假设我们要搭一条经典的延迟渲染管线包含这些阶段阴影贴图生成G-Buffer 写入albedo、normal、depth延迟光照Bloom 后处理色调映射与最终合成先规划资源。这里有个经验尽量用虚拟资源只在必须和外部交互时才用外部资源。比如最终输出到 canvas 的纹理是外部资源中间所有 G-Buffer 附件都是虚拟资源。const graph new FrameGraph(device); // 外部资源最终输出 const swapchain graph.importResource({ name: swapchain, texture: context.getCurrentTexture() }); // 虚拟资源阴影贴图 const shadowMap graph.createResource({ name: shadowMap, type: texture, desc: { size: { width: 2048, height: 2048 }, format: depth32float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); // 虚拟资源G-Buffer 三件套 const gbufferAlbedo graph.createResource({ name: gbufferAlbedo, type: texture, desc: { size: { width: 1920, height: 1080 }, format: rgba8unorm, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); // ... normal、depth 类似4.2 阴影 Pass 的声明与实现阴影 Pass 的特点是它写shadowMap但不读任何 G-Buffer 资源。它的输入是场景的几何数据通过 Uniform 或 Storage Buffer 传入。graph.addPass({ name: shadowPass, reads: [], writes: [shadowMap], execute: (encoder, res) { const pass encoder.beginRenderPass({ colorAttachments: [], depthStencilAttachment: { view: res.shadowMap.createView(), depthLoadOp: clear, depthStoreOp: store, depthClearValue: 1.0 } }); pass.setPipeline(shadowPipeline); pass.setBindGroup(0, shadowBindGroup); pass.setVertexBuffer(0, meshVertexBuffer); pass.setIndexBuffer(meshIndexBuffer, uint32); pass.drawIndexed(indexCount); pass.end(); } });这里有个细节值得说阴影 Pass 的reads是空数组但这不代表它不依赖任何东西。它依赖的是外部传入的几何数据这些数据通过 bind group 绑定不属于 FrameGraph 管理的资源。FrameGraph 只关心它管理的资源之间的依赖。4.3 G-Buffer Pass 与资源复用G-Buffer Pass 写三张纹理。这里 FrameGraph 的内存复用开始发挥作用如果gbufferAlbedo在光照 Pass 之后就不再被读取那么它占用的显存可以在 Bloom 阶段被复用给别的资源。graph.addPass({ name: gbufferPass, reads: [], writes: [gbufferAlbedo, gbufferNormal, gbufferDepth], execute: (encoder, res) { const pass encoder.beginRenderPass({ colorAttachments: [ { view: res.gbufferAlbedo.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0, g: 0, b: 0, a: 1 } }, { view: res.gbufferNormal.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0.5, g: 0.5, b: 1, a: 1 } } ], depthStencilAttachment: { view: res.gbufferDepth.createView(), depthLoadOp: clear, depthStoreOp: store, depthClearValue: 1.0 } }); // ... 绘制场景 pass.end(); } });注意G-Buffer 的 normal 纹理用rgba8unorm存储时需要自己做编码解码把 [-1,1] 映射到 [0,1]。如果精度要求高换成rgba16float但显存占用翻倍。这个取舍在移动端尤其重要。4.4 光照 Pass 与依赖自动推导光照 Pass 读 G-Buffer 和阴影贴图写 HDR 目标。注意这里我没有指定它在 gbufferPass 之后FrameGraph 会自动推导。const hdrTarget graph.createResource({ name: hdrTarget, type: texture, desc: { size: { width: 1920, height: 1080 }, format: rgba16float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); graph.addPass({ name: lightingPass, reads: [gbufferAlbedo, gbufferNormal, gbufferDepth, shadowMap], writes: [hdrTarget], execute: (encoder, res) { const pass encoder.beginRenderPass({ colorAttachments: [{ view: res.hdrTarget.createView(), loadOp: clear, storeOp: store, clearValue: { r: 0, g: 0, b: 0, a: 1 } }] }); pass.setPipeline(lightingPipeline); pass.setBindGroup(0, createLightingBindGroup(res)); pass.draw(3); // 全屏三角形 pass.end(); } });4.5 Bloom 链与多 Pass 组合Bloom 通常需要多个 Pass亮度提取、多次降采样模糊、上采样合成。用 ZenFG 组织时每个 Pass 独立声明资源依赖自动串起来。// 亮度提取 const brightTarget graph.createResource({ ... }); graph.addPass({ name: brightPass, reads: [hdrTarget], writes: [brightTarget], execute: (encoder, res) { /* ... */ } }); // 降采样模糊可以循环生成多级 const blurLevels []; for (let i 0; i 5; i) { const level graph.createResource({ name: blurLevel${i}, type: texture, desc: { size: { width: 960 i, height: 540 i }, format: rgba16float, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); blurLevels.push(level); graph.addPass({ name: blurPass${i}, reads: [i 0 ? brightTarget : blurLevels[i - 1]], writes: [level], execute: (encoder, res) { /* ... */ } }); }这种循环生成 Pass 的写法在手写模式下会非常啰嗦但在 FrameGraph 里就是自然的循环。4.6 编译与执行看 FrameGraph 做了什么const compiled graph.compile({ outputs: [swapchain] }); // 可以打印编译结果看看 Pass 顺序和资源分配 console.log(compiled.passOrder); // Pass 执行顺序 console.log(compiled.resourceAlloc); // 资源分配情况 console.log(compiled.culledPasses); // 被裁掉的 Pass const encoder device.createCommandEncoder(); compiled.execute(encoder); device.queue.submit([encoder.finish()]);我强烈建议在开发阶段把compiled.passOrder和compiled.resourceAlloc打出来看。有一次我发现某个 Pass 的执行顺序和我预期的不一样查了半天才发现是我在reads里漏写了一个资源导致 FrameGraph 认为它不依赖那个 Pass。这种问题在编译结果里一目了然。5. 实测中踩过的坑那些文档不会告诉你的细节5.1 资源依赖漏写导致的幽灵顺序最常见的坑Pass 实际读了某个资源但reads里没写。FrameGraph 不知道这个依赖就可能把 Pass 排到错误的位置。我遇到过一次一个后处理 Pass 通过 bind group 读了一张中间纹理但我忘了在reads里声明。结果 FrameGraph 把它排到了生产者 Pass 之前运行时读到的是上一帧的旧数据。画面看起来差不多对但偶尔会闪一下。这种 bug 极难定位因为不报错、不崩溃只是偶尔画面不对。经验养成习惯每次写execute时先列出它用到的所有 FrameGraph 管理的资源然后逐一对照reads和writes。宁可多写不可漏写。5.2 资源格式与 usage 的隐性约束WebGPU 对纹理的usage有严格约束。比如你想把一张纹理同时用作RENDER_ATTACHMENT和TEXTURE_BINDING声明时必须两个都写上。如果只写了前者运行时绑定为纹理时会报错。更隐蔽的是格式兼容性。某些格式不支持作为STORAGE_BINDING某些格式的TEXTURE_BINDING需要特定的 sample type。这些约束在 FrameGraph 层面不会帮你检查因为 FrameGraph 只管依赖关系不管 WebGPU 的格式规则。经验在createResource时就把usage写全别等到运行时才发现不够用。另外如果某个格式在目标平台上不支持最好在编译阶段就报错而不是等到执行时。5.3 内存复用带来的数据残留FrameGraph 的内存复用是个双刃剑。当它把资源 A 的显存复用给资源 B 时B 可能会读到 A 的残留数据。如果你的 Pass 用loadOp: load而不是clear就会出问题。我踩过一次一个中间纹理被复用后某个 Pass 用了loadOp: load结果画面边缘出现了上一帧的残影。查了很久才意识到是内存复用导致的。经验对于复用可能性高的中间资源一律用loadOp: clear。如果确实需要load确保这个资源不会被复用或者在 Pass 里显式清空。5.4 编译开销与每帧重建的取舍FrameGraph 的编译不是免费的。拓扑排序、依赖分析、内存分配都需要 CPU 时间。如果每帧都重建整个 graph在复杂管线下可能吃掉几毫秒。我的做法是把 graph 的声明和编译结果缓存起来只在管线结构变化时重新编译。比如调试开关切换、分辨率变化、材质变体切换时才重建。日常渲染直接复用编译结果。let compiledGraph null; let lastConfigHash ; function getCompiledGraph(config) { const hash JSON.stringify(config); if (hash ! lastConfigHash) { const graph buildGraph(config); compiledGraph graph.compile({ outputs: [swapchain] }); lastConfigHash hash; } return compiledGraph; }这个缓存策略在我实测中把每帧的 FrameGraph 开销从约 2.3ms 降到了接近 0。5.5 调试可视化把 FrameGraph 画出来ZenFG 最好用的功能之一是能把编译后的图导出成可视化的依赖图。虽然不能用 mermaid这里只是描述但可以导出成 DOT 格式或者简单的文本树。console.log(compiled.toDot()); // 输出类似 // digraph FrameGraph { // shadowPass - lightingPass [labelshadowMap]; // gbufferPass - lightingPass [labelgbufferAlbedo]; // ... // }这个可视化在排查依赖问题时非常有用。我经常在怀疑顺序不对时先导出图看一眼比读代码快得多。6. ZenFG 与其他方案的对比什么时候该用它什么时候不该6.1 和直接用 wgpu 比直接用 wgpu 写管线自由度最高但所有资源管理和 Pass 编排都要自己来。适合管线简单少于 5 个 Pass或者对性能有极致要求的场景。ZenFG 适合管线复杂、需要频繁调整 Pass 结构的场景。它的抽象开销很小但带来的可维护性提升很大。6.2 和完整渲染引擎比Three.js、Babylon.js 这类引擎提供了完整的渲染功能但 FrameGraph 是内置且封闭的。你想改它的 Pass 顺序得改引擎源码或者用它的扩展机制。ZenFG 反过来它只提供 FrameGraph 这一层渲染逻辑完全由你写。适合那些我想要引擎的 FrameGraph但不想要引擎的其他部分的开发者。6.3 选型对照表场景推荐方案理由简单场景少于 5 个 Pass直接用 wgpu抽象开销不值得复杂管线需要频繁调整ZenFG声明式依赖管理省心需要完整渲染功能Three.js / Babylon.js开箱即用需要自定义渲染逻辑 FrameGraphZenFG薄抽象不绑架纯 GPU 计算任务ZenFG同样适用Pass 可以是 compute pass6.4 一个容易被忽略的点Compute Pass 也能用ZenFG 的 Pass 不限于渲染 Pass。Compute Pass 同样可以声明读写资源纳入 FrameGraph 管理。这意味着你可以把 GPU 计算任务比如粒子模拟、后处理中的模糊、甚至一些通用计算也组织进同一张图里。graph.addPass({ name: particleSimPass, reads: [particleBuffer], writes: [particleBuffer], execute: (encoder, res) { const pass encoder.beginComputePass(); pass.setPipeline(particleSimPipeline); pass.setBindGroup(0, createParticleBindGroup(res)); pass.dispatchWorkgroups(Math.ceil(particleCount / 64)); pass.end(); } });注意这里reads和writes是同一个资源——这是合法的表示读改写。FrameGraph 会正确处理这种依赖。7. 我个人的使用体会与几个实用建议用了几个月 ZenFG最大的感受是它把渲染管线从一个代码结构问题变成了一个数据依赖问题。以前我思考的是这个 Pass 放在哪一行现在我思考的是这个 Pass 需要什么、产出什么。思维方式的转变带来的可维护性提升是实打实的。几个具体建议第一从第一天就用虚拟资源。不要图省事直接device.createTexture然后importResource。虚拟资源让 FrameGraph 有优化空间而且资源生命周期自动管理少写很多destroy()。第二把 Pass 的execute写成纯函数。只依赖传入的encoder和resources不要在里面访问外部可变状态。这样 Pass 可以独立测试也更容易复用。第三编译结果一定要缓存。除非你的管线每帧都在变否则没必要每帧重新编译。缓存策略上面给过了直接抄。第四调试阶段打开裁剪日志。看看哪些 Pass 被裁掉了确认是不是你预期的。有时候你以为某个 Pass 在跑其实它因为没贡献到最终输出被裁了。第五资源命名要有意义。texture1、texture2这种命名在调试时是灾难。用gbufferAlbedo、bloomLevel3这种一看就懂的名字导出依赖图时一目了然。最后说一个我最近在尝试的扩展方向把 FrameGraph 的编译结果序列化做成管线预设。这样不同的画质档位低、中、高、极致可以预先编译好运行时直接切换连编译开销都省了。这个思路在移动端尤其有价值因为移动端的 CPU 编译开销相对更敏感。