diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Bind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Bind.md
index 96716bf5..b63cbd9e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Bind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Bind.md
@@ -1,30 +1,28 @@
-# OpenGLBuffer::Bind
-
-公开方法，详见头文件声明。
+# OpenGLBuffer::Bind()
 
 ```cpp
 void Bind() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前 buffer 绑定到由 [GetType](GetType.md) 决定的 OpenGL target。
 
-**返回：** `void` - 无返回值。
-
-**示例：**
+## 当前实现行为
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::Bind(...)。
-    (void)object;
-}
+unsigned int target = ToOpenGL(m_type);
+glBindBuffer(target, m_buffer);
 ```
 
+## 需要注意
+
+- 绑定目标只取决于 `m_type`，与 [GetBufferType](GetBufferType.md) 无关。
+- 不会检查 `m_buffer` 是否为 `0`。
+- 不会验证当前上下文状态。
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Unbind](Unbind.md)
+- [GetType](GetType.md)
+- [BindBase](BindBase.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/BindBase.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/BindBase.md
index 8db9cceb..25604dff 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/BindBase.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/BindBase.md
@@ -1,32 +1,35 @@
-# OpenGLBuffer::BindBase
-
-公开方法，详见头文件声明。
+# OpenGLBuffer::BindBase()
 
 ```cpp
 void BindBase(unsigned int target, unsigned int index) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `target` - 参数语义详见头文件声明。
-- `index` - 参数语义详见头文件声明。
+把当前 buffer 绑定到某个 indexed binding point。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `target`: OpenGL 的 indexed target，例如 `GL_UNIFORM_BUFFER`、`GL_SHADER_STORAGE_BUFFER`、`GL_ATOMIC_COUNTER_BUFFER`。
+- `index`: 目标 binding point 索引。
+
+## 当前实现行为
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::BindBase(...)。
-    (void)object;
-}
+glBindBufferBase(target, index, m_buffer);
 ```
 
+## 关键区别
+
+和 [Bind](Bind.md) 不同，这个函数不会根据 `m_type` 自动决定 target，而是完全信任调用方传入的 `target`。
+
+这意味着:
+
+- 你可以把一个以某种 `OpenGLBufferType` 初始化的对象，绑定到另一个兼容的 indexed target。
+- 也意味着如果传入了不匹配或不合法的 target，函数不会提前阻止你。
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [GetType](GetType.md)
+- [GetBufferType](GetBufferType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Constructor.md
index 83759032..c71f7905 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Constructor.md
@@ -1,28 +1,33 @@
 # OpenGLBuffer::OpenGLBuffer()
 
-构造对象。
-
 ```cpp
 OpenGLBuffer();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个尚未持有原生 OpenGL buffer 的对象。
 
-**返回：** `void` - 无返回值。
+## 初始状态
 
-**示例：**
+构造函数会把成员初始化为:
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+- `m_buffer = 0`
+- `m_size = 0`
+- `m_isIndexBuffer = false`
+- `m_dynamic = false`
+- `m_type = OpenGLBufferType::Vertex`
+- `m_bufferType = BufferType::Vertex`
+- `m_stride = 0`
+- `m_name = ""`
+- `m_state = ResourceStates::Common`
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-}
-```
+## 需要注意
+
+这里的默认值更多是“安全起点”和“占位元数据”，并不代表对象已经是一个可用的顶点缓冲。真正的 OpenGL buffer 只有在 [Initialize](Initialize.md) 成功后才会生成。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Shutdown](Shutdown.md)
+- [~OpenGLBuffer()](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Destructor.md
index 3a80e338..15fee8bf 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Destructor.md
@@ -1,29 +1,28 @@
 # OpenGLBuffer::~OpenGLBuffer()
 
-销毁对象并释放相关资源。
-
 ```cpp
 ~OpenGLBuffer() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+析构对象，并释放当前持有的 OpenGL buffer。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+析构函数只做一件事:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 对象离开作用域时会自动触发析构。
-}
+Shutdown();
 ```
 
+这意味着:
+
+- 如果 `m_buffer != 0`，析构会删除该原生 buffer。
+- 初始化失败后若对象依然持有已创建的 buffer，析构也会负责最终清理。
+- 除 `m_buffer` 之外的其他元数据不会在析构前被额外处理。
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [OpenGLBuffer()](Constructor.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetBufferType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetBufferType.md
index 5cff0658..3de9f68d 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetBufferType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetBufferType.md
@@ -1,30 +1,20 @@
-# OpenGLBuffer::GetBufferType
-
-获取相关状态或对象。
+# OpenGLBuffer::GetBufferType()
 
 ```cpp
 BufferType GetBufferType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的跨后端 RHI 逻辑 buffer 类型。
 
-**返回：** `BufferType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetBufferType(...)。
-    (void)object;
-}
-```
+- 默认值来自构造函数中的 `BufferType::Vertex`。
+- [Initialize](Initialize.md) 不会自动根据 `OpenGLBufferType` 改写它。
+- 它主要是给上层渲染框架和跨后端逻辑读的元数据。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [SetBufferType](SetBufferType.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetID.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetID.md
index 6ac571f8..04ddcc1a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetID.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetID.md
@@ -1,30 +1,18 @@
-# OpenGLBuffer::GetID
-
-获取相关状态或对象。
+# OpenGLBuffer::GetID()
 
 ```cpp
 unsigned int GetID() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前原生 OpenGL buffer 对象 ID。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetID(...)。
-    (void)object;
-}
-```
+- `m_buffer`
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetName.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetName.md
index 63525097..e81eae63 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetName.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetName.md
@@ -1,30 +1,18 @@
-# OpenGLBuffer::GetName
-
-获取相关状态或对象。
+# OpenGLBuffer::GetName()
 
 ```cpp
 const std::string& GetName() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的调试名称。
 
-**返回：** `const std::string&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetName(...)。
-    (void)object;
-}
-```
+- 默认值为空字符串。
+- 它只是引擎侧元数据，不会自动映射到 `glObjectLabel()`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [SetName](SetName.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetNativeHandle.md
index c016dd9d..90607059 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetNativeHandle.md
@@ -1,30 +1,25 @@
-# OpenGLBuffer::GetNativeHandle
-
-获取相关状态或对象。
+# OpenGLBuffer::GetNativeHandle()
 
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以通用句柄形式返回原生 buffer ID。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+实现会把 `m_buffer` 转成 `uintptr_t`，再转成 `void*`:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetNativeHandle(...)。
-    (void)object;
-}
+return reinterpret_cast<void*>(static_cast<uintptr_t>(m_buffer));
 ```
 
+## 需要注意
+
+它本质上仍然只是一个整数 ID 的包装，不是可解引用指针。
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetID](GetID.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetSize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetSize.md
index efe53848..e1e75591 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetSize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetSize.md
@@ -1,30 +1,18 @@
-# OpenGLBuffer::GetSize
-
-获取相关状态或对象。
+# OpenGLBuffer::GetSize()
 
 ```cpp
 uint64_t GetSize() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回对象内部缓存的 buffer 大小，单位为字节。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetSize(...)。
-    (void)object;
-}
-```
+这个值来自最近一次 [Initialize](Initialize.md) 时写入的 `m_size`。后续 [SetData](SetData.md) 不会重新计算或同步它。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [SetData](SetData.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetState.md
index 70a5ab5c..45bb7f25 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetState.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetState.md
@@ -1,30 +1,19 @@
-# OpenGLBuffer::GetState
-
-获取相关状态或对象。
+# OpenGLBuffer::GetState()
 
 ```cpp
 ResourceStates GetState() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的软状态元数据。
 
-**返回：** `ResourceStates` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetState(...)。
-    (void)object;
-}
-```
+- 默认值为 `ResourceStates::Common`。
+- 这个状态不会自动和任何 OpenGL barrier、绑定点或驱动状态同步。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [SetState](SetState.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetStride.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetStride.md
index 05c4df2a..dade3a4f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetStride.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetStride.md
@@ -1,30 +1,20 @@
-# OpenGLBuffer::GetStride
-
-获取相关状态或对象。
+# OpenGLBuffer::GetStride()
 
 ```cpp
 uint32_t GetStride() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的步长元数据。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetStride(...)。
-    (void)object;
-}
-```
+- 该值默认是 `0`。
+- 初始化 buffer 时不会自动根据数据格式推导。
+- 它通常由更上层的网格、资源视图或输入布局构建代码设置。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [SetStride](SetStride.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetType.md
index 97331e07..55f1137b 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/GetType.md
@@ -1,30 +1,25 @@
-# OpenGLBuffer::GetType
-
-获取相关状态或对象。
+# OpenGLBuffer::GetType()
 
 ```cpp
 OpenGLBufferType GetType() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象记录的 OpenGL 目标类型。
 
-**返回：** `OpenGLBufferType` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `m_type`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 与 `GetBufferType()` 的区别
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::GetType(...)。
-    (void)object;
-}
-```
+- `GetType()` 表示“这个对象主要按哪个 OpenGL target 使用”。
+- [GetBufferType](GetBufferType.md) 表示“跨后端 RHI 视角下，它被标记成什么逻辑 buffer 类型”。
+
+这两个值可能一致，也可能由调用方故意分开维护。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetBufferType](GetBufferType.md)
+- [Bind](Bind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Initialize.md
index 74831cce..dd76ed4b 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Initialize.md
@@ -1,34 +1,51 @@
-# OpenGLBuffer::Initialize
-
-初始化内部状态。
+# OpenGLBuffer::Initialize()
 
 ```cpp
 bool Initialize(OpenGLBufferType type, size_t size, const void* data = nullptr, bool dynamic = false);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `type` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
