渲染系列的源码篇到此收尾，最后留一篇实战。触发点是读者迟早会遇到的那类问题：画面全黑但没有报错、自定义 compute 之后屏幕花了、某个后处理 pass 让整个视图消失。这类问题的共同点是CPU 侧一切正常，错误发生在 GPU 上，而 GPU 不会主动告诉你它哪儿不高兴了。标准排查流程就两件工具：validation layer 排 API 错误，RenderDoc 排逻辑错误。
Step 1：validation layer 排 API 错误
Vulkan 的 validation layer（VK_LAYER_KHRONOS_validation）会拦截每次 API 调用，按规范逐条检查参数、同步状态和资源生命周期。Godot 有两条路启用它：
- 自编译：
scons dev_build=yes编出的二进制带DEV_ENABLED宏，VulkanContext 创建 instance 时自动加载验证层； - 官方二进制（4.3+）：命令行加
--gpu-validation；再加--gpu-abort可以在第一条验证错误处直接 abort，调用栈停在出错的 API 调用上——这是它最有价值的用法，比翻日志快得多。
验证消息长这样，核心是先找 VUID（规范条目号）再看细节：
VUID-VkImageMemoryBarrier-oldLayout-01212(ERROR / SPEC): ...
srcLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, dstLayout = ...UNDEFINED...
几条高频错误和它们的含义：
| 报错关键词 | 典型原因 |
|---|---|
oldLayout ... does not match |
barrier 写的源布局和资源实际布局不符，基本是忘了 transition |
must have been created with ... usage |
拿 storage 用的 buffer 没加 STORAGE usage flag |
exceeds push constant range |
push constant 塞超了创建管线时声明的大小 |
descriptor set ... not updated |
绑了未写过的 descriptor，RD 里对应 UniformSet 缓存键弄错了 |
validation 全绿不能证明渲染正确——它只保证 API 用法合法，不保证你画的逻辑对。但 validation 红了，后面 RenderDoc 看到的任何现象都不可信，所以顺序不能换。
Step 2：RenderDoc 抓帧定位
RenderDoc 通过注入层拦下整帧的命令流，回放时提供四个视角。用法：打开 RenderDoc，Executable 填 Godot 二进制，Command line 把项目参数带全（--path /your/project --editor 之类），Launch 后按 F12 或触发 capture。注意 RD 路径才能抓：Vulkan/D3D12/Metal 驱动后端都行，Compatibility 渲染器的 GLES3 不在 RenderDoc 支持范围内。
拿到 capture 后的标准动作，按事件浏览器（Event Browser）里每个 action 的 GPU 耗时排序，先确认钱花在哪，再对黑屏 pass 用三视图：
- Mesh Viewer：选中可疑 draw，看顶点数据是否真的进了管线——顶点全在但屏幕黑，问题在光栅化之后；
- Pipeline State：看绑定的 framebuffer 是不是你以为的那个、shader 是否编译成功、viewport/scissor 有没有把画面裁没；
- Texture Viewer：直接看 render target 在 pass 前后的内容——RT 里有内容但屏幕黑，查后处理链和合成；RT 里就是黑的，回溯到上一个有内容的 pass。
我的一次真实排查（自定义 compute 后全黑）：validation 报 oldLayout 不符，定位到我在 compute 读贴图前忘了把它从 UNDEFINED 迁出来，修完 validation 干净了但还是黑——RenderDoc 里发现 compute 写结果的 buffer 根本没绑上（UniformSet 缓存键算错，RD 复用了一张旧的），Pipeline State 一对比就露馅。两个工具各抓一个错，缺一个都得再耗半天。
Godot 特有的坑
- 编辑器抓帧文件很大。编辑器一帧几百上千个 draw，capture 前先开个最小复现场景；
- 官方模板二进制没有验证层开关之外的调试符号，
--gpu-abort崩出来的是无符号栈，自编译 dev_build 才能看到函数名； - validation 的开销不小（每次调用多一次检查），复现完就关，别挂着测性能。
这套流程对引擎外的渲染代码一样适用：validation 管"合不合规"，RenderDoc 管"合不合意"，两者正交，先合规再合意。
工具链说明：validation layer 为 VK_LAYER_KHRONOS_validation（Vulkan SDK 自带）；--gpu-validation / --gpu-abort 为 Godot 4.3+ 命令行选项；RenderDoc 抓取需 RD 驱动后端，Compatibility（GLES3）不适用。