xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update RHI API docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 02:35:45 +08:00
parent ea756c0177
commit 070b444f8f
501 changed files with 13493 additions and 2022 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/api/rhi/opengl/command-list/clear.md
View File

@@ -1,24 +1,46 @@
# OpenGLCommandList::Clear
```cpp
void Clear(float r, float g, float b, float a, unsigned int buffers);
void Clear(float r, float g, float b, float a, unsigned int buffers)
```
清除缓冲区。
清除指定的缓冲区。
**参数：**
- `r` - 红色分量
- `g` - 绿色分量
- `b` - 蓝色分量
- `a` - Alpha 分量
- `buffers` - 要清除的缓冲区标志
- `r` - 清除颜色红色分量（范围 0.0f - 1.0f）
- `g` - 清除颜色绿色分量（范围 0.0f - 1.0f）
- `b` - 清除颜色蓝色分量（范围 0.0f - 1.0f）
- `a` - 清除颜色 Alpha 分量（范围 0.0f - 1.0f）
- `buffers` - 要清除的缓冲区标志，使用 `ClearFlag` 枚举值的位或组合：
- `ClearFlag::Color` (1) - 清除颜色缓冲区
- `ClearFlag::Depth` (2) - 清除深度缓冲区
- `ClearFlag::Stencil` (4) - 清除模板缓冲区
**返回值**：无
**示例：**
```cpp
commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f, Color | Depth);
// 清除颜色缓冲区
commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f, static_cast<unsigned int>(ClearFlag::Color));
// 清除颜色和深度缓冲区
commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f,
static_cast<unsigned int>(ClearFlag::Color) |
static_cast<unsigned int>(ClearFlag::Depth));
// 清除所有缓冲区
commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f,
static_cast<unsigned int>(ClearFlag::Color) |
static_cast<unsigned int>(ClearFlag::Depth) |
static_cast<unsigned int>(ClearFlag::Stencil));
```
## 相关文档
- [OpenGLCommandList 总览](command-list.md) - 返回类总览
- [ClearColor](clear-color.md) - 仅清除颜色缓冲区
- [ClearDepth](clear-depth.md) - 仅清除深度缓冲区
- [ClearStencil](clear-stencil.md) - 仅清除模板缓冲区
- [ClearDepthStencil](clear-depth-stencil.md) - 清除深度和模板缓冲区
- [ClearFlag 枚举](../../enums/clear-flag.md) - 清除缓冲区标志

119
docs/api/rhi/opengl/command-list/command-list.md
View File

