docs: update RHI API docs

docs/api/rhi/buffer/buffer.md

@@ -4,6 +4,8 @@
 
 **类型**: `class` (abstract)
 
+**头文件**: `XCEngine/RHI/RHIBuffer.h`
+
 **描述**: GPU 缓冲区资源抽象接口，用于管理顶点缓冲、索引缓冲、常量缓冲等 GPU 内存资源。
 
 ## 概述

docs/api/rhi/buffer/get-buffer-type.md

@@ -4,12 +4,25 @@
 virtual BufferType GetBufferType() const = 0;
 ```
 
-获取缓冲区类型。
+获取缓冲区的类型，用于区分顶点缓冲、索引缓冲、常量缓冲等。
 
-**返回：** 缓冲区类型枚举值
+**返回：** `BufferType` 枚举值
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+BufferType type = buffer->GetBufferType();
+if (type == BufferType::Vertex) {
+    printf("This is a vertex buffer\n");
+} else if (type == BufferType::Index) {
+    printf("This is an index buffer\n");
+}
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-name.md

@@ -4,12 +4,21 @@
 virtual const std::string& GetName() const = 0;
 ```
 
-获取缓冲区名称（用于调试）。
+获取缓冲区名称（用于调试和诊断）。名称通常在图形调试器（如 RenderDoc、PIX）中显示。
 
-**返回：** 缓冲区名称
+**返回：** 缓冲区名称字符串
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+const std::string& name = buffer->GetName();
+printf("Buffer name: %s\n", name.c_str());
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-native-handle.md

@@ -4,14 +4,26 @@
 virtual void* GetNativeHandle() = 0;
 ```
 
-获取原生 API 句柄。
+获取底层图形 API 的原生资源句柄，用于平台特定操作或调试。
 
-**返回：** 
+**返回：**
 - D3D12: `ID3D12Resource*`
-- OpenGL: `GLuint` 指针
+- Vulkan: `VkBuffer`
+- OpenGL: `GLuint`
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+void* handle = buffer->GetNativeHandle();
+#ifdef _WIN32
+    ID3D12Resource* d3d12Resource = static_cast<ID3D12Resource*>(handle);
+#endif
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-size.md

@@ -4,12 +4,21 @@
 virtual uint64_t GetSize() const = 0;
 ```
 
-获取缓冲区大小（字节）。
+获取缓冲区总大小（字节）。
 
-**返回：** 缓冲区大小
+**返回：** 缓冲区大小（字节）
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+uint64_t size = buffer->GetSize();
+printf("Buffer size: %llu bytes\n", (unsigned long long)size);
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-state.md

@@ -4,12 +4,23 @@
 virtual ResourceStates GetState() const = 0;
 ```
 
-获取当前资源状态。
+获取缓冲区当前所处的资源状态。资源状态决定缓冲区可以用于哪些 GPU 操作。
 
-**返回：** 资源状态枚举值
+**返回：** `ResourceStates` 枚举值
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ResourceStates state = buffer->GetState();
+if (state == ResourceStates::VertexAndConstantBuffer) {
+    printf("Buffer is ready for vertex binding\n");
+}
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-stride.md

@@ -4,12 +4,21 @@
 virtual uint32_t GetStride() const = 0;
 ```
 
-获取单个元素的字节大小。
+获取单个元素的字节大小（步长）。对于顶点缓冲是单个顶点的字节大小，对于索引缓冲是单个索引的字节大小。
 
 **返回：** 元素步长（字节）
 
+**线程安全：** ✅
+
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+uint32_t stride = buffer->GetStride();
+printf("Element stride: %u bytes\n", stride);
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/map.md

@@ -4,9 +4,11 @@
 virtual void* Map() = 0;
 ```
 
-映射缓冲区内存到 CPU 可访问空间。
+将缓冲区 GPU 内存映射到 CPU 可访问的虚拟地址空间。映射后可直接使用 memcpy 等 CPU 内存操作函数写入数据。
 
-**返回：** 指向缓冲区数据的指针
+**返回：** 指向缓冲区数据的指针，映射失败返回 `nullptr`
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 

docs/api/rhi/buffer/set-buffer-type.md

@@ -4,13 +4,21 @@
 virtual void SetBufferType(BufferType type) = 0;
 ```
 
-设置缓冲区类型。
+设置缓冲区的类型。应在缓冲区创建后立即设置，确保后续绑定到渲染管线时使用正确的类型。
 
 **参数：**
-- `type` - 新的缓冲区类型
+- `type` - 缓冲区类型（`Vertex`、`Index`、`Constant` 等）
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+buffer->SetBufferType(BufferType::Vertex);
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/set-stride.md

@@ -4,13 +4,21 @@
 virtual void SetStride(uint32_t stride) = 0;
 ```
 
-设置元素字节大小。
+设置单个元素的字节大小（步长）。
 
 **参数：**
-- `stride` - 新的步长值
+- `stride` - 新的步长值（字节）
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+buffer->SetStride(sizeof(Vertex));
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/shutdown.md

@@ -4,10 +4,20 @@
 virtual void Shutdown() = 0;
 ```
 
-释放缓冲区资源。
+关闭并释放缓冲区资源。调用后缓冲区不再可用，所有已绑定的命令列表中的引用将失效。
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+buffer->Shutdown();
+// buffer is now invalid
+delete buffer;
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/unmap.md

@@ -4,15 +4,17 @@
 virtual void Unmap() = 0;
 ```
 
-取消内存映射。
+取消缓冲区内存映射，使 GPU 可以继续访问该内存。在调用 `Map()` 后必须调用此方法。
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
 **示例：**
 
 ```cpp