-- `data` - 参数语义详见头文件声明。
-- `dynamic` - 参数语义详见头文件声明。
+创建一个指定类型的 OpenGL buffer，并可选上传初始数据。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `type`: buffer 的主要 OpenGL 用途类型。
+- `size`: 分配的字节数。
+- `data`: 初始数据指针；传入 `nullptr` 时只分配存储。
+- `dynamic`: 是否使用动态用法提示。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::Initialize(...)。
-    (void)object;
-}
-```
+当前实现始终返回 `true`。
+
+## 当前实现行为
+
+函数会按以下顺序执行:
+
+1. 写入 `m_type`、`m_size`、`m_dynamic`。
+2. 根据 `type == OpenGLBufferType::Index` 设置 `m_isIndexBuffer`。
+3. 通过 `ToOpenGL(type)` 选择目标绑定点。
+4. 根据 `dynamic` 选择 `GL_DYNAMIC_DRAW` 或 `GL_STATIC_DRAW`。
+5. 调用 `glGenBuffers()` 创建 `m_buffer`。
+6. 绑定目标。
+7. 调用 `glBufferData(target, size, data, usage)` 分配并上传数据。
+8. 解绑目标。
+
+## 重要限制
+
+- 没有显式错误检查，也不会因为 `glGetError()` 或其他失败信号返回 `false`。
+- 不会自动设置 `m_bufferType`、`m_stride`、`m_name`、`m_state`。
+- 不会检查当前 OpenGL 上下文是否已经正确激活。
+- `dynamic` 只影响 usage hint，不会改变后续 [Map](Map.md) 或 [SetData](SetData.md) 的具体 API 选择。
+
+## 设计说明
+
+显式 API 里，buffer 的用途往往会细分为 usage、memory type、bind flags、state 等多个维度。OpenGL 把这些概念压缩得更扁平，所以 `Initialize()` 只能先选择一个主要 target 和一个 usage hint，其余跨后端语义要靠额外元数据补齐。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeVertexBuffer](InitializeVertexBuffer.md)
+- [InitializeIndexBuffer](InitializeIndexBuffer.md)
+- [GetType](GetType.md)
+- [IsDynamic](IsDynamic.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeIndexBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeIndexBuffer.md
index 2b9dcd3f..c1244ad8 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeIndexBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeIndexBuffer.md
@@ -1,32 +1,40 @@
-# OpenGLBuffer::InitializeIndexBuffer
-
-初始化内部状态。
+# OpenGLBuffer::InitializeIndexBuffer()
 
 ```cpp
 bool InitializeIndexBuffer(const void* data, size_t size);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `data` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
+使用“索引缓冲”预设快速初始化当前对象。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `data`: 初始索引数据。
+- `size`: 数据总字节数。
+
+## 返回值
+
+转调 [Initialize](Initialize.md) 的返回值。当前实现始终为 `true`。
+
+## 当前实现行为
+
+函数等价于:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::InitializeIndexBuffer(...)。
-    (void)object;
-}
+return Initialize(OpenGLBufferType::Index, size, data, false);
 ```
 
+这会带来两个直接效果:
+
+- `m_type` 变为 `OpenGLBufferType::Index`
+- `m_isIndexBuffer` 被设置为 `true`
+
+## 需要注意
+
+这里并不会自动推导索引格式。引擎里真正决定 `glDrawElements*` 使用哪种 index type 的，通常是更上层的资源视图或命令列表逻辑，而不是 `OpenGLBuffer` 本身。
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeVertexBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeVertexBuffer.md
index f3fb7c81..e53664ef 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeVertexBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/InitializeVertexBuffer.md
@@ -1,32 +1,38 @@
-# OpenGLBuffer::InitializeVertexBuffer
-
-初始化内部状态。
+# OpenGLBuffer::InitializeVertexBuffer()
 
 ```cpp
 bool InitializeVertexBuffer(const void* data, size_t size);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `data` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
+使用“顶点缓冲”预设快速初始化当前对象。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `data`: 初始顶点数据。
+- `size`: 数据总字节数。
+
+## 返回值
+
+转调 [Initialize](Initialize.md) 的返回值。当前实现始终为 `true`。
+
+## 当前实现行为
+
+函数等价于:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::InitializeVertexBuffer(...)。
-    (void)object;
-}
+return Initialize(OpenGLBufferType::Vertex, size, data, false);
 ```
 
+也就是说:
+
+- `OpenGLBufferType` 固定为 `Vertex`
+- `dynamic` 固定为 `false`
+- 绑定目标固定落到 `GL_ARRAY_BUFFER`
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Bind](Bind.md)
+- [SetStride](SetStride.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/IsDynamic.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/IsDynamic.md
index 2cf69617..a816815c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/IsDynamic.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/IsDynamic.md
@@ -1,30 +1,20 @@
-# OpenGLBuffer::IsDynamic
-
-查询当前状态。
+# OpenGLBuffer::IsDynamic()
 
 ```cpp
 bool IsDynamic() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象是否以动态 usage hint 初始化。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::IsDynamic(...)。
-    (void)object;
-}
-```
+- 这个值只由 [Initialize](Initialize.md) 的 `dynamic` 参数决定。
+- 它不会根据实际更新频率自动变化。
+- 它主要影响初始化和整块 [SetData](SetData.md) 时传入 `glBufferData()` 的 usage 参数。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [SetData](SetData.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Map.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Map.md
index 2018ca58..8cb47e49 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Map.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Map.md
@@ -1,30 +1,38 @@
-# OpenGLBuffer::Map
-
-公开方法，详见头文件声明。
+# OpenGLBuffer::Map()
 
 ```cpp
 void* Map() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前 buffer 映射为 CPU 可写内存，并返回映射指针。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `glMapBuffer()` 返回的原始指针。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::Map(...)。
-    (void)object;
-}
-```
+函数会:
+
+1. 根据 `m_type` 绑定对应 target
+2. 调用 `glMapBuffer(target, GL_WRITE_ONLY)`
+3. 解绑 target
+4. 返回映射结果
+
+## 重要限制
+
+- 当前只支持 `GL_WRITE_ONLY` 映射。
+- 不支持读映射、读写映射、持久映射或显式同步 flag。
+- 不会检查返回值是否为空之外的任何错误条件。
+
+## 工程解读
+
+这是一种非常经典、但也比较基础的 OpenGL 写映射封装。对小型工具和单测足够直接，但对于商业引擎里的高频 streaming buffer 更新，通常还需要更精细的 ring buffer、persistent mapping 或 staging 策略。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Unmap](Unmap.md)
+- [SetData](SetData.md)
+- [IsDynamic](IsDynamic.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/OpenGLBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/OpenGLBuffer.md
index 6dec49f5..0bbd4466 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/OpenGLBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/OpenGLBuffer.md
@@ -6,50 +6,82 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLBuffer.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLBuffer` public API。
+**描述**: OpenGL 后端的通用缓冲区封装，负责创建原生 buffer 对象，并在引擎侧缓存一部分跨后端元数据。
 
-## 概述
+## 概览
 
-`OpenGLBuffer.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`OpenGLBuffer` 是 OpenGL RHI 里最基础的资源包装之一。它做的事情其实很直接:
 
-## 声明概览
+- 按指定 `OpenGLBufferType` 创建一个 OpenGL buffer
+- 记录大小、动态标记和目标类型
+- 提供绑定、映射、更新数据等常见入口
+- 额外缓存 `BufferType`、`stride`、`name`、`state` 这类跨后端元数据
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLBufferType` | `enum class` | 头文件中的公开声明。 |
-| `OpenGLBuffer` | `class` | 继承自 `RHIBuffer` 的公开声明。 |
+从商业引擎的设计视角看，这种“原生对象 + 少量 RHI 元数据”的组合非常常见。原因是底层驱动对象本身只知道“这是一块 buffer”，但上层渲染框架还需要知道它被当作顶点缓冲、索引缓冲、常量缓冲还是别的什么角色来使用。
 
