XCEngine/docs/api/XCEngine/Debug/RenderDocCapture/RenderDocCapture.md

# RenderDocCapture

**命名空间**: `XCEngine::Debug`

**类型**: `class (singleton)`

**头文件**: `XCEngine/Debug/RenderDocCapture.h`

**描述**: 在 Windows 上动态加载 RenderDoc，并为引擎或测试程序提供抓帧入口。

## 概述

`RenderDocCapture` 把外部 GPU 调试工具接入到引擎运行流程中。它的价值不在于替代 RenderDoc，而在于让测试程序、后端样例和编辑器工具可以用统一代码主动触发捕获。

当前实现的关键事实：

- 公共头文件直接依赖 `windows.h`，因此它是明显的 Windows 专用 API。
- 运行时会尝试从当前可执行文件目录加载 `renderdoc.dll`。
- 初始化时可以先只传入 `window` 或者都传 `nullptr`，稍后再通过 [SetDevice](SetDevice.md) / [SetWindow](SetWindow.md) 补齐。
- 抓帧前要求 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](Get.md) | 获取全局 `RenderDocCapture` 实例。 |
| [Initialize](Initialize.md) | 加载 RenderDoc 并记录设备/窗口句柄。 |
| [Shutdown](Shutdown.md) | 结束抓帧并卸载 RenderDoc。 |
| [SetDevice](SetDevice.md) | 更新当前活动图形设备指针。 |
| [SetWindow](SetWindow.md) | 更新当前活动窗口句柄。 |
| [IsLoaded](IsLoaded.md) | 查询 RenderDoc 是否成功加载。 |
| [IsCapturing](IsCapturing.md) | 查询当前是否处于抓帧中。 |
| [GetNumCaptures](GetNumCaptures.md) | 查询可访问的 capture 数量。 |
| [GetCapture](GetCapture.md) | 读取指定 capture 的元数据。 |
| [BeginCapture](BeginCapture.md) | 开始一次手动抓帧。 |
| [EndCapture](EndCapture.md) | 结束当前抓帧。 |
| [TriggerCapture](TriggerCapture.md) | 请求 RenderDoc 触发一次 capture。 |
| [SetCaptureFilePath](SetCaptureFilePath.md) | 设置 capture 文件路径模板。 |
| [SetCaptureComments](SetCaptureComments.md) | 设置 capture 注释。 |
| [SetCaptureOptionU32](SetCaptureOptionU32.md) | 以原始 option id 设置 U32 选项。 |
| [LaunchReplayUI](LaunchReplayUI.md) | 请求启动 RenderDoc Replay UI。 |

## 真实使用位置

当前代码库已经在多个 D3D12 / OpenGL 集成测试中使用它：

- 先创建窗口。
- 调用 `Initialize(nullptr, hwnd)`。
- 图形设备初始化完成后调用 `SetDevice(...)`。
- 在目标帧前后调用 `BeginCapture` / `EndCapture`。

## 相关文档

- [当前模块](../Debug.md)
- [RenderDoc Capture Workflow](../../../_guides/Debug/RenderDoc-Capture-Workflow.md)