-buffer->Map();
-memcpy(mappedData, sourceData, size);
+void* data = buffer->Map();
+memcpy(data, sourceData, size);
 buffer->Unmap();
 ```
 

docs/api/rhi/capabilities/capabilities.md

@@ -4,61 +4,65 @@
 
 **类型**: `struct`
 
+**头文件**: `XCEngine/RHI/RHICapabilities.h`
+
 **描述**: GPU 设备能力结构体，描述了当前图形设备支持的各种功能和限制。
 
-## 公共成员
+## 概述
 
-### 特性支持
+`RHICapabilities` 是一个纯数据结构的 struct，用于在运行时查询当前 GPU 设备的能力和限制。开发者可以通过 `RHIDevice::GetCapabilities()` 获取设备能力信息，据此决定是否启用特定图形特性（如光线追踪、网格着色器等），或在进行资源创建时确保不超过设备支持的范围。
 
-| 成员 | 类型 | 描述 |
-|------|------|------|
-| `bSupportsRayTracing` | `bool` | 支持光线追踪 |
-| `bSupportsMeshShaders` | `bool` | 支持 Mesh 着色器 |
-| `bSupportsExplicitMultiThreading` | `bool` | 支持显式多线程 |
-| `bSupportsGeometryShaders` | `bool` | 支持几何着色器 |
-| `bSupportsTessellation` | `bool` | 支持曲面细分 |
-| `bSupportsComputeShaders` | `bool` | 支持计算着色器 |
-| `bSupportsDepthBoundsTest` | `bool` | 支持深度范围测试 |
-| `bSupportsAlphaToCoverage` | `bool` | 支持 Alpha 到覆盖 |
-| `bSupportsIndependentBlend` | `bool` | 支持独立混合 |
-| `bSupportsLogicOps` | `bool` | 支持逻辑操作 |
-| `bSupportsMultiViewport` | `bool` | 支持多视口 |
-| `bSupportsConservativeRasterization` | `bool` | 支持保守光栅化 |
-| `bSupportsProgrammableSamplePositions` | `bool` | 支持可编程采样位置 |
+## 结构体成员
+
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `bSupportsRayTracing` | `bool` | 支持光线追踪 | - |
+| `bSupportsMeshShaders` | `bool` | 支持 Mesh 着色器 | - |
+| `bSupportsExplicitMultiThreading` | `bool` | 支持显式多线程 | - |
+| `bSupportsGeometryShaders` | `bool` | 支持几何着色器 | - |
+| `bSupportsTessellation` | `bool` | 支持曲面细分 | - |
+| `bSupportsComputeShaders` | `bool` | 支持计算着色器 | - |
+| `bSupportsDepthBoundsTest` | `bool` | 支持深度范围测试 | - |
+| `bSupportsAlphaToCoverage` | `bool` | 支持 Alpha 到覆盖 | - |
+| `bSupportsIndependentBlend` | `bool` | 支持独立混合 | - |
+| `bSupportsLogicOps` | `bool` | 支持逻辑操作 | - |
+| `bSupportsMultiViewport` | `bool` | 支持多视口 | - |
+| `bSupportsConservativeRasterization` | `bool` | 支持保守光栅化 | - |
+| `bSupportsProgrammableSamplePositions` | `bool` | 支持可编程采样位置 | - |
 
 ### 资源限制
 
-| 成员 | 类型 | 描述 |
-|------|------|------|
-| `maxTexture2DSize` | `uint32_t` | 最大 2D 纹理尺寸 |
-| `maxTexture3DSize` | `uint32_t` | 最大 3D 纹理尺寸 |
-| `maxTextureCubeSize` | `uint32_t` | 最大立方体贴图尺寸 |
-| `maxRenderTargets` | `uint32_t` | 最大渲染目标数量 |
-| `maxViewports` | `uint32_t` | 最大视口数量 |
-| `maxVertexAttribs` | `uint32_t` | 最大顶点属性数量 |
-| `maxConstantBufferSize` | `uint32_t` | 最大常量缓冲大小 |
-| `maxAnisotropy` | `uint32_t` | 最大各向异性级别 |
-| `maxColorAttachments` | `uint32_t` | 最大颜色附件数量 |
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `maxTexture2DSize` | `uint32_t` | 最大 2D 纹理尺寸 | - |
+| `maxTexture3DSize` | `uint32_t` | 最大 3D 纹理尺寸 | - |
+| `maxTextureCubeSize` | `uint32_t` | 最大立方体贴图尺寸 | - |
+| `maxRenderTargets` | `uint32_t` | 最大渲染目标数量 | - |
+| `maxViewports` | `uint32_t` | 最大视口数量 | - |
+| `maxVertexAttribs` | `uint32_t` | 最大顶点属性数量 | - |
+| `maxConstantBufferSize` | `uint32_t` | 最大常量缓冲大小 | - |
+| `maxAnisotropy` | `uint32_t` | 最大各向异性级别 | - |
+| `maxColorAttachments` | `uint32_t` | 最大颜色附件数量 | - |
 
 ### 线宽和点大小
 
-| 成员 | 类型 | 描述 |
-|------|------|------|
-| `minSmoothedLineWidth` | `float` | 最小平滑线宽 |
-| `maxSmoothedLineWidth` | `float` | 最大平滑线宽 |
-| `minPointSize` | `float` | 最小点大小 |
-| `maxPointSize` | `float` | 最大点大小 |
-| `maxPointSizeAA` | `float` | 抗锯齿最大点大小 |
-| `maxLineWidth` | `float` | 最大线宽 |
-| `maxLineWidthAA` | `float` | 抗锯齿最大线宽 |
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `minSmoothedLineWidth` | `float` | 最小平滑线宽 | - |
+| `maxSmoothedLineWidth` | `float` | 最大平滑线宽 | - |
+| `minPointSize` | `float` | 最小点大小 | - |
+| `maxPointSize` | `float` | 最大点大小 | - |
+| `maxPointSizeAA` | `float` | 抗锯齿最大点大小 | - |
+| `maxLineWidth` | `float` | 最大线宽 | - |
+| `maxLineWidthAA` | `float` | 抗锯齿最大线宽 | - |
 
 ### 版本信息
 
-| 成员 | 类型 | 描述 |
-|------|------|------|
-| `majorVersion` | `int` | 主版本号 |
-| `minorVersion` | `int` | 次版本号 |
-| `shaderModel` | `std::string` | 着色器模型版本 |
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `majorVersion` | `int` | 主版本号 | - |
+| `minorVersion` | `int` | 次版本号 | - |
+| `shaderModel` | `std::string` | 着色器模型版本 | - |
 
 ## 使用示例
 
@@ -78,5 +82,5 @@ uint32_t textureSize = std::min(requestedSize, caps.maxTexture2DSize);
 
 ## 相关文档
 
-- [../rhi/rhi.md](../rhi.md) - RHI 模块总览
+- [RHI 模块](../rhi.md) - RHI 模块总览
 - [RHIDevice](../device/device.md) - 设备对象

docs/api/rhi/command-list/clear-depth-stencil.md

@@ -4,12 +4,20 @@
 virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) = 0;
 ```
 
-清除深度模板缓冲区。
+清除深度模板视图。可同时清除深度值和模板值。
 
 **参数：**
-- `depthStencil` - 深度模板缓冲区指针
-- `depth` - 深度值
-- `stencil` - 模板值
+- `depthStencil` - 深度模板视图指针
+- `depth` - 清除深度值（通常为 1.0）
+- `stencil` - 清除模板值（范围 0-255）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -20,3 +28,5 @@ cmdList->ClearDepthStencil(depthStencil, 1.0f, 0);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [Clear](clear.md) - 清除多个渲染目标
+- [SetRenderTargets](set-render-targets.md) - 设置渲染目标

docs/api/rhi/command-list/clear-render-target.md

@@ -4,11 +4,19 @@
 virtual void ClearRenderTarget(void* renderTarget, const float color[4]) = 0;
 ```
 
-清除渲染目标。
+清除指定的渲染目标视图。用给定的颜色值填充整个渲染目标。
 
 **参数：**
-- `renderTarget` - 渲染目标指针
-- `color` - 清除颜色 [r, g, b, a]
+- `renderTarget` - 渲染目标视图指针
+- `color` - 4 元素浮点数数组，表示 RGBA 清除颜色（范围 0.0-1.0）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -20,3 +28,5 @@ cmdList->ClearRenderTarget(renderTarget, color);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [Clear](clear.md) - 清除多个渲染目标
+- [SetRenderTargets](set-render-targets.md) - 设置渲染目标

docs/api/rhi/command-list/clear.md

@@ -4,17 +4,31 @@
 virtual void Clear(float r, float g, float b, float a, uint32_t buffers) = 0;
 ```
 
-清除渲染目标。
+清除多个渲染目标。可同时清除颜色、深度和模板缓冲区。
 
 **参数：**
-- `r` - 红色分量
-- `g` - 绿色分量
-- `b` - 蓝色分量
-- `a` - Alpha 分量
-- `buffers` - 要清除的缓冲区标志
+- `r` - 清除颜色红色分量（范围 0.0-1.0）
+- `g` - 清除颜色绿色分量（范围 0.0-1.0）
+- `b` - 清除颜色蓝色分量（范围 0.0-1.0）
+- `a` - 清除颜色 Alpha 分量（范围 0.0-1.0）
+- `buffers` - 要清除的缓冲区标志位（ClearFlags 枚举组合）
 
-**复杂度：** O(1)
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+cmdList->Clear(0.0f, 0.0f, 0.0f, 1.0f, 0x1); // 清除颜色缓冲
+```
 
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [ClearRenderTarget](clear-render-target.md) - 清除渲染目标
+- [ClearDepthStencil](clear-depth-stencil.md) - 清除深度模板

docs/api/rhi/command-list/close.md

@@ -4,10 +4,26 @@
 virtual void Close() = 0;
 ```
 
-关闭命令列表以执行。
+关闭命令列表以执行。调用此方法后，命令列表中的命令无法再被修改，可以提交给图形设备执行。
+
+**参数：** 无
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+commandList->Close();
+```
+
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [Reset](reset.md) - 重置命令列表
+- [Shutdown](shutdown.md) - 关闭命令列表

docs/api/rhi/command-list/command-list.md

@@ -4,12 +4,26 @@
 
 **类型**: `class` (abstract)
 
-**描述**: GPU 命令列表抽象接口，用于录制和执行 GPU 命令。
+**头文件**: `XCEngine/RHI/RHICommandList.h`
+
+**描述**: GPU 命令列表抽象接口，用于录制和执行 GPU 渲染命令
+
+## 概述
+
+`RHICommandList` 是渲染硬件接口（RHI）层提供的抽象命令列表类，用于录制 GPU 命令并提交执行。该类是纯虚接口，具体实现由各图形 API（D3D12、Vulkan 等）提供。
+
+主要功能包括：
+- 状态设置（管线、视口、裁剪、渲染目标等）
+- 资源绑定（顶点缓冲、索引缓冲等）
+- 绘制调用（Draw、DrawIndexed）
+- 资源操作（复制、转换状态）
+- 计算着色器分发
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
+| [`Shutdown`](shutdown.md) | 关闭命令列表并释放资源 |
 | [`Reset`](reset.md) | 重置命令列表 |
 | [`Close`](close.md) | 关闭命令列表 |
 | [`TransitionBarrier`](transition-barrier.md) | 资源状态转换 |
@@ -21,7 +35,7 @@
 | [`SetScissorRects`](set-scissor-rects.md) | 设置多个裁剪矩形 |
 | [`SetRenderTargets`](set-render-targets.md) | 设置渲染目标 |
 | [`SetDepthStencilState`](set-depth-stencil-state.md) | 设置深度模板状态 |
-| [`SetStencilRef`](set-stencil-ref.md) | 设置模板引用值 |
+| [`SetStencilRef`](set-stencil-ref.md) | 设置模板参考值 |
 | [`SetBlendState`](set-blend-state.md) | 设置混合状态 |
 | [`SetBlendFactor`](set-blend-factor.md) | 设置混合因子 |
 | [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲 |
@@ -34,7 +48,6 @@
 | [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度模板 |
 | [`CopyResource`](copy-resource.md) | 复制资源 |
 | [`Dispatch`](dispatch.md) | 分发计算任务 |
-| [`Shutdown`](shutdown.md) | 关闭并释放资源 |
 
 ## 使用示例
 
@@ -51,5 +64,5 @@ commandQueue->ExecuteCommandLists(1, (void**)&commandList);
 
 ## 相关文档
 
-- [../rhi/rhi.md](../rhi.md) - RHI 模块总览
-- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列
+- [RHI 模块总览](../rhi.md) - RHI 模块总览
+- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列

docs/api/rhi/command-list/copy-resource.md

@@ -4,11 +4,19 @@
 virtual void CopyResource(void* dst, void* src) = 0;
 ```
 
