# RHICommandList

**命名空间**: `XCEngine::RHI`

**类型**: `class` (abstract)

**描述**: GPU 命令列表抽象接口，用于录制和执行 GPU 命令。

## 概述

`RHICommandList` 封装了 GPU 命令的录制和执行。每个后端实现需要提供命令列表的创建、重置、命令录制和关闭等功能。

## 公共类型

### DepthStencilState

深度模板状态结构体。

```cpp
struct DepthStencilState {
    bool depthEnable = true;           // 启用深度测试
    bool depthWriteMask = true;        // 深度写入掩码
    ComparisonFunc depthFunc;          // 深度比较函数
    bool stencilEnable = false;        // 启用模板测试
    uint8_t stencilReadMask = 0xFF;   // 模板读取掩码
    uint8_t stencilWriteMask = 0xFF;   // 模板写入掩码
    struct StencilOpDesc {             // 模板操作描述
        StencilOp stencilFailOp;       // 模板失败操作
        StencilOp stencilDepthFailOp;  // 深度失败操作
        StencilOp stencilPassOp;       // 通过操作
        ComparisonFunc stencilFunc;    // 模板比较函数
    };
    StencilOpDesc frontFace;           // 前面模板状态
    StencilOpDesc backFace;            // 背面模板状态
};
```

### BlendState

混合状态结构体。

```cpp
struct BlendState {
    bool alphaToCoverageEnable = false;     // Alpha 到覆盖
    bool independentBlendEnable = false;      // 独立混合
    struct RenderTarget {                    // 渲染目标混合
        bool blendEnable;                     // 启用混合
        BlendFactor srcBlend;                 // 源混合因子
        BlendFactor dstBlend;                 // 目标混合因子
        BlendOp blendOp;                      // 混合操作
        BlendFactor srcBlendAlpha;            // Alpha 源混合
        BlendFactor dstBlendAlpha;            // Alpha 目标混合
        BlendOp blendOpAlpha;                 // Alpha 混合操作
        uint8_t renderTargetWriteMask;        // 颜色写入掩码
    };
    RenderTarget renderTargets[8];            // 每个 RT 的混合状态
    float blendFactor[4];                     // 全局混合因子
};
```

## 公共方法

### 生命周期

| 方法 | 描述 |
|------|------|
| `virtual void Shutdown()` | 释放命令列表资源 |

### 命令录制控制

| 方法 | 描述 |
|------|------|
| `virtual void Reset()` | 重置命令列表，开始新的录制 |
| `virtual void Close()` | 关闭命令列表，结束录制 |

### 资源状态转换

| 方法 | 描述 |
|------|------|
| `virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter)` | 资源状态转换屏障 |

### 渲染状态设置

| 方法 | 描述 |
|------|------|
| `virtual void SetPipelineState(void* pso)` | 设置管线状态对象 |
| `virtual void SetPrimitiveTopology(PrimitiveTopology topology)` | 设置图元拓扑 |
| `virtual void SetViewport(const Viewport& viewport)` | 设置视口 |
| `virtual void SetViewports(uint32_t count, const Viewport* viewports)` | 设置多个视口 |
| `virtual void SetScissorRect(const Rect& rect)` | 设置裁剪矩形 |
| `virtual void SetScissorRects(uint32_t count, const Rect* rects)` | 设置多个裁剪矩形 |
| `virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr)` | 设置渲染目标 |

### 深度/混合状态

| 方法 | 描述 |
|------|------|
| `virtual void SetDepthStencilState(const DepthStencilState& state)` | 设置深度模板状态 |
| `virtual void SetStencilRef(uint8_t ref)` | 设置模板参考值 |
| `virtual void SetBlendState(const BlendState& state)` | 设置混合状态 |
| `virtual void SetBlendFactor(const float factor[4])` | 设置混合因子 |

### 顶点/索引缓冲

| 方法 | 描述 |
|------|------|
| `virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride)` | 设置顶点缓冲 |
| `virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides)` | 设置多个顶点缓冲 |
| `virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format)` | 设置索引缓冲 |

### 绘制命令

| 方法 | 描述 |
|------|------|
| `virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0)` | 绘制调用 |
| `virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0)` | 索引绘制调用 |

### 清除命令

| 方法 | 描述 |
|------|------|
| `virtual void Clear(float r, float g, float b, float a, uint32_t buffers)` | 清除缓冲 |
| `virtual void ClearRenderTarget(void* renderTarget, const float color[4])` | 清除渲染目标 |
| `virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil)` | 清除深度模板 |

### 资源复制

| 方法 | 描述 |
|------|------|
| `virtual void CopyResource(void* dst, void* src)` | 复制资源 |

### 计算着色器

| 方法 | 描述 |
|------|------|
| `virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z)` | 分发计算着色器 |

## 图元拓扑类型 (PrimitiveTopology)

| 枚举值 | 描述 |
|--------|------|
| `PointList` | 点列表 |
| `LineList` | 线段列表 |
| `LineStrip` | 线段条带 |
| `TriangleList` | 三角形列表 |
| `TriangleStrip` | 三角形条带 |
| `PatchList` | 补丁列表（曲面细分） |

## 使用示例

```cpp
// 重置命令列表
commandList->Reset();

// 设置渲染状态
commandList->SetPipelineState(pipelineState);
commandList->SetPrimitiveTopology(PrimitiveTopology::TriangleList);
commandList->SetViewport(viewport);
commandList->SetRenderTargets(1, &renderTarget, depthStencil);

// 设置顶点缓冲
commandList->SetVertexBuffer(0, vertexBuffer->GetNativeHandle(), 0, sizeof(Vertex));
commandList->SetIndexBuffer(indexBuffer->GetNativeHandle(), 0, Format::R32_UInt);

// 绘制
commandList->DrawIndexed(indexCount, 1, 0, 0, 0);

// 关闭命令列表
commandList->Close();

// 提交到命令队列执行
commandQueue->ExecuteCommandLists(1, (void**)&commandList);
```

## 相关文档

- [RHICommandQueue](./rhi-command-queue.md) - 命令队列
- [RHIPipelineState](./rhi-pipeline-state.md) - 管线状态
- [RHIDevice](./rhi-device.md) - 创建设备