docs: update RHI API docs

docs/api/rhi/d3d12/command-queue/command-queue.md

@@ -2,25 +2,48 @@
 
 **命名空间**: `XCEngine::RHI`
 
+**类型**: `class`
+
+**继承**: `RHICommandQueue`
+
 **描述**: DirectX 12 命令队列的 D3D12 实现，继承自 `RHICommandQueue`。
 
 ## 公共方法
 
-| 方法 | 描述 |
-|------|------|
-| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化命令队列 |
-| [`Shutdown`](../../../threading/task-system/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) | 等待空闲 |
-| [`GetType`](../../command-queue/get-type.md) | 获取队列类型 |
-| [`GetTimestampFrequency`](get-timestamp-frequency.md) | 获取时间戳频率 |
-| [`GetCommandQueue`](get-command-queue.md) | 获取 D3D12 命令队列 |
-| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 |
+| 方法 | 描述 | 类型 |
+|------|------|------|
+| [`Initialize`](initialize.md) | 初始化命令队列 | D3D12 特有 |
+| [`Shutdown`](shutdown.md) | 关闭命令队列 | Override |
+| [`ExecuteCommandLists`](execute-command-lists.md) | 执行命令列表 | Override |
+| [`Signal`](signal.md) | 信号栅栏（RHIFence 重载） | Override |
+| [`Signal(ID3D12Fence*)`](signal-native.md) | 信号栅栏（Native D3D12Fence） | D3D12 特有 |
+| [`Wait`](wait.md) | 等待栅栏达到指定值 | Override |
+| [`Wait(ID3D12Fence*)`](wait-native.md) | 等待栅栏（Native D3D12Fence） | D3D12 特有 |
+| [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | Override |
+| [`WaitForIdle`](wait-for-idle.md) | 等待空闲 | Override |
+| [`GetType`](get-type.md) | 获取队列类型 | Override |
+| [`GetTimestampFrequency`](get-timestamp-frequency.md) | 获取时间戳频率 | Override |
+| [`GetCommandQueue`](get-command-queue.md) | 获取 D3D12 命令队列 | D3D12 特有 |
+| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | Override |
+
+## 使用示例
+
+```cpp
+ID3D12Device* device; // 初始化好的 D3D12 设备
+D3D12CommandQueue commandQueue;
+
+if (commandQueue.Initialize(device, CommandQueueType::Direct)) {
+    // 使用命令队列
+    commandQueue.ExecuteCommandLists(count, lists);
+    
+    // 等待完成
+    commandQueue.WaitForIdle();
+}
+```
 
 ## 相关文档
 
-- [D3D12 后端总览](../../opengl/overview.md)
+- [D3D12 后端总览](../d3d12.md)
 - [RHICommandQueue](../../command-queue/command-queue.md) - 抽象命令队列接口
+- [D3D12CommandList](../command-list/command-list.md)
+- [D3D12Fence](../fence/fence.md)

docs/api/rhi/d3d12/command-queue/execute-command-lists.md

@@ -4,14 +4,31 @@
 void ExecuteCommandLists(uint32_t count, void** lists) override;
 ```
 
-执行命令列表。
+将指定数量的命令列表提交到命令队列执行。所有命令列表将在 GPU 上按提交顺序串行执行。
 
 **参数：**
-- `count` - 命令列表数量
-- `lists` - 命令列表指针数组
+- `count` - 命令列表数量，为正整数
+- `lists` - 命令列表指针数组，每个元素类型为 `ID3D12CommandList*`
 
-**复杂度：** O(n)
+**返回：** 无
+
+**线程安全：** 可从任意线程调用，建议从单线程提交以保证顺序
+
+**复杂度：** O(1) 提交，O(n) GPU 执行（n 为命令数量）
+
+**注意：** 此方法会阻塞调用线程直到命令列表提交完成，GPU 实际执行是异步的。
+
+## 示例
+
+```cpp
+ID3D12CommandList* lists[2];
+lists[0] = commandList1->GetCommandList();
+lists[1] = commandList2->GetCommandList();
+
+commandQueue.ExecuteCommandLists(2, reinterpret_cast<void**>(lists));
+```
 
 ## 相关文档
 
 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [D3D12CommandList](../command-list/command-list.md)

docs/api/rhi/d3d12/command-queue/get-completed-value.md

@@ -4,12 +4,16 @@
 uint64_t GetCompletedValue() override;
 ```
 
-获取已完成值。
+获取命令队列关联的栅栏的当前完成值。
 
-**返回：** 栅栏已完成的值
+**返回：** 栅栏的已完成值
 
 **复杂度：** O(1)
 
+**注意：** 当前实现始终返回 0，表示此方法为未完成功能。使用前请确认功能状态。
+
 ## 相关文档
 
 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Signal](signal.md) - 向栅栏发送信号