-复制资源。
+复制整个资源的内容。源资源和目标资源必须类型相同且大小相等。
 
 **参数：**
-- `dst` - 目标资源
-- `src` - 源资源
+- `dst` - 目标资源指针
+- `src` - 源资源指针
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(n)，n 为资源大小
 
 **示例：**
 
@@ -19,3 +27,4 @@ cmdList->CopyResource(dstTexture, srcTexture);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [TransitionBarrier](transition-barrier.md) - 设置资源状态转换

docs/api/rhi/command-list/dispatch.md

@@ -4,13 +4,21 @@
 virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z) = 0;
 ```
 
-分发计算着色器。
+分发计算着色器线程组。用于执行计算着色器（Compute Shader），将工作分配到三维线程网格中。
 
 **参数：**
 - `x` - X 方向线程组数量
 - `y` - Y 方向线程组数量
 - `z` - Z 方向线程组数量
 
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(x * y * z)
+
 **示例：**
 
 ```cpp
@@ -20,3 +28,5 @@ cmdList->Dispatch(8, 8, 1); // 分发 8x8x1 线程组
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetPipelineState](set-pipeline-state.md) - 设置管线状态
+- [Draw](draw.md) - 绘制

docs/api/rhi/command-list/draw-indexed.md

@@ -4,14 +4,22 @@
 virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) = 0;
 ```
 
-绘制索引图元。
+执行索引绘制调用。通过索引缓冲区从顶点缓冲区中选择顶点绘制图元，允许顶点复用。
 
 **参数：**
 - `indexCount` - 索引数量
-- `instanceCount` - 实例数量（默认1）
-- `startIndex` - 起始索引
-- `baseVertex` - 基础顶点索引
-- `startInstance` - 起始实例索引
+- `instanceCount` - 实例数量（默认 1）
+- `startIndex` - 起始索引偏移（默认 0）
+- `baseVertex` - 基础顶点偏移（默认 0）
+- `startInstance` - 起始实例偏移（默认 0）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(indexCount * instanceCount)
 
 **示例：**
 
@@ -22,3 +30,5 @@ cmdList->DrawIndexed(36); // 绘制36个索引
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [Draw](draw.md) - 绘制
+- [SetIndexBuffer](set-index-buffer.md) - 设置索引缓冲

docs/api/rhi/command-list/draw.md

@@ -4,13 +4,21 @@
 virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) = 0;
 ```
 
-绘制调用。
+执行非索引绘制调用。从顶点缓冲区按顺序读取顶点数据绘制图元。
 
 **参数：**
 - `vertexCount` - 顶点数量
-- `instanceCount` - 实例数量（默认1）
-- `startVertex` - 起始顶点索引
-- `startInstance` - 起始实例索引
+- `instanceCount` - 实例数量（默认 1）
+- `startVertex` - 起始顶点偏移（默认 0）
+- `startInstance` - 起始实例偏移（默认 0）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(vertexCount * instanceCount)
 
 **示例：**
 
@@ -21,3 +29,5 @@ cmdList->Draw(36); // 绘制36个顶点
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [DrawIndexed](draw-indexed.md) - 索引绘制
+- [SetVertexBuffer](set-vertex-buffer.md) - 设置顶点缓冲

docs/api/rhi/command-list/methods.md

@@ -1,201 +0,0 @@
-# RHICommandList 方法
-
-## Reset
-
-```cpp
-virtual void Reset() = 0;
-```
-
-重置命令列表，开始新的录制。
-
-## Close
-
-```cpp
-virtual void Close() = 0;
-```
-
-关闭命令列表，结束录制。
-
-## TransitionBarrier
-
-```cpp
-virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) = 0;
-```
-
-资源状态转换屏障。
-
-## SetPipelineState
-
-```cpp
-virtual void SetPipelineState(void* pso) = 0;
-```
-
-设置管线状态对象。
-
-## SetPrimitiveTopology
-
-```cpp
-virtual void SetPrimitiveTopology(PrimitiveTopology topology) = 0;
-```
-
-设置图元拓扑。
-
-## SetViewport
-
-```cpp
-virtual void SetViewport(const Viewport& viewport) = 0;
-```
-
-设置视口。
-
-## SetViewports
-
-```cpp
-virtual void SetViewports(uint32_t count, const Viewport* viewports) = 0;
-```
-
-设置多个视口。
-
-## SetScissorRect
-
-```cpp
-virtual void SetScissorRect(const Rect& rect) = 0;
-```
-
-设置裁剪矩形。
-
-## SetScissorRects
-
-```cpp
-virtual void SetScissorRects(uint32_t count, const Rect* rects) = 0;
-```
-
-设置多个裁剪矩形。
-
-## SetRenderTargets
-
-```cpp
-virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) = 0;
-```
-
-设置渲染目标。
-
-## SetDepthStencilState
-
-```cpp
-virtual void SetDepthStencilState(const DepthStencilState& state) = 0;
-```
-
-设置深度模板状态。
-
-## SetStencilRef
-
-```cpp
-virtual void SetStencilRef(uint8_t ref) = 0;
-```
-
-设置模板参考值。
-
-## SetBlendState
-
-```cpp
-virtual void SetBlendState(const BlendState& state) = 0;
-```
-
-设置混合状态。
-
-## SetBlendFactor
-
-```cpp
-virtual void SetBlendFactor(const float factor[4]) = 0;
-```
-
-设置混合因子。
-
-## SetVertexBuffer
-
-```cpp
-virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) = 0;
-```
-
-设置顶点缓冲。
-
-## SetVertexBuffers
-
-```cpp
-virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) = 0;
-```
-
-设置多个顶点缓冲。
-
-## SetIndexBuffer
-
-```cpp
-virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format) = 0;
-```
-
-设置索引缓冲。
-
-## Draw
-
-```cpp
-virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) = 0;
-```
-
-绘制调用。
-
-## DrawIndexed
-
-```cpp
-virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) = 0;
-```
-
-索引绘制调用。
-
-## Clear
-
-```cpp
-virtual void Clear(float r, float g, float b, float a, uint32_t buffers) = 0;
-```
-
-清除缓冲。
-
-## ClearRenderTarget
-
-```cpp
-virtual void ClearRenderTarget(void* renderTarget, const float color[4]) = 0;
-```
-
-清除渲染目标。
-
-## ClearDepthStencil
-
-```cpp
-virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) = 0;
-```
-
-清除深度模板。
-
-## CopyResource
-
-```cpp
-virtual void CopyResource(void* dst, void* src) = 0;
-```
-
-复制资源。
-
-## Dispatch
-
-```cpp
-virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z) = 0;
-```
-
-分发计算着色器。
-
-## Shutdown
-
-```cpp
-virtual void Shutdown() = 0;
-```
-
-释放命令列表资源。

docs/api/rhi/command-list/reset.md

@@ -4,10 +4,26 @@
 virtual void Reset() = 0;
 ```
 
-重置命令列表以重新录制。
+重置命令列表以重新录制。调用此方法后，可以重新开始向命令列表添加命令。
+
+**参数：** 无
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+commandList->Reset();
+```
+
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [Close](close.md) - 关闭命令列表
+- [Shutdown](shutdown.md) - 关闭命令列表

docs/api/rhi/command-list/set-blend-factor.md

@@ -4,10 +4,18 @@
 virtual void SetBlendFactor(const float factor[4]) = 0;
 ```
 
-设置混合因子。
+设置混合因子数组。当混合函数使用可编程混合因子时，使用此方法设置 RGBA 四个通道的混合因子。
 
 **参数：**
-- `factor` - 混合因子数组 [r, g, b, a]
+- `factor` - 4 元素浮点数数组，表示 RGBA 混合因子（范围 0.0-1.0）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -19,3 +27,4 @@ cmdList->SetBlendFactor(factor);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetBlendState](set-blend-state.md) - 设置混合状态

docs/api/rhi/command-list/set-blend-state.md

@@ -4,10 +4,18 @@
 virtual void SetBlendState(const BlendState& state) = 0;
 ```
 
