89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
# 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)
|