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

# OpenGLCommandList - OpenGL 特有方法

以下方法是 `OpenGLCommandList` 中 OpenGL 特有的底层逃逸方法。这些方法不存在于 RHI 抽象接口中，用于需要直接操作 OpenGL 状态的高级场景。

**注意**：这些方法直接映射到对应的 OpenGL 函数，调用时需确保 OpenGL 上下文已正确设置。

## 生命周期（占位实现）

### Shutdown

```cpp
void Shutdown()
```

关闭命令列表并释放资源。当前为空实现。

### Reset

```cpp
void Reset()
```

重置命令列表状态。当前为空实现。

### Close

```cpp
void Close()
```

关闭命令列表。当前为空实现。

---

## 顶点缓冲区（OpenGL 逃逸）

### SetVertexBuffer (GL uint)

```cpp
void SetVertexBuffer(unsigned int buffer, size_t offset, size_t stride)
```

直接使用 OpenGL buffer ID 设置顶点缓冲区。

**参数：**
- `buffer` - OpenGL buffer 对象的名称（ID）
- `offset` - 缓冲区中的字节偏移量
- `stride` - 顶点之间的字节 stride

**返回值**：无

**示例：**

```cpp
cmdList->SetVertexBuffer(vbo, 0, sizeof(Vertex));
```

### SetVertexBuffers (GL uint)

```cpp
void SetVertexBuffers(unsigned int startSlot, unsigned int count, const unsigned int* buffers, const size_t* offsets, const size_t* strides)
```

批量设置多个顶点缓冲区。

**参数：**
- `startSlot` - 起始顶点属性槽位
- `count` - 缓冲区数量
- `buffers` - OpenGL buffer ID 数组
- `offsets` - 偏移量数组
- `strides` - stride 数组

**返回值**：无

### SetIndexBuffer (GL uint)

```cpp
void SetIndexBuffer(unsigned int buffer, unsigned int type)
void SetIndexBuffer(unsigned int buffer, unsigned int type, size_t offset)
```

直接设置索引缓冲区。

**参数：**
- `buffer` - OpenGL buffer ID
- `type` - 索引数据类型（如 GL_UNSIGNED_INT）
- `offset` - 缓冲区中的字节偏移量（可选）

**返回值**：无

---

## 顶点数组

### BindVertexArray

```cpp
void BindVertexArray(unsigned int vao)
void BindVertexArray(unsigned int vao, unsigned int indexBuffer, unsigned int indexType)
```

绑定顶点数组对象（VAO），可同时设置索引缓冲区。

**参数：**
- `vao` - 顶点数组对象 ID
- `indexBuffer` - 索引缓冲区 ID（可选）
- `indexType` - 索引数据类型（可选）

**返回值**：无

**示例：**

```cpp
cmdList->BindVertexArray(vao);
```

### UseShader

```cpp
void UseShader(unsigned int program)
```

激活 OpenGL shader program。

**参数：**
- `program` - Shader program ID

**返回值**：无

**示例：**

```cpp
cmdList->UseShader(shaderProgram);
```

---

## 视口与裁剪

### SetViewport (int)

```cpp
void SetViewport(int x, int y, int width, int height)
```

使用整数参数设置视口。

**参数：**
- `x` - 视口左下角 X 坐标
- `y` - 视口左下角 Y 坐标
- `width` - 视口宽度
- `height` - 视口高度

**返回值**：无

### SetViewport (float)

```cpp
void SetViewport(float x, float y, float width, float height, float minDepth, float maxDepth)
```

使用浮点参数设置视口，包含深度范围。

**参数：**
- `x` - 视口左下角 X 坐标
- `y` - 视口左下角 Y 坐标
- `width` - 视口宽度
- `height` - 视口高度
- `minDepth` - 最小深度值（通常为 0.0）
- `maxDepth` - 最大深度值（通常为 1.0）

**返回值**：无

### SetViewports

```cpp
void SetViewports(unsigned int count, const float* viewports)
```

批量设置多个视口。

**参数：**
- `count` - 视口数量
- `viewports` - 视口数组，每6个浮点数表示一个视口（x, y, width, height, minDepth, maxDepth）

**返回值**：无

**示例：**