-## 公共方法
+## 设计背景
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLBuffer()](Constructor.md) | 构造对象。 |
-| [~OpenGLBuffer()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [InitializeVertexBuffer](InitializeVertexBuffer.md) | 初始化内部状态。 |
-| [InitializeIndexBuffer](InitializeIndexBuffer.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
-| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
-| [BindBase](BindBase.md) | 公开方法，详见头文件声明。 |
-| [Map](Map.md) | 公开方法，详见头文件声明。 |
-| [Unmap](Unmap.md) | 公开方法，详见头文件声明。 |
-| [SetData](SetData.md) | 设置相关状态或配置。 |
-| [GetID](GetID.md) | 获取相关状态或对象。 |
-| [GetSize](GetSize.md) | 获取相关状态或对象。 |
-| [GetType](GetType.md) | 获取相关状态或对象。 |
-| [IsDynamic](IsDynamic.md) | 查询当前状态。 |
-| [GetBufferType](GetBufferType.md) | 获取相关状态或对象。 |
-| [SetBufferType](SetBufferType.md) | 设置相关状态或配置。 |
-| [GetStride](GetStride.md) | 获取相关状态或对象。 |
-| [SetStride](SetStride.md) | 设置相关状态或配置。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetState](GetState.md) | 获取相关状态或对象。 |
-| [SetState](SetState.md) | 设置相关状态或配置。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
-| [SetName](SetName.md) | 设置相关状态或配置。 |
+现代显式 API 往往把“资源本体”和“如何使用它”拆得更细。例如 D3D12/Vulkan 里 buffer 的用途、状态和 view 往往由更多配套对象共同表达。OpenGL 则更多依赖“把同一个 buffer 绑定到不同 target”来体现用途。
+
+`OpenGLBuffer` 的策略是:
+
+- 用 `OpenGLBufferType` 决定当前 buffer 的主要 OpenGL 绑定目标。
+- 用 `BufferType`、`stride`、`state` 等字段补充跨后端语义。
+
+这样做的好处是接口统一，上层代码比较容易跨后端复用；代价是调用方必须清楚地区分“OpenGL 原生目标”和“RHI 语义元数据”不是同一个概念。
+
+## `OpenGLBufferType` 与绑定目标
+
+当前枚举和 `ToOpenGL(OpenGLBufferType)` 的映射关系如下:
+
+- `Vertex` -> `GL_ARRAY_BUFFER`
+- `Index` -> `GL_ELEMENT_ARRAY_BUFFER`
+- `Uniform` -> `GL_UNIFORM_BUFFER`
+- `CopyRead` -> `GL_COPY_READ_BUFFER`
+- `CopyWrite` -> `GL_COPY_WRITE_BUFFER`
+- `AtomicCounter` -> `GL_ATOMIC_COUNTER_BUFFER`
+- `DispatchIndirect` -> `GL_DISPATCH_INDIRECT_BUFFER`
+- `DrawIndirect` -> `GL_DRAW_INDIRECT_BUFFER`
+- `ShaderBindingTable` -> `GL_SHADER_STORAGE_BUFFER`
+
+最后这一项尤其值得注意: `ShaderBindingTable` 在当前 OpenGL 后端并不对应真正的硬件光追 SBT，而是退化映射到了 `GL_SHADER_STORAGE_BUFFER`。这正是商业级跨后端抽象里常见的做法: 保留统一语义名，但允许某些后端落到“最接近、但不完全等价”的实现。
+
+## 生命周期
+
+- [OpenGLBuffer()](Constructor.md) 构造空对象。
+- [Initialize](Initialize.md) / [InitializeVertexBuffer](InitializeVertexBuffer.md) / [InitializeIndexBuffer](InitializeIndexBuffer.md) 生成原生 buffer 并上传初始数据。
+- [Bind](Bind.md)、[BindBase](BindBase.md)、[Map](Map.md)、[SetData](SetData.md) 在使用阶段操作该 buffer。
+- [Shutdown](Shutdown.md) 删除原生 buffer。
+- [~OpenGLBuffer()](Destructor.md) 析构时自动调用 `Shutdown()`。
+
+## 当前实现的真实行为
+
+- [Initialize](Initialize.md) 当前始终返回 `true`，没有显式错误处理或状态回滚。
+- `m_isIndexBuffer` 会在初始化时根据 `OpenGLBufferType::Index` 设置，但当前没有公开 getter，也没有在其他逻辑里继续参与行为。
+- `m_bufferType`、`m_stride`、`m_name`、`m_state` 都不会在初始化时自动推导，需要调用方自行设置。
+- [Map](Map.md) 固定使用 `GL_WRITE_ONLY`，不支持读映射、持久映射或显式 map flag。
+- [Unmap](Unmap.md) 会调用 `glUnmapBuffer()`，但忽略它的返回值。
+- [SetData](SetData.md) 只有在“整块覆盖且大小等于原始 `m_size`”时才走 `glBufferData()`，否则走 `glBufferSubData()`，不会做越界检查，也不会更新 `m_size`。
+- 单测 `tests/RHI/OpenGL/unit/test_buffer.cpp` 主要覆盖初始化、绑定和写映射路径，没有覆盖复杂错误场景。
+
+## 使用建议
+
+- 如果你的调用逻辑依赖 RHI 侧的 `BufferType`、`stride` 或 `state`，请显式设置，不要假设 `Initialize()` 会自动填好。
+- 如果需要把同一个 buffer 绑定到 indexed target，使用 [BindBase](BindBase.md) 时要明确传入正确的 OpenGL target，函数不会帮你从 `m_type` 推断。
+- 当前不要把 `ShaderBindingTable` 视为真正的 OpenGL ray tracing SBT 支持。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [Bind](Bind.md)
+- [BindBase](BindBase.md)
+- [Map](Map.md)
+- [SetData](SetData.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLEnums](../OpenGLEnums/OpenGLEnums.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
+- [OpenGLVertexArray](../OpenGLVertexArray/OpenGLVertexArray.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetBufferType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetBufferType.md
index 138c9b43..2c5e01ca 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetBufferType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetBufferType.md
@@ -1,31 +1,32 @@
-# OpenGLBuffer::SetBufferType
-
-设置相关状态或配置。
+# OpenGLBuffer::SetBufferType()
 
 ```cpp
 void SetBufferType(BufferType type) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `type` - 参数语义详见头文件声明。
+设置跨后端 RHI 逻辑 buffer 类型元数据。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `type`: 要记录的逻辑类型。
+
+## 当前实现行为
+
+函数只是:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::SetBufferType(...)。
-    (void)object;
-}
+m_bufferType = type;
 ```
 
+它不会:
+
+- 重新创建 OpenGL buffer
+- 修改 `m_type`
+- 自动改变任何绑定或数据上传行为
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetBufferType](GetBufferType.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetData.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetData.md
index 67a12d96..ce2fc10d 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetData.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetData.md
@@ -1,33 +1,41 @@
-# OpenGLBuffer::SetData
-
-设置相关状态或配置。
+# OpenGLBuffer::SetData()
 
 ```cpp
 void SetData(const void* data, size_t size, size_t offset = 0) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `data` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
-- `offset` - 参数语义详见头文件声明。
+更新当前 buffer 的全部或部分内容。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `data`: 源数据指针。
+- `size`: 要写入的字节数。
+- `offset`: 写入偏移。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::SetData(...)。
-    (void)object;
-}
-```
+函数会先绑定目标，然后分两种路径:
+
+- 当 `offset == 0 && size == m_size` 时，调用 `glBufferData(target, size, data, usage)`，相当于整块重建存储。
+- 其他情况调用 `glBufferSubData(target, offset, size, data)`，相当于局部更新。
+
+最后它会解绑目标。
+
+## 重要限制
+
+- 不会检查 `offset + size` 是否越界。
+- 不会在局部更新后修改 `m_size`。
+- 如果传入一个和原始大小不同、但又不是“整块覆盖”的写入请求，函数仍然会走 `glBufferSubData()`，其合法性完全交给驱动。
+- `usage` 依然只取决于最初初始化时的 `m_dynamic`。
+
+## 设计说明
+
+很多引擎会把“重建存储”和“局部上传”明确拆成两个接口，因为它们在性能和资源生命周期上的语义并不相同。当前这里把两条路径折叠到一起，优点是简单，缺点是行为边界需要通过文档讲清楚。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Map](Map.md)
+- [GetSize](GetSize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetName.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetName.md
index a2c7d266..c5dace1c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetName.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetName.md
@@ -1,31 +1,21 @@
-# OpenGLBuffer::SetName
-
-设置相关状态或配置。
+# OpenGLBuffer::SetName()
 
 ```cpp
 void SetName(const std::string& name) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+设置当前对象的调试名称元数据。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `name`: 要缓存的名称。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::SetName(...)。
-    (void)object;
-}
-```
+函数只把字符串保存到 `m_name`，不会调用任何 OpenGL 调试标记 API。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetName](GetName.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetState.md
index ae3b02bc..4fc99b83 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetState.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetState.md
@@ -1,31 +1,26 @@
-# OpenGLBuffer::SetState
-
-设置相关状态或配置。
+# OpenGLBuffer::SetState()
 
 ```cpp
 void SetState(ResourceStates state) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+设置当前对象缓存的软状态元数据。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `state`: 要记录的资源状态。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::SetState(...)。
-    (void)object;
-}
-```
+函数只做成员赋值，不会:
+
+- 调用任何 OpenGL barrier
+- 做状态合法性检查
+- 影响 [Bind](Bind.md) 或 [SetData](SetData.md) 的后续行为
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetState](GetState.md)
+- [OpenGLCommandList::TransitionBarrier](../OpenGLCommandList/TransitionBarrier.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetStride.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetStride.md
index 9c9fa977..9799cd0c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetStride.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/SetStride.md
@@ -1,31 +1,22 @@
-# OpenGLBuffer::SetStride
-
-设置相关状态或配置。
+# OpenGLBuffer::SetStride()
 
 ```cpp
 void SetStride(uint32_t stride) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `stride` - 参数语义详见头文件声明。
+设置当前对象的步长元数据。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `stride`: 以字节为单位的元素步长。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::SetStride(...)。
-    (void)object;
-}
-```
+函数只修改 `m_stride`，不会触发任何 OpenGL 调用。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetStride](GetStride.md)
+- [SetBufferType](SetBufferType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Shutdown.md
index aa15dbb5..c78ec6dd 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Shutdown.md
@@ -1,30 +1,29 @@
-# OpenGLBuffer::Shutdown
-
-关闭并清理内部状态。
+# OpenGLBuffer::Shutdown()
 
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+删除当前对象持有的原生 OpenGL buffer。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 当 `m_buffer != 0` 时，调用 `glDeleteBuffers(1, &m_buffer)`。
+- 然后把 `m_buffer` 设为 `0`。
+- 其他成员保持原值。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+## 这意味着什么
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::Shutdown(...)。
-    (void)object;
-}
-```
+调用 `Shutdown()` 之后:
+
+- [GetID](GetID.md) 会返回 `0`
+- [GetSize](GetSize.md)、[GetType](GetType.md)、[GetBufferType](GetBufferType.md)、[GetStride](GetStride.md) 等元数据不会自动回到构造态
+
+如果调用方把 `Shutdown()` 视为“彻底重置整个对象”，就会误解当前实现。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [~OpenGLBuffer()](Destructor.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unbind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unbind.md
index cec90ee3..f7189ea1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unbind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unbind.md
@@ -1,30 +1,26 @@
-# OpenGLBuffer::Unbind
-
-公开方法，详见头文件声明。
+# OpenGLBuffer::Unbind()
 
 ```cpp
 void Unbind() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前对象所属 target 的 buffer 解绑为 `0`。
 
-**返回：** `void` - 无返回值。
-
-**示例：**
+## 当前实现行为
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::Unbind(...)。
-    (void)object;
-}
+unsigned int target = ToOpenGL(m_type);
+glBindBuffer(target, 0);
 ```
 
+## 需要注意
+
+- 它不会恢复调用 `Bind()` 之前绑定的旧 buffer，而是直接把对应 target 清空。
+- 解绑目标同样只取决于 `m_type`。
+
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unmap.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unmap.md
index be6b2ed4..56f5c21e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unmap.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLBuffer/Unmap.md
@@ -1,30 +1,27 @@
-# OpenGLBuffer::Unmap
-
-公开方法，详见头文件声明。
+# OpenGLBuffer::Unmap()
 
 ```cpp
 void Unmap() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLBuffer.h`，当前页面用于固定 `OpenGLBuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+结束当前 buffer 的映射状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+函数会:
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLBuffer.h>
+1. 根据 `m_type` 绑定目标
+2. 调用 `glUnmapBuffer(target)`
+3. 解绑目标
 
-void Example() {
-    XCEngine::RHI::OpenGLBuffer object;
-    // 根据上下文补齐参数后调用 OpenGLBuffer::Unmap(...)。
-    (void)object;
-}
-```
+## 需要注意
+
+- 当前忽略 `glUnmapBuffer()` 的返回值。
+- 因此文档调用方无法从这个接口直接得知映射内容是否因为存储失效而被驱动判定为无效。
 
 ## 相关文档
 
-- [返回类总览](OpenGLBuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Map](Map.md)
+- [SetData](SetData.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLEnums/OpenGLEnums.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLEnums/OpenGLEnums.md
index f4aa00c1..0ec9bce9 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLEnums/OpenGLEnums.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLEnums/OpenGLEnums.md
@@ -1,18 +1,103 @@
 # OpenGLEnums
 
-**命名空间**: `XCEngine`
+**命名空间**: `XCEngine::RHI`
 
 **类型**: `header`
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLEnums.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLEnums` public API。
+**描述**: OpenGL 后端的头文件内联映射工具集，负责把跨后端 RHI 枚举和 OpenGL 专用枚举转换成底层 `GLenum` / `GLbitfield` / 格式组合。
 
-## 概述
+## 概览
 
-`OpenGLEnums.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`OpenGLEnums.h` 不是“普通的常量头文件”，而是 OpenGL RHI 行为的核心翻译层之一。很多看似分散在 `OpenGLTexture`、`OpenGLBuffer`、`OpenGLPipelineState`、`OpenGLRenderTargetView`、`OpenGLDepthStencilView` 里的行为，最终都依赖这里的内联函数完成跨后端语义到 OpenGL 枚举的落地。
+
+从商业引擎的设计角度看，这种集中式映射层非常重要，因为它能把:
+
+- 跨后端统一语义
+- 后端特有枚举
+- 近似映射和能力退化
+
+明确地放在一个地方管理，而不是散落在每个资源类和命令类里。
+
+## 映射类别
+
+当前头文件里的内联函数主要覆盖以下几组语义:
+
+- 图元与拓扑: `PrimitiveTopology`、`PrimitiveType`
+- 深度/模板与混合: `ComparisonFunc`、`StencilOp`、`BlendFactor`、`BlendOp`
+- 纹理与格式: `OpenGLTextureType`、`OpenGLFormat`
+- Buffer 与顶点输入: `OpenGLBufferType`、`VertexAttributeType`
+- 渲染目标: `RenderTargetType`
+- 采样与光栅状态: `SamplerWrapMode`、`SamplerFilter`、`TextureAddressMode`、`FilterMode`、`CullMode`、`FrontFace`、`FillMode`
+- 清除与 attachment: `ToOpenGLClearBuffer()`、`ToOpenGLDepthAttachment()`、`ToOpenGLStencilAttachment()`、`ToOpenGLDepthStencilAttachment()`、`ToOpenGLColorAttachment()`
+
+## 设计意义
+
+这层映射的价值不只是“少写几个 `switch`”。更关键的是它明确了 OpenGL 后端当前的真实能力边界:
+
+- 哪些枚举能一一对应落地
+- 哪些枚举只是近似模拟
+- 哪些跨后端概念在 OpenGL 里只能退化表达
+
+这对 API 文档尤其重要，因为用户看到统一 RHI 接口时，很容易默认不同后端的表达能力是完全对称的。`OpenGLEnums.h` 恰好就是把这种对称性打破并说明白的地方。
+
+## 需要特别注意的映射
+
+### Buffer 角色并不总是“一一对等”
+
+`OpenGLBufferType::ShaderBindingTable` 当前被映射到 `GL_SHADER_STORAGE_BUFFER`。这说明 OpenGL 后端保留了统一命名，但实际落地是“最接近的通用存储缓冲表达”，而不是真正的硬件光追 SBT 模型。
+
+### `OpenGLFormat` 只实现了部分格式
+
+`ToOpenGLFormat()` 当前只显式处理:
+
+- `R8`
+- `RG8`
+- `RG32F`
+- `RGBA8`
+- `RGBA16F`
+- `RGBA32F`
+- `Depth24Stencil8`
+- `Depth32F`
+
+`CompressedDXT1` 和 `CompressedDXT5` 不在当前分支中，最终会落入默认值 `GL_RGBA8 / GL_RGBA / GL_UNSIGNED_BYTE`。也就是说，相关枚举虽然存在，但当前通用纹理初始化路径并没有实现压缩纹理上传语义。
+
+### 过滤模式存在能力退化
+
+`FilterMode::Anisotropic`、`FilterMode::ComparisonLinear`、`FilterMode::ComparisonAnisotropic` 等模式，在当前映射里会退化成普通 `GL_LINEAR` 或 `GL_NEAREST`。这意味着仅靠这层函数并不能表达完整的各向异性采样或比较采样状态，还需要 sampler 对象和额外参数共同参与。
+
+### attachment helper 很直接，但语义后果很大
+
+- `ToOpenGLDepthAttachment()` 固定返回 `GL_DEPTH_ATTACHMENT`
+- `ToOpenGLStencilAttachment()` 固定返回 `GL_STENCIL_ATTACHMENT`
+- `ToOpenGLDepthStencilAttachment()` 固定返回 `GL_DEPTH_STENCIL_ATTACHMENT`
+- `ToOpenGLColorAttachment(index)` 返回 `GL_COLOR_ATTACHMENT0 + index`
+
+这类 helper 很薄，但它们直接决定了 framebuffer / view 文档里很多“当前行为为什么是这样”的结论。例如 `OpenGLDepthStencilView` 当前初始化路径使用的是 `ToOpenGLDepthAttachment()`，这就是它为何更偏向深度附件而不是完整 depth-stencil attachment 落地的直接来源。
+
+### 清除位掩码是引擎自定义协议
+
+`ToOpenGLClearBuffer(uint32_t buffers)` 当前把:
+
+- `1` 映射到 `GL_COLOR_BUFFER_BIT`
+- `2` 映射到 `GL_DEPTH_BUFFER_BIT`
+- `4` 映射到 `GL_STENCIL_BUFFER_BIT`
+
+这说明这里不是直接接受 OpenGL 原始位掩码，而是在消费引擎内部约定的自定义 bit mask。
+
+## 当前实现的整体特点
+
+- 全部是 `inline` 头文件函数，没有独立 cpp 和运行时状态。
+- 映射函数本身不做能力探测、不做错误检查。
+- 很多地方采用“合理默认值 + 退化映射”策略，而不是追求完全语义对等。
+
+对商业级引擎来说，这种做法是务实且常见的，但前提是文档必须把退化点讲透，否则上层会误把它当成“已经完整支持”。
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGLBuffer](../OpenGLBuffer/OpenGLBuffer.md)
+- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)
+- [OpenGLRenderTargetView](../OpenGLRenderTargetView/OpenGLRenderTargetView.md)
+- [OpenGLDepthStencilView](../OpenGLDepthStencilView/OpenGLDepthStencilView.md)
+- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Bind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Bind.md
index 235d9d47..f36517d2 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Bind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Bind.md
@@ -1,31 +1,32 @@
-# OpenGLTexture::Bind
-
-公开方法，详见头文件声明。
+# OpenGLTexture::Bind()
 
 ```cpp
 void Bind(int slot = 0) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `slot` - 参数语义详见头文件声明。
+把当前纹理绑定到指定 texture unit。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `slot`: 目标 texture unit 索引。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::Bind(...)。
-    (void)object;
-}
-```
+函数会:
+
+1. 根据 `m_type` 解析 OpenGL target
+2. 调用 `glActiveTexture(GL_TEXTURE0 + slot)`
+3. 调用 `glBindTexture(target, m_texture)`
+
+## 需要注意
+
+- 它会修改当前 active texture unit。
+- 不会恢复调用前的 active unit。
+- 不会检查 `slot` 是否超出硬件支持范围。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Unbind](Unbind.md)
+- [BindImage](BindImage.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/BindImage.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/BindImage.md
index 98e23b5e..3705b94e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/BindImage.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/BindImage.md
@@ -1,33 +1,45 @@
-# OpenGLTexture::BindImage
-
-公开方法，详见头文件声明。
+# OpenGLTexture::BindImage()
 
 ```cpp
 void BindImage(int slot, bool read, bool write) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `slot` - 参数语义详见头文件声明。
