docs: update RHI API docs

docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md

@@ -4,25 +4,45 @@
 void AddVertexBuffer(unsigned int buffer, const VertexAttribute& attribute)
 ```
 
-添加顶点缓冲区并指定顶点属性。
+添加顶点缓冲区并配置顶点属性。
+
+**详细描述：**
+将顶点缓冲区绑定到 VAO，并配置顶点属性的读取方式。调用时：
+1. 绑定 VAO
+2. 绑定顶点缓冲区
+3. 启用顶点属性数组
+4. 使用 `glVertexAttribPointer` 配置属性格式
+5. 解绑缓冲区和 VAO
 
 **参数：**
-- `buffer` - OpenGL 缓冲区对象 ID
-- `attribute` - 顶点属性描述结构体
+- `buffer` - OpenGL 缓冲区对象 ID（GL_ARRAY_BUFFER 类型）
+- `attribute` - 顶点属性描述结构体 [`VertexAttribute`](vertex-attribute.md)
 
 **示例：**
 
 ```cpp
+// 位置属性 (对应着色器 layout(location = 0))
 VertexAttribute attr;
 attr.index = 0;
-attr.count = 3;
-attr.type = GL_FLOAT;
-attr.normalized = GL_FALSE;
-attr.stride = sizeof(Vertex);
-attr.offset = 0;
-vao.AddVertexBuffer(vbo, attr);
+attr.count = 3;                    // xyz 三个分量
+attr.type = GL_FLOAT;              // float 类型
+attr.normalized = GL_FALSE;        // 不归一化
+attr.stride = sizeof(Vertex);      // 顶点结构体大小
+attr.offset = 0;                   // 位置在结构体起始处
+vao.AddVertexBuffer(positionVBO, attr);
+
+// 纹理坐标属性 (对应着色器 layout(location = 1))
+VertexAttribute texAttr;
+texAttr.index = 1;
+texAttr.count = 2;                              // uv 两个分量
+texAttr.type = GL_FLOAT;
+texAttr.normalized = GL_FALSE;
+texAttr.stride = sizeof(Vertex);
+texAttr.offset = offsetof(Vertex, texCoord);    // 纹理坐标偏移
+vao.AddVertexBuffer(texCoordVBO, texAttr);
 ```
 
 ## 相关文档
 
 - [OpenGLVertexArray](vertex-array.md) - 返回类总览
+- [VertexAttribute](vertex-attribute.md) - 属性结构体详细说明

docs/api/rhi/opengl/vertex-array/bind.md

@@ -0,0 +1,18 @@
+# OpenGLVertexArray::Bind
+
+```cpp
+void Bind() const
+```
+
+绑定顶点数组对象到当前 OpenGL 上下文。
+
+**示例：**
+
+```cpp
+vao.Bind();
+glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_INT, 0);
+```
+
+## 相关文档
+
+- [OpenGLVertexArray](vertex-array.md) - 返回类总览

docs/api/rhi/opengl/vertex-array/constructor.md

@@ -0,0 +1,31 @@
+# OpenGLVertexArray::OpenGLVertexArray
+
+```cpp
+OpenGLVertexArray()
+```
+
+默认构造函数。初始化所有成员变量为默认值。
+
+**详细描述：**
+- `m_vao` = 0
+- `m_indexBuffer` = 0
+- `m_indexCount` = 0
+- `m_vertexBufferCount` = 0
+
+不创建任何 OpenGL 资源，需调用 `Initialize()` 后才能使用。
+
+**示例：**
+
+```cpp
+OpenGLVertexArray vao;
+// 此时 vao 未初始化，不能使用 Bind 等方法
+if (vao.Initialize()) {
+    vao.Bind();  // 现在可以使用了
+}
+```
+
+## 相关文档
+
+- [OpenGLVertexArray](vertex-array.md) - 返回类总览
+- [Initialize](initialize.md) - 初始化方法
+- [Shutdown](shutdown.md) - 关闭方法

docs/api/rhi/opengl/vertex-array/destructor.md

@@ -0,0 +1,29 @@
+# OpenGLVertexArray::~OpenGLVertexArray
+
+```cpp
+~OpenGLVertexArray()
+```
+
+析构函数。在对象销毁时自动调用 `Shutdown()` 释放 OpenGL 资源。
+
+**详细描述：**
+确保 VAO 资源被正确释放。如果 `Shutdown()` 尚未调用，会自动调用以释放 `glGenVertexArrays` 创建的资源。
+
+**注意：**
+- 不会释放关联的顶点缓冲区和索引缓冲区（它们通常由独立的缓冲区管理对象管理）
+- 仅释放 `glGenVertexArrays` 生成的 VAO
+
+**示例：**
+
+```cpp
+{
+    OpenGLVertexArray vao;
+    vao.Initialize();
+    // 使用 vao...
+} // vao 超出作用域时自动调用析构函数，释放资源
+```
+
+## 相关文档
+
+- [OpenGLVertexArray](vertex-array.md) - 返回类总览
+- [Shutdown](shutdown.md) - 关闭方法

docs/api/rhi/opengl/vertex-array/get-index-count.md

@@ -6,15 +6,24 @@ unsigned int GetIndexCount() const
 
 获取索引数量。
 
-**返回：** `unsigned int` - 索引数量
+**详细描述：**
+返回 `m_indexCount` 成员的值。**注意**：当前实现中 `m_indexCount` 仅在构造函数中初始化为 0，
+`SetIndexBuffer` 不会更新此值。如需获取索引数量，需在调用 `SetIndexBuffer` 后手动维护或通过其他方式获取。
+
+**返回：** `unsigned int` - 索引数量（当前实现中始终为 0，需手动维护）
 
 **示例：**
 
 ```cpp
