xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update RHI API docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 02:35:45 +08:00
parent ea756c0177
commit 070b444f8f
501 changed files with 13493 additions and 2022 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/api/rhi/command-queue/command-queue.md
View File

@@ -2,49 +2,73 @@
**命名空间**: `XCEngine::RHI`
**类型**: `class` (abstract)
**类型**: `class` (抽象基类)
**头文件**: `XCEngine/RHI/RHICommandQueue.h`
**描述**: GPU 命令队列抽象接口，负责提交和执行命令列表，以及 GPU/CPU 同步。
## 概述
`RHICommandQueue` 是 RHI（Render Hardware Interface）系统中的核心抽象接口之一，封装了底层图形 API（D3D12/Vulkan/Metal 等）的命令队列功能。
主要职责：
- **命令提交**：将准备好的命令列表提交到 GPU 执行
- **GPU/CPU 同步**：通过栅栏（Fence）机制协调 CPU 和 GPU 的执行顺序
- **队列类型管理**：区分直接队列、计算队列和复制队列
使用场景：
- 渲染循环中提交绘制命令
- 资源在 GPU 和 CPU 之间传输时的同步
- 多线程渲染时的命令生成和提交
## 公共方法
| 方法 | 描述 |
|------|------|
| [`Shutdown`](shutdown.md) | 关闭并释放资源 |
| [`ExecuteCommandLists`](execute-command-lists.md) | 执行命令列表 |
| [`Signal`](signal.md) | 信号栅栏 |
| [`Wait`](../../threading/task-group/wait.md) | 等待栅栏 |
| [`GetCompletedValue`](get-completed-value.md) | 获取完成值 |
| [`WaitForIdle`](wait-for-idle.md) | 等待空闲 |
| [`Signal`](signal.md) | 向栅栏发送信号 |
| [`Wait`](wait.md) | 等待栅栏达到指定值 |
| [`GetCompletedValue`](get-completed-value.md) | 获取栅栏已完成的值 |
| [`WaitForIdle`](wait-for-idle.md) | 等待队列所有操作完成 |
| [`GetType`](get-type.md) | 获取队列类型 |
| [`GetTimestampFrequency`](get-timestamp-frequency.md) | 获取时间戳频率 |
| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |
## 命令队列类型 (CommandQueueType)
| 枚举值 | 描述 |
|--------|------|
| `Direct` | 直接队列，用于图形和计算命令 |
| `Compute` | 计算队列，专门用于计算着色器 |
| `Copy` | 复制队列，专门用于资源复制 |
## 使用示例
```cpp
CommandQueueDesc queueDesc;
queueDesc.queueType = (uint32_t)CommandQueueType::Direct;
RHICommandQueue* commandQueue = device->CreateCommandQueue(queueDesc);
#include "RHICommandQueue.h"
#include "RHIDevice.h"
#include "RHIFence.h"
#include "RHICommandList.h"
FenceDesc fenceDesc;
RHIFence* fence = device->CreateFence(fenceDesc);
void RenderLoop(RHIDevice* device, RHICommandQueue* cmdQueue) {
CommandQueueDesc queueDesc;
queueDesc.queueType = (uint32_t)CommandQueueType::Direct;
RHICommandQueue* commandQueue = device->CreateCommandQueue(queueDesc);
commandQueue->ExecuteCommandLists(1, (void**)&commandList);
commandQueue->Signal(fence, 1);
fence->Wait(1);
FenceDesc fenceDesc;
RHIFence* fence = device->CreateFence(fenceDesc);
RHICommandList* commandList = device->CreateCommandList();
commandList->Begin();
commandList->DrawInstanced(vertices, vertexCount, 0);
commandList->End();
void* lists[1] = { commandList };
commandQueue->ExecuteCommandLists(1, lists);
commandQueue->Signal(fence, 1);
fence->Wait(1);
commandQueue->WaitForIdle();
commandQueue->Shutdown();
}
```
## 相关文档
- [../rhi/rhi.md](../rhi.md) - RHI 模块总览
- [RHI 模块](../rhi.md) - RHI 模块总览
- [RHICommandList](../command-list/command-list.md) - 命令列表
- [RHIFence](../fence/fence.md) - 同步栅栏

