一个模型渲染出来全黑？纹理显示不对？传统排查需要手动点几十步。用 renderdoc-mcp，一场对话就能定位问题。

场景：模型渲染全黑

你在开发一个 3D 场景，某个模型渲染出来是全黑的。你知道问题出在 GPU 这一侧，于是用 RenderDoc 抓了一帧。

传统排查方式：

1. 打开 RenderDoc，加载 .rdc 文件

2. 在事件列表中找到目标 draw call（可能几百个事件）

3. 点击 draw call，展开管线状态

4. 逐个检查 shader 是否正确绑定

5. 查看常量缓冲区，确认 uniform 值

6. 切到纹理面板，看资源是否正确

7. 导出 render target 对比前后帧

8. 检查验证层日志

每一步都要手动点击和切换面板，信息分散在不同的 tab 中。

AI 排查方式：一场连续对话搞定。

实战对话：逐步定位问题

第一步：打开抓帧，看全局

用户：打开 D:/captures/scene_bug.rdc，帮我看看里面有什么。
​
AI：这是一个 D3D12 抓帧，共有 847 个事件，其中 123 个 draw call。
    GPU 为 NVIDIA GeForce RTX 4070，驱动版本 551.xx。
    验证层没有报错。

一句话就获得了全局概览。

第二步：找到目标 draw call

用户：帮我找名字里带 "Character" 的 draw call。
​
AI：找到 3 个相关的 draw call：
    - 事件 342: DrawIndexed(2160) - "Character_Body"
    - 事件 345: DrawIndexed(876) - "Character_Head"
    - 事件 348: DrawIndexed(540) - "Character_Weapon"

不需要自己翻几百个事件，直接按名字过滤。

第三步：检查管线状态

用户：跳到事件 342，管线状态是什么？
​
AI：事件 342 的管线状态：
    - 顶点着色器：ResourceId::45，入口点 VSMain
    - 像素着色器：ResourceId::46，入口点 PSMain
    - 渲染目标：ResourceId::12，格式 R8G8B8A8_UNORM，1920x1080
    - Viewport：(0, 0) - (1920, 1080)
    - 深度测试：开启，格式 D24_UNORM_S8_UINT

第四步：检查资源绑定

用户：这个 draw call 绑定了哪些资源？
​
AI：VS 阶段：
    - 常量缓冲区 CBScene（bind 0，256 字节）
    - 常量缓冲区 CBObject（bind 1，128 字节）
    PS 阶段：
    - 常量缓冲区 CBMaterial（bind 0，64 字节）
    - 纹理 diffuseMap（bind 0）
    - 纹理 normalMap（bind 1）
    - 采样器 linearSampler（bind 0）

第五步：查看 shader 反射

用户：看看像素着色器的反射数据，CBMaterial 里有什么变量？
​
AI：CBMaterial 包含以下变量：
    - baseColor: float4 (offset 0, 16 bytes) = (0.0, 0.0, 0.0, 1.0)
    - roughness: float (offset 16, 4 bytes)
    - metallic: float (offset 20, 4 bytes)
    注意：baseColor 的值是 (0, 0, 0, 1)，也就是纯黑色。
    这可能就是模型全黑的原因。

找到了！常量缓冲区里的 baseColor 是 (0, 0, 0, 1)，导致模型渲染为全黑。

第六步：导出验证

用户：导出事件 342 的 render target，让我看看。
​
AI：已导出到 D:/captures/export_event342_rt0.png。
    画面中可以看到场景中其他物体正常渲染，
    只有角色模型区域是纯黑色，与 baseColor 为零一致。

20 个工具速查

renderdoc-mcp 提供 20 个工具，覆盖完整的 GPU 调试流程：

会话管理

工具	用途	典型用法
open_capture	打开 .rdc 文件	"打开这个抓帧"

事件与 Draw Call

工具	用途	典型用法
list_events	列出事件，支持名字过滤	"列出所有事件"
goto_event	跳转到指定事件	"跳到事件 42"
list_draws	列出 draw call	"有哪些 draw call？"
get_draw_info	查看 draw call 详情	"这个 draw 画了多少三角形？"

管线与绑定

工具	用途	典型用法
get_pipeline_state	查看管线状态	"管线状态是什么？"
get_bindings	查看 shader 资源绑定	"绑定了哪些纹理？"

Shader

工具	用途	典型用法
get_shader	获取 shader 反汇编或反射	"看看顶点着色器的代码"
list_shaders	列出所有 shader	"这帧用了多少个 shader？"
search_shaders	搜索 shader 代码	"哪个 shader 里用了 normalMap？"

资源

工具	用途	典型用法
list_resources	列出 GPU 资源	"有哪些纹理？"
get_resource_info	查看资源详情	"这个纹理多大？什么格式？"
list_passes	列出渲染 pass	"有几个渲染 pass？"
get_pass_info	查看 pass 详情	"Shadow pass 包含哪些 draw？"

导出

工具	用途	典型用法
export_render_target	导出 render target 为 PNG	"导出渲染结果"
export_texture	导出纹理为 PNG	"导出这张纹理"
export_buffer	导出 buffer 为二进制	"把这个 buffer 导出来"

信息与诊断

工具	用途	典型用法
get_capture_info	查看抓帧元数据	"用的什么 GPU 和驱动？"
get_stats	性能统计	"哪个 pass 最耗时？"
get_log	调试日志	"有没有验证层报错？"

提问最佳实践

从全局到细节

先问全局概览，再逐步深入到具体事件和资源。不要一上来就问某个 ResourceId 的详情。

好的流程：打开抓帧 → 列出 draw call → 跳到目标事件 → 查看管线 → 检查绑定

用关键字过滤

大部分列表工具都支持过滤，善用关键字缩小范围：

"列出名字里带 Shadow 的 draw call"
"找使用了 normalMap 的 shader"
"只看 Texture 类型的资源"

对比两个事件

当你知道"从哪个 draw 开始出问题"时，对比是最有效的排查方式：

"事件 120 和 121 之间发生了什么变化？"

善用导出验证

文字分析到最后，导出 render target 看一眼最直观：

"导出事件 120 和 121 的 render target，让我对比一下"

常见调试场景

症状	排查思路
模型全黑	检查材质常量缓冲区中的颜色值，或纹理是否正确绑定
模型不可见	检查 viewport 设置、裁剪面、深度测试配置
纹理错误	检查 shader 绑定点，导出纹理确认内容
闪烁/Z-fighting	查看深度缓冲格式和精度，比较重叠 draw 的深度值
性能异常	用 get_stats 找到最耗时的 pass 和最大的 draw
验证报错	用 get_log 查看验证层消息，按事件过滤定位

下一步

想了解 renderdoc-mcp 的设计理念，以及 MCP 如何让 AI 获得专业工具能力？