-- `read` - 参数语义详见头文件声明。
-- `write` - 参数语义详见头文件声明。
+把当前纹理绑定到 image unit，供图像加载/存储或计算着色器访问使用。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `slot`: image unit 索引。
+- `read`: 是否允许读。
+- `write`: 是否允许写。
+
+## 当前实现行为
+
+函数会:
+
+- 先计算 `target = ToOpenGL(m_type)`，但这个局部变量并没有继续使用。
+- 根据 `read` / `write` 组合选择:
+  - `read && write` -> `GL_READ_WRITE`
+  - `read && !write` -> `GL_READ_ONLY`
+  - 其他情况 -> `GL_WRITE_ONLY`
+- 调用:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::BindImage(...)。
-    (void)object;
-}
+glBindImageTexture(slot, m_texture, 0, GL_FALSE, 0, access, GL_RGBA8);
 ```
 
+## 重要限制
+
+- 固定绑定 `level 0`
+- 固定 `layered = GL_FALSE`
+- 固定 `layer = 0`
+- 固定 image format 为 `GL_RGBA8`
+- 不会根据真实纹理格式、层级或数组属性自适应
+
+这说明它更像一个简化的“把纹理当作最普通 RGBA8 image 绑定出去”的工具接口，而不是完整的 image view 抽象。
+
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Constructor.md
index 2218a26f..d122eb8b 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Constructor.md
@@ -1,28 +1,33 @@
 # OpenGLTexture::OpenGLTexture()
 
-构造对象。
-
 ```cpp
 OpenGLTexture();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个尚未持有原生 OpenGL texture 的对象。
 