-设置混合状态。
+设置颜色混合状态。控制源颜色和目标颜色如何混合，影响最终输出像素的颜色值。
 
 **参数：**
-- `state` - 混合状态结构体
+- `state` - 混合状态结构体（包含 alphaToCoverageEnable、independentBlendEnable、renderTargets[] 等）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -15,9 +23,15 @@ virtual void SetBlendState(const BlendState& state) = 0;
 BlendState blendState;
 blendState.alphaToCoverageEnable = false;
 blendState.independentBlendEnable = false;
+blendState.renderTargets[0].blendEnable = true;
+blendState.renderTargets[0].srcBlend = BlendFactor::SrcAlpha;
+blendState.renderTargets[0].dstBlend = BlendFactor::InvSrcAlpha;
+blendState.renderTargets[0].blendOp = BlendOp::Add;
 cmdList->SetBlendState(blendState);
 ```
 
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetBlendFactor](set-blend-factor.md) - 设置混合因子
+- [SetPipelineState](set-pipeline-state.md) - 设置管线状态

docs/api/rhi/command-list/set-depth-stencil-state.md

@@ -4,10 +4,18 @@
 virtual void SetDepthStencilState(const DepthStencilState& state) = 0;
 ```
 
-设置深度模板状态。
+设置深度测试和模板测试的状态配置。控制像素是否根据深度值和模板值被丢弃。
 
 **参数：**
-- `state` - 深度模板状态结构体
+- `state` - 深度模板状态结构体（包含 depthEnable、depthWriteMask、depthFunc、stencilEnable 等）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -16,9 +24,12 @@ DepthStencilState dsState;
 dsState.depthEnable = true;
 dsState.depthWriteMask = true;
 dsState.depthFunc = ComparisonFunc::Less;
+dsState.stencilEnable = false;
 cmdList->SetDepthStencilState(dsState);
 ```
 
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetStencilRef](set-stencil-ref.md) - 设置模板参考值
+- [SetPipelineState](set-pipeline-state.md) - 设置管线状态

docs/api/rhi/command-list/set-index-buffer.md

@@ -4,12 +4,20 @@
 virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format) = 0;
 ```
 
-设置索引缓冲区。
+绑定索引缓冲区。索引缓冲区存储顶点索引，用于 `DrawIndexed` 调用，从顶点缓冲区中选择顶点组成图元。
 
 **参数：**
 - `buffer` - 索引缓冲区指针
-- `offset` - 数据偏移量
-- `format` - 索引格式（R16_UINT 或 R32_UINT）
+- `offset` - 缓冲区内的起始偏移量（字节）
+- `format` - 索引格式（Format::R16_UINT 或 Format::R32_UINT）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -20,3 +28,5 @@ cmdList->SetIndexBuffer(indexBuffer, 0, Format::R16_UINT);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [DrawIndexed](draw-indexed.md) - 索引绘制
+- [SetVertexBuffer](set-vertex-buffer.md) - 设置顶点缓冲

docs/api/rhi/command-list/set-pipeline-state.md

@@ -4,11 +4,19 @@
 virtual void SetPipelineState(void* pso) = 0;
 ```
 
-设置渲染管线状态对象。
+设置渲染管线状态对象。管线状态包含着色器、混合模式、深度模板设置等所有影响渲染的固定功能配置。
 
 **参数：**
 - `pso` - 管线状态对象指针
 
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
 **示例：**
 
 ```cpp
@@ -18,3 +26,5 @@ cmdList->SetPipelineState(pipelineState);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetPrimitiveTopology](set-primitive-topology.md) - 设置图元拓扑
+- [SetDepthStencilState](set-depth-stencil-state.md) - 设置深度模板状态

docs/api/rhi/command-list/set-primitive-topology.md

@@ -4,10 +4,18 @@
 virtual void SetPrimitiveTopology(PrimitiveTopology topology) = 0;
 ```
 
-设置图元拓扑类型。
+设置图元拓扑类型。拓扑类型决定了顶点如何被解释为几何图元，如点列表、线段列表、三角形列表等。
 
 **参数：**
-- `topology` - 图元拓扑类型（点、线、三角形等）
+- `topology` - 图元拓扑类型（枚举值：PointList、LineList、TriangleList 等）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -18,3 +26,5 @@ cmdList->SetPrimitiveTopology(PrimitiveTopology::TriangleList);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [Draw](draw.md) - 绘制
+- [DrawIndexed](draw-indexed.md) - 索引绘制

docs/api/rhi/command-list/set-render-targets.md

@@ -4,12 +4,20 @@
 virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) = 0;
 ```
 
-设置渲染目标和深度模板缓冲区。
+设置渲染目标和深度模板缓冲区。指定着色器将输出到的颜色缓冲区和深度模板缓冲区。
 
 **参数：**
-- `count` - 渲染目标数量
-- `renderTargets` - 渲染目标数组
-- `depthStencil` - 深度模板缓冲区（可选）
+- `count` - 渲染目标数量（最多 8 个）
+- `renderTargets` - 渲染目标数组指针
+- `depthStencil` - 深度模板缓冲区指针（可选，默认为 nullptr）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -21,3 +29,5 @@ cmdList->SetRenderTargets(1, targets, depthStencil);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [ClearRenderTarget](clear-render-target.md) - 清除渲染目标
+- [ClearDepthStencil](clear-depth-stencil.md) - 清除深度模板

docs/api/rhi/command-list/set-scissor-rect.md

@@ -4,10 +4,18 @@
 virtual void SetScissorRect(const Rect& rect) = 0;
 ```
 
-设置裁剪矩形。
+设置裁剪矩形。超出该矩形区域的像素将被丢弃。此操作用于实现遮罩、屏幕空间裁剪等效果。
 
 **参数：**
-- `rect` - 裁剪矩形结构体
+- `rect` - 裁剪矩形结构体（包含 left、top、right、bottom，单位为像素）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -23,3 +31,5 @@ cmdList->SetScissorRect(rect);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetScissorRects](set-scissor-rects.md) - 设置多个裁剪矩形
+- [SetViewport](set-viewport.md) - 设置视口

docs/api/rhi/command-list/set-scissor-rects.md

@@ -4,12 +4,20 @@
 virtual void SetScissorRects(uint32_t count, const Rect* rects) = 0;
 ```
 
-设置多个裁剪矩形。
+批量设置多个裁剪矩形。与 `SetViewports` 类似，用于多重渲染场景，每个视口对应一个裁剪矩形。
 
 **参数：**
-- `count` - 裁剪矩形数量
+- `count` - 裁剪矩形数量（最大 16）
 - `rects` - 裁剪矩形数组指针
 
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(n)，n 为矩形数量
+
 **示例：**
 
 ```cpp
@@ -22,3 +30,5 @@ cmdList->SetScissorRects(2, rects);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetScissorRect](set-scissor-rect.md) - 设置单个裁剪矩形
+- [SetViewports](set-viewports.md) - 设置多个视口

docs/api/rhi/command-list/set-stencil-ref.md

@@ -4,10 +4,18 @@
 virtual void SetStencilRef(uint8_t ref) = 0;
 ```
 
-设置模板参考值。
+设置模板测试的参考值。模板测试将每个像素的模板值与此参考值进行比较，决定像素是否被写入。
 
 **参数：**
-- `ref` - 模板参考值
+- `ref` - 模板参考值（范围 0-255）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -18,3 +26,4 @@ cmdList->SetStencilRef(0xFF);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetDepthStencilState](set-depth-stencil-state.md) - 设置深度模板状态

docs/api/rhi/command-list/set-vertex-buffer.md

@@ -4,13 +4,21 @@
 virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) = 0;
 ```
 
-设置顶点缓冲区。
+绑定单个顶点缓冲区到指定的槽位。顶点缓冲区包含绘制所需的顶点数据。
 
 **参数：**
-- `slot` - 顶点缓冲区槽位
+- `slot` - 顶点缓冲区槽位索引（范围 0-15）
 - `buffer` - 顶点缓冲区指针
-- `offset` - 数据偏移量
-- `stride` - 顶点步长
+- `offset` - 缓冲区内的起始偏移量（字节）
+- `stride` - 每个顶点的字节大小
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -21,3 +29,5 @@ cmdList->SetVertexBuffer(0, vertexBuffer, 0, sizeof(Vertex));
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetVertexBuffers](set-vertex-buffers.md) - 设置多个顶点缓冲
+- [SetIndexBuffer](set-index-buffer.md) - 设置索引缓冲

docs/api/rhi/command-list/set-vertex-buffers.md

@@ -4,14 +4,22 @@
 virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) = 0;
 ```
 
-设置多个顶点缓冲区。
+批量绑定多个顶点缓冲区到连续的槽位。用于需要多个顶点流的高级渲染场景。
 
 **参数：**
