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

# RenderDocCapture::BeginCapture

开始一次手动 RenderDoc 抓帧。

```cpp
bool BeginCapture(const char* title = nullptr);
```

## 行为说明

当前实现会在开始抓帧前依次检查：

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
using namespace XCEngine::Debug;

if (RenderDocCapture::Get().BeginCapture("D3D12_Triangle_Test")) {
    Logger::Get().Info(LogCategory::RenderDoc, "Capture started");
}
```

## 相关文档

- [返回类型总览](RenderDocCapture.md)
- [EndCapture](EndCapture.md)
- [Initialize](Initialize.md)