```cpp
float viewports[12] = {
    0.0f, 0.0f, 800.0f, 600.0f, 0.0f, 1.0f,
    400.0f, 0.0f, 400.0f, 600.0f, 0.0f, 1.0f
};
cmdList->SetViewports(2, viewports);
```

### SetScissor

```cpp
void SetScissor(int x, int y, int width, int height)
```

设置裁剪矩形。

**参数：**
- `x` - 裁剪矩形左下角 X 坐标
- `y` - 裁剪矩形左下角 Y 坐标
- `width` - 裁剪矩形宽度
- `height` - 裁剪矩形高度

**返回值**：无

### SetScissorRects

```cpp
void SetScissorRects(unsigned int count, const int* rects)
```

批量设置裁剪矩形。

**参数：**
- `count` - 裁剪矩形数量
- `rects` - 裁剪矩形数组，每4个整数表示一个矩形（x, y, width, height）

**返回值**：无

### EnableScissorTest

```cpp
void EnableScissorTest(bool enable)
```

启用或禁用裁剪测试。

**参数：**
- `enable` - true 启用，false 禁用

**返回值**：无

---

## 深度测试

### EnableDepthTest

```cpp
void EnableDepthTest(bool enable)
```

启用或禁用深度测试。

**参数：**
- `enable` - true 启用，false 禁用

**返回值**：无

### EnableDepthWrite

```cpp
void EnableDepthWrite(bool enable)
```

启用或禁用深度写入。

**参数：**
- `enable` - true 启用深度写入，false 禁用

**返回值**：无

### SetDepthFunc

```cpp
void SetDepthFunc(unsigned int func)
```

设置深度比较函数。

**参数：**
- `func` - OpenGL 比较函数（GL_NEVER, GL_LESS, GL_EQUAL, GL_LEQUAL, GL_GREATER, GL_NOTEQUAL, GL_GEQUAL, GL_ALWAYS）

**返回值**：无

---

## 模板测试

### EnableStencilTest

```cpp
void EnableStencilTest(bool enable)
```

启用或禁用模板测试。

**参数：**
- `enable` - true 启用，false 禁用

**返回值**：无

### SetStencilFunc

```cpp
void SetStencilFunc(unsigned int func, int ref, unsigned int mask)
```

设置模板测试函数和参考值。

**参数：**
- `func` - OpenGL 比较函数
- `ref` - 模板参考值
- `mask` - 模板缓冲区读写掩码

**返回值**：无

### SetStencilOp

```cpp
void SetStencilOp(unsigned int fail, unsigned int zfail, unsigned int zpass)
```

设置模板缓冲区操作。

**参数：**
- `fail` - 模板测试失败时的操作（如 GL_KEEP, GL_ZERO, GL_REPLACE）
- `zfail` - 模板测试通过但深度测试失败时的操作
- `zpass` - 两者都通过时的操作

**返回值**：无

---

## 混合

### EnableBlending

```cpp
void EnableBlending(bool enable)
```

启用或禁用颜色混合。

**参数：**
- `enable` - true 启用，false 禁用

**返回值**：无

### SetBlendFunc

```cpp
void SetBlendFunc(unsigned int src, unsigned int dst)
```

设置混合函数。

**参数：**
- `src` - 源混合因子（如 GL_ONE, GL_SRC_ALPHA, GL_DST_ALPHA）
- `dst` - 目标混合因子

**返回值**：无

**示例：**

```cpp
cmdList->SetBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
```

### SetBlendFuncSeparate

```cpp
void SetBlendFuncSeparate(unsigned int srcRGB, unsigned int dstRGB, unsigned int srcAlpha, unsigned int dstAlpha)
```

分别设置 RGB 和 Alpha 的混合函数。

**参数：**
- `srcRGB` - RGB 源混合因子
- `dstRGB` - RGB 目标混合因子
- `srcAlpha` - Alpha 源混合因子
- `dstAlpha` - Alpha 目标混合因子

**返回值**：无

### SetBlendEquation

```cpp
void SetBlendEquation(unsigned int mode)
```

设置混合方程。

**参数：**
- `mode` - 混合方程模式（GL_FUNC_ADD, GL_FUNC_SUBTRACT, GL_FUNC_REVERSE_SUBTRACT, GL_MIN, GL_MAX）