-- `startSlot` - 起始槽位
-- `count` - 缓冲区数量
-- `buffers` - 缓冲区指针数组
-- `offsets` - 偏移量数组
-- `strides` - 步长数组
+- `startSlot` - 起始槽位索引（范围 0-15）
+- `count` - 顶点缓冲区数量
+- `buffers` - 顶点缓冲区指针数组
+- `offsets` - 偏移量数组（字节）
+- `strides` - 步长数组（每个顶点的字节大小）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(n)，n 为缓冲区数量
 
 **示例：**
 
@@ -25,3 +33,4 @@ cmdList->SetVertexBuffers(0, 2, buffers, offsets, strides);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetVertexBuffer](set-vertex-buffer.md) - 设置单个顶点缓冲

docs/api/rhi/command-list/set-viewport.md

@@ -4,10 +4,18 @@
 virtual void SetViewport(const Viewport& viewport) = 0;
 ```
 
-设置视口。
+设置渲染区域视口。视口定义了渲染输出到目标区域的映射变换。
 
 **参数：**
-- `viewport` - 视口结构体
+- `viewport` - 视口结构体（包含 topLeftX、topLeftY、width、height、minDepth、maxDepth）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -25,3 +33,5 @@ cmdList->SetViewport(vp);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetViewports](set-viewports.md) - 设置多个视口
+- [SetScissorRect](set-scissor-rect.md) - 设置裁剪矩形

docs/api/rhi/command-list/set-viewports.md

@@ -4,12 +4,20 @@
 virtual void SetViewports(uint32_t count, const Viewport* viewports) = 0;
 ```
 
-设置多个视口。
+批量设置多个渲染视口。用于需要多重渲染（Multi-Rendering）的场景，如立体渲染或分屏渲染。
 
 **参数：**
-- `count` - 视口数量
+- `count` - 视口数量（最大 16）
 - `viewports` - 视口数组指针
 
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(n)，n 为视口数量
+
 **示例：**
 
 ```cpp
@@ -22,3 +30,5 @@ cmdList->SetViewports(2, viewports);
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [SetViewport](set-viewport.md) - 设置单个视口
+- [SetScissorRects](set-scissor-rects.md) - 设置多个裁剪矩形

docs/api/rhi/command-list/shutdown.md

@@ -4,10 +4,26 @@
 virtual void Shutdown() = 0;
 ```
 
-关闭命令列表，释放所有相关资源。
+关闭命令列表，释放所有相关资源。此方法将命令列表置于不可用状态。
 
-**复杂度：** O(n) - 取决于管理的命令数量
+**参数：** 无
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+commandList->Shutdown();
+```
 
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [Reset](reset.md) - 重置命令列表
+- [Close](close.md) - 关闭命令列表

docs/api/rhi/command-list/transition-barrier.md

@@ -4,12 +4,20 @@
 virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) = 0;
 ```
 
-设置资源状态转换屏障，确保 GPU 资源在状态转换前完成所有操作。
+设置资源状态转换屏障，确保 GPU 资源在状态转换前完成所有操作。资源在 GPU 不同的使用方式之间切换时需要通过此方法进行状态转换。
 
 **参数：**
 - `resource` - 目标资源指针
-- `stateBefore` - 转换前的资源状态
-- `stateAfter` - 转换后的资源状态
+- `stateBefore` - 转换前的资源状态（枚举值）
+- `stateAfter` - 转换后的资源状态（枚举值）
+
+**返回：** `void`
+
+**异常：** 无
+
+**线程安全：** ❌
+
+**复杂度：** O(1)
 
 **示例：**
 
@@ -21,3 +29,5 @@ cmdList->TransitionBarrier(texture, ResourceStates::RenderTarget, ResourceStates
 ## 相关文档
 
 - [RHICommandList 总览](command-list.md) - 返回类总览
+- [CopyResource](copy-resource.md) - 复制资源
+- [SetRenderTargets](set-render-targets.md) - 设置渲染目标

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

@@ -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) - 同步栅栏

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

@@ -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) - 命令列表

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

@@ -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) - 等待栅栏

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

@@ -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) - 返回类总览

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

@@ -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);
+}
 ```
 
 ## 相关文档

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

@@ -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) - 返回类总览

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

@@ -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 句柄。

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

@@ -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();
+}
+```
 
 ## 相关文档
 

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

@@ -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) - 同步栅栏

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

@@ -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) - 等待栅栏

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

@@ -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) - 同步栅栏

docs/api/rhi/d3d12/buffer/buffer.md

@@ -2,36 +2,79 @@
 
 **命名空间**: `XCEngine::RHI`
 
+**类型**: `class` (继承自 `RHIBuffer`)
+
 **描述**: DirectX 12 缓冲区的 D3D12 实现，继承自 `RHIBuffer`。
 
+## 概述
+
+`D3D12Buffer` 是 RHI 缓冲区接口的 DirectX 12 后端实现。该类封装了 `ID3D12Resource` 对象，提供缓冲区的创建、初始化、数据更新和状态管理功能。支持顶点缓冲区、索引缓冲区、常量缓冲区等多种缓冲区类型。
+
 ## 公共方法
 
+### D3D12 特有方法
+
 | 方法 | 描述 |
 |------|------|
 | [`Initialize`](initialize.md) | 初始化缓冲区 |
 | [`InitializeFromExisting`](initialize-from-existing.md) | 从现有资源初始化 |
 | [`InitializeWithData`](initialize-with-data.md) | 初始化并写入数据 |
-| [`Shutdown`](shutdown.md) | 关闭缓冲区 |
 | [`UpdateData`](update-data.md) | 更新数据 |
-| [`Map`](map.md) | 映射缓冲区 |
-| [`Unmap`](unmap.md) | 取消映射 |
-| [`SetData`](set-data.md) | 设置数据 |
 | [`GetResource`](get-resource.md) | 获取 D3D12 资源 |
 | [`GetDesc`](get-desc.md) | 获取描述符 |
 | [`GetGPUVirtualAddress`](get-gpu-virtual-address.md) | 获取 GPU 虚拟地址 |
 | [`GetGPUAddress`](get-gpu-address.md) | 获取 GPU 地址 |
-| [`GetSize`](get-size.md) | 获取缓冲区大小 |
-| [`GetState`](get-state.md) | 获取资源状态 |
+
+### 继承自 RHIBuffer 的方法
+
+| 方法 | 描述 |
+|------|------|
+| [`Shutdown`](../../buffer/shutdown.md) | 关闭缓冲区 |
+| [`Map`](../../buffer/map.md) | 映射缓冲区 |
+| [`Unmap`](../../buffer/unmap.md) | 取消映射 |
+| [`SetData`](../../buffer/set-data.md) | 设置数据 |
+| [`GetSize`](../../buffer/get-size.md) | 获取缓冲区大小 |
+| [`GetState`](../../buffer/get-state.md) | 获取资源状态 |
 | [`SetState`](../../buffer/set-state.md) | 设置资源状态 |
-| [`GetName`](get-name.md) | 获取资源名称 |
+| [`GetName`](../../buffer/get-name.md) | 获取资源名称 |
 | [`SetName`](../../buffer/set-name.md) | 设置资源名称 |
-| [`GetStride`](get-stride.md) | 获取步长 |
+| [`GetStride`](../../buffer/get-stride.md) | 获取步长 |
 | [`SetStride`](../../buffer/set-stride.md) | 设置步长 |
-| [`GetBufferType`](get-buffer-type.md) | 获取缓冲区类型 |
+| [`GetBufferType`](../../buffer/get-buffer-type.md) | 获取缓冲区类型 |
 | [`SetBufferType`](../../buffer/set-buffer-type.md) | 设置缓冲区类型 |
-| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |
+| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 |
+
+## 使用示例
+
+```cpp
+// 创建顶点缓冲区
+D3D12Buffer vertexBuffer;
+vertexBuffer.Initialize(
+    device,
+    sizeof(Vertex) * vertexCount,
+    D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER,
+    D3D12_HEAP_TYPE_DEFAULT);
+vertexBuffer.SetName(L"VertexBuffer");
+vertexBuffer.SetBufferType(BufferType::Vertex);
+vertexBuffer.SetStride(sizeof(Vertex));
+
+// 创建索引缓冲区（带初始数据）
+D3D12Buffer indexBuffer;
+uint16_t indices[] = { 0, 1, 2, 1, 3, 2 };
+indexBuffer.InitializeWithData(
+    device,
+    commandList,
+    indices,
+    sizeof(indices),
+    D3D12_RESOURCE_STATE_INDEX_BUFFER);
+
+// 使用 UPLOAD 堆更新数据
+D3D12Buffer uploadBuffer;
+uploadBuffer.Initialize(device, uploadSize, D3D12_RESOURCE_STATE_GENERIC_READ, D3D12_HEAP_TYPE_UPLOAD);
+uploadBuffer.UpdateData(newData, dataSize);
+```
 
 ## 相关文档
 
