3.4 KiB
3.4 KiB
RenderDocCapture
命名空间: XCEngine::Debug
类型: class (singleton)
头文件: XCEngine/Debug/RenderDocCapture.h
描述: 在 Windows 上动态加载 RenderDoc，并为引擎或测试程序提供抓帧入口。
概述
RenderDocCapture 把外部 GPU 调试工具接入到引擎运行流程中。它的价值不在于替代 RenderDoc，而在于让测试程序、后端样例和编辑器工具可以用统一代码主动触发捕获。
当前实现的关键事实：
- 公共头文件直接依赖
windows.h，因此它是明显的 Windows 专用 API。 - 运行时会尝试从当前可执行文件目录加载
renderdoc.dll。 - 初始化时可以先只传入
window或者都传nullptr，稍后再通过 SetDevice / SetWindow 补齐。 - 抓帧前要求 RenderDoc 已加载，且
device与window都不为空。
当前实现边界
- 只封装了 RenderDoc 1.7.0 API 中的一小部分函数。
Initialize是幂等的；如果已经初始化，再次调用不会刷新device和window参数。LaunchReplayUI的底层 RenderDoc 调用没有返回值，XCEngine 只能报告“请求已发出”，不能证明 UI 一定成功启动。SetCaptureComments当前直接把nullptr作为 capture file path 传给 RenderDoc。
线程语义
- 当前实现没有显式同步机制。
- 典型使用方式是在创建窗口和图形设备的主线程上完成初始化、抓帧和关闭。
BeginCapture和TriggerCapture会尝试把窗口设为前台并设置焦点，这属于有副作用的 UI 行为。
声明概览
| 声明 | 类型 | 说明 |
|---|---|---|
RenderDocCaptureInfo |
struct |
保存单个 capture 的文件名、长度和时间戳。 |
RenderDocCapture |
class |
RenderDoc 封装与抓帧控制入口。 |
公开方法
| 方法 | 说明 |
|---|---|
| Get | 获取全局 RenderDocCapture 实例。 |
| Initialize | 加载 RenderDoc 并记录设备/窗口句柄。 |
| Shutdown | 结束抓帧并卸载 RenderDoc。 |
| SetDevice | 更新当前活动图形设备指针。 |
| SetWindow | 更新当前活动窗口句柄。 |
| IsLoaded | 查询 RenderDoc 是否成功加载。 |
| IsCapturing | 查询当前是否处于抓帧中。 |
| GetNumCaptures | 查询可访问的 capture 数量。 |
| GetCapture | 读取指定 capture 的元数据。 |
| BeginCapture | 开始一次手动抓帧。 |
| EndCapture | 结束当前抓帧。 |
| TriggerCapture | 请求 RenderDoc 触发一次 capture。 |
| SetCaptureFilePath | 设置 capture 文件路径模板。 |
| SetCaptureComments | 设置 capture 注释。 |
| SetCaptureOptionU32 | 以原始 option id 设置 U32 选项。 |
| LaunchReplayUI | 请求启动 RenderDoc Replay UI。 |
真实使用位置
当前代码库已经在多个 D3D12 / OpenGL 集成测试中使用它：
- 先创建窗口。
- 调用
Initialize(nullptr, hwnd)。 - 图形设备初始化完成后调用
SetDevice(...)。 - 在目标帧前后调用
BeginCapture/EndCapture。