**返回值**：无

### SetBlendColor

```cpp
void SetBlendColor(float r, float g, float b, float a)
```

设置混合常量颜色。

**参数：**
- `r` - 红色分量
- `g` - 绿色分量
- `b` - 蓝色分量
- `a` - Alpha 分量

**返回值**：无

---

## 光栅化

### EnableCulling

```cpp
void EnableCulling(bool enable)
```

启用或禁用面剔除。

**参数：**
- `enable` - true 启用，false 禁用

**返回值**：无

### SetCullFace

```cpp
void SetCullFace(unsigned int face)
```

设置要剔除的面。

**参数：**
- `face` - OpenGL 面模式（GL_FRONT, GL_BACK, GL_FRONT_AND_BACK）

**返回值**：无

### SetFrontFace

```cpp
void SetFrontFace(unsigned int face)
```

设置正面顶点的缠绕顺序。

**参数：**
- `face` - GL_CW（顺时针）或 GL_CCW（逆时针）

**返回值**：无

### SetPolygonMode

```cpp
void SetPolygonMode(unsigned int mode)
```

设置多边形光栅化模式。

**参数：**
- `mode` - 光栅化模式（GL_POINT, GL_LINE, GL_FILL）

**返回值**：无

### SetPolygonOffset

```cpp
void SetPolygonOffset(float factor, float units)
```

设置多边形深度偏移。

**参数：**
- `factor` - 深度偏移因子
- `units` - 深度偏移单位

**返回值**：无

### SetPrimitiveType

```cpp
void SetPrimitiveType(PrimitiveType type)
```

设置图元类型（内部状态保存，不直接调用 GL）。

**参数：**
- `type` - 图元类型枚举

**返回值**：无

---

## 绘制（OpenGL 类型）

### Draw (PrimitiveType)

```cpp
void Draw(PrimitiveType type, unsigned int vertexCount, unsigned int startVertex)
```

绘制非索引图元。

**参数：**
- `type` - 图元类型
- `vertexCount` - 顶点数量
- `startVertex` - 起始顶点偏移

**返回值**：无

**示例：**

```cpp
cmdList->Draw(PrimitiveType::Triangles, 3, 0);
```

### DrawInstanced

```cpp
void DrawInstanced(PrimitiveType type, unsigned int vertexCount, unsigned int instanceCount, unsigned int startVertex, unsigned int startInstance)
```

实例化绘制。

**参数：**
- `type` - 图元类型
- `vertexCount` - 每个实例的顶点数量
- `instanceCount` - 实例数量
- `startVertex` - 起始顶点偏移
- `startInstance` - 起始实例 ID

**返回值**：无

### DrawIndexed (PrimitiveType)

```cpp
void DrawIndexed(PrimitiveType type, unsigned int indexCount, unsigned int startIndex, int baseVertex)
```

绘制索引图元。

**参数：**
- `type` - 图元类型
- `indexCount` - 索引数量
- `startIndex` - 起始索引偏移
- `baseVertex` - 基础顶点偏移（当前实现中未使用）

**返回值**：无

### DrawIndexedInstanced

```cpp
void DrawIndexedInstanced(PrimitiveType type, unsigned int indexCount, unsigned int instanceCount, unsigned int startIndex, int baseVertex, unsigned int startInstance)
```

实例化索引绘制。

**参数：**
- `type` - 图元类型
- `indexCount` - 索引数量
- `instanceCount` - 实例数量
- `startIndex` - 起始索引偏移
- `baseVertex` - 基础顶点偏移（当前实现中未使用）
- `startInstance` - 起始实例 ID

**返回值**：无

### DrawIndirect

```cpp
void DrawIndirect(PrimitiveType type, unsigned int buffer, size_t offset, unsigned int drawCount, unsigned int stride)
```

间接绘制命令。

**参数：**
- `type` - 图元类型
- `buffer` - 包含绘制参数的缓冲区
- `offset` - 缓冲区中的字节偏移
- `drawCount` - 绘制命令数量（当前实现中未使用）
- `stride` - 绘制参数结构 stride（当前实现中未使用）

**返回值**：无

### DrawIndexedIndirect

```cpp
void DrawIndexedIndirect(PrimitiveType type, unsigned int buffer, size_t offset, unsigned int drawCount, unsigned int stride)
```

