docs: rebuild Debug API content
This commit is contained in:
@@ -1,31 +1,52 @@
|
||||
# RenderDocCapture::BeginCapture
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
开始一次手动 RenderDoc 抓帧。
|
||||
|
||||
```cpp
|
||||
bool BeginCapture(const char* title = nullptr);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `title` - 参数语义详见头文件声明。
|
||||
当前实现会在开始抓帧前依次检查：
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
1. RenderDoc 是否已加载。
|
||||
2. 当前是否已经处于抓帧中。
|
||||
3. `m_device` 与 `m_window` 是否都非空。
|
||||
|
||||
**示例：**
|
||||
任一条件不满足时都会记录警告并返回 `false`。
|
||||
|
||||
如果检查通过，当前实现会：
|
||||
|
||||
- 如果 `title` 非空，则调用 `SetCaptureTitle(title)`。
|
||||
- 调用 `SetForegroundWindow` 和 `SetFocus`，把目标窗口切到前台。
|
||||
- 调用 `SetActiveWindow(m_device, m_window)`。
|
||||
- 调用 `StartFrameCapture(m_device, m_window)`。
|
||||
|
||||
## 参数
|
||||
|
||||
- `title` - 可选的 capture 标题。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - `true` 表示已向 RenderDoc 发出开始抓帧请求；`false` 表示前置条件不满足。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在拥有目标窗口与图形设备上下文的主线程调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::BeginCapture(...)。
|
||||
(void)object;
|
||||
if (RenderDocCapture::Get().BeginCapture("D3D12_Triangle_Test")) {
|
||||
Logger::Get().Info(LogCategory::RenderDoc, "Capture started");
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [EndCapture](EndCapture.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,30 +1,48 @@
|
||||
# RenderDocCapture::EndCapture
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
结束当前正在进行的 RenderDoc 抓帧。
|
||||
|
||||
```cpp
|
||||
bool EndCapture();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现会先检查：
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
- RenderDoc 是否已加载。
|
||||
- 当前是否确实处于抓帧状态。
|
||||
|
||||
**示例：**
|
||||
如果任一条件不成立，会记录警告并返回 `false`。条件成立时会调用：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
m_api->EndFrameCapture(m_device, m_window);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::EndCapture(...)。
|
||||
(void)object;
|
||||
## 参数
|
||||
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - `true` 表示已发出结束抓帧请求；`false` 表示当前没有可结束的抓帧。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 应与 [BeginCapture](BeginCapture.md) 在同一渲染工作流中配对调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
if (XCEngine::Debug::RenderDocCapture::Get().EndCapture()) {
|
||||
XCEngine::Debug::Logger::Get().Info(
|
||||
XCEngine::Debug::LogCategory::RenderDoc,
|
||||
"Capture ended"
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [BeginCapture](BeginCapture.md)
|
||||
|
||||
@@ -1,29 +1,35 @@
|
||||
# RenderDocCapture::Get
|
||||
|
||||
获取相关状态或对象。
|
||||
获取进程级全局 `RenderDocCapture` 实例。
|
||||
|
||||
```cpp
|
||||
static RenderDocCapture& Get();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现使用函数内静态对象保存单例。`Get()` 本身不会加载 RenderDoc，也不会自动设置 `device` 或 `window`。
|
||||
|
||||
**返回：** `RenderDocCapture&` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `RenderDocCapture&` - 全局 RenderDoc 封装对象引用。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 单例构造由 C++ 保证线程安全；后续抓帧 API 仍建议在主线程统一使用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
auto& instance = XCEngine::Debug::RenderDocCapture::Get();
|
||||
(void)instance;
|
||||
}
|
||||
auto& capture = XCEngine::Debug::RenderDocCapture::Get();
|
||||
capture.Initialize(nullptr, hwnd);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,32 +1,52 @@
|
||||
# RenderDocCapture::GetCapture
|
||||
|
||||
获取相关状态或对象。
|
||||
读取指定 capture 的元数据。
|
||||
|
||||
```cpp
|
||||
bool GetCapture(uint32_t index, RenderDocCaptureInfo* info) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `index` - 参数语义详见头文件声明。
|
||||
- `info` - 参数语义详见头文件声明。
|
||||
当前实现要求：
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
- RenderDoc 已加载。
|
||||
- `info` 非空。
|
||||
|
||||
**示例：**
|
||||
满足条件后，它会调用底层 RenderDoc API，把结果写入 `info->filename`、`info->length` 和 `info->timestamp`。如果底层返回值等于 `1`，则方法返回 `true`。
|
||||
|
||||
注意当前包装层的一个实现细节：
|
||||
|
||||
- `RenderDocCaptureInfo::filename` 是固定 256 字节数组。
|
||||
- XCEngine 直接把这块缓冲区传给 RenderDoc。
|
||||
|
||||
因此调用方不应假设超长路径总能被完整保留。
|
||||
|
||||
## 参数
|
||||
|
||||
- `index` - capture 索引。
|
||||
- `info` - 输出缓冲区，成功时会被填充。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - `true` 表示成功读取该 capture 的元数据。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 无显式同步；通常在抓帧结束后的主线程诊断阶段调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::GetCapture(...)。
|
||||
(void)object;
|
||||
RenderDocCaptureInfo info{};
|
||||
if (RenderDocCapture::Get().GetCapture(0, &info)) {
|
||||
Logger::Get().Info(LogCategory::RenderDoc, info.filename);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [GetNumCaptures](GetNumCaptures.md)
|
||||
|
||||
@@ -1,30 +1,34 @@
|
||||
# RenderDocCapture::GetNumCaptures
|
||||
|
||||
获取相关状态或对象。
|
||||
查询当前可访问的 capture 数量。
|
||||
|
||||
```cpp
|
||||
uint32_t GetNumCaptures() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
如果 RenderDoc 尚未加载，当前实现返回 `0`。否则直接转发到底层 `GetNumCaptures()`。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `uint32_t` - 当前 capture 数量；RenderDoc 未加载时为 `0`。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 无显式同步；通常在主线程诊断阶段调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::GetNumCaptures(...)。
|
||||
(void)object;
|
||||
}
|
||||
uint32_t count = XCEngine::Debug::RenderDocCapture::Get().GetNumCaptures();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [GetCapture](GetCapture.md)
|
||||
|
||||
@@ -1,32 +1,54 @@
|
||||
# RenderDocCapture::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
加载 `renderdoc.dll` 并初始化当前抓帧上下文。
|
||||
|
||||
```cpp
|
||||
bool Initialize(void* device = nullptr, void* window = nullptr);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `device` - 参数语义详见头文件声明。
|
||||
- `window` - 参数语义详见头文件声明。
|
||||
当前实现是幂等的：
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
- 如果已经初始化，直接返回 `true`。
|
||||
- 注意：在“已经初始化”的情况下，新的 `device` 和 `window` 参数不会写回内部状态。
|
||||
|
||||
**示例：**
|
||||
首次初始化时，当前实现会：
|
||||
|
||||
1. 保存 `device` 与 `window` 指针。
|
||||
2. 在可执行文件所在目录查找并加载 `renderdoc.dll`。
|
||||
3. 获取 RenderDoc 1.7.0 API。
|
||||
4. 额外设置三个默认 U32 capture 选项：`2`、`8`、`9` 都设为 `1`。
|
||||
5. 记录一条初始化成功日志。
|
||||
|
||||
当前 API 允许在初始化时传空指针；这种情况下只要 DLL 可用，初始化仍可成功，但之后 [BeginCapture](BeginCapture.md) 仍要求设备和窗口已补齐。
|
||||
|
||||
## 参数
|
||||
|
||||
- `device` - 可选的图形设备指针。
|
||||
- `window` - 可选的窗口句柄。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - `true` 表示 RenderDoc 已成功加载并可继续配置；`false` 表示加载或 API 获取失败。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在创建窗口后、图形后端初始化期间由主线程调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::Initialize(...)。
|
||||
(void)object;
|
||||
if (RenderDocCapture::Get().Initialize(nullptr, hwnd)) {
|
||||
RenderDocCapture::Get().SetDevice(devicePtr);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [SetDevice](SetDevice.md)
|
||||
- [SetWindow](SetWindow.md)
|
||||
- [RenderDoc Capture Workflow](../../../_guides/Debug/RenderDoc-Capture-Workflow.md)
|
||||
|
||||
@@ -1,30 +1,36 @@
|
||||
# RenderDocCapture::IsCapturing
|
||||
|
||||
查询当前状态。
|
||||
查询当前是否处于 RenderDoc 抓帧状态。
|
||||
|
||||
```cpp
|
||||
bool IsCapturing() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
如果 RenderDoc 尚未加载或 API 指针无效，当前实现返回 `false`。否则会调用底层 `IsFrameCapturing()`，并把非零结果解释为 `true`。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - `true` 表示当前正在抓帧。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 无显式同步；通常与 [BeginCapture](BeginCapture.md) / [EndCapture](EndCapture.md) 在同一线程使用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::IsCapturing(...)。
|
||||
(void)object;
|
||||
if (XCEngine::Debug::RenderDocCapture::Get().IsCapturing()) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [IsLoaded](IsLoaded.md)
|
||||
|
||||
@@ -1,30 +1,36 @@
|
||||
# RenderDocCapture::IsLoaded
|
||||
|
||||
查询当前状态。
|
||||
查询 RenderDoc 是否已成功加载。
|
||||
|
||||
```cpp
|
||||
bool IsLoaded() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
这是一个内联查询函数，直接返回内部布尔值 `m_isLoaded`。它不验证 `device`、`window` 或当前是否处于抓帧状态，因此“已加载”只表示 RenderDoc API 已获取成功。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - `true` 表示 RenderDoc DLL 和 API 已可用。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 只读查询；当前实现没有额外同步。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::IsLoaded(...)。
|
||||
(void)object;
|
||||
if (!XCEngine::Debug::RenderDocCapture::Get().IsLoaded()) {
|
||||
// RenderDoc unavailable
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,32 +1,40 @@
|
||||
# RenderDocCapture::LaunchReplayUI
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
请求启动 RenderDoc Replay UI。
|
||||
|
||||
```cpp
|
||||
bool LaunchReplayUI(uint32_t connect = 1, const char* cmdline = nullptr);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `connect` - 参数语义详见头文件声明。
|
||||
- `cmdline` - 参数语义详见头文件声明。
|
||||
如果 RenderDoc 尚未加载，当前实现会记录警告并返回 `false`。否则会直接调用底层 `LaunchReplayUI(connect, cmdline)` 并返回 `true`。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
注意：
|
||||
|
||||
**示例：**
|
||||
- 底层 RenderDoc 函数本身没有返回值。
|
||||
- 因此 XCEngine 无法确认 Replay UI 最终是否真的成功启动。
|
||||
|
||||
## 参数
|
||||
|
||||
- `connect` - 是否尝试连接到目标实例。
|
||||
- `cmdline` - 传给 Replay UI 的可选命令行。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - `true` 表示已发出启动请求；`false` 表示 RenderDoc 未加载。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在工具线程或主线程的诊断分支中调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::LaunchReplayUI(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::RenderDocCapture::Get().LaunchReplayUI();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [GetCapture](GetCapture.md)
|
||||
|
||||
@@ -6,41 +6,70 @@
|
||||
|
||||
**头文件**: `XCEngine/Debug/RenderDocCapture.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/Debug` 子目录中的 `RenderDocCapture` public API。
|
||||
**描述**: 在 Windows 上动态加载 RenderDoc，并为引擎或测试程序提供抓帧入口。
|
||||
|
||||
## 概述
|
||||
|
||||
`RenderDocCapture.h` 是 `XCEngine/Debug` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`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` | 头文件中的公开声明。 |
|
||||
| `RenderDocCapture` | `class` | 头文件中的公开声明。 |
|
||||
| `RenderDocCaptureInfo` | `struct` | 保存单个 capture 的文件名、长度和时间戳。 |
|
||||
| `RenderDocCapture` | `class` | RenderDoc 封装与抓帧控制入口。 |
|
||||
|
||||
## 公共方法
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [Get](Get.md) | 获取相关状态或对象。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [SetDevice](SetDevice.md) | 设置相关状态或配置。 |
|
||||
| [SetWindow](SetWindow.md) | 设置相关状态或配置。 |
|
||||
| [IsLoaded](IsLoaded.md) | 查询当前状态。 |
|
||||
| [IsCapturing](IsCapturing.md) | 查询当前状态。 |
|
||||
| [GetNumCaptures](GetNumCaptures.md) | 获取相关状态或对象。 |
|
||||
| [GetCapture](GetCapture.md) | 获取相关状态或对象。 |
|
||||
| [BeginCapture](BeginCapture.md) | 公开方法，详见头文件声明。 |
|
||||
| [EndCapture](EndCapture.md) | 公开方法，详见头文件声明。 |
|
||||
| [TriggerCapture](TriggerCapture.md) | 公开方法，详见头文件声明。 |
|
||||
| [SetCaptureFilePath](SetCaptureFilePath.md) | 设置相关状态或配置。 |
|
||||
| [SetCaptureComments](SetCaptureComments.md) | 设置相关状态或配置。 |
|
||||
| [SetCaptureOptionU32](SetCaptureOptionU32.md) | 设置相关状态或配置。 |
|
||||
| [LaunchReplayUI](LaunchReplayUI.md) | 公开方法，详见头文件声明。 |
|
||||
| [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) - 返回 `Debug` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Debug.md)
|
||||
- [RenderDoc Capture Workflow](../../../_guides/Debug/RenderDoc-Capture-Workflow.md)
|
||||
|
||||
@@ -1,31 +1,40 @@
|
||||
# RenderDocCapture::SetCaptureComments
|
||||
|
||||
设置相关状态或配置。
|
||||
设置 capture 注释文本。
|
||||
|
||||
```cpp
|
||||
void SetCaptureComments(const char* comments);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `comments` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
如果 RenderDoc 尚未加载，当前实现直接返回。否则会调用：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
m_api->SetCaptureFileComments(nullptr, comments);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::SetCaptureComments(...)。
|
||||
(void)object;
|
||||
}
|
||||
这意味着 XCEngine 当前没有显式指定 capture 文件路径，而是把 `nullptr` 传给 RenderDoc。注释最终如何关联到具体 capture，取决于 RenderDoc 对该调用形式的处理。
|
||||
|
||||
## 参数
|
||||
|
||||
- `comments` - 注释文本。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 无显式同步；通常在抓帧前后由主线程调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::RenderDocCapture::Get().SetCaptureComments("Frame 30 validation capture");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [SetCaptureFilePath](SetCaptureFilePath.md)
|
||||
|
||||
@@ -1,31 +1,36 @@
|
||||
# RenderDocCapture::SetCaptureFilePath
|
||||
|
||||
设置相关状态或配置。
|
||||
设置 capture 文件路径模板。
|
||||
|
||||
```cpp
|
||||
void SetCaptureFilePath(const char* path);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `path` - 参数语义详见头文件声明。
|
||||
如果 RenderDoc 尚未加载，当前实现直接返回。否则会把 `path` 转发给底层 `SetCaptureFilePathTemplate`。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
这个路径通常在抓帧前配置，用于决定生成的 `.rdc` 文件落到哪里，以及以什么名前缀生成。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `path` - capture 文件路径模板。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在开始抓帧前完成配置。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::SetCaptureFilePath(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::RenderDocCapture::Get().SetCaptureFilePath(".\\triangle_frame30");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [SetCaptureComments](SetCaptureComments.md)
|
||||
|
||||
@@ -1,32 +1,37 @@
|
||||
# RenderDocCapture::SetCaptureOptionU32
|
||||
|
||||
设置相关状态或配置。
|
||||
以原始 option id 设置一个 32 位 RenderDoc capture 选项。
|
||||
|
||||
```cpp
|
||||
void SetCaptureOptionU32(uint32_t option, uint32_t value);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `option` - 参数语义详见头文件声明。
|
||||
- `value` - 参数语义详见头文件声明。
|
||||
如果 RenderDoc 尚未加载，当前实现直接返回。否则会把 `option` 和 `value` 原样传给底层 `SetCaptureOptionU32`。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
当前公共头文件没有为这些 option id 提供命名常量，因此调用方需要自行保证 option 编号与目标 RenderDoc 版本匹配。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `option` - RenderDoc 选项编号。
|
||||
- `value` - 对应的 U32 值。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在初始化阶段或抓帧前配置。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::SetCaptureOptionU32(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::RenderDocCapture::Get().SetCaptureOptionU32(2, 1);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,31 +1,40 @@
|
||||
# RenderDocCapture::SetDevice
|
||||
|
||||
设置相关状态或配置。
|
||||
更新当前用于抓帧的图形设备指针。
|
||||
|
||||
```cpp
|
||||
void SetDevice(void* device);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `device` - 参数语义详见头文件声明。
|
||||
当前实现只是把 `device` 原样写入内部成员 `m_device`，不做类型检查、平台检查或合法性验证。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
这个方法通常用于这样的流程：
|
||||
|
||||
**示例：**
|
||||
1. 先在创建窗口后调用 [Initialize](Initialize.md)。
|
||||
2. 图形后端初始化完成后，把真实设备指针补给 `RenderDocCapture`。
|
||||
|
||||
## 参数
|
||||
|
||||
- `device` - 底层图形设备指针。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在图形设备创建线程中配置，并在抓帧前保持稳定。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::SetDevice(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::RenderDocCapture::Get().SetDevice(gDevice.GetDevice());
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [SetWindow](SetWindow.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,31 +1,34 @@
|
||||
# RenderDocCapture::SetWindow
|
||||
|
||||
设置相关状态或配置。
|
||||
更新当前用于抓帧的窗口句柄。
|
||||
|
||||
```cpp
|
||||
void SetWindow(void* window);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `window` - 参数语义详见头文件声明。
|
||||
当前实现只是把 `window` 原样写入内部成员 `m_window`，不做任何合法性检查。之后 [BeginCapture](BeginCapture.md) 与 [TriggerCapture](TriggerCapture.md) 可能会把它转换为 `HWND` 并尝试设置前台窗口与焦点。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `window` - 目标窗口指针；在 Windows 平台上通常是 `HWND`。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在窗口所属线程或主线程设置。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::SetWindow(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::RenderDocCapture::Get().SetWindow(hwnd);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [SetDevice](SetDevice.md)
|
||||
|
||||
@@ -1,30 +1,42 @@
|
||||
# RenderDocCapture::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
结束抓帧并卸载 RenderDoc。
|
||||
|
||||
```cpp
|
||||
void Shutdown();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现只有在 `m_initialized` 为 `true` 时才执行关闭逻辑。关闭流程包括：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
1. 如果当前仍在抓帧，先调用 [EndCapture](EndCapture.md)。
|
||||
2. 卸载 `renderdoc.dll`。
|
||||
3. 清空 API 指针并把 `m_isLoaded` 设为 `false`。
|
||||
4. 把 `m_initialized` 设为 `false`。
|
||||
|
||||
**示例：**
|
||||
当前不会清空 `m_device` 与 `m_window` 指针，但下次 `Initialize` 会用新的参数覆盖它们。
|
||||
|
||||
## 参数
|
||||
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在图形设备和窗口销毁前、主线程受控退出阶段调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::RenderDocCapture::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [EndCapture](EndCapture.md)
|
||||
|
||||
@@ -1,30 +1,39 @@
|
||||
# RenderDocCapture::TriggerCapture
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
请求 RenderDoc 触发一次 capture。
|
||||
|
||||
```cpp
|
||||
void TriggerCapture();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/RenderDocCapture.h`，当前页面用于固定 `RenderDocCapture` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
如果 RenderDoc 尚未加载，当前实现直接返回。否则：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
- 如果 `m_window` 非空，会先把窗口设为前台并设置焦点。
|
||||
- 调用底层 `TriggerCapture()` 请求 RenderDoc 执行一次捕获。
|
||||
|
||||
**示例：**
|
||||
与 [BeginCapture](BeginCapture.md) / [EndCapture](EndCapture.md) 相比，这个方法更适合交给 RenderDoc 自己决定具体捕获时机。
|
||||
|
||||
## 参数
|
||||
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在拥有目标窗口焦点控制权的线程调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/RenderDocCapture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::RenderDocCapture object;
|
||||
// 根据上下文补齐参数后调用 RenderDocCapture::TriggerCapture(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::RenderDocCapture::Get().TriggerCapture();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](RenderDocCapture.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](RenderDocCapture.md)
|
||||
- [BeginCapture](BeginCapture.md)
|
||||
|
||||
Reference in New Issue
Block a user