180 lines
6.3 KiB
Markdown
180 lines
6.3 KiB
Markdown
# 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) - 创建设备
|