-unsigned int count = vao.GetIndexCount();
-glDrawElements(GL_TRIANGLES, count, GL_UNSIGNED_INT, 0);
+// 注意：GetIndexCount() 总是返回 0
+// 建议自行维护索引数量
+unsigned int indexCount = /* 从外部获取或手动设置 */;
+glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_INT, 0);
 ```
 
+**另见：**
+- [SetIndexBuffer](set-index-buffer.md) - 设置索引缓冲（不更新 m_indexCount）
+
 ## 相关文档
 
 - [OpenGLVertexArray](vertex-array.md) - 返回类总览

docs/api/rhi/opengl/vertex-array/initialize.md

@@ -0,0 +1,33 @@
+# OpenGLVertexArray::Initialize
+
+```cpp
+bool Initialize()
+```
+
+初始化 OpenGL 顶点数组对象。
+
+**详细描述：**
+调用 `glGenVertexArrays(1, &m_vao)` 生成一个新的顶点数组对象并存储其 ID。
+必须在使用 VAO 之前调用。
+
+**返回：** `bool` - 始终返回 `true`（当前实现不进行错误检查）
+
+**注意：**
+- 如果初始化失败，`m_vao` 将保持为 0
+- 当前实现不检查 OpenGL 错误，建议在调用前确保 OpenGL 上下文已创建
+
+**示例：**
+
+```cpp
+OpenGLVertexArray vao;
+if (vao.Initialize()) {
+    // VAO 初始化成功，可以添加缓冲和绑定
+    vao.AddVertexBuffer(vbo, positionAttr);
+    vao.Bind();
+}
+```
+
+## 相关文档
+
+- [OpenGLVertexArray](vertex-array.md) - 返回类总览
+- [Shutdown](shutdown.md) - 关闭方法

docs/api/rhi/opengl/vertex-array/set-index-buffer.md

@@ -6,9 +6,14 @@ void SetIndexBuffer(unsigned int buffer, unsigned int type)
 
 设置索引缓冲区。
 
+**详细描述：**
+将索引缓冲区绑定到此 VAO。绑定后，绘制调用 `glDrawElements` 将使用此索引缓冲。
+注意：当前实现中 `type` 参数仅存储，不影响实际 OpenGL 调用；`m_indexCount` 也不会被更新，
+需通过其他方式跟踪索引数量。
+
 **参数：**
-- `buffer` - OpenGL 缓冲区对象 ID
-- `type` - 索引数据类型（GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, GL_UNSIGNED_INT）
+- `buffer` - OpenGL 缓冲区对象 ID（ELEMENT_ARRAY_BUFFER）
+- `type` - 索引数据类型（`GL_UNSIGNED_BYTE`、`GL_UNSIGNED_SHORT`、`GL_UNSIGNED_INT`），当前未使用
 
 **示例：**
 
@@ -16,6 +21,10 @@ void SetIndexBuffer(unsigned int buffer, unsigned int type)
 vao.SetIndexBuffer(ibo, GL_UNSIGNED_INT);
 ```
 