-- [D3D12 后端总览](../../opengl/overview.md)
+- [D3D12 后端总览](../../d3d12/d3d12.md)
 - [RHIBuffer](../../buffer/buffer.md) - 抽象缓冲区接口

docs/api/rhi/d3d12/buffer/get-buffer-type.md

@@ -1,16 +0,0 @@
-# D3D12Buffer::GetBufferType / SetBufferType
-
-## 函数签名
-
-```cpp
-BufferType GetBufferType() const override
-void SetBufferType(BufferType type) override
-```
-
-## 中文描述
-
-获取和设置缓冲区类型（Vertex / Index / Constant 等）。
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/get-name.md

@@ -1,16 +0,0 @@
-# D3D12Buffer::GetName / SetName
-
-## 函数签名
-
-```cpp
-const std::string& GetName() const override
-void SetName(const std::string& name) override
-```
-
-## 中文描述
-
-获取和设置对象名称（用于调试）。
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/get-native-handle.md

@@ -1,19 +0,0 @@
-# D3D12Buffer::GetNativeHandle
-
-## 函数签名
-
-```cpp
-void* GetNativeHandle() override
-```
-
-## 中文描述
-
-返回原生句柄，即 `ID3D12Resource*`。
-
-## 返回值
-
-`void*` - 原生句柄
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/get-size.md

@@ -1,19 +0,0 @@
-# D3D12Buffer::GetSize
-
-## 函数签名
-
-```cpp
-uint64_t GetSize() const override
-```
-
-## 中文描述
-
-获取缓冲区大小（字节）。
-
-## 返回值
-
-`uint64_t` - 缓冲区大小
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/get-state.md

@@ -1,16 +0,0 @@
-# D3D12Buffer::GetState / SetState
-
-## 函数签名
-
-```cpp
-ResourceStates GetState() const
-void SetState(ResourceStates state)
-```
-
-## 中文描述
-
-获取和设置当前资源状态。用于状态跟踪和屏障生成。
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/get-stride.md

@@ -1,16 +0,0 @@
-# D3D12Buffer::GetStride / SetStride
-
-## 函数签名
-
-```cpp
-uint32_t GetStride() const override
-void SetStride(uint32_t stride) override
-```
-
-## 中文描述
-
-获取和设置顶点缓冲区步长（字节）。
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/initialize-with-data.md

@@ -33,9 +33,9 @@ O(n) - 取决于数据大小，内部创建临时上传堆
 ```cpp
 uint16_t indices[] = { 0, 1, 2, 1, 3, 2 };
 D3D12Buffer indexBuffer;
-D3D12Buffer::InitializeWithData(
-    device->GetDevice(),
-    cmdList->GetCommandList(),
+indexBuffer.InitializeWithData(
+    device,
+    commandList,
     indices,
     sizeof(indices),
     D3D12_RESOURCE_STATE_INDEX_BUFFER);

docs/api/rhi/d3d12/buffer/map.md

@@ -1,27 +0,0 @@
-# D3D12Buffer::Map
-
-## 函数签名
-
-```cpp
-void* Map() override
-```
-
-## 中文描述
-
-将缓冲区内存映射到 CPU 可访问地址。仅对 UPLOAD 或 READBACK 堆有效。
-
-## 返回值
-
-`void*` - 映射的内存指针
-
-## 复杂度
-
-O(1)
-
-## 示例
-
-```cpp
-void* mapped = uploadBuffer.Map();
-memcpy(mapped, vertexData, sizeof(vertexData));
-buffer.Unmap();
-```

docs/api/rhi/d3d12/buffer/set-data.md

@@ -1,23 +0,0 @@
-# D3D12Buffer::SetData
-
-## 函数签名
-
-```cpp
-void SetData(const void* data, size_t size, size_t offset = 0) override
-```
-
-## 中文描述
-
-设置缓冲区数据。通过 Map/Unmap 实现。
-
-## 参数
-
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| `data` | `const void*` | 数据指针 |
-| `size` | `size_t` | 数据大小 |
-| `offset` | `size_t` | 缓冲区内的偏移量 |
-
-## 复杂度
-
-O(n)

docs/api/rhi/d3d12/buffer/shutdown.md

@@ -1,15 +0,0 @@
-# D3D12Buffer::Shutdown
-
-## 函数签名
-
-```cpp
-void Shutdown() override
-```
-
-## 中文描述
-
-释放 D3D12 缓冲区资源，将成员变量置为空。
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/unmap.md

@@ -1,15 +0,0 @@
-# D3D12Buffer::Unmap
-
-## 函数签名
-
-```cpp
-void Unmap() override
-```
-
-## 中文描述
-
-解除缓冲区内存映射。
-
-## 复杂度
-
-O(1)

docs/api/rhi/d3d12/buffer/update-data.md

@@ -17,6 +17,10 @@ void UpdateData(const void* data, uint64_t size)
 | `data` | `const void*` | 新数据指针 |
 | `size` | `uint64_t` | 数据大小 |
 
+## 返回值
+
+无
+
 ## 复杂度
 
 O(n)

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

@@ -2,18 +2,49 @@
 
 **命名空间**: `XCEngine::RHI`
 
-**描述**: DirectX 12 命令分配器的 D3D12 实现。
+**类型**: `class` (standalone, does not inherit from base)
+
+**描述**: DirectX 12 命令分配器的 D3D12 实现，用于管理 GPU 命令分配内存。
+
+## 构造函数
+
+| 方法 | 描述 |
+|------|------|
+| [`D3D12CommandAllocator`](constructor.md) | 默认构造函数 |
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
-| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化命令分配器 |
-| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令分配器 |
-| [`Reset`](../../command-list/reset.md) | 重置命令分配器 |
+| [`Initialize`](initialize.md) | 初始化命令分配器 |
+| [`Shutdown`](shutdown.md) | 关闭命令分配器 |
+| [`Reset`](reset.md) | 重置命令分配器 |
 | [`IsReady`](is-ready.md) | 检查是否就绪 |
 | [`GetCommandAllocator`](get-command-allocator.md) | 获取 D3D12 命令分配器 |
 
+## 析构函数
+
+| 方法 | 描述 |
+|------|------|
+| [`~D3D12CommandAllocator`](destructor.md) | 析构函数，自动调用 Shutdown |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/RHI/D3D12/D3D12CommandAllocator.h>
+
+using namespace XCEngine::RHI;
+
+D3D12CommandAllocator allocator;
+if (allocator.Initialize(device, CommandQueueType::Direct)) {
+    allocator.Reset();
+    if (allocator.IsReady()) {
+        ID3D12CommandAllocator* native = allocator.GetCommandAllocator();
+    }
+    allocator.Shutdown();
+}
+```
+
 ## 相关文档
 
-- [D3D12 后端总览](../../opengl/overview.md)
+- [D3D12 后端总览](../../d3d12/d3d12.md)

docs/api/rhi/d3d12/command-allocator/constructor.md

@@ -0,0 +1,20 @@
+# D3D12CommandAllocator::D3D12CommandAllocator
+
+```cpp
+D3D12CommandAllocator();
+```
+
+默认构造函数，创建一个未初始化的命令分配器实例。创建后需要调用 [`Initialize`](initialize.md) 进行初始化。
+
+## 示例
+
+```cpp
+D3D12CommandAllocator allocator;
+// 此时 allocator 未初始化，需要调用 Initialize
+allocator.Initialize(device);
+```
+
+## 相关文档
+
+- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览
+- [D3D12CommandAllocator::Initialize](initialize.md) - 初始化分配器

docs/api/rhi/d3d12/command-allocator/destructor.md

@@ -0,0 +1,22 @@
+# D3D12CommandAllocator::~D3D12CommandAllocator
+
+```cpp
+~D3D12CommandAllocator();
+```
+
+析构函数，自动调用 [`Shutdown`](shutdown.md) 释放底层 D3D12 资源。
+
+## 示例
+
+```cpp
+{
+    D3D12CommandAllocator allocator;
+    allocator.Initialize(device);
+    // 使用分配器
+} // 离开作用域时析构函数自动调用 Shutdown
+```
+
+## 相关文档
+
+- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览
+- [D3D12CommandAllocator::Shutdown](shutdown.md) - 关闭分配器

docs/api/rhi/d3d12/command-allocator/get-command-allocator.md