间接索引绘制命令。

**参数：**
- `type` - 图元类型
- `buffer` - 包含绘制参数的缓冲区
- `offset` - 缓冲区中的字节偏移
- `drawCount` - 绘制命令数量（当前实现中未使用）
- `stride` - 绘制参数结构 stride（当前实现中未使用）

**返回值**：无

### MultiDrawArrays

```cpp
void MultiDrawArrays(PrimitiveType type, const int* first, const int* count, unsigned int drawCount)
```

多重绘制。

**参数：**
- `type` - 图元类型
- `first` - 每个绘制命令的起始索引数组
- `count` - 每个绘制命令的顶点数量数组
- `drawCount` - 绘制命令数量

**返回值**：无

### MultiDrawElements

```cpp
void MultiDrawElements(PrimitiveType type, const int* count, unsigned int type_, const void* const* indices, unsigned int drawCount)
```

多重索引绘制。

**参数：**
- `type` - 图元类型
- `count` - 每个绘制命令的索引数量数组
- `type_` - 索引数据类型
- `indices` - 索引指针数组
- `drawCount` - 绘制命令数量

**返回值**：无

---

## 计算着色器

### DispatchIndirect

```cpp
void DispatchIndirect(unsigned int buffer, size_t offset)
```

间接分发计算着色器。

**参数：**
- `buffer` - 包含分发参数的缓冲区
- `offset` - 缓冲区中的字节偏移

**返回值**：无

### DispatchCompute

```cpp
void DispatchCompute(unsigned int x, unsigned int y, unsigned int z, unsigned int groupX, unsigned int groupY, unsigned int groupZ)
```

分发计算着色器（带参数版本）。

**参数：**
- `x`, `y`, `z` - 工作组尺寸参数（当前实现中未使用）
- `groupX`, `groupY`, `groupZ` - 工作组数量

**返回值**：无

---

## 内存屏障

### MemoryBarrier

```cpp
void MemoryBarrier(unsigned int barriers)
```

设置内存屏障。

**参数：**
- `barriers` - OpenGL 屏障标志（如 GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT, GL_SHADER_STORAGE_BARRIER_BIT）

**返回值**：无

### TextureBarrier

```cpp
void TextureBarrier()
```

设置纹理屏障。

**返回值**：无

---

## 纹理绑定

### BindTexture

```cpp
void BindTexture(unsigned int target, unsigned int unit, unsigned int texture)
```

绑定纹理到纹理单元。

**参数：**
- `target` - 纹理目标（GL_TEXTURE_2D, GL_TEXTURE_3D 等）
- `unit` - 纹理单元索引
- `texture` - 纹理对象 ID

**返回值**：无

**示例：**

```cpp
cmdList->BindTexture(GL_TEXTURE_2D, 0, textureID);
```

### BindTextures

```cpp
void BindTextures(unsigned int first, unsigned int count, const unsigned int* textures)
```

批量绑定纹理。

**参数：**
- `first` - 起始纹理单元
- `count` - 纹理数量
- `textures` - 纹理 ID 数组

**返回值**：无

### BindSampler

```cpp
void BindSampler(unsigned int unit, unsigned int sampler)
```

绑定采样器。

**参数：**
- `unit` - 纹理单元索引
- `sampler` - 采样器对象 ID

**返回值**：无

### BindSamplers

```cpp
void BindSamplers(unsigned int first, unsigned int count, const unsigned int* samplers)
```

批量绑定采样器。

**参数：**
- `first` - 起始纹理单元
- `count` - 采样器数量
- `samplers` - 采样器 ID 数组

**返回值**：无

### BindImageTexture

```cpp
void BindImageTexture(unsigned int unit, unsigned int texture, int level, bool layered, int layer, unsigned int access, unsigned int format)
```

绑定纹理为图像单元。

**参数：**
- `unit` - 图像单元索引
- `texture` - 纹理对象 ID
- `level` - Mipmap 级别
- `layered` - 是否绑定整个纹理数组
- `layer` - 数组层索引
- `access` - 访问权限（GL_READ_ONLY, GL_WRITE_ONLY, GL_READ_WRITE）
- `format` - 纹理格式

**返回值**：无

---