+**注意：**
+- `m_indexCount` 在调用此方法后不会自动更新，需手动维护索引数量
+- 索引缓冲区的实际类型信息由 OpenGL 绑定时确定
+
 ## 相关文档
 
 - [OpenGLVertexArray](vertex-array.md) - 返回类总览

docs/api/rhi/opengl/vertex-array/shutdown.md

@@ -0,0 +1,32 @@
+# OpenGLVertexArray::Shutdown
+
+```cpp
+void Shutdown()
+```
+
+关闭顶点数组对象，释放 OpenGL 资源。
+
+**详细描述：**
+调用 `glDeleteVertexArrays(1, &m_vao)` 释放 VAO 资源，并将 `m_vao` 重置为 0。
+
+**释放的资源：**
+- `m_vao` - 顶点数组对象
+
+**不释放的资源：**
+- 顶点缓冲区（由独立的缓冲区管理对象管理）
+- 索引缓冲区（由独立的缓冲区管理对象管理）
+
+**幂等性：**
+可安全多次调用。如果 `m_vao` 为 0，则不执行任何操作。
+
+**示例：**
+
+```cpp
+vao.Shutdown();  // 释放 VAO
+// 此后不能再调用 Bind()
+```
+
+## 相关文档
+
+- [OpenGLVertexArray](vertex-array.md) - 返回类总览
+- [Initialize](initialize.md) - 初始化方法

docs/api/rhi/opengl/vertex-array/unbind.md

@@ -0,0 +1,17 @@
+# OpenGLVertexArray::Unbind
+
+```cpp
+void Unbind() const
+```
+
+解除当前绑定的顶点数组对象。
+
+**示例：**
+
+```cpp
+vao.Unbind();
+```
+
+## 相关文档
+
+- [OpenGLVertexArray](vertex-array.md) - 返回类总览

docs/api/rhi/opengl/vertex-array/vertex-array.md

@@ -2,22 +2,67 @@
 
 **命名空间**: `XCEngine::RHI`
 