27
docs/api/rhi/command-queue/execute-command-lists.md
View File

@@ -4,19 +4,36 @@
virtual void ExecuteCommandLists(uint32_t count, void** lists) = 0;
```
执行命令列表。
将一个或多个命令列表提交到 GPU 执行。命令列表会在 GPU 上异步执行，具体执行时机取决于底层图形 API 的调度策略。
**参数：**
- `count` - 命令列表数量
- `lists` - 命令列表指针数组
- `count` - 命令列表数量，指定 `lists` 数组中的有效元素个数
- `lists` - 命令列表指针数组，每个元素必须是一个已完成的 `RHICommandList` 对象
**返回：** 无
**线程安全：** ❌ 非线程安全，应在渲染线程中调用
**复杂度：** O(n) - n 为命令列表中的命令数量
**示例：**
```cpp
void* lists[1] = {cmdList};
cmdQueue->ExecuteCommandLists(1, lists);
#include "RHICommandQueue.h"
#include "RHICommandList.h"
void SubmitDrawCommands(RHICommandQueue* cmdQueue, RHICommandList* cmdList) {
RHICommandList* lists[1] = { cmdList };
cmdList->Begin();
cmdList->SetPipelineState(pipelineState);
cmdList->SetVertexBuffer(vertexBuffer);
cmdList->DrawInstanced(vertices, vertexCount, 0);
cmdList->End();
cmdQueue->ExecuteCommandLists(1, (void**)lists);
}
```
## 相关文档
- [RHICommandQueue 总览](command-queue.md) - 返回类总览
- [RHICommandList](../command-list/command-list.md) - 命令列表

21
docs/api/rhi/command-queue/get-completed-value.md
View File

@@ -4,16 +4,31 @@
virtual uint64_t GetCompletedValue() = 0;
```
获取栅栏已完成值。
查询栅栏的当前完成值。返回值表示栅栏已被 GPU 完成的最新信号值。如果返回的值小于等待的值，则表示 GPU 尚未完成到该点的所有操作。
**返回：** 已完成的信号值
**参数：** 无
**返回：** 栅栏已完成的最大信号值（uint64_t）
**线程安全：** ✅ 线程安全，可以从任意线程调用
**复杂度：** O(1)
**示例：**
```cpp
uint64_t value = cmdQueue->GetCompletedValue();
#include "RHICommandQueue.h"
#include "RHIFence.h"
void CheckFenceStatus(RHICommandQueue* cmdQueue, RHIFence* fence) {
uint64_t completed = cmdQueue->GetCompletedValue();
if (completed >= fence->GetCurrentValue()) {
}
}
```
## 相关文档
- [RHICommandQueue 总览](command-queue.md) - 返回类总览
- [Signal](signal.md) - 信号栅栏
- [Wait](wait.md) - 等待栅栏

19
docs/api/rhi/command-queue/get-native-handle.md
View File