-**返回：** `void` - 无返回值。
+## 初始状态
 
-**示例：**
+构造函数会把成员初始化为:
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+- `m_texture = 0`
+- `m_type = OpenGLTextureType::Texture2D`
+- `m_width = 0`
+- `m_height = 0`
+- `m_depth = 0`
+- `m_mipLevels = 1`
+- `m_channels = 0`
+- `m_format = Format::Unknown`
+- `m_name = ""`
+- `m_state = ResourceStates::Common`
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-}
-```
+## 需要注意
+
+默认 `m_type = Texture2D` 只是占位初值，不代表对象已经拥有一个 2D 纹理资源。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Destructor.md
index 18dfc1d3..4ca5a557 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Destructor.md
@@ -1,29 +1,22 @@
 # OpenGLTexture::~OpenGLTexture()
 
-销毁对象并释放相关资源。
-
 ```cpp
 ~OpenGLTexture() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+析构对象，并释放当前持有的原生纹理。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+析构函数只调用:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 对象离开作用域时会自动触发析构。
-}
+Shutdown();
 ```
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [OpenGLTexture()](Constructor.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GenerateMipmap.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GenerateMipmap.md
index b27b5a88..40129207 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GenerateMipmap.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GenerateMipmap.md
@@ -1,30 +1,28 @@
-# OpenGLTexture::GenerateMipmap
-
-公开方法，详见头文件声明。
+# OpenGLTexture::GenerateMipmap()
 
 ```cpp
 void GenerateMipmap();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+为当前纹理生成 mipmap。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+函数会:
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+1. 根据 `m_type` 绑定纹理 target
+2. 调用 `glGenerateMipmap(target)`
+3. 解绑 target
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GenerateMipmap(...)。
-    (void)object;
-}
-```
+## 需要注意
+
+- 该函数不会更新 `m_mipLevels`。
+- 因此 [GetMipLevels](GetMipLevels.md) 返回的仍然是旧的缓存值。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize2D](Initialize2D.md)
+- [InitializeCubeMap](InitializeCubeMap.md)
+- [GetMipLevels](GetMipLevels.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetDepth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetDepth.md
index ac0232b1..a0eeb3f2 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetDepth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetDepth.md
@@ -1,30 +1,19 @@
-# OpenGLTexture::GetDepth
-
-获取相关状态或对象。
+# OpenGLTexture::GetDepth()
 
 ```cpp
 uint32_t GetDepth() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回缓存的深度或层数。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetDepth(...)。
-    (void)object;
-}
-```
+- 对 `Texture3D`、`Texture2DArray`、`TextureCubeArray`，它通常表示深度或层数。
+- 对普通 `Texture2D` 和 `TextureCube`，这里只是初始化时记录下来的值，不等价于独立的 OpenGL 查询结果。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetOpenGLType](GetOpenGLType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetFormat.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetFormat.md
index 3a38c180..fb2cbdfc 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetFormat.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetFormat.md
@@ -1,30 +1,24 @@
-# OpenGLTexture::GetFormat
-
-获取相关状态或对象。
+# OpenGLTexture::GetFormat()
 
 ```cpp
 Format GetFormat() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的 RHI `Format` 元数据。
 
-**返回：** `Format` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 默认值为 `Format::Unknown`
+- 直接调用 [Initialize](Initialize.md)、[Initialize2D](Initialize2D.md)、[InitializeCubeMap](InitializeCubeMap.md)、[LoadFromFile](LoadFromFile.md) 都不会自动设置它
+- 如果纹理通过 `OpenGLDevice::CreateTexture()` 创建，设备层会在初始化后调用 [SetFormat](SetFormat.md)
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 为什么这很重要
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetFormat(...)。
-    (void)object;
-}
-```
+很多上层系统会把 `GetFormat()` 当作资源视图、清除路径、copy 路径和索引格式推导的重要依据。如果文档不讲清楚，调用方很容易误以为底层已经自动同步了真实纹理格式。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [SetFormat](SetFormat.md)
+- [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetHeight.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetHeight.md
index ac290dee..d8ee7d76 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetHeight.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetHeight.md
@@ -1,30 +1,18 @@
-# OpenGLTexture::GetHeight
-
-获取相关状态或对象。
+# OpenGLTexture::GetHeight()
 
 ```cpp
 uint32_t GetHeight() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回缓存的纹理高度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetHeight(...)。
-    (void)object;
-}
-```
+这个值由初始化函数写入，不是从 OpenGL 反查得来。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetWidth](GetWidth.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetID.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetID.md
index 22edd5ae..180e4403 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetID.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetID.md
@@ -1,30 +1,18 @@
-# OpenGLTexture::GetID
-
-获取相关状态或对象。
+# OpenGLTexture::GetID()
 
 ```cpp
 unsigned int GetID() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前原生 OpenGL texture 对象 ID。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetID(...)。
-    (void)object;
-}
-```
+- `m_texture`
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetMipLevels.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetMipLevels.md
index 270250f0..7e9c0f78 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetMipLevels.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetMipLevels.md
@@ -1,30 +1,23 @@
-# OpenGLTexture::GetMipLevels
-
-获取相关状态或对象。
+# OpenGLTexture::GetMipLevels()
 
 ```cpp
 uint32_t GetMipLevels() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回缓存的 mip 数量元数据。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+这个值不一定等于真实可用 mip 级别数:
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetMipLevels(...)。
-    (void)object;
-}
-```
+- 通用 [Initialize](Initialize.md) 会直接记录传入的 `mipLevels`
+- [Initialize2D](Initialize2D.md) 在 `generateMipmap = true` 时会把它设成 `0`
+- [GenerateMipmap](GenerateMipmap.md) 不会再把它修正为真实级数
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Initialize2D](Initialize2D.md)
+- [GenerateMipmap](GenerateMipmap.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetName.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetName.md
index 81cc740d..d1914c3c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetName.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetName.md
@@ -1,30 +1,17 @@
-# OpenGLTexture::GetName
-
-获取相关状态或对象。
+# OpenGLTexture::GetName()
 
 ```cpp
 const std::string& GetName() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的调试名称。
 