@@ -6,6 +6,16 @@ ID3D12CommandAllocator* GetCommandAllocator() const { return m_commandAllocator.
 
 获取底层的 D3D12 命令分配器接口。
 
+## 示例
+
+```cpp
+D3D12CommandAllocator allocator;
+if (allocator.Initialize(device)) {
+    ID3D12CommandAllocator* native = allocator.GetCommandAllocator();
+    // 使用原生 D3D12 接口
+}
+```
+
 **返回：** `ID3D12CommandAllocator*`
 
 **复杂度：** O(1)

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

@@ -0,0 +1,37 @@
+# D3D12CommandAllocator::Initialize
+
+```cpp
+bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct);
+```
+
+初始化 D3D12 命令分配器，创建指定类型的命令分配器。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `device` | `ID3D12Device*` | D3D12 设备指针 |
+| `type` | `CommandQueueType` | 命令队列类型，默认值为 `Direct` |
+
+## 返回值
+
+`bool` - 初始化是否成功
+
+## 示例
+
+```cpp
+D3D12CommandAllocator allocator;
+if (allocator.Initialize(device, CommandQueueType::Direct)) {
+    // 分配器初始化成功
+}
+```
+
+## 复杂度
+
+O(1)
+
+## 相关文档
+
+- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览
+- [D3D12CommandAllocator::Reset](reset.md) - 重置分配器
+- [D3D12CommandAllocator::Shutdown](shutdown.md) - 关闭分配器

docs/api/rhi/d3d12/command-allocator/is-ready.md

@@ -6,6 +6,17 @@ bool IsReady() const;
 
 检查命令分配器是否准备就绪。
 
+## 示例
+
+```cpp
+D3D12CommandAllocator allocator;
+if (allocator.Initialize(device)) {
+    if (allocator.IsReady()) {
+        // 分配器就绪可以使用
+    }
+}
+```
+
 **返回：** 分配器是否准备就绪
 
 **复杂度：** O(1)

docs/api/rhi/d3d12/command-allocator/reset.md

@@ -0,0 +1,25 @@
+# D3D12CommandAllocator::Reset
+
+```cpp
+void Reset();
+```
+
+重置命令分配器，将分配器重置为初始状态，使其可以重新使用。此方法必须在 GPU 完成所有使用该分配器的命令后才能调用。
+
+## 示例
+
+```cpp
+D3D12CommandAllocator allocator;
+if (allocator.Initialize(device)) {
+    allocator.Reset(); // 重置以重新使用
+}
+```
+
+## 复杂度
+
+O(1)
+
+## 相关文档
+
+- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览
+- [D3D12CommandAllocator::Initialize](initialize.md) - 初始化分配器

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

@@ -0,0 +1,27 @@
+# D3D12CommandAllocator::Shutdown
+
+```cpp
+void Shutdown();
+```
+
+关闭 D3D12 命令分配器，释放底层 D3D12 资源。此方法通常不需要显式调用，析构函数会自动执行。
+
+## 示例
+
+```cpp
+D3D12CommandAllocator allocator;
+if (allocator.Initialize(device)) {
+    // 使用分配器
+    allocator.Shutdown(); // 显式关闭
+}
+// 或者依靠析构函数自动关闭
+```
+
+## 复杂度
+
+O(1)
+
+## 相关文档
+
+- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览
+- [D3D12CommandAllocator::Initialize](initialize.md) - 初始化分配器

docs/api/rhi/d3d12/command-list/begin-query.md

@@ -13,6 +13,15 @@ void BeginQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index);
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ID3D12QueryHeap* queryHeap = /* 获取查询堆 */;
+cmdList.BeginQuery(queryHeap, QueryType::Timestamp, 0);
+```
+
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [EndQuery](end-query.md) - 结束查询
+- [ResolveQueryData](resolve-query-data.md) - 解析查询数据

docs/api/rhi/d3d12/command-list/clear.md

@@ -0,0 +1,21 @@
+# D3D12CommandList::Clear
+
+```cpp
+void Clear(float r, float g, float b, float a, uint32_t buffers) override;
+```
+
+清除渲染目标和/或深度模板缓冲区。
+
+**参数：**
+- `r` - 清除颜色（红色通道）
+- `g` - 清除颜色（绿色通道）
+- `b` - 清除颜色（蓝色通道）
+- `a` - 清除颜色（Alpha通道）
+- `buffers` - 要清除的缓冲区标志
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [RHICommandList::Clear](../../command-list/command-list.md) - 基类方法

docs/api/rhi/d3d12/command-list/close.md

@@ -0,0 +1,14 @@
+# D3D12CommandList::Close
+
+```cpp
+void Close() override;
+```
+
+关闭命令列表，停止录制。
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [RHICommandList::Close](../../command-list/command-list.md) - 基类方法

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

@@ -2,18 +2,33 @@
 
 **命名空间**: `XCEngine::RHI`
 
-**描述**: DirectX 12 命令列表的 D3D12 实现，继承自 `RHICommandList`。
+**继承自**: [`RHICommandList`](../../command-list/command-list.md)
+
+**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h`
+
+## 概述
+
+`D3D12CommandList` 是 DirectX 12 命令列表的 RHI 实现，封装了 `ID3D12GraphicsCommandList` 接口。该类负责记录 GPU 命令，包括绘制调用、资源状态转换、渲染目标设置等。
+
+### 主要功能
+
+- **命令录制**: 支持图形和计算命令的录制
+- **资源状态管理**: 维护资源状态映射表，跟踪资源转换
+- **描述符管理**: 管理 GPU 描述符堆和描述符表
+- **状态设置**: 设置管线状态、根签名、视口、裁剪矩形等
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
-| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令列表 |
-| [`Reset`](../../command-list/reset.md) | 重置命令列表 |
-| [`Close`](../../command-list/close.md) | 关闭命令列表 |
+| [`D3D12CommandList`](../../../threading/lambdatask/constructor.md) | 构造函数 |
+| [`~D3D12CommandList`](../../../threading/readwritelock/destructor.md) | 析构函数 |
+| [`Initialize`](initialize.md) | 初始化命令列表 |
+| [`Shutdown`](shutdown.md) | 关闭命令列表 |
+| [`Reset`](reset.md) | 重置命令列表 |
+| [`Close`](close.md) | 关闭命令列表 |
 | [`GetCommandList`](get-command-list.md) | 获取 D3D12 命令列表 |
 | [`TransitionBarrier`](transition-barrier.md) | 资源状态转换 |
-| [`TransitionBarrierInternal`](transition-barrier-internal.md) | 内部资源状态转换 |
 | [`UAVBarrier`](uav-barrier.md) | UAV 屏障 |
 | [`AliasBarrier`](alias-barrier.md) | 别名屏障 |
 | [`SetPipelineState`](set-pipeline-state.md) | 设置管线状态 |
@@ -24,8 +39,6 @@
 | [`SetScissorRect`](set-scissor-rect.md) | 设置裁剪矩形 |
 | [`SetScissorRects`](set-scissor-rects.md) | 设置多个裁剪矩形 |
 | [`SetRenderTargets`](set-render-targets.md) | 设置渲染目标 |
