docs(api): deepen OpenGL helper backend docs

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/Bind.md

@@ -1,31 +1,28 @@
 # OpenGLSampler::Bind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Bind(unsigned int unit) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSampler.h`，当前页面用于固定 `OpenGLSampler` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `unit` - 参数语义详见头文件声明。
+把当前 sampler object 绑定到指定纹理单元。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `unit`: 目标纹理单元编号。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-    // 根据上下文补齐参数后调用 OpenGLSampler::Bind(...)。
-    (void)object;
-}
-```
+- 直接调用 `glBindSampler(unit, m_sampler)`。
+- 不校验 `m_sampler` 是否有效，也不保存之前该纹理单元上的 sampler 绑定。
+
+## 使用建议
+
+- `unit` 必须与纹理绑定和着色器采样槽约定保持一致。
+- 如果对象尚未初始化，当前实现会把 `0` 绑定到该槽位，相当于未使用独立 sampler object。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [Unbind](Unbind.md)
+- [GetID](GetID.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/Constructor.md

@@ -1,28 +1,20 @@
-# OpenGLSampler::OpenGLSampler()
-
-构造对象。
+# OpenGLSampler::OpenGLSampler
 
 ```cpp
 OpenGLSampler();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSampler.h`，当前页面用于固定 `OpenGLSampler` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 OpenGL sampler 封装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-}
-```
+- 仅把 `m_sampler` 初始化为 `0`。
+- `m_desc` 使用结构体默认值。
+- 不执行任何 OpenGL 调用。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [OpenGLSampler](OpenGLSampler.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/Destructor.md

@@ -1,29 +1,24 @@
-# OpenGLSampler::~OpenGLSampler()
-
-销毁对象并释放相关资源。
+# OpenGLSampler::~OpenGLSampler
 
 ```cpp
 ~OpenGLSampler() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSampler.h`，当前页面用于固定 `OpenGLSampler` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 `OpenGLSampler` 对象本身。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 当前析构函数是空实现。
+- 它不会自动调用 [Shutdown](Shutdown.md)。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
+## 重要限制
 
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 这意味着如果调用方在销毁前没有显式 `Shutdown()`，底层 sampler object 可能不会被及时删除。
+- 它和引擎中许多“析构里自动释放”的包装类行为不同，文档和使用者都必须注意这一点。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/GetID.md

@@ -1,42 +1,25 @@
 # OpenGLSampler::GetID
 
-获取相关状态或对象。
-
-该方法在 `XCEngine/RHI/OpenGL/OpenGLSampler.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 unsigned int GetID() const;
-```
-
-**参数：** 无。
-
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 unsigned int GetID() override;
 ```
 
-**参数：** 无。
+## 作用
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+返回底层 OpenGL sampler object id。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
+- 初始化成功后通常返回非零 id。
+- 构造后或 `Shutdown()` 之后返回 `0`。
 
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-    // 根据上下文补齐参数后调用 OpenGLSampler::GetID(...)。
-    (void)object;
-}
-```
+## 当前实现行为
+
+- 两个重载都直接返回 `m_sampler`。
+- 单元测试会校验初始化后该值非零。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/GetNativeHandle.md

@@ -1,30 +1,23 @@
 # OpenGLSampler::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSampler.h`，当前页面用于固定 `OpenGLSampler` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以 `void*` 形式暴露底层 sampler 句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `m_sampler` 转换后的值。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-    // 根据上下文补齐参数后调用 OpenGLSampler::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 不创建新对象，也不附带其他副作用。
+- 其语义与 [GetID](GetID.md) 一致，只是为了适配统一 RHI 的 native handle 接口。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [GetID](GetID.md)
+- [OpenGLSampler](OpenGLSampler.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/Initialize.md

@@ -1,31 +1,44 @@
 # OpenGLSampler::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize(const OpenGLSamplerDesc& desc);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSampler.h`，当前页面用于固定 `OpenGLSampler` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `desc` - 参数语义详见头文件声明。
+创建一个真正的 OpenGL sampler object，并把采样参数写入驱动。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数说明
 
-**示例：**
+- `desc`: 采样器描述，包含过滤模式、寻址模式、比较模式、LOD 范围、各向异性和边界色等参数。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-    // 根据上下文补齐参数后调用 OpenGLSampler::Initialize(...)。
-    (void)object;
-}
-```
+- 当前实现恒定返回 `true`。
+
+## 当前实现行为
+
+- 先复制 `desc` 到 `m_desc`。
+- 调用 `glGenSamplers(1, &m_sampler)` 创建原生 sampler。
+- 依次设置:
+  - `GL_TEXTURE_MIN_FILTER`
+  - `GL_TEXTURE_MAG_FILTER`
+  - `GL_TEXTURE_WRAP_S/T/R`
+  - `GL_TEXTURE_LOD_BIAS`
+  - `GL_TEXTURE_MIN_LOD`
+  - `GL_TEXTURE_MAX_LOD`
+  - `GL_TEXTURE_MAX_ANISOTROPY`
+  - `GL_TEXTURE_COMPARE_MODE`
+  - `GL_TEXTURE_COMPARE_FUNC`
+  - `GL_TEXTURE_BORDER_COLOR`
+
+## 重要限制
+
+- 当前实现没有检查 `glGenSamplers` 或参数设置是否失败。
+- `compareFunc` 作为原始整数直接传给 OpenGL，要求调用方或设备工厂提前完成正确映射。
+- 代码默认可用 `GL_TEXTURE_MAX_ANISOTROPY`，没有做扩展存在性保护。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/OpenGLSampler.md

@@ -6,36 +6,64 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLSampler.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLSampler` public API。
+**描述**: OpenGL 后端的独立 sampler object 封装，用于保存过滤、寻址、LOD 和比较采样状态。
 
-## 概述
+## 概览
 
-`OpenGLSampler.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+和 `OpenGLResourceView` 那种“统一抽象视图元数据”不同，`OpenGLSampler` 对应的是一个真实的 OpenGL 原生对象: sampler object。
 
-## 声明概览
+这类对象的作用和商业引擎里的独立采样器资源一致:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `SamplerWrapMode` | `enum class` | 头文件中的公开声明。 |
-| `SamplerFilter` | `enum class` | 头文件中的公开声明。 |
-| `SamplerCompareMode` | `enum class` | 头文件中的公开声明。 |
-| `OpenGLSamplerDesc` | `struct` | 头文件中的公开声明。 |
-| `OpenGLSampler` | `class` | 继承自 `RHISampler` 的公开声明。 |
+- 把纹理采样状态从纹理对象本身拆出来
+- 让同一张纹理能以不同采样方式被复用
+- 让 descriptor / binding 层更接近现代图形 API 的资源组织方式
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLSampler()](Constructor.md) | 构造对象。 |
-| [~OpenGLSampler()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
-| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
-| [GetID](GetID.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
+`OpenGLSampler` 在当前引擎中承担的是“真实后端资源包装器”角色，而不是纯元数据对象。
+
+它的好处是:
+
+- 采样状态可以独立于纹理复用
+- 更容易与上层 `RHISampler` 抽象对齐
+
+当前实现的代价是:
+
+- 初始化路径非常直接，没有错误处理兜底
+- 析构函数没有自动释放原生对象，必须依赖显式 `Shutdown()`
+
+## 生命周期
+
+- 构造后 `m_sampler = 0`。
+- [Initialize](Initialize.md) 成功后持有真实 sampler id。
+- [Shutdown](Shutdown.md) 删除 sampler object。
+- 析构函数当前不会自动执行 `Shutdown()`。
+
+## 线程语义
+
+- 不包含锁。
+- 所有操作都依赖当前 OpenGL 上下文，应视为渲染线程资源对象。
+
+## 当前实现的真实行为
+
+- `OpenGLDevice::CreateSampler()` 会把通用 `SamplerDesc` 转换成 `OpenGLSamplerDesc`，再调用 [Initialize](Initialize.md)。
+- `OpenGLDescriptorSet` 在更新采样器时，会读取 [GetID](GetID.md) 保存 sampler id。
+- 单元测试 `tests/RHI/OpenGL/unit/test_sampler.cpp` 覆盖了默认初始化、自定义参数初始化、绑定/解绑和 `GetID()`。
+
+## 当前限制
+
+- 析构不自动释放原生 sampler。
+- 初始化没有显式失败检测。
+- 比较函数和各向异性能力依赖调用环境和扩展支持。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [Bind](Bind.md)
+- [Unbind](Unbind.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/Shutdown.md

@@ -1,30 +1,25 @@
 # OpenGLSampler::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSampler.h`，当前页面用于固定 `OpenGLSampler` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+删除底层 sampler object。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_sampler != 0`，调用 `glDeleteSamplers(1, &m_sampler)`。
+- 然后把 `m_sampler` 设回 `0`。
+- 不会清空 `m_desc`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-    // 根据上下文补齐参数后调用 OpenGLSampler::Shutdown(...)。
-    (void)object;
-}
-```
+- 由于析构函数不会自动调用它，调用方应把 `Shutdown()` 当作释放原生 sampler 的必经步骤。
+- 多次调用是安全的，后续调用会因 `m_sampler == 0` 而成为 no-op。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [GetID](GetID.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLSampler/Unbind.md

@@ -1,31 +1,23 @@
 # OpenGLSampler::Unbind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Unbind(unsigned int unit) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSampler.h`，当前页面用于固定 `OpenGLSampler` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `unit` - 参数语义详见头文件声明。
+从指定纹理单元解绑独立 sampler object。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `unit`: 目标纹理单元编号。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSampler.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLSampler object;
-    // 根据上下文补齐参数后调用 OpenGLSampler::Unbind(...)。
-    (void)object;
-}
-```
+- 直接执行 `glBindSampler(unit, 0)`。
+- 不要求当前对象已经初始化，因为它不依赖 `m_sampler`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSampler.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/Allocate.md

@@ -1,30 +1,24 @@
 # OpenGLTextureUnitAllocator::Allocate
 
-公开方法，详见头文件声明。
-
 ```cpp
 int32_t Allocate();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+分配一个可用的纹理单元编号。
 
-**返回：** `int32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 成功时返回第一个空闲 unit。
+- 没有空闲槽位时返回 `-1`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::Allocate(...)。
-    (void)object;
-}
-```
+- 采用从 `0` 开始的线性扫描。
+- 找到第一个 `m_allocated[i] == false` 的槽位后，标记为已分配并返回。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Free](Free.md)
+- [IsAllocated](IsAllocated.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/BindTexture.md

@@ -1,32 +1,35 @@
 # OpenGLTextureUnitAllocator::BindTexture
 
-公开方法，详见头文件声明。
-
 ```cpp
 void BindTexture(int32_t unit, OpenGLTexture* texture);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `unit` - 参数语义详见头文件声明。
-- `texture` - 参数语义详见头文件声明。
+把纹理绑定到指定 texture unit，并更新分配器缓存。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `unit`: 目标纹理单元。
+- `texture`: 需要绑定的纹理对象；可为空。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::BindTexture(...)。
-    (void)object;
-}
-```
+- 非法 `unit` 直接返回。
+- 调用 `glActiveTexture(GL_TEXTURE0 + unit)`。
+- 如果 `texture` 非空:
+  - 使用 `texture->GetOpenGLType()` 作为绑定目标
+  - 使用 `texture->GetID()` 作为纹理 id
+- 如果 `texture == nullptr`:
+  - 执行 `glBindTexture(GL_TEXTURE_2D, 0)`
+- 最后把 `m_boundTextures[unit]` 缓存为该纹理指针。
+
+## 重要限制
+
+- 该函数会修改当前 active texture unit，但不会恢复之前的活动单元。
+- 空纹理解绑路径固定写死为 `GL_TEXTURE_2D`，并不区分先前绑定的是 3D、cubemap 或 array 纹理。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [UnbindTexture](UnbindTexture.md)
+- [GetBoundTexture](GetBoundTexture.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/Constructor.md

@@ -1,28 +1,19 @@
-# OpenGLTextureUnitAllocator::OpenGLTextureUnitAllocator()
-
-构造对象。
+# OpenGLTextureUnitAllocator::OpenGLTextureUnitAllocator
 
 ```cpp
 OpenGLTextureUnitAllocator();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的纹理单元分配器。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-}
-```
+- 仅把 `m_maxUnits` 初始化为 `0`。
+- 分配和绑定缓存数组保持为空。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [OpenGLTextureUnitAllocator](OpenGLTextureUnitAllocator.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/Destructor.md

@@ -1,29 +1,18 @@
-# OpenGLTextureUnitAllocator::~OpenGLTextureUnitAllocator()
-
-销毁对象并释放相关资源。
+# OpenGLTextureUnitAllocator::~OpenGLTextureUnitAllocator
 
 ```cpp
 ~OpenGLTextureUnitAllocator();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁分配器并释放它仍然持有的 unit。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/Free.md

@@ -1,31 +1,20 @@
 # OpenGLTextureUnitAllocator::Free
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Free(int32_t unit);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `unit` - 参数语义详见头文件声明。
+释放一个先前分配的纹理单元。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::Free(...)。
-    (void)object;
-}
-```
+- 非法 `unit` 直接返回。
+- 调用 [UnbindTexture](UnbindTexture.md) 清空该单元上的纹理绑定缓存。
+- 把 `m_allocated[unit]` 设为 `false`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Allocate](Allocate.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/GetBoundTexture.md

@@ -1,31 +1,23 @@
 # OpenGLTextureUnitAllocator::GetBoundTexture
 
-获取相关状态或对象。
-
 ```cpp
 OpenGLTexture* GetBoundTexture(int32_t unit) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `unit` - 参数语义详见头文件声明。
+返回分配器缓存中记录的已绑定纹理对象。
 
-**返回：** `OpenGLTexture*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `unit` 合法时返回缓存的 `OpenGLTexture*`。
+- 非法 `unit` 返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::GetBoundTexture(...)。
-    (void)object;
-}
-```
+- 这不是对 OpenGL 实际状态的查询，只是返回分配器维护的缓存。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [BindTexture](BindTexture.md)
+- [IsAllocated](IsAllocated.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/GetMaxUnits.md

@@ -1,30 +1,19 @@
 # OpenGLTextureUnitAllocator::GetMaxUnits
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetMaxUnits() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回分配器当前配置的最大纹理单元数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::GetMaxUnits(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_maxUnits`。
+- `Shutdown()` 后该值会回到 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/Initialize.md

@@ -1,31 +1,29 @@
 # OpenGLTextureUnitAllocator::Initialize
 
-初始化内部状态。
-
 ```cpp
 void Initialize(uint32_t maxUnits = 16);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `maxUnits` - 参数语义详见头文件声明。
+初始化纹理单元分配器容量和缓存数组。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `maxUnits`: 可管理的纹理单元数量，默认 `16`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::Initialize(...)。
-    (void)object;
-}
-```
+- 把 `m_maxUnits` 设为 `maxUnits`。
+- 调用 `resize(maxUnits, false)` 初始化 `m_allocated`。
+- 调用 `resize(maxUnits, nullptr)` 初始化 `m_boundTextures`。
+
+## 重要限制
+
+- 如果在同一个对象上重复调用 `Initialize()` 而不先 `Shutdown()`，`resize()` 会保留已有元素内容，不能保证完全重置旧状态。
+- 当前设计更适合“一次初始化，长期使用”。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [GetMaxUnits](GetMaxUnits.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/IsAllocated.md

@@ -1,31 +1,19 @@
 # OpenGLTextureUnitAllocator::IsAllocated
 
-查询当前状态。
-
 ```cpp
 bool IsAllocated(int32_t unit) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `unit` - 参数语义详见头文件声明。
+检查指定纹理单元是否已被分配。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::IsAllocated(...)。
-    (void)object;
-}
-```
+- 非法 `unit` 返回 `false`。
+- 合法 `unit` 直接返回 `m_allocated[unit]`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Allocate](Allocate.md)
+- [Free](Free.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md

@@ -6,35 +6,63 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLTextureUnitAllocator` public API。
+**描述**: OpenGL 后端的轻量 texture unit 分配器，负责分配槽位并缓存每个单元当前绑定的纹理对象。
 
-## 概述
+## 概览
 
-`OpenGLTextureUnitAllocator.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+OpenGL 没有现代图形 API 那样统一的 descriptor heap / descriptor set 机制。很多资源绑定最终都要落到 texture unit。
 
-## 声明概览
+`OpenGLTextureUnitAllocator` 的职责就是把这件事做成一个简单、可复用的后端基础设施:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLTextureUnitAllocator` | `class` | 头文件中的公开声明。 |
+- 分配一个空闲 texture unit
+- 把纹理绑定到这个 unit
+- 记录当前绑定缓存
+- 在释放时做对应解绑
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLTextureUnitAllocator()](Constructor.md) | 构造对象。 |
-| [~OpenGLTextureUnitAllocator()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
-| [Free](Free.md) | 公开方法，详见头文件声明。 |
-| [BindTexture](BindTexture.md) | 公开方法，详见头文件声明。 |
-| [UnbindTexture](UnbindTexture.md) | 公开方法，详见头文件声明。 |
-| [GetBoundTexture](GetBoundTexture.md) | 获取相关状态或对象。 |
-| [IsAllocated](IsAllocated.md) | 查询当前状态。 |
-| [GetMaxUnits](GetMaxUnits.md) | 获取相关状态或对象。 |
+它不是一个完整的资源绑定系统，而是一个非常基础的槽位管理器。真正使用它的通常是:
+
+- `OpenGLResourceView` 的 UAV 路径
+- `OpenGLDescriptorSet` 的 SRV / UAV / sampler 绑定准备流程
+
+这种设计在商业引擎里也常见: 先把“后端稀缺槽位管理”独立出来，再由更高层的 descriptor / pipeline 系统消费。
+
+## 生命周期
+
+- 构造后为空。
+- [Initialize](Initialize.md) 设置容量。
+- [Allocate](Allocate.md) / [Free](Free.md) 管理槽位。
+- [Shutdown](Shutdown.md) 释放所有已分配槽位并清空缓存。
+
+## 线程语义
+
+- 无锁。
+- 涉及 OpenGL 绑定状态和活动纹理单元切换，应在持有当前上下文的线程使用。
+
+## 当前实现的真实行为
+
+- 采用线性 first-fit 分配策略。
+- 绑定和解绑都会调用 `glActiveTexture()`，但不会恢复之前的活动纹理单元。
+- `GetBoundTexture()` 只是分配器内部缓存，不是实际 GL 状态查询。
+- 解绑逻辑固定使用 `GL_TEXTURE_2D` 清空当前 unit，这对非 2D 目标来说是简化实现。
+
+## 当前限制
+
+- 没有引用计数或多方共享语义。
+- 没有检测 OpenGL 真实最大纹理单元数。
+- 重复 `Initialize()` 不是完全安全的“重置”路径。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [Allocate](Allocate.md)
+- [BindTexture](BindTexture.md)
+- [Free](Free.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
+- [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/Shutdown.md

@@ -1,30 +1,20 @@
 # OpenGLTextureUnitAllocator::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放所有已分配 texture unit，并清空分配器内部状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::Shutdown(...)。
-    (void)object;
-}
-```
+- 遍历 `[0, m_maxUnits)`。
+- 对每个已分配槽位调用 [Free](Free.md)。
+- 然后清空 `m_allocated`、`m_boundTextures`，并把 `m_maxUnits` 设为 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [Free](Free.md)
+- [Destructor](Destructor.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator/UnbindTexture.md

@@ -1,31 +1,26 @@
 # OpenGLTextureUnitAllocator::UnbindTexture
 
-公开方法，详见头文件声明。
-
 ```cpp
 void UnbindTexture(int32_t unit);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h`，当前页面用于固定 `OpenGLTextureUnitAllocator` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `unit` - 参数语义详见头文件声明。
+从指定纹理单元解绑纹理，并清空本地缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 非法 `unit` 直接返回。
+- 调用 `glActiveTexture(GL_TEXTURE0 + unit)`。
+- 固定执行 `glBindTexture(GL_TEXTURE_2D, 0)`。
+- 把 `m_boundTextures[unit]` 设为 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTextureUnitAllocator.h>
+## 重要限制
 
-void Example() {
-    XCEngine::RHI::OpenGLTextureUnitAllocator object;
-    // 根据上下文补齐参数后调用 OpenGLTextureUnitAllocator::UnbindTexture(...)。
-    (void)object;
-}
-```
+- 不会恢复之前的 active texture unit。
+- 解绑目标写死为 `GL_TEXTURE_2D`，并不覆盖所有纹理类型。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTextureUnitAllocator.md)
-- [返回模块目录](../OpenGL.md)
+- [BindTexture](BindTexture.md)
+- [Free](Free.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/Allocate.md

@@ -1,30 +1,24 @@
 # OpenGLUniformBufferManager::Allocate
 
-公开方法，详见头文件声明。
-
 ```cpp
 int32_t Allocate();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+分配一个可用的 uniform buffer binding point。
 
-**返回：** `int32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 成功时返回第一个空闲绑定点。
+- 没有空闲槽位时返回 `-1`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::Allocate(...)。
-    (void)object;
-}
-```
+- 采用线性 first-fit 扫描。
+- 找到空闲槽位后立刻把 `m_allocated[i]` 标记为 `true`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Free](Free.md)
+- [IsAllocated](IsAllocated.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/BindBuffer.md

@@ -1,34 +1,33 @@
 # OpenGLUniformBufferManager::BindBuffer
 
-公开方法，详见头文件声明。
-
 ```cpp
 void BindBuffer(int32_t bindingPoint, OpenGLBuffer* buffer, uint32_t offset = 0, uint32_t size = 0);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `bindingPoint` - 参数语义详见头文件声明。
-- `buffer` - 参数语义详见头文件声明。
-- `offset` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
+把缓冲区绑定到指定 uniform buffer binding point。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `bindingPoint`: 目标绑定点。
+- `buffer`: 需要绑定的缓冲区；可为空。
+- `offset`: 预留的偏移参数。
+- `size`: 预留的大小参数。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::BindBuffer(...)。
-    (void)object;
-}
-```
+- 非法 `bindingPoint` 直接返回。
+- 如果 `buffer` 非空，执行 `glBindBufferBase(GL_UNIFORM_BUFFER, bindingPoint, buffer->GetID())`。
+- 否则把该绑定点清空为 `0`。
+- 更新 `m_boundBuffers[bindingPoint]` 缓存。
+
+## 重要限制
+
+- 当前实现完全忽略 `offset` 和 `size`。
+- 这不是 `glBindBufferRange()` 语义，而是“整块 UBO 绑定”。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [UnbindBuffer](UnbindBuffer.md)
+- [GetBoundBuffer](GetBoundBuffer.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/Constructor.md

@@ -1,28 +1,18 @@
-# OpenGLUniformBufferManager::OpenGLUniformBufferManager()
-
-构造对象。
+# OpenGLUniformBufferManager::OpenGLUniformBufferManager
 
 ```cpp
 OpenGLUniformBufferManager();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 UBO 绑定点管理器。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-}
-```
+- 仅把 `m_maxBindingPoints` 初始化为 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [OpenGLUniformBufferManager](OpenGLUniformBufferManager.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/Destructor.md

@@ -1,29 +1,18 @@
-# OpenGLUniformBufferManager::~OpenGLUniformBufferManager()
-
-销毁对象并释放相关资源。
+# OpenGLUniformBufferManager::~OpenGLUniformBufferManager
 
 ```cpp
 ~OpenGLUniformBufferManager();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁管理器并释放所有已分配绑定点。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/Free.md

@@ -1,31 +1,20 @@
 # OpenGLUniformBufferManager::Free
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Free(int32_t bindingPoint);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `bindingPoint` - 参数语义详见头文件声明。
+释放一个先前分配的 UBO 绑定点。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::Free(...)。
-    (void)object;
-}
-```
+- 非法 `bindingPoint` 直接返回。
+- 调用 [UnbindBuffer](UnbindBuffer.md) 清空实际绑定和缓存。
+- 把 `m_allocated[bindingPoint]` 设为 `false`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Allocate](Allocate.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/GetBoundBuffer.md

@@ -1,31 +1,23 @@
 # OpenGLUniformBufferManager::GetBoundBuffer
 
-获取相关状态或对象。
-
 ```cpp
 OpenGLBuffer* GetBoundBuffer(int32_t bindingPoint) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `bindingPoint` - 参数语义详见头文件声明。
+返回管理器缓存中记录的已绑定缓冲区。
 
-**返回：** `OpenGLBuffer*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 合法绑定点返回缓存的 `OpenGLBuffer*`。
+- 非法绑定点返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::GetBoundBuffer(...)。
-    (void)object;
-}
-```
+- 这是本地缓存查询，不会去问 OpenGL 当前真实绑定状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [BindBuffer](BindBuffer.md)
+- [IsAllocated](IsAllocated.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/GetMaxBindingPoints.md

@@ -1,30 +1,19 @@
 # OpenGLUniformBufferManager::GetMaxBindingPoints
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetMaxBindingPoints() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回管理器当前配置的最大绑定点数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::GetMaxBindingPoints(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_maxBindingPoints`。
+- `Shutdown()` 后会回到 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/Initialize.md

@@ -1,31 +1,28 @@
 # OpenGLUniformBufferManager::Initialize
 
-初始化内部状态。
-
 ```cpp
 void Initialize(uint32_t maxBindingPoints = 16);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `maxBindingPoints` - 参数语义详见头文件声明。
+初始化 UBO 绑定点管理器的容量。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `maxBindingPoints`: 可管理的绑定点数量，默认 `16`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::Initialize(...)。
-    (void)object;
-}
-```
+- 把 `m_maxBindingPoints` 设为 `maxBindingPoints`。
+- 调用 `resize(maxBindingPoints, false)` 初始化分配标记。
+- 调用 `resize(maxBindingPoints, nullptr)` 初始化绑定缓存。
+
+## 重要限制
+
+- 和 `OpenGLTextureUnitAllocator` 一样，重复 `Initialize()` 而不先 `Shutdown()` 不能保证完全清空旧状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [GetMaxBindingPoints](GetMaxBindingPoints.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/IsAllocated.md

@@ -1,31 +1,19 @@
 # OpenGLUniformBufferManager::IsAllocated
 
-查询当前状态。
-
 ```cpp
 bool IsAllocated(int32_t bindingPoint) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `bindingPoint` - 参数语义详见头文件声明。
+检查指定绑定点是否已被分配。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::IsAllocated(...)。
-    (void)object;
-}
-```
+- 非法索引返回 `false`。
+- 合法索引直接返回 `m_allocated[bindingPoint]`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Allocate](Allocate.md)
+- [Free](Free.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/OpenGLUniformBufferManager.md

@@ -6,35 +6,63 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLUniformBufferManager` public API。
+**描述**: OpenGL 后端的 uniform buffer 绑定点管理器，负责槽位分配、整块 UBO 绑定和本地缓存维护。
 
-## 概述
+## 概览
 
-`OpenGLUniformBufferManager.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+在统一 RHI 语义里，常量缓冲视图看起来像独立的 CBV；但在当前 OpenGL 后端里，这件事最终仍然要落到 uniform buffer binding point。
 
-## 声明概览
+`OpenGLUniformBufferManager` 的职责就是管理这些绑定点:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLUniformBufferManager` | `class` | 头文件中的公开声明。 |
+- 分配和释放 binding point
+- 把某个 `OpenGLBuffer` 绑定到指定槽位
+- 缓存当前绑定关系，供其他后端封装读取
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLUniformBufferManager()](Constructor.md) | 构造对象。 |
-| [~OpenGLUniformBufferManager()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
-| [Free](Free.md) | 公开方法，详见头文件声明。 |
-| [BindBuffer](BindBuffer.md) | 公开方法，详见头文件声明。 |
-| [UnbindBuffer](UnbindBuffer.md) | 公开方法，详见头文件声明。 |
-| [GetBoundBuffer](GetBoundBuffer.md) | 获取相关状态或对象。 |
-| [IsAllocated](IsAllocated.md) | 查询当前状态。 |
-| [GetMaxBindingPoints](GetMaxBindingPoints.md) | 获取相关状态或对象。 |
+它和 `OpenGLTextureUnitAllocator` 属于同一层级的基础设施:
+
+- 本身不代表高层 descriptor
+- 本身也不管理 buffer 生命周期
+- 只是把稀缺的后端绑定点做成可复用服务
+
+对于商业引擎式的 RHI 文档来说，关键不是把它包装成“更高级”的东西，而是把它当前真的只做到哪一步说清楚。
+
+## 生命周期
+
+- 构造后为空。
+- [Initialize](Initialize.md) 设置容量。
+- [Allocate](Allocate.md) / [Free](Free.md) 管理 binding point。
+- [Shutdown](Shutdown.md) 释放所有已分配槽位并清空缓存。
+
+## 线程语义
+
+- 无锁。
+- 依赖 OpenGL 上下文，应在渲染线程或拥有上下文的线程使用。
+
+## 当前实现的真实行为
+
+- 使用线性 first-fit 分配策略。
+- [BindBuffer](BindBuffer.md) 固定使用 `glBindBufferBase()`，不会做范围绑定。
+- `GetBoundBuffer()` 只是本地缓存查询。
+- `OpenGLResourceView::InitializeAsConstantBuffer()` 会通过它分配绑定点。
+
+## 当前限制
+
+- 不支持 offset / size 范围绑定。
+- 没有同步验证 OpenGL 真实支持的最大 UBO 绑定点数量。
+- 重复 `Initialize()` 不是可靠的重置流程。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [Allocate](Allocate.md)
+- [BindBuffer](BindBuffer.md)
+- [Free](Free.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
+- [OpenGLBuffer](../OpenGLBuffer/OpenGLBuffer.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/Shutdown.md

@@ -1,30 +1,20 @@
 # OpenGLUniformBufferManager::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放所有已分配 UBO 绑定点，并清空内部缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::Shutdown(...)。
-    (void)object;
-}
-```
+- 遍历所有绑定点。
+- 对每个已分配槽位调用 [Free](Free.md)。
+- 随后清空 `m_allocated` 和 `m_boundBuffers`，并把 `m_maxBindingPoints` 设为 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [Free](Free.md)
+- [Destructor](Destructor.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLUniformBufferManager/UnbindBuffer.md

@@ -1,31 +1,20 @@
 # OpenGLUniformBufferManager::UnbindBuffer
 
-公开方法，详见头文件声明。
-
 ```cpp
 void UnbindBuffer(int32_t bindingPoint);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h`，当前页面用于固定 `OpenGLUniformBufferManager` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `bindingPoint` - 参数语义详见头文件声明。
+从指定 binding point 解绑 UBO，并清空本地缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLUniformBufferManager.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLUniformBufferManager object;
-    // 根据上下文补齐参数后调用 OpenGLUniformBufferManager::UnbindBuffer(...)。
-    (void)object;
-}
-```
+- 非法 `bindingPoint` 直接返回。
+- 调用 `glBindBufferBase(GL_UNIFORM_BUFFER, bindingPoint, 0)`。
+- 把 `m_boundBuffers[bindingPoint]` 设为 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLUniformBufferManager.md)
-- [返回模块目录](../OpenGL.md)
+- [BindBuffer](BindBuffer.md)
+- [Free](Free.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/AddVertexBuffer.md

@@ -1,32 +1,33 @@
 # OpenGLVertexArray::AddVertexBuffer
 
-添加元素或建立关联。
-
 ```cpp
 void AddVertexBuffer(unsigned int buffer, const VertexAttribute& attribute);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffer` - 参数语义详见头文件声明。
-- `attribute` - 参数语义详见头文件声明。
+把一个顶点缓冲及其属性描述写入当前 VAO。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `buffer`: 顶点缓冲对象 id。
+- `attribute`: 顶点属性描述，包含 attribute index、分量数、类型、是否归一化、步长和偏移。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::AddVertexBuffer(...)。
-    (void)object;
-}
-```
+- 绑定当前 VAO。
+- 绑定 `buffer` 到 `GL_ARRAY_BUFFER`。
+- 调用 `glEnableVertexAttribArray(attribute.index)`。
+- 通过 `glVertexAttribPointer()` 写入属性格式。
+- 随后解绑 `GL_ARRAY_BUFFER` 和 VAO。
+- 把 `m_vertexBufferCount` 自增 1。
+
+## 重要限制
+
+- 当前实现无论属性类型是否为整数或双精度，都统一走 `glVertexAttribPointer()`，没有使用 `glVertexAttribIPointer()` 或 `glVertexAttribLPointer()`。
+- 这意味着某些非浮点属性路径在语义上是简化实现。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/Bind.md

@@ -1,30 +1,19 @@
 # OpenGLVertexArray::Bind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Bind() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+绑定当前 VAO。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::Bind(...)。
-    (void)object;
-}
-```
+- 直接执行 `glBindVertexArray(m_vao)`。
+- 不检查 `m_vao` 是否有效。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [Unbind](Unbind.md)
+- [GetID](GetID.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/Constructor.md

@@ -1,28 +1,22 @@
-# OpenGLVertexArray::OpenGLVertexArray()
-
-构造对象。
+# OpenGLVertexArray::OpenGLVertexArray
 
 ```cpp
 OpenGLVertexArray();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 VAO 封装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-}
-```
+- 初始化默认值:
+  - `m_vao = 0`
+  - `m_indexBuffer = 0`
+  - `m_indexCount = 0`
+  - `m_vertexBufferCount = 0`
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [OpenGLVertexArray](OpenGLVertexArray.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/Destructor.md

@@ -1,29 +1,19 @@
-# OpenGLVertexArray::~OpenGLVertexArray()
-
-销毁对象并释放相关资源。
+# OpenGLVertexArray::~OpenGLVertexArray
 
 ```cpp
 ~OpenGLVertexArray();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象并删除底层 VAO。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
+- 只负责删除 VAO，不负责删除顶点缓冲或索引缓冲。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [SetIndexBuffer](SetIndexBuffer.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/GetID.md

@@ -1,30 +1,19 @@
 # OpenGLVertexArray::GetID
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetID() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 VAO id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::GetID(...)。
-    (void)object;
-}
-```
+- 初始化成功后通常为非零值。
+- 构造后或 `Shutdown()` 之后返回 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/GetIndexBuffer.md

@@ -1,30 +1,23 @@
 # OpenGLVertexArray::GetIndexBuffer
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetIndexBuffer() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前记录的索引缓冲 id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 该值仅在 [SetIndexBuffer](SetIndexBuffer.md) 时更新。
+- `Shutdown()` 不会把它重置回 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::GetIndexBuffer(...)。
-    (void)object;
-}
-```
+- 它表示“上次通过该封装记录的索引缓冲”，不是对 OpenGL 当前绑定状态的实时查询。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [SetIndexBuffer](SetIndexBuffer.md)
+- [GetIndexCount](GetIndexCount.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/GetIndexCount.md

@@ -1,30 +1,24 @@
 # OpenGLVertexArray::GetIndexCount
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetIndexCount() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前记录的索引数量。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 当前实现始终返回成员 `m_indexCount`。
+- 但源码中没有任何地方更新这个成员，因此它默认保持为 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::GetIndexCount(...)。
-    (void)object;
-}
-```
+- 不要把它当作可靠的绘制索引数量来源。
+- 实际绘制计数需要由上层 draw 调用参数或资源描述维护。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [SetIndexBuffer](SetIndexBuffer.md)
+- [OpenGLVertexArray](OpenGLVertexArray.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/Initialize.md

@@ -1,30 +1,23 @@
 # OpenGLVertexArray::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+创建一个底层 OpenGL vertex array object。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 当前实现恒定返回 `true`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::Initialize(...)。
-    (void)object;
-}
-```
+- 调用 `glGenVertexArrays(1, &m_vao)`。
+- 不检查返回结果，也不验证生成的 id 是否为非零。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [AddVertexBuffer](AddVertexBuffer.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/OpenGLVertexArray.md

@@ -6,38 +6,63 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLVertexArray` public API。
+**描述**: OpenGL 后端的轻量 VAO 封装，用于保存顶点属性布局和索引缓冲绑定。
 
-## 概述
+## 概览
 
-`OpenGLVertexArray.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`OpenGLVertexArray` 是一个相对旧式、直接的 OpenGL 工具封装。它做的事情很简单:
 
-## 声明概览
+- 创建一个 VAO
+- 把顶点属性描述写入这个 VAO
+- 记录一个索引缓冲绑定
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `VertexAttributeType` | `enum class` | 头文件中的公开声明。 |
-| `VertexAttributeNormalized` | `enum class` | 头文件中的公开声明。 |
-| `VertexAttribute` | `struct` | 头文件中的公开声明。 |
-| `OpenGLVertexArray` | `class` | 头文件中的公开声明。 |
+它并不尝试成为完整的跨后端输入布局系统。更现代的路径已经更多依赖 `OpenGLCommandList` 和 pipeline / input layout 的组合去驱动属性配置。
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLVertexArray()](Constructor.md) | 构造对象。 |
-| [~OpenGLVertexArray()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [AddVertexBuffer](AddVertexBuffer.md) | 添加元素或建立关联。 |
-| [SetIndexBuffer](SetIndexBuffer.md) | 设置相关状态或配置。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
-| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
-| [GetID](GetID.md) | 获取相关状态或对象。 |
-| [GetIndexBuffer](GetIndexBuffer.md) | 获取相关状态或对象。 |
-| [GetIndexCount](GetIndexCount.md) | 获取相关状态或对象。 |
+可以把它看成“对原生 VAO 的薄封装”，适合:
+
+- 单元测试
+- OpenGL 集成样例
+- 较直接的后端实验代码
+
+但它不是一个高度完备的商业级输入装配抽象，当前实现里仍有明显的简化点。
+
+## 生命周期
+
+- 构造后为空对象。
+- [Initialize](Initialize.md) 创建原生 VAO。
+- [AddVertexBuffer](AddVertexBuffer.md) / [SetIndexBuffer](SetIndexBuffer.md) 向 VAO 写入状态。
+- [Shutdown](Shutdown.md) 删除 VAO。
+
+## 线程语义
+
+- 无锁。
+- 所有操作依赖 OpenGL 上下文，应在渲染线程或拥有当前上下文的线程执行。
+
+## 当前实现的真实行为
+
+- `AddVertexBuffer()` 总是用 `glVertexAttribPointer()` 写属性。
+- `SetIndexBuffer()` 会绑定 `GL_ELEMENT_ARRAY_BUFFER`，但 `type` 参数当前被忽略。
+- `m_indexCount` 从未被更新，因此 [GetIndexCount](GetIndexCount.md) 目前基本没有实际意义。
+- `Shutdown()` 只删除 VAO，不清理缓存的索引缓冲字段。
+- 单元测试 `tests/RHI/OpenGL/unit/test_vertex_array.cpp` 覆盖了初始化、顶点缓冲添加、索引缓冲设置、绑定/解绑和多属性场景。
+
+## 当前限制
+
+- 不区分整数属性和浮点属性写入路径。
+- 不维护真实索引数量。
+- 不是当前 RHI 输入布局路径的唯一或最终方案。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [AddVertexBuffer](AddVertexBuffer.md)
+- [SetIndexBuffer](SetIndexBuffer.md)
+- [Bind](Bind.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/SetIndexBuffer.md

@@ -1,32 +1,31 @@
 # OpenGLVertexArray::SetIndexBuffer
 
-设置相关状态或配置。
-
 ```cpp
 void SetIndexBuffer(unsigned int buffer, unsigned int type);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffer` - 参数语义详见头文件声明。
-- `type` - 参数语义详见头文件声明。
+把一个索引缓冲绑定到当前 VAO。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `buffer`: 索引缓冲对象 id。
+- `type`: 索引类型参数。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::SetIndexBuffer(...)。
-    (void)object;
-}
-```
+- 绑定当前 VAO。
+- 把 `buffer` 绑定到 `GL_ELEMENT_ARRAY_BUFFER`。
+- 解绑 VAO。
+- 保存 `m_indexBuffer = buffer`。
+
+## 重要限制
+
+- `type` 参数当前完全没有被使用。
+- 该函数也不会更新 `m_indexCount`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [GetIndexBuffer](GetIndexBuffer.md)
+- [GetIndexCount](GetIndexCount.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/Shutdown.md

@@ -1,30 +1,24 @@
 # OpenGLVertexArray::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+删除底层 VAO。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_vao != 0`，调用 `glDeleteVertexArrays(1, &m_vao)`。
+- 然后把 `m_vao` 设为 `0`。
+- 不会重置 `m_indexBuffer`、`m_indexCount` 或 `m_vertexBufferCount`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::Shutdown(...)。
-    (void)object;
-}
-```
+- 如果你需要“完全复位”的对象状态，建议重新构造对象，而不是复用 `Shutdown()` 之后的实例。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [GetID](GetID.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLVertexArray/Unbind.md

@@ -1,30 +1,18 @@
 # OpenGLVertexArray::Unbind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Unbind() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLVertexArray.h`，当前页面用于固定 `OpenGLVertexArray` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+解绑当前 VAO，恢复到默认 VAO `0`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLVertexArray.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLVertexArray object;
-    // 根据上下文补齐参数后调用 OpenGLVertexArray::Unbind(...)。
-    (void)object;
-}
-```
+- 直接执行 `glBindVertexArray(0)`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLVertexArray.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [Shutdown](Shutdown.md)

docs/api/_meta/rebuild-status.md

@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-27 23:33:00`
+**生成时间**: `2026-03-27 23:42:53`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`