@@ -4,12 +4,27 @@
virtual void* GetNativeHandle() = 0;
```
获取原生 API 句柄。
获取底层图形 API 的原生命令队列句柄。返回类型为 `void*`，具体类型取决于使用的图形 API（D3D12 ID3D12CommandQueue*、Vulkan VkQueue 等）。
**返回：** 原生命令队列句柄
**参数：** 无
**返回：** 原生命令队列句柄（void*），可用于平台特定的互操作操作
**线程安全：** ✅ 线程安全，可以从任意线程调用
**复杂度：** O(1)
**示例：**
```cpp
#include "RHICommandQueue.h"
void* GetNativeQueue(RHICommandQueue* cmdQueue) {
void* handle = cmdQueue->GetNativeHandle();
return handle;
}
```
## 相关文档
- [RHICommandQueue 总览](command-queue.md) - 返回类总览

17
docs/api/rhi/command-queue/get-timestamp-frequency.md
View File

@@ -4,14 +4,25 @@
virtual uint64_t GetTimestampFrequency() const = 0;
```
获取时间戳频率。
获取命令队列的时间戳频率，即每秒计时计数次数。该频率用于解析时间戳查询结果，计算 GPU 操作的耗时。
**返回：** 时间戳频率（每秒计数）
**参数：** 无
**返回：** 时间戳频率（每秒计数次数，uint64_t）
**线程安全：** ✅ 线程安全，可以从任意线程调用
**复杂度：** O(1)
**示例：**
```cpp
uint64_t freq = cmdQueue->GetTimestampFrequency();
#include "RHICommandQueue.h"
void CalculateGPUTime(RHICommandQueue* cmdQueue, uint64_t start, uint64_t end) {
uint64_t frequency = cmdQueue->GetTimestampFrequency();
double elapsedSeconds = static_cast<double>(end - start) / static_cast<double>(frequency);
}
```
## 相关文档

28
docs/api/rhi/command-queue/get-type.md
View File

@@ -4,12 +4,36 @@
virtual CommandQueueType GetType() const = 0;
```
获取命令队列类型。
获取命令队列的类型。命令队列类型决定了它能执行的操作类型。
**返回：** 命令队列类型枚举值
**参数：** 无
**返回：** `CommandQueueType` 枚举值
| 枚举值 | 描述 |
|--------|------|
| `Direct` | 直接队列，用于图形和计算命令 |
| `Compute` | 计算队列，专门用于计算着色器 |
| `Copy` | 复制队列，专门用于资源复制 |
**线程安全：** ✅ 线程安全，可以从任意线程调用
**复杂度：** O(1)
**示例：**
```cpp
#include "RHICommandQueue.h"
void CheckQueueType(RHICommandQueue* cmdQueue) {
CommandQueueType type = cmdQueue->GetType();
if (type == CommandQueueType::Direct) {
} else if (type == CommandQueueType::Compute) {
} else if (type == CommandQueueType::Copy) {
}
}
```
## 相关文档
- [RHICommandQueue 总览](command-queue.md) - 返回类总览

73
docs/api/rhi/command-queue/methods.md
View File

@@ -1,73 +0,0 @@
# RHICommandQueue 方法
## Shutdown
```cpp
virtual void Shutdown() = 0;
```
关闭命令队列。
## ExecuteCommandLists
```cpp
virtual void ExecuteCommandLists(uint32_t count, void** lists) = 0;
```
执行命令列表。
## Signal
```cpp
virtual void Signal(RHIFence* fence, uint64_t value) = 0;
```
信号通知栅栏。
## Wait
```cpp
virtual void Wait(RHIFence* fence, uint64_t value) = 0;
```
等待栅栏。
## GetCompletedValue
```cpp
virtual uint64_t GetCompletedValue() = 0;
```
获取已完成的值。
## WaitForIdle
```cpp
virtual void WaitForIdle() = 0;
```
等待队列空闲。
## GetType
```cpp
virtual CommandQueueType GetType() const = 0;
```
获取队列类型。
## GetTimestampFrequency
```cpp
virtual uint64_t GetTimestampFrequency() const = 0;
```
获取时间戳频率。
## GetNativeHandle
```cpp
virtual void* GetNativeHandle() = 0;
```
获取原生 API 句柄。

22
docs/api/rhi/command-queue/shutdown.md
View File

@@ -4,9 +4,27 @@
virtual void Shutdown() = 0;
```
关闭命令队列，释放所有相关资源。
关闭命令队列，释放所有相关资源。调用此方法后，命令队列将不再可用，必须重新创建才能继续使用。
**复杂度：** O(n) - 取决于管理的命令列表数量
**参数：** 无
**返回：** 无
**线程安全：** ❌ 非线程安全，应在确保没有其他线程访问该队列时调用
**复杂度：** O(n) - 取决于管理的命令列表数量和待处理的 GPU 操作
**示例：**
```cpp
#include "RHICommandQueue.h"
#include "RHIDevice.h"
void CleanupQueue(RHICommandQueue* cmdQueue, RHIDevice* device) {
cmdQueue->WaitForIdle();
cmdQueue->Shutdown();
}
```
## 相关文档