## 缓冲区绑定

### BindBufferBase

```cpp
void BindBufferBase(unsigned int target, unsigned int index, unsigned int buffer)
```

绑定缓冲区到固定 binding point。

**参数：**
- `target` - 缓冲区目标（如 GL_UNIFORM_BUFFER, GL_SHADER_STORAGE_BUFFER）
- `index` - Binding point 索引
- `buffer` - 缓冲区对象 ID

**返回值**：无

### BindBufferRange

```cpp
void BindBufferRange(unsigned int target, unsigned int index, unsigned int buffer, size_t offset, size_t size)
```

绑定缓冲区到范围 binding point。

**参数：**
- `target` - 缓冲区目标
- `index` - Binding point 索引
- `buffer` - 缓冲区对象 ID
- `offset` - 缓冲区中的字节偏移
- `size` - 绑定范围大小

**返回值**：无

---

## OpenGL 状态

### Enable / Disable

```cpp
void Enable(unsigned int cap)
void Disable(unsigned int cap)
void Enablei(unsigned int cap, unsigned int index)
void Disablei(unsigned int cap, unsigned int index)
```

启用或禁用 GL capability。

**参数：**
- `cap` - OpenGL capability 标识符
- `index` - 目标索引（用于 indexed capabilities）

**返回值**：无

**示例：**

```cpp
cmdList->Enable(GL_PROGRAM_POINT_SIZE);
```

---

## Uniform 设置

### SetUniform1i / SetUniform1f

```cpp
void SetUniform1i(int location, int v)
void SetUniform1f(int location, float v)
```

设置单个 uniform 变量。

**参数：**
- `location` - Uniform 变量位置
- `v` - 值

**返回值**：无

### SetUniform2f

```cpp
void SetUniform2f(int location, float x, float y)
```

设置 vec2 uniform 变量。

**参数：**
- `location` - Uniform 变量位置
- `x`, `y` - 向量分量

**返回值**：无

### SetUniform3f

```cpp
void SetUniform3f(int location, float x, float y, float z)
```

设置 vec3 uniform 变量。

**参数：**
- `location` - Uniform 变量位置
- `x`, `y`, `z` - 向量分量

**返回值**：无

### SetUniform4f

```cpp
void SetUniform4f(int location, float x, float y, float z, float w)
```

设置 vec4 uniform 变量。

**参数：**
- `location` - Uniform 变量位置
- `x`, `y`, `z`, `w` - 向量分量

**返回值**：无

### SetUniform1fv / SetUniform2fv / SetUniform3fv / SetUniform4fv

```cpp
void SetUniform1fv(int location, int count, const float* v)
void SetUniform2fv(int location, int count, const float* v)
void SetUniform3fv(int location, int count, const float* v)
void SetUniform4fv(int location, int count, const float* v)
```

设置 float 数组 uniform 变量。

**参数：**
- `location` - Uniform 变量位置
- `count` - 数组元素数量
- `v` - 值数组指针

**返回值**：无

**示例：**

```cpp
float vec3Array[3] = {1.0f, 2.0f, 3.0f};
cmdList->SetUniform3fv(location, 1, vec3Array);
```

### SetUniformMatrix4fv

```cpp
void SetUniformMatrix4fv(int location, int count, bool transpose, const float* v)
```

设置矩阵 uniform 变量。

**参数：**
- `location` - Uniform 变量位置
- `count` - 矩阵数量
- `transpose` - 是否转置矩阵
- `v` - 矩阵数据指针

**返回值**：无

---

## Shader 程序

### UseProgram

```cpp
void UseProgram(unsigned int program)
```

激活 shader program。

**参数：**
- `program` - Program 对象 ID

**返回值**：无

### BindFragDataLocation

```cpp
void BindFragDataLocation(unsigned int program, unsigned int colorNumber, const char* name)
void BindFragDataLocationIndexed(unsigned int program, unsigned int colorNumber, unsigned int index, const char* name)
```

设置 fragment shader 颜色输出绑定。

**参数：**
- `program` - Program 对象 ID
- `colorNumber` - 颜色缓冲区编号
- `index` - 颜色索引（用于双源混合）
- `name` - Fragment shader 中的输出变量名

**返回值**：无

---

## 查询