+- [D3D12Fence](../fence/fence.md)

docs/api/rhi/d3d12/command-queue/get-native-handle.md

@@ -0,0 +1,18 @@
+# D3D12CommandQueue::GetNativeHandle
+
+```cpp
+void* GetNativeHandle() override { return m_commandQueue.Get(); }
+```
+
+获取命令队列的原生句柄，用于与底层 D3D12 API 交互。
+
+**返回：** `void*` 类型的原生指针，实际类型为 `ID3D12CommandQueue*`
+
+**复杂度：** O(1)
+
+**注意：** 返回的指针在命令队列销毁后将变为无效。请勿在命令队列销毁后继续使用。
+
+## 相关文档
+
+- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [GetCommandQueue](get-command-queue.md) - 获取类型安全的 D3D12 命令队列指针

docs/api/rhi/d3d12/command-queue/get-type.md

@@ -0,0 +1,21 @@
+# D3D12CommandQueue::GetType
+
+```cpp
+CommandQueueType GetType() const override { return m_type; }
+```
+
+获取命令队列的类型。
+
+**返回：** `CommandQueueType` 枚举值，表示命令队列类型
+
+- `Direct` - 直接命令队列，用于图形和计算操作
+- `Compute` - 计算命令队列，用于纯计算操作
+- `Copy` - 复制命令队列，用于数据传输操作
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Initialize](initialize.md) - 初始化命令队列
+- [CommandQueueType](../../common/enums.md#commandqueuetype) - 队列类型枚举说明

docs/api/rhi/d3d12/command-queue/initialize.md

@@ -0,0 +1,31 @@
+# D3D12CommandQueue::Initialize
+
+```cpp
+bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct);
+```
+
+初始化 D3D12 命令队列，创建底层 `ID3D12CommandQueue` 对象。
+
+**参数：**
+- `device` - D3D12 设备指针
+- `type` - 命令队列类型，默认为 `Direct`
+
+**返回：** 初始化成功返回 `true`，失败返回 `false`
+
+**复杂度：** O(1)
+
+## 示例
+
+```cpp
+ID3D12Device* device; // 已初始化的 D3D12 设备
+D3D12CommandQueue commandQueue;
+
+if (commandQueue.Initialize(device, CommandQueueType::Direct)) {
+    // 命令队列初始化成功
+}
+```
+
+## 相关文档
+
+- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Shutdown](../../command-queue/shutdown.md) - 关闭命令队列

docs/api/rhi/d3d12/command-queue/shutdown.md

@@ -0,0 +1,31 @@
+# D3D12CommandQueue::Shutdown
+
+```cpp
+void Shutdown() override;
+```
+
+关闭命令队列并释放底层 D3D12 资源。调用此方法后，命令队列将变为无效状态。
+
+**返回：** 无
+
+**注意：**
+- 此方法由析构函数自动调用
+- 调用前应确保没有正在执行命令
+- 释放底层的 `ID3D12CommandQueue` 接口
+
+## 示例
+
+```cpp
+D3D12CommandQueue commandQueue;
+commandQueue.Initialize(device, CommandQueueType::Direct);
+
+// 使用命令队列...
+
+// 关闭并释放资源
+commandQueue.Shutdown();
+```
+
+## 相关文档
+
+- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Initialize](initialize.md) - 初始化命令队列

docs/api/rhi/d3d12/command-queue/signal-native.md

@@ -0,0 +1,25 @@
+# D3D12CommandQueue::Signal (Native)
+
+```cpp
+void Signal(ID3D12Fence* fence, uint64_t value);
+```
+
+向 D3D12 原生栅栏发送信号。
+
+**参数：**
+- `fence` - D3D12 原生栅栏指针
+- `value` - 信号值
+
+**复杂度：** O(1)
+
+## 示例
+
+```cpp
+ID3D12Fence* nativeFence; // D3D12 原生栅栏
+commandQueue.Signal(nativeFence, 1);
+```
+
+## 相关文档
+
+- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Signal(RHIFence*)](../../command-queue/signal.md) - RHIFence 重载版本