-| [`SetRenderTargetsInternal`](set-render-targets-internal.md) | 内部渲染目标设置 |
-| [`SetRenderTargetsHandle`](set-render-targets-handle.md) | 句柄渲染目标设置 |
 | [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲 |
 | [`SetVertexBuffers`](set-vertex-buffers.md) | 设置多个顶点缓冲 |
 | [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲 |
@@ -44,7 +57,7 @@
 | [`DrawIndexed`](draw-indexed.md) | 索引绘制 |
 | [`DrawInstancedIndirect`](draw-instanced-indirect.md) | 实例化间接绘制 |
 | [`DrawIndexedInstancedIndirect`](draw-indexed-instanced-indirect.md) | 索引实例化间接绘制 |
-| [`Clear`](../../command-list/clear.md) | 清除 |
+| [`Clear`](clear.md) | 清除 |
 | [`ClearRenderTarget`](clear-render-target.md) | 清除渲染目标 |
 | [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度模板 |
 | [`CopyResource`](copy-resource.md) | 复制资源 |
@@ -59,7 +72,45 @@
 | [`GetResourceState`](get-resource-state.md) | 获取资源状态 |
 | [`TrackResource`](track-resource.md) | 跟踪资源 |
 
+## 使用示例
+
+```cpp
+#include "XCEngine/RHI/D3D12/D3D12CommandList.h"
+#include "XCEngine/RHI/D3D12/D3D12Device.h"
+
+using namespace XCEngine::RHI;
+
+// 创建命令列表
+D3D12CommandList cmdList;
+ID3D12Device* device = /* 获取设备 */;
+
+// 初始化
+if (!cmdList.Initialize(device, CommandQueueType::Direct)) {
+    return false;
+}
+
+// 重置并开始录制
+cmdList.Reset();
+
+// 设置渲染状态
+cmdList.SetPipelineState(pipelineState);
+cmdList.SetRootSignature(rootSignature);
+cmdList.SetPrimitiveTopology(PrimitiveTopology::TriangleList);
+cmdList.SetViewport(viewport);
+cmdList.SetRenderTargets(1, renderTargets, depthStencil);
+
+// 绑定资源
+cmdList.SetVertexBuffer(0, vertexBuffer, 0, sizeof(Vertex));
+cmdList.SetIndexBuffer(indexBuffer, 0, Format::R32_UINT);
+
+// 绘制
+cmdList.DrawIndexed(indexCount, 1, 0, 0, 0);
+
+// 关闭命令列表
+cmdList.Close();
+```
+
 ## 相关文档
 
-- [D3D12 后端总览](../../opengl/overview.md)
+- [D3D12 后端总览](../d3d12.md)
 - [RHICommandList](../../command-list/command-list.md) - 抽象命令列表接口

docs/api/rhi/d3d12/command-list/copy-buffer.md

@@ -13,8 +13,18 @@ void CopyBuffer(ID3D12Resource* dst, uint64_t dstOffset, ID3D12Resource* src, ui
 - `srcOffset` - 源偏移
 - `size` - 复制大小
 
-**复杂度：** O(n)
+**复杂度：** O(n)，n 为复制数据量
+
+**示例：**
+
+```cpp
+ID3D12Resource* srcBuffer = /* 源缓冲区 */;
+ID3D12Resource* dstBuffer = /* 目标缓冲区 */;
+cmdList.CopyBuffer(dstBuffer, 0, srcBuffer, 0, 1024);
+```
 
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [CopyResource](copy-resource.md) - 复制整个资源
+- [CopyTexture](copy-texture.md) - 复制纹理数据

docs/api/rhi/d3d12/command-list/copy-resource.md

@@ -10,8 +10,18 @@ void CopyResource(void* dst, void* src) override;
 - `dst` - 目标资源指针
 - `src` - 源资源指针
 
-**复杂度：** O(n)
+**复杂度：** O(n)，n 为资源大小
+
+**示例：**
+
+```cpp
+ID3D12Resource* dst = /* 目标资源 */;
+ID3D12Resource* src = /* 源资源 */;
+cmdList.CopyResource(dst, src);
+```
 
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [CopyBuffer](copy-buffer.md) - 复制缓冲区数据
+- [CopyTexture](copy-texture.md) - 复制纹理数据

docs/api/rhi/d3d12/command-list/copy-texture.md

@@ -12,8 +12,26 @@ void CopyTexture(ID3D12Resource* dst, const D3D12_TEXTURE_COPY_LOCATION& dstLoca
 - `src` - 源纹理
 - `srcLocation` - 源位置
 
-**复杂度：** O(n)
+**复杂度：** O(n)，n 为复制数据量
+
+**示例：**
+
+```cpp
+D3D12_TEXTURE_COPY_LOCATION dstLoc = {};
+dstLoc.pResource = dstTexture;
+dstLoc.Type = D3D12_TEXTURE_COPY_TYPE_SUBRESOURCE_INDEX;
+dstLoc.SubresourceIndex = 0;
+
+D3D12_TEXTURE_COPY_LOCATION srcLoc = {};
+srcLoc.pResource = srcTexture;
+srcLoc.Type = D3D12_TEXTURE_COPY_TYPE_SUBRESOURCE_INDEX;
+srcLoc.SubresourceIndex = 0;
+
+cmdList.CopyTexture(dst, dstLoc, src, srcLoc);
+```
 
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [CopyResource](copy-resource.md) - 复制整个资源
+- [CopyBuffer](copy-buffer.md) - 复制缓冲区数据

docs/api/rhi/d3d12/command-list/dispatch-indirect.md

@@ -4,7 +4,7 @@
 void DispatchIndirect(void* argBuffer, uint64_t alignedByteOffset);
 ```
 
-间接分发计算命令。
+间接分发计算命令，使用存储在缓冲区中的参数执行 `Dispatch` 操作。
 
 **参数：**
 - `argBuffer` - 参数缓冲区
@@ -12,6 +12,14 @@ void DispatchIndirect(void* argBuffer, uint64_t alignedByteOffset);
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ID3D12Resource* argBuffer = /* 包含 DispatchIndirect 参数的缓冲区 */;
+cmdList.DispatchIndirect(argBuffer, 0);
+```
+
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [Dispatch](dispatch.md) - 直接分发计算任务

docs/api/rhi/d3d12/command-list/end-query.md

@@ -13,6 +13,15 @@ void EndQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index);
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ID3D12QueryHeap* queryHeap = /* 获取查询堆 */;
+cmdList.EndQuery(queryHeap, QueryType::Timestamp, 0);
+```
+
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [BeginQuery](begin-query.md) - 开始查询
+- [ResolveQueryData](resolve-query-data.md) - 解析查询数据

docs/api/rhi/d3d12/command-list/execute-bundle.md

@@ -11,6 +11,13 @@ void ExecuteBundle(ID3D12GraphicsCommandList* bundle);
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ID3D12GraphicsCommandList* bundle = /* 获取 Bundle */;
+cmdList.ExecuteBundle(bundle);
+```
+
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览

docs/api/rhi/d3d12/command-list/get-resource-state.md

@@ -9,10 +9,22 @@ ResourceStates GetResourceState(ID3D12Resource* resource) const;
 **参数：**
 - `resource` - D3D12 资源指针
 
-**返回：** 资源当前状态
+**返回值：** 资源当前状态，如果资源未被跟踪则返回 `ResourceStates::Common`
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ID3D12Resource* resource = /* 获取资源 */;
+ResourceStates state = cmdList.GetResourceState(resource);
+if (state == ResourceStates::RenderTarget) {
+    // 资源当前为渲染目标状态
+}
+```
+
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [TrackResource](track-resource.md) - 跟踪资源
+- [TransitionBarrier](transition-barrier.md) - 资源状态转换

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

@@ -0,0 +1,40 @@
+# D3D12CommandList::Initialize
+
+```cpp
+bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct, ID3D12CommandAllocator* allocator = nullptr);
+```
+
+初始化 D3D12 命令列表，创建 `ID3D12GraphicsCommandList` 实例。
+
+**参数：**
+- `device` - D3D12 设备指针
+- `type` - 命令队列类型，默认为 `CommandQueueType::Direct`
+- `allocator` - 命令分配器指针，如果为 `nullptr`，则由方法内部创建
+
+**返回值：**
+- `bool` - 初始化成功返回 `true`，失败返回 `false`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+D3D12CommandList cmdList;
+ID3D12Device* device = /* 获取设备 */;
+
+if (!cmdList.Initialize(device)) {
+    // 处理初始化失败
+    return;
+}
+
+// 使用命令列表...
+cmdList.Reset();
+// ... 录制命令
+cmdList.Close();
+```
+
+## 相关文档
+
+- [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [Shutdown](shutdown.md) - 关闭命令列表
+- [Close](close.md) - 关闭命令列表

docs/api/rhi/d3d12/command-list/reset.md

@@ -0,0 +1,14 @@
+# D3D12CommandList::Reset
+
+```cpp
+void Reset() override;
+```
+
+重置命令列表，准备录制新命令。
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [RHICommandList::Reset](../../command-list/command-list.md) - 基类方法

docs/api/rhi/d3d12/command-list/resolve-query-data.md

@@ -14,8 +14,18 @@ void ResolveQueryData(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t start
 - `resultBuffer` - 结果缓冲区
 - `resultOffset` - 结果偏移
 
-**复杂度：** O(n)
+**复杂度：** O(n)，n 为查询数量
+
+**示例：**
+
+```cpp
+ID3D12QueryHeap* queryHeap = /* 获取查询堆 */;
+ID3D12Resource* resultBuffer = /* 结果缓冲区 */;
+cmdList.ResolveQueryData(queryHeap, QueryType::Timestamp, 0, 1, resultBuffer, 0);
+```
 
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [BeginQuery](begin-query.md) - 开始查询
+- [EndQuery](end-query.md) - 结束查询

docs/api/rhi/d3d12/command-list/set-depth-bias.md

@@ -13,6 +13,16 @@ void SetDepthBias(float depthBias, float slopeScaledDepthBias, float depthBiasCl
 
 **复杂度：** O(1)
 
+**注意：** 当前实现为空，深度偏移通过管线状态对象设置。
+
+**示例：**
+
+```cpp
+// 深度偏移参数通常在 PSO 中设置
+// 此方法当前为空实现
+cmdList.SetDepthBias(0.0f, 0.0f, 0.0f);
+```
+
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览

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

@@ -0,0 +1,14 @@
+# D3D12CommandList::Shutdown
+
+```cpp
+void Shutdown() override;
+```
+
+关闭命令列表并释放相关资源。
+
+**复杂度：** O(n) - 遍历释放所有跟踪的资源
+
+## 相关文档
+
+- [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [RHICommandList::Shutdown](../../command-list/command-list.md) - 基类方法

docs/api/rhi/d3d12/command-list/track-resource.md

@@ -11,6 +11,15 @@ void TrackResource(ID3D12Resource* resource);
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ID3D12Resource* resource = /* 获取资源 */;
+cmdList.TrackResource(resource);
+```
+
 ## 相关文档
 
 - [D3D12CommandList 总览](command-list.md) - 返回类总览
+- [GetResourceState](get-resource-state.md) - 获取资源状态
+- [TransitionBarrier](transition-barrier.md) - 资源状态转换

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 重载版本