@@ -2,41 +2,112 @@
**命名空间**: `XCEngine::RHI`
**描述**: OpenGL 命令列表实现，继承自 `RHICommandList`。
**描述**: OpenGL 命令列表实现，继承自 `RHICommandList`。提供 OpenGL 图形 API 的命令录制与执行接口，支持底层 OpenGL 状态操作以及跨平台 RHI 抽象接口。
## 概述
`OpenGLCommandList` 是 XCEngine RHI（渲染硬件接口）层在 OpenGL 后端的实现类。它封装了 OpenGL 图形命令的调用，提供了两类接口：
1. **RHI 抽象接口**：继承自 `RHICommandList`，提供跨后端一致性接口
2. **OpenGL 特有方法**：底层逃逸接口，用于需要直接操作 OpenGL 状态的场景
## 公共方法
### 生命周期
| 方法 | 描述 |
|------|------|
| [`Shutdown`](opengl-methods.md#shutdown) | 关闭命令列表（占位实现） |
| [`Reset`](opengl-methods.md#reset) | 重置命令列表（占位实现） |
| [`Close`](opengl-methods.md#close) | 关闭命令列表（占位实现） |
### 清除操作
| 方法 | 描述 |
|------|------|
| [`Clear`](clear.md) | 清除指定缓冲区 |
| [`ClearColor`](clear-color.md) | 清除颜色缓冲区 |
| [`ClearDepth`](clear-depth.md) | 清除深度缓冲区 |
| [`ClearStencil`](clear-stencil.md) | 清除模板缓冲区 |
| [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度和模板缓冲区 |
| [`ClearRenderTarget`](clear-render-target.md) | 清除渲染目标 |
### 状态设置
| 方法 | 描述 |
|------|------|
| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令列表 |
| [`Reset`](../../command-list/reset.md) | 重置命令列表 |
| [`Close`](../../command-list/close.md) | 关闭命令列表 |
| [`Clear`](clear.md) | 清除 |
| [`ClearColor`](clear-color.md) | 清除颜色 |
| [`ClearDepth`](clear-depth.md) | 清除深度 |
| [`ClearStencil`](clear-stencil.md) | 清除模板 |
| [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度模板 |
| [`SetPipelineState`](set-pipeline-state.md) | 设置管线状态 |
| [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲 |
| [`SetVertexBuffers`](set-vertex-buffers.md) | 设置多个顶点缓冲 |
| [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲 |
| [`TransitionBarrier`](transition-barrier.md) | 资源状态转换 |
| [`SetPrimitiveTopology`](set-primitive-topology.md) | 设置图元拓扑 |
| [`SetViewport`](set-viewport.md) | 设置视口 |
| [`SetViewports`](set-viewports.md) | 设置多个视口 |
| [`SetScissorRect`](set-scissor-rect.md) | 设置裁剪矩形 |
| [`SetScissorRects`](set-scissor-rects.md) | 设置多个裁剪矩形 |
| [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲区 |
| [`SetVertexBuffers`](set-vertex-buffers.md) | 批量设置顶点缓冲区 |
| [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲区 |
| [`SetRenderTargets`](set-render-targets.md) | 设置渲染目标 |
| [`SetDepthStencilState`](set-depth-stencil-state.md) | 设置深度模板状态 |
| [`SetStencilRef`](set-stencil-ref.md) | 设置模板引用值 |
| [`SetBlendState`](set-blend-state.md) | 设置混合状态 |
| [`SetBlendFactor`](set-blend-factor.md) | 设置混合因子 |
| [`ClearRenderTarget`](clear-render-target.md) | 清除渲染目标 |
| [`Draw`](draw.md) | 绘制 |
| [`DrawIndexed`](draw-indexed.md) | 索引绘制 |
| [`SetBlendFactor`](set-blend-factor.md) | 设置混合因子颜色 |
| [`SetPrimitiveTopology`](set-primitive-topology.md) | 设置图元拓扑 |
### 视口与裁剪
| 方法 | 描述 |
|------|------|
| [`SetViewport`](set-viewport.md) | 设置视口 |
| [`SetViewports`](set-viewports.md) | 批量设置视口 |
| [`SetScissorRect`](set-scissor-rect.md) | 设置裁剪矩形 |
| [`SetScissorRects`](set-scissor-rects.md) | 批量设置裁剪矩形 |
### 绘制
| 方法 | 描述 |
|------|------|
| [`Draw`](draw.md) | 绘制非索引图元 |
| [`DrawIndexed`](draw-indexed.md) | 绘制索引图元 |
### 计算
| 方法 | 描述 |
|------|------|
| [`Dispatch`](dispatch.md) | 分发计算任务 |
| [`CopyResource`](copy-resource.md) | 复制资源 |
| [`OpenGLMethods`](opengl-methods.md) | OpenGL 特有方法 |
| [`CopyResource`](copy-resource.md) | 复制资源（占位实现） |
| [`TransitionBarrier`](transition-barrier.md) | 资源状态转换（占位实现） |
### OpenGL 特有方法
| 方法 | 描述 |
|------|------|
| [`OpenGLMethods`](opengl-methods.md) | 底层 OpenGL 逃逸接口 |
## 使用示例
```cpp
#include "XCEngine/RHI/OpenGL/OpenGLCommandList.h"
using namespace XCEngine::RHI;
// 创建命令列表
OpenGLCommandList* cmdList = new OpenGLCommandList();
// 清除颜色缓冲区
cmdList->ClearColor(0.0f, 0.0f, 0.0f, 1.0f);
// 设置视口
Viewport viewport;
viewport.topLeftX = 0.0f;
viewport.topLeftY = 0.0f;
viewport.width = 800.0f;
viewport.height = 600.0f;
viewport.minDepth = 0.0f;
viewport.maxDepth = 1.0f;
cmdList->SetViewport(viewport);
// 绑定 shader program
cmdList->UseShader(shaderProgram);
// 绘制
cmdList->Draw(3, 1, 0, 0);
delete cmdList;
```
## 相关文档

26
docs/api/rhi/opengl/command-list/draw.md
View File

@@ -4,20 +4,34 @@
void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance)
```
绘制非索引图元。
绘制非索引图元（实例化绘制）。
**参数：**
- `vertexCount` - 顶点数量
- `instanceCount` - 实例数量
- `startVertex` - 起始顶点
- `startInstance` - 起始实例
- `vertexCount` - 每个实例的顶点数量
- `instanceCount` - 要绘制的实例数量
- `startVertex` - 第一个顶点的索引
- `startInstance` - 第一个实例的 ID
**返回值**：无
**详细描述**：
此方法使用 `glDrawArraysInstanced` 执行实例化绘制。当 `instanceCount` 为 1 时，等同于普通的非实例化绘制。
**示例：**
```cpp
// 绘制单个实例（相当于 glDrawArrays）
commandList->Draw(3, 1, 0, 0);
// 绘制 100 个实例
commandList->Draw(3, 100, 0, 0);
// 绘制多个实例，从实例 ID 10 开始
commandList->Draw(3, 50, 0, 10);
```
## 相关文档
- [OpenGLCommandList](command-list.md) - 返回类总览
- [OpenGLCommandList 总览](command-list.md) - 返回类总览
- [DrawIndexed](draw-indexed.md) - 索引绘制
- [OpenGL 特有 Draw 方法](opengl-methods.md#draw-primitivetype) - 使用 PrimitiveType 的版本

653
docs/api/rhi/opengl/command-list/opengl-methods.md
View File

File diff suppressed because it is too large Load Diff

31
docs/api/rhi/opengl/command-list/set-blend-state.md
View File

@@ -4,21 +4,40 @@
void SetBlendState(const BlendState& state)
```
设置混合状态。
设置颜色混合状态。
**参数：**
- `state` - 混合状态结构
- `state` - 混合状态结构，包含以下成员：
- `alphaToCoverageEnable` - Alpha to coverage 使能标志
- `renderTargets[0]` - 渲染目标混合配置（以第一个为例）：
- `blendEnable` - 混合使能标志
- `srcBlend` - RGB 源混合因子（参见 `BlendFactor` 枚举）
- `dstBlend` - RGB 目标混合因子
- `srcBlendAlpha` - Alpha 源混合因子
- `dstBlendAlpha` - Alpha 目标混合因子
- `blendOp` - RGB 混合操作（参见 `BlendOp` 枚举）
- `blendOpAlpha` - Alpha 混合操作
**返回值**：无
**示例：**
```cpp
BlendState state;
state.enable = true;
state.srcBlend = BlendFunc::SrcAlpha;
state.dstBlend = BlendFunc::InvSrcAlpha;
state.alphaToCoverageEnable = false;
state.renderTargets[0].blendEnable = true;
state.renderTargets[0].srcBlend = BlendFactor::SrcAlpha;
state.renderTargets[0].dstBlend = BlendFactor::InvSrcAlpha;
state.renderTargets[0].srcBlendAlpha = BlendFactor::One;
state.renderTargets[0].dstBlendAlpha = BlendFactor::InvSrcAlpha;
state.renderTargets[0].blendOp = BlendOp::Add;
state.renderTargets[0].blendOpAlpha = BlendOp::Add;
commandList->SetBlendState(state);
```
## 相关文档
- [OpenGLCommandList](command-list.md) - 返回类总览
- [OpenGLCommandList 总览](command-list.md) - 返回类总览
- [SetBlendFactor](set-blend-factor.md) - 设置混合常量颜色
- [BlendFactor](../../enums/blend-factor.md) - 混合因子枚举
- [BlendOp](../../enums/blend-op.md) - 混合操作枚举

24
docs/api/rhi/opengl/command-list/set-viewport.md
View File

@@ -4,21 +4,33 @@
void SetViewport(const Viewport& viewport)
```
设置视口。
设置渲染视口区域。
**参数：**
- `viewport` - 视口结构
- `viewport` - 视口结构，包含以下成员：
- `topLeftX` - 视口左下角 X 坐标
- `topLeftY` - 视口左下角 Y 坐标
- `width` - 视口宽度
- `height` - 视口高度
- `minDepth` - 最小深度值（通常为 0.0f）
- `maxDepth` - 最大深度值（通常为 1.0f）
**返回值**：无
**示例：**
```cpp
Viewport viewport;
viewport.x = 0; viewport.y = 0;
viewport.width = 800; viewport.height = 600;
viewport.minDepth = 0.0f; viewport.maxDepth = 1.0f;
viewport.topLeftX = 0.0f;
viewport.topLeftY = 0.0f;
viewport.width = 800.0f;
viewport.height = 600.0f;
viewport.minDepth = 0.0f;
viewport.maxDepth = 1.0f;
commandList->SetViewport(viewport);
```
## 相关文档
- [OpenGLCommandList](command-list.md) - 返回类总览
- [OpenGLCommandList 总览](command-list.md) - 返回类总览
- [SetViewports](set-viewports.md) - 批量设置视口