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

# OpenGLCommandList

OpenGL 命令列表实现。OpenGL 是立即模式 API，此类提供命令录制和批量提交的能力。

## 头文件

```cpp
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
```

## 继承关系

```
RHICommandList (interface)
└── OpenGLCommandList (implementation)
```

## 枚举

### PrimitiveType

| 值 | OpenGL 常量 |
|----|-------------|
| `Points` | `GL_POINTS` |
| `Lines` | `GL_LINES` |
| `LineStrip` | `GL_LINE_STRIP` |
| `Triangles` | `GL_TRIANGLES` |
| `TriangleStrip` | `GL_TRIANGLE_STRIP` |
| `TriangleFan` | `GL_TRIANGLE_FAN` |
| `LineListAdj` | `GL_LINES_ADJACENCY` |
| `TriangleListAdj` | `GL_TRIANGLES_ADJACENCY` |
| `Patch` | `GL_PATCHES` |

### ClearFlag

| 值 | 描述 |
|----|------|
| `Color` | 清除颜色缓冲区 |
| `Depth` | 清除深度缓冲区 |
| `Stencil` | 清除模板缓冲区 |

支持 `|` 操作符合并。

## 公共成员函数

### 生命周期

#### `void Shutdown() override`

#### `void Reset() override`
重置命令列表。

#### `void Close() override`
关闭命令列表。

### 清除操作

#### `void Clear(float r, float g, float b, float a, unsigned int buffers)`
清除指定缓冲区。

#### `void ClearColor(float r, float g, float b, float a)`

#### `void ClearDepth(float depth)`

#### `void ClearStencil(int stencil)`

#### `void ClearDepthStencil(float depth, int stencil)`

### RHI 接口实现

#### `void SetPipelineState(void* pipelineState) override`

#### `void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) override`

#### `void SetVertexBuffers(uint32_t startSlot, uint32_t count, ...) override`

#### `void SetIndexBuffer(void* buffer, uint64_t offset, Format format) override`

#### `void TransitionBarrier(void* resource, ...) override`
OpenGL 实现为空（无显式状态管理）。

#### `void SetPrimitiveTopology(PrimitiveTopology topology) override`

#### `void SetViewport(const Viewport& viewport) override`

#### `void SetViewports(uint32_t count, const Viewport* viewports) override`

#### `void SetScissorRect(const Rect& rect) override`

#### `void SetScissorRects(uint32_t count, const Rect* rects) override`

#### `void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil) override`

#### `void SetDepthStencilState(const DepthStencilState& state) override`

#### `void SetStencilRef(uint8_t ref) override`

#### `void SetBlendState(const BlendState& state) override`

#### `void SetBlendFactor(const float factor[4]) override`

#### `void ClearRenderTarget(void* renderTarget, const float color[4]) override`

#### `void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) override`

#### `void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance) override`

#### `void DrawIndexed(uint32_t indexCount, uint32_t instanceCount, uint32_t startIndex, int32_t baseVertex, uint32_t startInstance) override`

#### `void Dispatch(uint32_t x, uint32_t y, uint32_t z) override`

#### `void CopyResource(void* dst, void* src) override`

### OpenGL 特有方法

#### `void SetVertexBuffer(unsigned int buffer, size_t offset, size_t stride)`
直接设置顶点缓冲区（OpenGL 逃逸）。

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

#### `void SetIndexBuffer(unsigned int buffer, unsigned int type)`

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

#### `void BindVertexArray(unsigned int vao)`

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

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

### 视口与裁剪

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

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

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

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

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

#### `void EnableScissorTest(bool enable)`

### 深度测试

#### `void EnableDepthTest(bool enable)`

#### `void EnableDepthWrite(bool enable)`

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

### 模板测试

#### `void EnableStencilTest(bool enable)`

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

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

### 混合

#### `void EnableBlending(bool enable)`

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

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

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

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

### 光栅化

#### `void EnableCulling(bool enable)`

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

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

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

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

#### `void SetPrimitiveType(PrimitiveType type)`

### 绘制

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

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

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

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

#### `void DrawIndirect(...)`

#### `void DrawIndexedIndirect(...)`

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

#### `void MultiDrawElements(...)`

### 计算着色器

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

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

### 内存屏障

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

#### `void TextureBarrier()`

### 纹理绑定

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

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

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

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

#### `void BindImageTexture(...)`

### 缓冲区绑定

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

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

### OpenGL 状态

#### `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)`

### Uniform 设置

#### `void SetUniform1i(int location, int v)`

#### `void SetUniform1f(int location, float v)`

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

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

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

#### `void SetUniform1fv(int location, int count, const float* v)`

#### `void SetUniform2fv/3fv/4fv`

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

### Shader 程序

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

#### `void BindFragDataLocation(unsigned int program, unsigned int colorNumber, const char* name)`

#### `void BindFragDataLocationIndexed(...)`

### 查询

#### `void BeginQuery(unsigned int target, unsigned int id)`

#### `void EndQuery(unsigned int target)`

#### `void GetQueryObjectiv/GetQueryObjectuiv`

### Framebuffer 操作

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

#### `void BlitFramebuffer(...)`

#### `void CopyImageSubData(...)`

#### `void InvalidateFramebuffer(unsigned int target, unsigned int count, const unsigned int* attachments)`

#### `void InvalidateSubFramebuffer(...)`

### 调试

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

#### `void PopDebugGroup()`

## 内部成员

| 成员 | 类型 | 描述 |
|------|------|------|
| `m_primitiveType` | `unsigned int` | 当前图元类型 |
| `m_currentVAO` | `unsigned int` | 当前 VAO |
| `m_currentProgram` | `unsigned int` | 当前 program |

## 备注

- OpenGL 是立即模式 API，`OpenGLCommandList` 主要用于状态批处理
- `Reset()` 和 `Close()` 是可选的，可直接调用 GL 命令