-**返回：** `const std::string&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetName(...)。
-    (void)object;
-}
-```
+这是纯引擎侧字符串元数据，不会自动映射到 OpenGL 调试标签。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [SetName](SetName.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetNativeHandle.md
index e060b193..2b20bebe 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetNativeHandle.md
@@ -1,30 +1,17 @@
-# OpenGLTexture::GetNativeHandle
-
-获取相关状态或对象。
+# OpenGLTexture::GetNativeHandle()
 
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以通用句柄形式返回原生纹理 ID。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetNativeHandle(...)。
-    (void)object;
-}
-```
+实现会把 `m_texture` 转为 `uintptr_t` 再转成 `void*`。它本质上仍然只是一个整数句柄包装。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetID](GetID.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetOpenGLType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetOpenGLType.md
index 9c6bdbec..221d7867 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetOpenGLType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetOpenGLType.md
@@ -1,30 +1,18 @@
-# OpenGLTexture::GetOpenGLType
-
-获取相关状态或对象。
+# OpenGLTexture::GetOpenGLType()
 
 ```cpp
 OpenGLTextureType GetOpenGLType() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的 OpenGL 纹理类型。
 
-**返回：** `OpenGLTextureType` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetOpenGLType(...)。
-    (void)object;
-}
-```
+- `m_type`
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetTextureType](GetTextureType.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetState.md
index 0137d921..44ffc3a6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetState.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetState.md
@@ -1,30 +1,20 @@
-# OpenGLTexture::GetState
-
-获取相关状态或对象。
+# OpenGLTexture::GetState()
 
 ```cpp
 ResourceStates GetState() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象缓存的软状态元数据。
 
-**返回：** `ResourceStates` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetState(...)。
-    (void)object;
-}
-```
+- 默认值为 `ResourceStates::Common`
+- 通过 `OpenGLDevice::CreateTexture()` 创建的纹理，当前会被补设为 `ResourceStates::PixelShaderResource`
+- 该值不会和实际 OpenGL barrier 自动同步
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [SetState](SetState.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetTextureType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetTextureType.md
index 087cbd71..d0dde5de 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetTextureType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetTextureType.md
@@ -1,30 +1,17 @@
-# OpenGLTexture::GetTextureType
-
-获取相关状态或对象。
+# OpenGLTexture::GetTextureType()
 
 ```cpp
 TextureType GetTextureType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前 `OpenGLTextureType` 映射成跨后端 `TextureType`。
 