-**描述**: OpenGL 顶点数组对象 (VAO) 封装。
+**描述**: OpenGL 顶点数组对象 (VAO) 封装。管理顶点属性配置和索引缓冲绑定。
+
+## 概述
+
+`OpenGLVertexArray` 封装了 OpenGL 顶点数组对象 (Vertex Array Object, VAO)，用于：
+- 存储顶点属性配置
+- 绑定顶点缓冲区和索引缓冲区
+- 提供便捷的绑定/解绑接口
+
+## 类型
+
+| 类型 | 描述 |
+|------|------|
+| [`VertexAttribute`](vertex-attribute.md) | 顶点属性描述结构体 |
+
+## 构造函数/析构函数
+
+| 方法 | 描述 |
+|------|------|
+| [`OpenGLVertexArray()`](constructor.md) | 默认构造函数 |
+| [`~OpenGLVertexArray()`](destructor.md) | 析构函数，调用 `Shutdown()` 释放资源 |
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
-| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化顶点数组 |
-| [`AddVertexBuffer`](add-vertex-buffer.md) | 添加顶点缓冲 |
+| [`Initialize`](initialize.md) | 初始化顶点数组，生成 VAO |
+| [`AddVertexBuffer`](add-vertex-buffer.md) | 添加顶点缓冲并配置属性 |
 | [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲 |
-| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭顶点数组 |
-| [`Bind`](../../shader/bind.md) | 绑定顶点数组 |
-| [`Unbind`](../../shader/unbind.md) | 解绑顶点数组 |
+| [`Shutdown`](shutdown.md) | 关闭顶点数组，释放 VAO 资源 |
+| [`Bind`](bind.md) | 绑定顶点数组到当前 OpenGL 上下文 |
+| [`Unbind`](unbind.md) | 解绑顶点数组 |
 | [`GetID`](get-id.md) | 获取 OpenGL VAO ID |
-| [`GetIndexBuffer`](get-index-buffer.md) | 获取索引缓冲 |
-| [`GetIndexCount`](get-index-count.md) | 获取索引数量 |
+| [`GetIndexBuffer`](get-index-buffer.md) | 获取索引缓冲区 ID |
+| [`GetIndexCount`](get-index-count.md) | 获取索引数量（需手动维护） |
+
+## 使用示例
+
+```cpp
+// 创建 VAO
+OpenGLVertexArray vao;
+vao.Initialize();
+
+// 添加顶点缓冲和属性
+vao.AddVertexBuffer(vbo, positionAttr);
+vao.AddVertexBuffer(vbo, normalAttr);
+vao.AddVertexBuffer(vbo, texCoordAttr);
+
+// 设置索引缓冲
+vao.SetIndexBuffer(ibo, GL_UNSIGNED_INT);
+
+// 绑定并绘制
+vao.Bind();
+glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_INT, 0);
+vao.Unbind();
+
+// 销毁
+vao.Shutdown();
+```
 
 ## 相关文档
 
 - [OpenGL 后端总览](../overview.md)
+- [VertexAttribute 结构体](vertex-attribute.md)

docs/api/rhi/opengl/vertex-array/vertex-attribute.md

@@ -0,0 +1,72 @@
+# VertexAttribute
+
+**命名空间**: `XCEngine::RHI`
+
+**描述**: 顶点属性描述结构体，用于定义顶点缓冲区中单个属性的布局。
+
+## 成员
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `index` | `unsigned int` | 属性索引，对应着色器中 `layout(location = n)` |
+| `count` | `int` | 分量数量（1-4），如位置用 3，纹理坐标用 2 |
+| `type` | `unsigned int` | OpenGL 数据类型，如 `GL_FLOAT`、`GL_INT` |
+| `normalized` | `bool` | 是否归一化Fixed-point类型 |
+| `stride` | `size_t` | 连续顶点属性之间的字节偏移 |
+| `offset` | `size_t` | 此属性在顶点结构体中的字节偏移 |
+
+## 类型取值参考
+
+| 类型常量 | 描述 |
+|----------|------|
+| `GL_BYTE` | 有符号字节 |
+| `GL_UNSIGNED_BYTE` | 无符号字节 |
+| `GL_SHORT` | 有符号短整型 |
+| `GL_UNSIGNED_SHORT` | 无符号短整型 |
+| `GL_INT` | 有符号整型 |
+| `GL_UNSIGNED_INT` | 无符号整型 |
+| `GL_FLOAT` | 单精度浮点 |
+| `GL_DOUBLE` | 双精度浮点 |
+
+## 使用示例
+
+```cpp
+// 定义顶点结构体
+struct Vertex {
+    float position[3];
+    float normal[3];
+    float texCoord[2];
+};
+
+// 位置属性 (index=0)
+VertexAttribute posAttr;
+posAttr.index = 0;
+posAttr.count = 3;
+posAttr.type = GL_FLOAT;
+posAttr.normalized = GL_FALSE;
+posAttr.stride = sizeof(Vertex);
+posAttr.offset = 0;
+
+// 法线属性 (index=1)
+VertexAttribute normalAttr;
+normalAttr.index = 1;
+normalAttr.count = 3;
+normalAttr.type = GL_FLOAT;
+normalAttr.normalized = GL_FALSE;
+normalAttr.stride = sizeof(Vertex);
+normalAttr.offset = offsetof(Vertex, normal);
+
+// 纹理坐标属性 (index=2)
+VertexAttribute texAttr;
+texAttr.index = 2;
+texAttr.count = 2;
+texAttr.type = GL_FLOAT;
+texAttr.normalized = GL_FALSE;
+texAttr.stride = sizeof(Vertex);
+texAttr.offset = offsetof(Vertex, texCoord);
+```
+
+## 相关文档
+
+- [OpenGLVertexArray](vertex-array.md) - 返回类总览
+- [AddVertexBuffer](add-vertex-buffer.md) - 添加顶点缓冲方法