docs/api/rhi/d3d12/command-queue/signal.md

@@ -4,14 +4,31 @@
 void Signal(RHIFence* fence, uint64_t value) override;
 ```
 
-发送信号。
+向指定栅栏发送信号，将栅栏的完成值设置为给定值。该方法用于同步 GPU 和 CPU 操作。
 
 **参数：**
-- `fence` - 栅栏指针
-- `value` - 信号值
+- `fence` - 目标栅栏指针，不能为 `nullptr`
+- `value` - 信号值，一个正整数
+
+**返回：** 无
 
 **复杂度：** O(1)
 
+**使用场景：**
+- 标记命令队列中所有已提交命令完成的时间点
+- 用于 GPU-CPU 同步
+- 与 `Wait` 方法配合实现 GPU 流水线同步
+
+## 示例
+
+```cpp
+D3D12Fence* fence; // 已初始化的栅栏
+commandQueue.Signal(fence, 1);
+// CPU 可以继续其他工作，GPU 执行完成后 fence 的值变为 1
+```
+
 ## 相关文档
 
 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Wait](wait-for-idle.md) - 等待命令队列完成
+- [D3D12Fence](../fence/fence.md)

docs/api/rhi/d3d12/command-queue/wait-for-idle.md

@@ -4,10 +4,33 @@
 void WaitForIdle() override;
 ```
 
-等待空闲。
+阻塞当前线程，直到命令队列中所有已提交的命令全部执行完成。该方法会强制 GPU 等待所有待处理命令完成后才返回。
 
-**复杂度：** O(n)
+**返回：** 无
+
+**复杂度：** O(n)，其中 n 为待处理命令的数量
+
+**使用场景：**
+- 帧同步：确保一帧的所有渲染命令完成后再进行下一步操作
+- 资源管理：确保 GPU 不再使用某个资源后再释放
+- 调试：等待特定命令完成以便进行 GPU 调试
+
+**注意：** 这是一个阻塞调用，会暂停 CPU 线程直到 GPU 完成所有命令。频繁调用可能影响性能。
+
+## 示例
+
+```cpp
+// 提交渲染命令
+commandQueue.ExecuteCommandLists(count, lists);
+
+// 等待所有命令完成
+commandQueue.WaitForIdle();
+
+// 此时可以安全地释放命令列表使用的资源
+```
 
 ## 相关文档
 
 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Signal](signal.md) - 向栅栏发送信号
+- [Wait](signal.md) - 等待栅栏达到指定值

docs/api/rhi/d3d12/command-queue/wait-native.md

@@ -0,0 +1,25 @@
+# D3D12CommandQueue::Wait (Native)
+
+```cpp
+void Wait(ID3D12Fence* fence, uint64_t value);
+```
+
+等待 D3D12 原生栅栏达到指定值。
+
+**参数：**
+- `fence` - D3D12 原生栅栏指针
+- `value` - 等待的信号值
+
+**复杂度：** O(1)
+
+## 示例
+
+```cpp
+ID3D12Fence* nativeFence; // D3D12 原生栅栏
+commandQueue.Wait(nativeFence, 1);
+```
+
+## 相关文档
+
+- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Wait(RHIFence*)](../../command-queue/wait.md) - RHIFence 重载版本

docs/api/rhi/d3d12/command-queue/wait.md

@@ -0,0 +1,37 @@
+# D3D12CommandQueue::Wait
+
+```cpp
+void Wait(RHIFence* fence, uint64_t value) override;
+```
+
+阻塞命令队列，直到指定栅栏的完成值达到指定值。该方法用于 GPU 内部的同步操作。
+
+**参数：**
+- `fence` - 目标栅栏指针，不能为 `nullptr`
+- `value` - 等待的信号值
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**使用场景：**
+- 等待另一个命令队列的操作完成
+- 实现 GPU 流水线各阶段之间的同步
+- 多 GPU 节点间的同步
+
+**注意：** 如果栅栏的当前值已经大于或等于指定值，则此方法立即返回。
+
+## 示例
+
+```cpp
+D3D12Fence* fence; // 已发送信号的栅栏
+// 等待 fence 的值达到 1
+commandQueue.Wait(fence, 1);
+```
+
+## 相关文档
+
+- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览
+- [Signal](signal.md) - 向栅栏发送信号
+- [Wait(ID3D12Fence*)](wait-native.md) - Native D3D12Fence 版本
+- [D3D12Fence](../fence/fence.md)