-**返回：** `TextureType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetTextureType(...)。
-    (void)object;
-}
-```
+函数通过 `switch` 把 `m_type` 映射到对应的 RHI 纹理类型；未知情况会回退到 `TextureType::Texture2D`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetOpenGLType](GetOpenGLType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetWidth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetWidth.md
index 48260b29..48ee252b 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetWidth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/GetWidth.md
@@ -1,30 +1,18 @@
-# OpenGLTexture::GetWidth
-
-获取相关状态或对象。
+# OpenGLTexture::GetWidth()
 
 ```cpp
 uint32_t GetWidth() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回缓存的纹理宽度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::GetWidth(...)。
-    (void)object;
-}
-```
+这个值由初始化函数写入，不是从 OpenGL 反查得来。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetHeight](GetHeight.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize.md
index d27c9b24..18ed3dbf 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize.md
@@ -1,37 +1,56 @@
-# OpenGLTexture::Initialize
-
-初始化内部状态。
+# OpenGLTexture::Initialize()
 
 ```cpp
 bool Initialize(OpenGLTextureType type, int width, int height, int depth, int mipLevels, OpenGLFormat format, const void* data = nullptr);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `type` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
-- `depth` - 参数语义详见头文件声明。
-- `mipLevels` - 参数语义详见头文件声明。
-- `format` - 参数语义详见头文件声明。
-- `data` - 参数语义详见头文件声明。
+按通用参数创建一个 OpenGL 纹理对象。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `type`: 纹理类型。
+- `width`: 宽度。
+- `height`: 高度。
+- `depth`: 深度或层数。对 3D、2DArray、CubeArray 等类型有意义。
+- `mipLevels`: 期望的 mip 数量元数据。
+- `format`: OpenGL 后端使用的格式枚举。
+- `data`: 初始数据指针；传入 `nullptr` 时只分配 level 0 存储。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::Initialize(...)。
-    (void)object;
-}
-```
+当前实现始终返回 `true`。
+
+## 当前实现行为
+
+函数会:
+
+1. 写入 `m_type`、`m_width`、`m_height`、`m_depth`、`m_mipLevels`。
+2. 通过 `ToOpenGL(type)` 获取目标 target。
+3. 通过 `ToOpenGLFormat(format, internalFormat, glFormat, glType)` 解析上传格式。
+4. 生成并绑定纹理对象。
+5. 按类型选择上传路径:
+   - `TextureCube`: 对六个 face 分别调用一次 `glTexImage2D(..., level = 0, ..., data)`
+   - `Texture1D`: `glTexImage1D(..., level = 0, ..., data)`
+   - `Texture3D` / `Texture2DArray` / `TextureCubeArray`: `glTexImage3D(..., level = 0, ..., depth, ..., data)`
+   - 其他类型: `glTexImage2D(..., level = 0, ..., data)`
+6. 根据 `mipLevels > 1` 决定最小过滤器是 `GL_LINEAR_MIPMAP_LINEAR` 还是 `GL_LINEAR`。
+7. 把放大过滤器设为 `GL_LINEAR`。
+8. 对 cube / cube array 默认使用 `GL_CLAMP_TO_EDGE`，其他类型默认使用 `GL_REPEAT`。
+9. 对 3D、2DArray、Cube、CubeArray 额外设置 `GL_TEXTURE_WRAP_R`。
+10. 解绑纹理并返回 `true`。
+
+## 关键限制
+
+- 当前只真正创建了 level 0，`mipLevels` 更多是缓存字段和默认 min filter 决策依据。
+- 不会自动设置 [GetFormat](GetFormat.md) 对应的 RHI `Format` 元数据。
+- `CompressedDXT1` / `CompressedDXT5` 当前不会走压缩纹理上传 API。
+- 没有显式错误处理，也不会在失败时返回 `false`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize2D](Initialize2D.md)
+- [InitializeCubeMap](InitializeCubeMap.md)
+- [GetOpenGLType](GetOpenGLType.md)
+- [GetMipLevels](GetMipLevels.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize2D.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize2D.md
index a8ab27be..e7f89159 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize2D.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize2D.md
@@ -1,35 +1,45 @@
-# OpenGLTexture::Initialize2D
-
-初始化内部状态。
+# OpenGLTexture::Initialize2D()
 
 ```cpp
 bool Initialize2D(int width, int height, int channels, const void* data, bool generateMipmap = true);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
-- `channels` - 参数语义详见头文件声明。
-- `data` - 参数语义详见头文件声明。
-- `generateMipmap` - 参数语义详见头文件声明。
+以常见的 2D 颜色纹理路径快速创建当前对象。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `width`: 宽度。
+- `height`: 高度。
+- `channels`: 通道数。当前只区分 `4` 和“非 4”。
+- `data`: 初始像素数据。
+- `generateMipmap`: 是否在初始化时立即调用 `glGenerateMipmap()`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::Initialize2D(...)。
-    (void)object;
-}
-```
+当前实现始终返回 `true`。
+
+## 当前实现行为
+
+- `m_channels` 被设置为 `channels`。
+- `m_type` 被设置为 `Texture2D`。
+- `m_width`、`m_height` 被更新。
+- `m_depth` 被固定设置为 `1`。
+- 当 `generateMipmap` 为 `true` 时，`m_mipLevels` 被设置为 `0`；否则为 `1`。
+- `channels == 4` 时使用 `GL_RGBA`，否则使用 `GL_RGB` 作为 internal format 和 format。
+- 如果开启 mipmap，会调用 `glGenerateMipmap(GL_TEXTURE_2D)` 并设置 `GL_LINEAR_MIPMAP_LINEAR` 作为最小过滤器。
+- 否则最小过滤器为 `GL_LINEAR`。
+- Wrap 模式固定是 `GL_REPEAT`。
+
+## 需要注意
+
+- `m_mipLevels = 0` 只是当前实现的记录方式，不代表 OpenGL 规范里的有效 mip 级别计数。
+- 这个函数不会写入 [GetFormat](GetFormat.md) 对应的 RHI `Format`。
+- 只区分 RGBA 和 RGB 两条上传路径，不支持更细的格式选择。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GenerateMipmap](GenerateMipmap.md)
+- [GetMipLevels](GetMipLevels.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/InitializeCubeMap.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/InitializeCubeMap.md
index 67e56e30..29396cd2 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/InitializeCubeMap.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/InitializeCubeMap.md
@@ -1,34 +1,44 @@
-# OpenGLTexture::InitializeCubeMap
-
-初始化内部状态。
+# OpenGLTexture::InitializeCubeMap()
 
 ```cpp
 bool InitializeCubeMap(int size, int mipLevels, OpenGLFormat format, const void* data = nullptr);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `size` - 参数语义详见头文件声明。
-- `mipLevels` - 参数语义详见头文件声明。
-- `format` - 参数语义详见头文件声明。
-- `data` - 参数语义详见头文件声明。
+创建一个 cubemap 纹理。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `size`: 每个 face 的边长。
+- `mipLevels`: 期望的 mip 数量元数据。
+- `format`: OpenGL 后端格式。
+- `data`: 初始像素数据。当前会把同一指针重复用于六个 face。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::InitializeCubeMap(...)。
-    (void)object;
-}
-```
+当前实现始终返回 `true`。
+
+## 当前实现行为
+
+- `m_type = TextureCube`
+- `m_width = size`
+- `m_height = size`
+- `m_depth = 1`
+- `m_mipLevels = mipLevels`
+- 通过 `ToOpenGLFormat()` 解析上传格式
+- 对六个 cubemap face 分别调用一次 `glTexImage2D(..., level = 0, ..., data)`
+- 根据 `mipLevels > 1` 设置最小过滤器
+- Wrap 固定设为 `GL_CLAMP_TO_EDGE`
+
+## 重要限制
+
+- 当前不会根据 `mipLevels` 自动为所有 mip 级别分配存储。
+- 也不会自动生成 mipmap。
+- 如果传入非空 `data`，六个 face 会共享同一份初始数据。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GenerateMipmap](GenerateMipmap.md)
+- [Bind](Bind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/LoadFromFile.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/LoadFromFile.md
index 47e13d81..9caf7d2f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/LoadFromFile.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/LoadFromFile.md
@@ -1,32 +1,41 @@
-# OpenGLTexture::LoadFromFile
-
-加载资源或数据。
+# OpenGLTexture::LoadFromFile()
 
 ```cpp
 bool LoadFromFile(const char* path, bool flipVertical = false);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `path` - 参数语义详见头文件声明。
-- `flipVertical` - 参数语义详见头文件声明。
+从磁盘加载一张图片，并把它创建成 2D 纹理。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `path`: 图片路径。
+- `flipVertical`: 是否让 stb_image 在加载时做垂直翻转。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::LoadFromFile(...)。
-    (void)object;
-}
-```
+- `true`: 加载并初始化成功。
+- `false`: `stbi_load()` 失败。
+
+## 当前实现行为
+
+函数会:
+
+1. 调用 `stbi_set_flip_vertically_on_load(...)` 设置全局加载选项。
+2. 通过 `stbi_load(path, &m_width, &m_height, &m_channels, STBI_rgb_alpha)` 强制按 RGBA 输出数据。
+3. 如果失败，向 `std::cout` 打印错误并返回 `false`。
+4. 把 `m_channels` 强制改为 `4`。
+5. 调用 `Initialize2D(m_width, m_height, m_channels, data, false)` 创建纹理。
+6. 释放 stb_image 数据。
+
+## 需要注意
+
+- 当前不会自动生成 mipmap。
+- 当前不会填充 [GetFormat](GetFormat.md) 对应的 RHI `Format`。
+- `stbi_set_flip_vertically_on_load()` 是 stb_image 的全局状态，严格来说会影响同进程后续加载行为。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize2D](Initialize2D.md)
+- [GetFormat](GetFormat.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/OpenGLTexture.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/OpenGLTexture.md
index f9ef02e2..0c023f67 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/OpenGLTexture.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/OpenGLTexture.md
@@ -6,54 +6,102 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLTexture.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLTexture` public API。
+**描述**: OpenGL 后端的纹理资源封装，负责创建原生 texture 对象、缓存资源维度元数据，并提供最基础的绑定与采样参数配置入口。
 
-## 概述
+## 概览
 
-`OpenGLTexture.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`OpenGLTexture` 承担的是“纹理资源本体”职责，而不是完整的 view 系统。它主要负责:
 
-## 声明概览
+- 创建 1D / 2D / 2DArray / 3D / Cube / CubeArray 纹理对象
+- 上传基础像素数据
+- 维护宽高深、mip 数量、OpenGL 纹理类型等缓存字段
+- 提供绑定、image bind、mipmap 生成和采样参数设置接口
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLTextureType` | `enum class` | 头文件中的公开声明。 |
-| `OpenGLFormat` | `enum class` | 头文件中的公开声明。 |
-| `OpenGLInternalFormat` | `enum class` | 头文件中的公开声明。 |
-| `OpenGLTexture` | `class` | 继承自 `RHITexture` 的公开声明。 |
+在商业引擎里，这一层通常只关心“资源如何存在于 GPU 上”；至于它在本次渲染里被当作 SRV、UAV、RTV 还是 DSV 使用，则会交给 resource view 或 framebuffer 层表达。当前 OpenGL 后端也遵循了类似分层思路。
 
-## 公共方法
+## 设计背景
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLTexture()](Constructor.md) | 构造对象。 |
-| [~OpenGLTexture()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Initialize2D](Initialize2D.md) | 初始化内部状态。 |
-| [InitializeCubeMap](InitializeCubeMap.md) | 初始化内部状态。 |
-| [LoadFromFile](LoadFromFile.md) | 加载资源或数据。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
-| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
-| [BindImage](BindImage.md) | 公开方法，详见头文件声明。 |
-| [GenerateMipmap](GenerateMipmap.md) | 公开方法，详见头文件声明。 |
-| [SetFiltering](SetFiltering.md) | 设置相关状态或配置。 |
-| [SetWrapping](SetWrapping.md) | 设置相关状态或配置。 |
-| [GetID](GetID.md) | 获取相关状态或对象。 |
-| [GetOpenGLType](GetOpenGLType.md) | 获取相关状态或对象。 |
-| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
-| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
-| [GetDepth](GetDepth.md) | 获取相关状态或对象。 |
-| [GetMipLevels](GetMipLevels.md) | 获取相关状态或对象。 |
-| [GetTextureType](GetTextureType.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetState](GetState.md) | 获取相关状态或对象。 |
-| [SetState](SetState.md) | 设置相关状态或配置。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
-| [SetName](SetName.md) | 设置相关状态或配置。 |
-| [GetFormat](GetFormat.md) | 获取相关状态或对象。 |
-| [SetFormat](SetFormat.md) | 设置相关状态或配置。 |
+OpenGL 的纹理对象天然把“资源本体”和“一部分采样状态”绑在一起，这和 D3D12/Vulkan 那种显式分离资源、view、sampler 的风格不同。`OpenGLTexture` 的设计采用了一个实用主义折中:
+
+- 资源分配、上传和基础采样参数由 `OpenGLTexture` 直接负责。
+- 更细的资源视图语义交给 `OpenGLResourceView`、`OpenGLRenderTargetView`、`OpenGLDepthStencilView` 等类型处理。
+
+这样做的好处是易于落地和调试；代价是某些字段看起来像完整抽象，但实际上只是缓存元数据，必须通过文档把边界讲清楚。
+
+## 相关枚举
+
+### `OpenGLTextureType`
+
+当前支持:
+
+- `Texture1D`
+- `Texture2D`
+- `Texture2DArray`
+- `Texture3D`
+- `TextureCube`
+- `TextureCubeArray`
+
+它决定了 [Initialize](Initialize.md) 内部选用 `glTexImage1D`、`glTexImage2D` 还是 `glTexImage3D`，以及默认 wrap 参数如何设置。
+
+### `OpenGLFormat`
+
+头文件中声明了:
+
+- `R8`
+- `RG8`
+- `RG32F`
+- `RGBA8`
+- `RGBA16F`
+- `RGBA32F`
+- `Depth24Stencil8`
+- `Depth32F`
+- `CompressedDXT1`
+- `CompressedDXT5`
+
+但当前 `ToOpenGLFormat()` 实际只处理到 `Depth32F`。`CompressedDXT1` 和 `CompressedDXT5` 在现有实现里不会走压缩纹理上传路径，而会落入默认分支，退化为 `GL_RGBA8` 的普通纹理格式映射。
+
+### `OpenGLInternalFormat`
+
+头文件还声明了 `OpenGLInternalFormat` 数值枚举，但当前 `OpenGLTexture` 的实现并不直接消费它，而是通过 `OpenGLFormat + ToOpenGLFormat()` 获取真正的 OpenGL internal format / format / type 组合。
+
+## 生命周期
+
+- [OpenGLTexture()](Constructor.md) 构造空对象。
+- [Initialize](Initialize.md)、[Initialize2D](Initialize2D.md)、[InitializeCubeMap](InitializeCubeMap.md) 负责创建纹理资源。
+- [LoadFromFile](LoadFromFile.md) 通过 stb_image 加载文件后转调 [Initialize2D](Initialize2D.md)。
+- [Bind](Bind.md)、[BindImage](BindImage.md)、[GenerateMipmap](GenerateMipmap.md)、[SetFiltering](SetFiltering.md)、[SetWrapping](SetWrapping.md) 在使用阶段配置和绑定纹理。
+- [Shutdown](Shutdown.md) 删除原生纹理对象。
+
+## 当前实现的真实行为
+
+- 通用 [Initialize](Initialize.md) 只上传或分配 level 0，不会按 `mipLevels` 循环创建所有 mip 级别。
+- [Initialize2D](Initialize2D.md) 在 `generateMipmap = true` 时会实际调用 `glGenerateMipmap()`，但把 `m_mipLevels` 记成 `0`，而不是真实 mip 数。
+- [InitializeCubeMap](InitializeCubeMap.md) 会把同一个 `data` 指针上传到六个 cubemap face，且不会自动生成额外 mip 级别。
+- [LoadFromFile](LoadFromFile.md) 当前总是以 `STBI_rgb_alpha` 方式读取，并关闭自动 mipmap 生成。
+- [BindImage](BindImage.md) 固定绑定 `level 0`、`layered = GL_FALSE`、`layer = 0`、`format = GL_RGBA8`，不是通用 image view 封装。
+- [Unbind](Unbind.md) 不接收 slot 参数，只会在“当前 active texture unit”上解绑当前 target。
+- [GetFormat](GetFormat.md) 默认返回 `Format::Unknown`，除非外部显式调用 [SetFormat](SetFormat.md)。例如 `OpenGLDevice::CreateTexture()` 会在初始化后补一次 `SetFormat()`。
+- 单测 `tests/RHI/OpenGL/unit/test_texture.cpp` 只覆盖基本初始化、绑定、mipmap 生成和采样参数调用，不验证复杂格式与 image 绑定语义。
+
+## 使用建议
+
+- 如果纹理是通过 `OpenGLDevice::CreateTexture()` 创建的，`Format` 和初始 `ResourceStates` 元数据会更完整；如果直接调用 `OpenGLTexture::Initialize*()`，这些值需要你自行补齐。
+- 不要把 [GetMipLevels](GetMipLevels.md) 在 `Initialize2D(generateMipmap = true)` 后的返回值当作真实 mip 层数。
+- 若需要更一般化的 UAV / subresource image 语义，优先查看 `OpenGLResourceView`，不要直接依赖 [BindImage](BindImage.md)。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [Initialize2D](Initialize2D.md)
+- [InitializeCubeMap](InitializeCubeMap.md)
+- [Bind](Bind.md)
+- [BindImage](BindImage.md)
+- [GenerateMipmap](GenerateMipmap.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLEnums](../OpenGLEnums/OpenGLEnums.md)
+- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
+- [OpenGLRenderTargetView](../OpenGLRenderTargetView/OpenGLRenderTargetView.md)
+- [OpenGLDepthStencilView](../OpenGLDepthStencilView/OpenGLDepthStencilView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFiltering.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFiltering.md
index baab98d2..3a396d48 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFiltering.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFiltering.md
@@ -1,32 +1,28 @@
-# OpenGLTexture::SetFiltering
-
-设置相关状态或配置。
+# OpenGLTexture::SetFiltering()
 
 ```cpp
 void SetFiltering(int minFilter, int magFilter);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `minFilter` - 参数语义详见头文件声明。
-- `magFilter` - 参数语义详见头文件声明。
+设置当前纹理的最小和放大过滤模式。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `minFilter`: 传给 `GL_TEXTURE_MIN_FILTER` 的原始 OpenGL 枚举值。
+- `magFilter`: 传给 `GL_TEXTURE_MAG_FILTER` 的原始 OpenGL 枚举值。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::SetFiltering(...)。
-    (void)object;
-}
-```
+函数只是绑定纹理、写入两个 `glTexParameteri()`，然后解绑。
+
+## 需要注意
+
+- 它不做参数合法性检查。
+- 这里直接暴露的是 OpenGL 原始枚举，而不是跨后端过滤抽象。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [SetWrapping](SetWrapping.md)
+- [Bind](Bind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFormat.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFormat.md
index f94eb3c8..9607fc80 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFormat.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetFormat.md
@@ -1,31 +1,31 @@
-# OpenGLTexture::SetFormat
-
-设置相关状态或配置。
+# OpenGLTexture::SetFormat()
 
 ```cpp
 void SetFormat(Format format);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `format` - 参数语义详见头文件声明。
