docs: update RHI API docs

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) - 设置渲染目标