# RenderDoc Capture Workflow

## 为什么要把 RenderDoc 接进引擎

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

`RenderDocCapture` 的意义就在这里：

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

## 推荐接入顺序

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

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

示例：

```cpp
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 的开始/结束时机做成和帧数、状态机绑定，而不是临时热键。

## 相关 API

- [Debug](../../XCEngine/Debug/Debug.md)
- [RenderDocCapture](../../XCEngine/Debug/RenderDocCapture/RenderDocCapture.md)
- [Initialize](../../XCEngine/Debug/RenderDocCapture/Initialize.md)
- [BeginCapture](../../XCEngine/Debug/RenderDocCapture/BeginCapture.md)
- [EndCapture](../../XCEngine/Debug/RenderDocCapture/EndCapture.md)