+设置当前对象缓存的 RHI `Format` 元数据。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `format`: 要记录的格式。
+
+## 当前实现行为
+
+函数只做:
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::SetFormat(...)。
-    (void)object;
-}
+m_format = format;
 ```
 
+它不会:
+
+- 重建纹理存储
+- 校验这个 `Format` 是否和当前 OpenGL 纹理真实格式匹配
+- 影响 [Bind](Bind.md) 或 [BindImage](BindImage.md) 的底层参数
+
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetFormat](GetFormat.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetName.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetName.md
index 4ef7ff4c..31487967 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetName.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetName.md
@@ -1,31 +1,21 @@
-# OpenGLTexture::SetName
-
-设置相关状态或配置。
+# OpenGLTexture::SetName()
 
 ```cpp
 void SetName(const std::string& name) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+设置当前对象的调试名称元数据。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `name`: 要缓存的名称。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::SetName(...)。
-    (void)object;
-}
-```
+函数只修改 `m_name`，不会调用 `glObjectLabel()`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetName](GetName.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetState.md
index 8e97aa75..7e3fdb07 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetState.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetState.md
@@ -1,31 +1,22 @@
-# OpenGLTexture::SetState
-
-设置相关状态或配置。
+# OpenGLTexture::SetState()
 
 ```cpp
 void SetState(ResourceStates state) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+设置当前对象缓存的软状态元数据。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `state`: 要记录的资源状态。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::SetState(...)。
-    (void)object;
-}
-```
+函数只修改 `m_state`，不会触发任何 OpenGL barrier 或驱动调用。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [GetState](GetState.md)
+- [OpenGLCommandList::TransitionBarrier](../OpenGLCommandList/TransitionBarrier.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetWrapping.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetWrapping.md
index 1ccc362a..01c5f7e1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetWrapping.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/SetWrapping.md
@@ -1,33 +1,33 @@
-# OpenGLTexture::SetWrapping
-
-设置相关状态或配置。
+# OpenGLTexture::SetWrapping()
 
 ```cpp
 void SetWrapping(int wrapS, int wrapT, int wrapR = -1);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `wrapS` - 参数语义详见头文件声明。
-- `wrapT` - 参数语义详见头文件声明。
-- `wrapR` - 参数语义详见头文件声明。
+设置当前纹理的寻址模式。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `wrapS`: `GL_TEXTURE_WRAP_S`
+- `wrapT`: `GL_TEXTURE_WRAP_T`
+- `wrapR`: `GL_TEXTURE_WRAP_R`，默认 `-1` 表示不设置
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::SetWrapping(...)。
-    (void)object;
-}
-```
+函数会先绑定目标，然后:
+
+- 总是设置 `GL_TEXTURE_WRAP_S`
+- 总是设置 `GL_TEXTURE_WRAP_T`
+- 当 `wrapR >= 0` 且纹理类型属于 `Texture3D`、`Texture2DArray`、`TextureCube`、`TextureCubeArray` 时，额外设置 `GL_TEXTURE_WRAP_R`
+
+## 需要注意
+
+- 对 `Texture1D` 或 `Texture2D` 来说，`wrapR` 会被忽略。
+- 不做参数合法性检查。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [SetFiltering](SetFiltering.md)
+- [GetOpenGLType](GetOpenGLType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Shutdown.md
index f91bff6f..22d20811 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Shutdown.md
@@ -1,30 +1,20 @@
-# OpenGLTexture::Shutdown
-
-关闭并清理内部状态。
+# OpenGLTexture::Shutdown()
 
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+删除当前对象持有的原生 OpenGL texture。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::Shutdown(...)。
-    (void)object;
-}
-```
+- 如果 `m_texture != 0`，调用 `glDeleteTextures(1, &m_texture)`。
+- 然后把 `m_texture` 置为 `0`。
+- 其他缓存字段不做复位。
 
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [~OpenGLTexture()](Destructor.md)
+- [GetID](GetID.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Unbind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Unbind.md
index 4e47942a..269899c6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Unbind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Unbind.md
@@ -1,30 +1,25 @@
-# OpenGLTexture::Unbind
-
-公开方法，详见头文件声明。
+# OpenGLTexture::Unbind()
 
 ```cpp
 void Unbind() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLTexture.h`，当前页面用于固定 `OpenGLTexture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+在当前 active texture unit 上解绑当前纹理 target。
 
-**返回：** `void` - 无返回值。
-
-**示例：**
+## 当前实现行为
 
 ```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLTexture.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLTexture object;
-    // 根据上下文补齐参数后调用 OpenGLTexture::Unbind(...)。
-    (void)object;
-}
+unsigned int target = ToOpenGL(m_type);
+glBindTexture(target, 0);
 ```
 
+## 关键限制
+
+- 它不会调用 `glActiveTexture()`。
+- 因此它解绑的是“调用瞬间当前激活的 texture unit”，不一定是上一次 [Bind](Bind.md) 使用的那个 slot。
+
 ## 相关文档
 
-- [返回类总览](OpenGLTexture.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index ddb0538b..62847cb3 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-28 02:07:52`
+**生成时间**: `2026-03-28 02:20:55`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`