23
docs/api/rhi/command-queue/signal.md
View File

@@ -4,18 +4,33 @@
virtual void Signal(RHIFence* fence, uint64_t value) = 0;
```
向栅栏发送信号。
向指定的栅栏发送信号，将栅栏的当前值设置为 `value`。当 GPU 执行到此信号操作时，栅栏值会被更新。该方法用于 GPU 到 CPU 同步。
**参数：**
- `fence` - 目标栅栏
- `value` - 信号值
- `fence` - 目标栅栏对象，不能为 `nullptr`
- `value` - 信号值，一个 64 位无符号整数
**返回：** 无
**线程安全：** ❌ 非线程安全，应在渲染线程中调用
**复杂度：** O(1)
**示例：**
```cpp
cmdQueue->Signal(fence, 1);
#include "RHICommandQueue.h"
#include "RHIFence.h"
void GPUToCPUSync(RHICommandQueue* cmdQueue, RHIFence* fence) {
cmdQueue->ExecuteCommandLists(1, (void**)&cmdList);
cmdQueue->Signal(fence, 1);
fence->Wait(1);
}
```
## 相关文档
- [RHICommandQueue 总览](command-queue.md) - 返回类总览
- [Wait](wait.md) - 等待栅栏
- [RHIFence](../fence/fence.md) - 同步栅栏

18
docs/api/rhi/command-queue/wait-for-idle.md
View File

@@ -4,14 +4,28 @@
virtual void WaitForIdle() = 0;
```
等待命令队列完成所有操作。
等待命令队列完成所有已提交的操作。这是确保 GPU 执行完所有待处理命令的最简单方法，适用于需要完全同步的场景（如资源销毁前）。
**参数：** 无
**返回：** 无
**线程安全：** ❌ 非线程安全，应在渲染线程中调用
**复杂度：** O(n) - 取决于待处理命令的数量
**示例：**
```cpp
cmdQueue->WaitForIdle();
#include "RHICommandQueue.h"
void EnsureGPUIdle(RHICommandQueue* cmdQueue) {
cmdQueue->ExecuteCommandLists(1, (void**)&cmdList);
cmdQueue->WaitForIdle();
}
```
## 相关文档
- [RHICommandQueue 总览](command-queue.md) - 返回类总览
- [Wait](wait.md) - 等待栅栏

36
docs/api/rhi/command-queue/wait.md Normal file
View File

@@ -0,0 +1,36 @@
# RHICommandQueue::Wait
```cpp
virtual void Wait(RHIFence* fence, uint64_t value) = 0;
```
等待指定栅栏达到或超过 `value` 值。在栅栏值未达到指定值之前，命令队列的所有后续操作都不会开始执行。该方法用于 CPU 到 GPU 同步。
**参数：**
- `fence` - 目标栅栏对象，不能为 `nullptr`
- `value` - 等待的信号值，一个 64 位无符号整数
**返回：** 无
**线程安全：** ❌ 非线程安全，应在渲染线程中调用
**复杂度：** O(1) - 实际操作取决于底层同步机制
**示例：**
```cpp
#include "RHICommandQueue.h"
#include "RHIFence.h"
void CPUTO GPUSync(RHICommandQueue* cmdQueue, RHIFence* fence) {
cmdQueue->Signal(fence, 1);
cmdQueue->Wait(fence, 1);
}
```
## 相关文档
- [RHICommandQueue 总览](command-queue.md) - 返回类总览
- [Signal](signal.md) - 信号栅栏
- [GetCompletedValue](get-completed-value.md) - 获取完成值
- [RHIFence](../fence/fence.md) - 同步栅栏