RenderDoc Capture Workflow

为什么要把 RenderDoc 接进引擎

对图形引擎来说，GPU 调试不是“出了问题再临时打开工具”的事，而应该是测试与验证流程的一部分。

RenderDocCapture 的意义就在这里：

D3D12 和 OpenGL 集成测试可以在目标帧自动开始和结束抓帧。
调试流程可以和测试用例、窗口创建、设备初始化保持同一套代码路径。
不需要依赖人工热键或临时手动附加。

推荐接入顺序

当前代码库里的典型流程是：

创建窗口。
调用 RenderDocCapture::Get().Initialize(nullptr, hwnd)。
初始化图形设备。
调用 SetDevice(...) 补齐真实设备指针。
在目标帧前调用 BeginCapture(...)。
在目标帧后调用 EndCapture()。
程序结束前调用 Shutdown()。

示例：

using namespace XCEngine::Debug;

RenderDocCapture::Get().Initialize(nullptr, hwnd);
RenderDocCapture::Get().SetCaptureFilePath(".\\triangle_frame30");
RenderDocCapture::Get().SetDevice(devicePtr);

if (frameCount == 29) {
    RenderDocCapture::Get().BeginCapture("Triangle_Test");
}

if (frameCount == 30) {
    RenderDocCapture::Get().EndCapture();
}

为什么允许先不传 device

窗口通常比图形设备更早创建。当前 Initialize 支持先传 window、后传 device，就是为了对齐真实的引擎启动顺序。

这点在图形测试里尤其重要，因为：

有时必须先拿到 HWND 才能初始化后端。
但 RenderDoc 的目标窗口又应该尽早绑定好。

这套设计的好处

把“抓帧时机”从人工操作变成代码可控流程。
D3D12 / OpenGL 可以复用同一套抓帧入口。
自动化测试更容易固定在某一帧抓取稳定结果。

当前限制

这是 Windows 专用封装。
renderdoc.dll 必须位于可执行文件目录。
BeginCapture 会尝试把窗口切到前台，这对自动化环境可能是有副作用的。
LaunchReplayUI 只能确认“请求已发出”，不能确认 UI 一定成功启动。
头文件暴露的是原始 void* 设备和窗口指针，没有类型安全包装。

和 Unity 的对照

它更接近“把外部 RenderDoc 工作流内嵌到引擎测试流程”，而不是 Unity Frame Debugger 那种引擎内逐 draw-call 可视化工具。

换句话说：

Unity Frame Debugger 侧重引擎自己解释渲染步骤。
RenderDocCapture 侧重让 RenderDoc 在正确的时机抓到正确的帧。

实战建议

把抓帧逻辑放在测试场景最稳定的关键帧，而不是随机运行时。
在调用 BeginCapture 前确保设备和窗口都已设置完成。
用 SetCaptureFilePath 给不同测试用例设置可区分的输出前缀。
如果要写自动化诊断流程，优先把 capture 的开始/结束时机做成和帧数、状态机绑定，而不是临时热键。

3.2 KiB Raw Blame History Unescape Escape