### BeginQuery / EndQuery

```cpp
void BeginQuery(unsigned int target, unsigned int id)
void EndQuery(unsigned int target)
```

开始或结束查询。

**参数：**
- `target` - 查询目标（如 GL_SAMPLES_PASSED, GL_ANY_SAMPLES_PASSED）
- `id` - 查询对象 ID

**返回值**：无

### GetQueryObjectiv / GetQueryObjectuiv

```cpp
void GetQueryObjectiv(unsigned int id, unsigned int pname, int* params)
void GetQueryObjectuiv(unsigned int id, unsigned int pname, unsigned int* params)
```

获取查询结果。

**参数：**
- `id` - 查询对象 ID
- `pname` - 查询参数（如 GL_QUERY_RESULT, GL_QUERY_RESULT_AVAILABLE）
- `params` - 结果输出数组

**返回值**：无

---

## Framebuffer 操作

### ReadPixels

```cpp
void ReadPixels(int x, int y, int width, int height, unsigned int format, unsigned int type, void* data)
```

读取像素数据。

**参数：**
- `x`, `y` - 读取区域左下角坐标
- `width`, `height` - 读取区域尺寸
- `format` - 像素格式（GL_RED, GL_GREEN, GL_BLUE, GL_RGBA 等）
- `type` - 数据类型（GL_UNSIGNED_BYTE, GL_FLOAT 等）
- `data` - 输出数据缓冲区

**返回值**：无

### BlitFramebuffer

```cpp
void BlitFramebuffer(int srcX0, int srcY0, int srcX1, int srcY1, int dstX0, int dstY0, int dstX1, int dstY1, unsigned int mask, unsigned int filter)
```

Blit 帧缓冲区。

**参数：**
- `srcX0, srcY0, srcX1, srcY1` - 源区域
- `dstX0, dstY0, dstX1, dstY1` - 目标区域
- `mask` - Blit 缓冲区掩码
- `filter` - 过滤方式（GL_NEAREST, GL_LINEAR）

**返回值**：无

### CopyImageSubData

```cpp
void CopyImageSubData(unsigned int srcName, unsigned int srcTarget, int srcLevel, int srcX, int srcY, int srcZ, unsigned int dstName, unsigned int dstTarget, int dstLevel, int dstX, int dstY, int dstZ, int width, int height, int depth)
```

复制图像子数据。

**参数：**
- `srcName` - 源纹理 ID
- `srcTarget` - 源纹理目标
- `srcLevel` - 源 Mipmap 级别
- `srcX/Y/Z` - 源区域偏移
- `dstName` - 目标纹理 ID
- `dstTarget` - 目标纹理目标
- `dstLevel` - 目标 Mipmap 级别
- `dstX/Y/Z` - 目标区域偏移
- `width/height/depth` - 复制区域尺寸

**返回值**：无

### InvalidateFramebuffer

```cpp
void InvalidateFramebuffer(unsigned int target, unsigned int count, const unsigned int* attachments)
void InvalidateSubFramebuffer(unsigned int target, unsigned int count, const unsigned int* attachments, int x, int y, int width, int height)
```

使帧缓冲区失效。

**参数：**
- `target` - 帧缓冲区目标
- `count` - 附件数量
- `attachments` - 附件数组
- `x, y, width, height` - 子区域坐标（仅 InvalidateSubFramebuffer）

**返回值**：无

---

## 调试

### PushDebugGroup / PopDebugGroup

```cpp
void PushDebugGroup(unsigned int source, unsigned int id, int length, const char* message)
void PopDebugGroup()
```

推送或弹出调试组。

**参数：**
- `source` - 调试源（GL_DEBUG_SOURCE_API, GL_DEBUG_SOURCE_WINDOW_SYSTEM 等）
- `id` - 调试消息 ID
- `length` - 消息长度（-1 表示 null 终止）
- `message` - 调试消息

**返回值**：无

**示例：**

```cpp
cmdList->PushDebugGroup(GL_DEBUG_SOURCE_APPLICATION, 1, -1, "Begin Frame");
cmdList->Draw(PrimitiveType::Triangles, 3, 0);
cmdList->PopDebugGroup();
```

---

## 相关文档

- [OpenGLCommandList 总览](command-list.md) - 返回类总览