diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Constructor.md
index f5a25f44..b3981af7 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Constructor.md
@@ -1,28 +1,28 @@
-# D3D12Texture::D3D12Texture()
-
-构造对象。
+# D3D12Texture::D3D12Texture
 
 ```cpp
 D3D12Texture();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 D3D12 纹理对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 构造函数本身没有显式逻辑。
+- 依赖类内默认值完成初始化:
+  - `m_state = ResourceStates::Common`
+  - `m_format = Format::Unknown`
+  - `m_textureType = TextureType::Texture2D`
+  - `m_name` 为空字符串
+  - `m_ownsResource = false`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-}
-```
+- 构造后必须调用某个初始化函数，或者通过 `D3D12Device::CreateTexture()` 获取已初始化实例。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [D3D12Texture](D3D12Texture.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/D3D12Texture.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/D3D12Texture.md
index 559edf38..87231613 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/D3D12Texture.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/D3D12Texture.md
@@ -6,50 +6,85 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12Texture.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Texture` public API。
+**描述**: D3D12 后端的纹理资源封装，持有 `ID3D12Resource` 并附带一层引擎侧格式、类型和状态元数据。
 
-## 概述
+## 概览
 
-`D3D12Texture.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`D3D12Texture` 是 `XCEngine` 在 D3D12 后端中对纹理资源的基础封装。它承担两层职责:
 
-## 声明概览
+- 管理一个 `ID3D12Resource`
+- 维护 RHI 层需要的 `Format`、`TextureType`、`ResourceStates`、名称和拥有权标记
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12Texture` | `class` | 继承自 `RHITexture` 的公开声明。 |
+这类封装在商业级引擎里很常见，因为上层系统需要统一的纹理抽象，而 D3D12 原生资源对象本身并不会替你维护这些跨模块元数据。
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12Texture()](Constructor.md) | 构造对象。 |
-| [~D3D12Texture()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [InitializeFromExisting](InitializeFromExisting.md) | 初始化内部状态。 |
-| [InitializeFromData](InitializeFromData.md) | 初始化内部状态。 |
-| [InitializeDepthStencil](InitializeDepthStencil.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetResource](GetResource.md) | 获取相关状态或对象。 |
-| [GetDesc](GetDesc.md) | 获取相关状态或对象。 |
-| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
-| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
-| [GetDepth](GetDepth.md) | 获取相关状态或对象。 |
-| [GetMipLevels](GetMipLevels.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetState](GetState.md) | 获取相关状态或对象。 |
-| [SetState](SetState.md) | 设置相关状态或配置。 |
-| [GetGPUAddress](GetGPUAddress.md) | 获取相关状态或对象。 |
-| [GetSize](GetSize.md) | 获取相关状态或对象。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
-| [SetName](SetName.md) | 设置相关状态或配置。 |
-| [GetArraySize](GetArraySize.md) | 获取相关状态或对象。 |
-| [GetFormat](GetFormat.md) | 获取相关状态或对象。 |
-| [GetTextureType](GetTextureType.md) | 获取相关状态或对象。 |
-| [SetFormat](SetFormat.md) | 设置相关状态或配置。 |
-| [SetTextureType](SetTextureType.md) | 设置相关状态或配置。 |
-| [OwnsResource](OwnsResource.md) | 公开方法，详见头文件声明。 |
+`D3D12Texture` 不是一个“自动把所有状态都维护正确”的智能对象。当前实现更接近:
+
+- 一个资源句柄封装器
+- 加上一些便于 RHI 使用的缓存字段
+
+因此你需要分清两件事:
+
+- 资源对象真正的 D3D12 创建参数是什么
+- 引擎侧 `m_state` / `m_format` / `m_textureType` 当前是否已经同步更新
+
+这也是本页重点要讲清楚的地方。
+
+## 生命周期
+
+- 构造后为空对象。
+- 可以通过以下路径获得资源:
+  - [Initialize](Initialize.md) 创建默认堆纹理
+  - [InitializeFromExisting](InitializeFromExisting.md) 包装已有资源
+  - [InitializeFromData](InitializeFromData.md) 创建 2D 纹理并上传初始数据
+  - [InitializeDepthStencil](InitializeDepthStencil.md) 创建深度纹理
+- [Shutdown](Shutdown.md) 会 `Reset()` 内部 `ComPtr`，并复位大部分元数据。
+- 析构时自动调用 `Shutdown()`。
+
+## 线程语义
+
+- 当前实现没有锁。
+- D3D12 资源对象本身支持跨线程引用，但该封装里的引擎侧元数据不是并发安全接口；通常仍应在资源创建/管理线程中维护。
+
+## 当前实现的真实行为
+
+- [Initialize](Initialize.md) 会创建 committed resource，但不会把 `m_state` 更新为传入的 `initialState`。
+- [InitializeDepthStencil](InitializeDepthStencil.md) 也会创建处于 `D3D12_RESOURCE_STATE_DEPTH_WRITE` 的资源，但不会同步修改 `m_state`。
+- `D3D12Device::CreateTexture()` 会在某些路径上补做 `SetFormat()`、`SetTextureType()`、`SetState()`，所以工厂路径比手工直接调初始化函数更完整。
+- [InitializeFromExisting](InitializeFromExisting.md) 即使传入 `nullptr` 也返回 `true`。
+- [OwnsResource](OwnsResource.md) 当前只是标记，不会改变 `Shutdown()` 的实际释放行为。
+- [SetName](SetName.md) 只设置引擎侧字符串，不会调用 `ID3D12Object::SetName()`。
+
+## 为什么这样设计
+
+这种实现很像很多引擎早期或中期阶段的 D3D12 资源层:
+
+- 先保证资源能被统一创建和访问
+- 再逐步把状态跟踪、调试命名、子资源语义等能力补齐
+
+它的好处是实现简单、上层可用。
+它的代价是文档必须把“哪些字段只是缓存、哪些行为依赖外部调用者补齐”写得非常明确，否则调用方很容易误判资源状态。
+
+## 当前限制
+
+- `GetDesc()` 和 `GetGPUAddress()` 没有空指针保护。
+- `GetSize()` 只是近似值，不是显存占用。
+- `GetDepth()` 与 [GetArraySize](GetArraySize.md) 都读取 `DepthOrArraySize`，语义上需要由调用方自己区分“深度纹理”还是“数组纹理”。
+- `OwnsResource` 不控制 `Shutdown()` 是否释放 `ComPtr`。
+- `SetName()` 不会把名称写入 D3D12 调试层对象。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [InitializeFromData](InitializeFromData.md)
+- [InitializeDepthStencil](InitializeDepthStencil.md)
+- [InitializeFromExisting](InitializeFromExisting.md)
+- [SetState](SetState.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12Device](../D3D12Device/D3D12Device.md)
+- [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Destructor.md
index 390e2d00..cd7eb48c 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Destructor.md
@@ -1,29 +1,19 @@
-# D3D12Texture::~D3D12Texture()
-
-销毁对象并释放相关资源。
+# D3D12Texture::~D3D12Texture
 
 ```cpp
 ~D3D12Texture() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象并释放内部 `ID3D12Resource` 引用。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
+- 不会根据 [OwnsResource](OwnsResource.md) 的值改变行为；只要 `m_resource` 非空，`ComPtr::Reset()` 就会释放当前引用。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [OwnsResource](OwnsResource.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetArraySize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetArraySize.md
index d1edc73f..45ab232e 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetArraySize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetArraySize.md
@@ -1,30 +1,25 @@
 # D3D12Texture::GetArraySize
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetArraySize() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回纹理数组大小。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_resource` 有效，直接返回 `GetDesc().DepthOrArraySize`。
+- 这意味着:
+  - 对数组纹理，它表示数组层数
+  - 对 3D 纹理，它实际上会返回深度
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetArraySize(...)。
-    (void)object;
-}
-```
+- 该接口没有额外区分资源维度，调用前应结合 [GetTextureType](GetTextureType.md) 判断语义。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetDepth](GetDepth.md)
+- [GetTextureType](GetTextureType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDepth.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDepth.md
index f6114f20..93ae93e0 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDepth.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDepth.md
@@ -1,30 +1,25 @@
 # D3D12Texture::GetDepth
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetDepth() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回纹理深度值。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_resource` 有效，返回 `GetDesc().DepthOrArraySize`。
+- 对 3D 纹理这是“深度”。
+- 对 2D array / cube array 纹理，这个值实际上是数组层数。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetDepth(...)。
-    (void)object;
-}
-```
+- 该方法沿用了统一 `RHITexture` 接口，但在 D3D12 里它与 [GetArraySize](GetArraySize.md) 共享同一底层字段。
+- 调用方必须结合纹理类型理解这个返回值。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetArraySize](GetArraySize.md)
+- [GetTextureType](GetTextureType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDesc.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDesc.md
index 7e88b62b..08cb0260 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDesc.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetDesc.md
@@ -1,30 +1,24 @@
 # D3D12Texture::GetDesc
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_RESOURCE_DESC GetDesc() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 `ID3D12Resource` 的资源描述。
 
-**返回：** `D3D12_RESOURCE_DESC` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接调用 `m_resource->GetDesc()`。
+- 这里没有空指针保护。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetDesc(...)。
-    (void)object;
-}
-```
+- 仅在资源已成功初始化后调用。
+- 如果对象可能处于未初始化或 `Shutdown()` 后状态，应先通过 [GetResource](GetResource.md) 判空。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetResource](GetResource.md)
+- [GetSize](GetSize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetFormat.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetFormat.md
index 5584925e..39563054 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetFormat.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetFormat.md
@@ -1,30 +1,24 @@
 # D3D12Texture::GetFormat
 
-获取相关状态或对象。
-
 ```cpp
 Format GetFormat() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该纹理的引擎侧格式。
 
-**返回：** `Format` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_format != Format::Unknown`，优先返回缓存值。
+- 否则如果 `m_resource` 有效，动态从 `GetDesc().Format` 转换得到。
+- 两者都不可用时返回 `Format::Unknown`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetFormat(...)。
-    (void)object;
-}
-```
+- 这解释了为什么工厂路径常常在创建完成后还会显式调用 [SetFormat](SetFormat.md): 它希望引擎侧元数据保持明确，不完全依赖运行时推导。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [SetFormat](SetFormat.md)
+- [InitializeFromExisting](InitializeFromExisting.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetGPUAddress.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetGPUAddress.md
index 77b07c8d..a872e0c5 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetGPUAddress.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetGPUAddress.md
@@ -1,30 +1,24 @@
 # D3D12Texture::GetGPUAddress
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetGPUAddress() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层资源的 GPU 虚拟地址。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接调用 `m_resource->GetGPUVirtualAddress()`。
+- 这里没有空指针保护。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetGPUAddress(...)。
-    (void)object;
-}
-```
+- 对大多数纹理资源来说，这个值通常没有 buffer 那样稳定明确的使用场景；它只是原样暴露底层接口结果。
+- 使用前必须确保资源已初始化。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetResource](GetResource.md)
+- [GetDesc](GetDesc.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetHeight.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetHeight.md
index b14baece..f27d76c3 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetHeight.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetHeight.md
@@ -1,30 +1,19 @@
 # D3D12Texture::GetHeight
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetHeight() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回纹理高度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetHeight(...)。
-    (void)object;
-}
-```
+- 如果 `m_resource` 有效，返回 `GetDesc().Height`。
+- 否则返回 `0`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetWidth](GetWidth.md)
+- [GetDesc](GetDesc.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetMipLevels.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetMipLevels.md
index 0f365d5f..e466b3b2 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetMipLevels.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetMipLevels.md
@@ -1,30 +1,19 @@
 # D3D12Texture::GetMipLevels
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetMipLevels() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回纹理的 mip 级别数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetMipLevels(...)。
-    (void)object;
-}
-```
+- 如果 `m_resource` 有效，返回 `GetDesc().MipLevels`。
+- 否则返回 `0`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [InitializeFromData](InitializeFromData.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetName.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetName.md
index 166a69e3..a7f50795 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetName.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetName.md
@@ -1,30 +1,24 @@
 # D3D12Texture::GetName
 
-获取相关状态或对象。
-
 ```cpp
 const std::string& GetName() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该纹理保存的引擎侧名称。
 
-**返回：** `const std::string&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回成员 `m_name`。
+- 名称来源于 [SetName](SetName.md)，不是从 `ID3D12Resource` 反查。
+- [Shutdown](Shutdown.md) 不会清空这个字段。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetName(...)。
-    (void)object;
-}
-```
+- 该字段更适合引擎内部调试、日志和文档语义，不代表 D3D12 调试层一定能看到同名对象。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [SetName](SetName.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetNativeHandle.md
index ed7c2fe1..a8391e34 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetNativeHandle.md
@@ -1,30 +1,23 @@
 # D3D12Texture::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层原生资源句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 直接返回 `m_resource.Get()`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 这是一个非常薄的包装，不做类型转换之外的额外处理。
+- 对 D3D12 调试或底层扩展代码来说，它是访问原生 `ID3D12Resource*` 的直接入口。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetResource](GetResource.md)
+- [InitializeFromExisting](InitializeFromExisting.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetResource.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetResource.md
index 164e8fea..45401c2d 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetResource.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetResource.md
@@ -1,30 +1,19 @@
 # D3D12Texture::GetResource
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12Resource* GetResource() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 `ID3D12Resource*`。
 
-**返回：** `ID3D12Resource*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetResource(...)。
-    (void)object;
-}
-```
+- 资源已初始化时返回有效指针。
+- 否则返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [GetDesc](GetDesc.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetSize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetSize.md
index df74b0b0..b3444cca 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetSize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetSize.md
@@ -1,30 +1,29 @@
 # D3D12Texture::GetSize
 
-获取相关状态或对象。
-
 ```cpp
 size_t GetSize() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回一个近似的资源尺寸值。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接计算 `GetDesc().Width * GetDesc().Height * GetDesc().DepthOrArraySize`。
+- 不考虑:
+  - 像素格式字节数
+  - mip 链
+  - 对齐填充
+  - MSAA
+  - 压缩格式
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetSize(...)。
-    (void)object;
-}
-```
+- 这个接口不能当作显存占用统计。
+- 如果你需要准确显存大小，应另行基于 footprint 或分配器信息计算。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetDesc](GetDesc.md)
+- [InitializeFromData](InitializeFromData.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetState.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetState.md
index 4be980c3..fd5a6018 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetState.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetState.md
@@ -1,30 +1,24 @@
 # D3D12Texture::GetState
 
-获取相关状态或对象。
-
 ```cpp
 ResourceStates GetState() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回引擎侧缓存的资源状态。
 
-**返回：** `ResourceStates` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回成员 `m_state`。
+- 这个字段不是所有初始化函数都会自动维护。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetState(...)。
-    (void)object;
-}
-```
+- 不要想当然地把 `GetState()` 等同于“底层 D3D12 资源当前真实状态”。
+- 在手工初始化资源后，通常需要结合 [SetState](SetState.md) 或设备工厂路径显式同步。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [SetState](SetState.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetTextureType.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetTextureType.md
index 7bd80f14..9914a360 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetTextureType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetTextureType.md
@@ -1,30 +1,19 @@
 # D3D12Texture::GetTextureType
 
-获取相关状态或对象。
-
 ```cpp
 TextureType GetTextureType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回纹理类型。
 
-**返回：** `TextureType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetTextureType(...)。
-    (void)object;
-}
-```
+- 直接返回缓存的 `m_textureType`。
+- 该字段可能来自初始化函数的资源维度推导，也可能由工厂路径通过 [SetTextureType](SetTextureType.md) 手工覆盖。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [SetTextureType](SetTextureType.md)
+- [GetArraySize](GetArraySize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetWidth.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetWidth.md
index 2476356a..306ecde2 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetWidth.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/GetWidth.md
@@ -1,30 +1,19 @@
 # D3D12Texture::GetWidth
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetWidth() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回纹理宽度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::GetWidth(...)。
-    (void)object;
-}
-```
+- 如果 `m_resource` 有效，返回 `GetDesc().Width`。
+- 否则返回 `0`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetHeight](GetHeight.md)
+- [GetDesc](GetDesc.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Initialize.md
index 4ecffa5f..eff34711 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Initialize.md
@@ -1,33 +1,42 @@
 # D3D12Texture::Initialize
 
-初始化内部状态。
-
 ```cpp
-bool Initialize(ID3D12Device* device, const D3D12_RESOURCE_DESC& desc, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON);
+bool Initialize(
+    ID3D12Device* device,
+    const D3D12_RESOURCE_DESC& desc,
+    D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `initialState` - 参数语义详见头文件声明。
+创建一个默认堆 committed texture 资源。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `device` 必须有效。
+- `desc` 必须描述一个合法的纹理资源。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::Initialize(...)。
-    (void)object;
-}
-```
+- `CreateCommittedResource()` 成功时返回 `true`。
+- 失败时返回 `false`。
+
+## 当前实现行为
+
+- 使用 `D3D12_HEAP_TYPE_DEFAULT` 创建 committed resource。
+- `pOptimizedClearValue` 当前固定为 `nullptr`。
+- 创建成功后:
+  - 从 `desc.Format` 推导并缓存 `m_format`
+  - 从 `desc.Dimension` 推导并缓存 `m_textureType`
+  - 设置 `m_ownsResource = true`
+- 不会把 `m_state` 更新为传入的 `initialState`。
+
+## 设计说明
+
+- 当前实现把“真实创建状态”和“引擎侧状态缓存”分开了。
+- 因此如果你直接调用这个接口而不是通过设备工厂，后续可能还需要显式 [SetState](SetState.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [SetState](SetState.md)
+- [../D3D12Device/CreateTexture.md](../D3D12Device/CreateTexture.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeDepthStencil.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeDepthStencil.md
index 12f3c003..81f74ec8 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeDepthStencil.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeDepthStencil.md
@@ -1,34 +1,41 @@
 # D3D12Texture::InitializeDepthStencil
 
-初始化内部状态。
-
 ```cpp
-bool InitializeDepthStencil(ID3D12Device* device, uint32_t width, uint32_t height, DXGI_FORMAT format = DXGI_FORMAT_D24_UNORM_S8_UINT);
+bool InitializeDepthStencil(
+    ID3D12Device* device,
+    uint32_t width,
+    uint32_t height,
+    DXGI_FORMAT format = DXGI_FORMAT_D24_UNORM_S8_UINT);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
-- `format` - 参数语义详见头文件声明。
+创建一个用于深度/模板用途的 2D 纹理。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 资源创建成功时返回 `true`。
+- 失败时返回 `false`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::InitializeDepthStencil(...)。
-    (void)object;
-}
-```
+- 构造一个 `D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL` 的 2D 纹理描述。
+- 使用默认堆创建资源。
+- 传入优化 clear value:
+  - `Depth = 1.0f`
+  - `Stencil = 0`
+- 真实初始状态是 `D3D12_RESOURCE_STATE_DEPTH_WRITE`。
+- 成功后仅设置:
+  - `m_format`
+  - `m_textureType = TextureType::Texture2D`
+  - `m_ownsResource = true`
+
+## 重要限制
+
+- 该函数不会把 `m_state` 同步为 `ResourceStates::DepthWrite`。
+- 设备工厂路径会在创建成功后额外调用 `SetState(ResourceStates::DepthWrite)`；如果你直接使用本函数，需要自己补这一步。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetState](GetState.md)
+- [SetState](SetState.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromData.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromData.md
index 476043f8..b27c9f51 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromData.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromData.md
@@ -1,38 +1,50 @@
 # D3D12Texture::InitializeFromData
 
-初始化内部状态。
-
 ```cpp
-bool InitializeFromData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* pixelData, uint32_t width, uint32_t height, DXGI_FORMAT format, uint32_t rowPitch = 0, ComPtr<ID3D12Resource>* uploadBuffer = nullptr);
+bool InitializeFromData(
+    ID3D12Device* device,
+    ID3D12GraphicsCommandList* commandList,
+    const void* pixelData,
+    uint32_t width,
+    uint32_t height,
+    DXGI_FORMAT format,
+    uint32_t rowPitch = 0,
+    ComPtr<ID3D12Resource>* uploadBuffer = nullptr);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `commandList` - 参数语义详见头文件声明。
-- `pixelData` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
-- `format` - 参数语义详见头文件声明。
-- `rowPitch` - 参数语义详见头文件声明。
-- `uploadBuffer` - 参数语义详见头文件声明。
+创建一个带初始像素数据的 2D 纹理，并录制上传拷贝命令。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `device`、`commandList` 和 `pixelData` 必须有效。
+- 当前实现只覆盖 2D、单 mip、单数组层纹理上传。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::InitializeFromData(...)。
-    (void)object;
-}
-```
+- 创建资源并成功写入上传命令时返回 `true`。
+- 任一步骤失败时返回 `false`。
+
+## 当前实现行为
+
+- 创建一个默认堆 2D 纹理，初始状态固定为 `D3D12_RESOURCE_STATE_COPY_DEST`。
+- 计算 copyable footprint。
+- 创建一个 upload heap buffer。
+- 逐行把 `pixelData` 拷贝到上传缓冲:
+  - `sourceRowPitch` 使用传入 `rowPitch`
+  - 如果 `rowPitch == 0`，退回到 footprint 的 `rowSizeInBytes`
+- 录制 `CopyTextureRegion()`。
+- 录制从 `COPY_DEST` 到 `PIXEL_SHADER_RESOURCE` 的 transition barrier。
+- 把 `m_state` 设置为 `ResourceStates::PixelShaderResource`。
+- 如果提供 `uploadBuffer` 输出参数，返回上传缓冲资源给调用方。
+
+## 重要限制
+
+- 该函数只负责“录制命令”，不负责关闭命令列表、提交队列或等待完成。
+- 当前实现固定创建 `MipLevels = 1`、`DepthOrArraySize = 1` 的 2D 纹理。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [../D3D12Device/CreateTexture.md](../D3D12Device/CreateTexture.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromExisting.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromExisting.md
index d58fd8c1..a70b723f 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromExisting.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/InitializeFromExisting.md
@@ -1,32 +1,39 @@
 # D3D12Texture::InitializeFromExisting
 
-初始化内部状态。
-
 ```cpp
 bool InitializeFromExisting(ID3D12Resource* resource, bool ownsResource = false);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `resource` - 参数语义详见头文件声明。
-- `ownsResource` - 参数语义详见头文件声明。
+用一个已经存在的 `ID3D12Resource` 初始化当前对象。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数说明
 
-**示例：**
+- `resource`: 需要包装的已有资源。
+- `ownsResource`: 引擎侧拥有权标记。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::InitializeFromExisting(...)。
-    (void)object;
-}
-```
+- 当前实现始终返回 `true`，即使 `resource == nullptr`。
+
+## 当前实现行为
+
+- 把 `resource` 赋给内部 `ComPtr`。
+- 如果资源非空，则根据 `GetDesc()` 推导 `m_format` 和 `m_textureType`。
+- 无论资源是否为空，都会保存 `m_ownsResource = ownsResource`。
+- 不会修改 `m_state`。
+
+## 重要限制
+
+- 传入空资源不会报错，这意味着调用方必须自行验证结果是否可用。
+- `ownsResource` 当前只是一个标记，不会阻止 [Shutdown](Shutdown.md) 调用 `ComPtr::Reset()`。
+
+## 典型场景
+
+- swap chain back buffer 包装就是这条路径，代码里会以 `ownsResource = false` 的方式接入已有资源。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [OwnsResource](OwnsResource.md)
+- [GetResource](GetResource.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/OwnsResource.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/OwnsResource.md
index 63faa268..a8b6290e 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/OwnsResource.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/OwnsResource.md
@@ -1,30 +1,24 @@
 # D3D12Texture::OwnsResource
 
-公开方法，详见头文件声明。
-
 ```cpp
 bool OwnsResource() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象记录的拥有权标记。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回成员 `m_ownsResource`。
+- 该标记由初始化函数写入，但当前不会改变 [Shutdown](Shutdown.md) 或析构的实际释放策略。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::OwnsResource(...)。
-    (void)object;
-}
-```
+- 把它理解为“引擎层的语义标签”更准确，而不是严格的 RAII 控制位。
+- 如果你需要真正区分谁应该释放底层资源，当前代码还需要更明确的生命周期约束。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeFromExisting](InitializeFromExisting.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetFormat.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetFormat.md
index f7436b28..1876bb5b 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetFormat.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetFormat.md
@@ -1,31 +1,24 @@
 # D3D12Texture::SetFormat
 
-设置相关状态或配置。
-
 ```cpp
 void SetFormat(Format format);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `format` - 参数语义详见头文件声明。
+手工覆盖该纹理的引擎侧格式缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 直接把 `m_format` 设为传入值。
+- 不修改底层 `ID3D12Resource` 的真实格式。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::SetFormat(...)。
-    (void)object;
-}
-```
+- 该接口主要用于设备工厂在创建完成后把 RHI 层的逻辑格式同步到对象。
+- 如果传入值与底层资源真实格式不一致，后续文档、调试和 view 创建逻辑都可能被误导。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetFormat](GetFormat.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetName.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetName.md
index f61de6d2..19863728 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetName.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetName.md
@@ -1,31 +1,23 @@
 # D3D12Texture::SetName
 
-设置相关状态或配置。
-
 ```cpp
 void SetName(const std::string& name) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+设置该纹理的引擎侧名称。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 只把 `name` 保存到 `m_name`。
+- 不会调用 `ID3D12Object::SetName()`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::SetName(...)。
-    (void)object;
-}
-```
+- 如果你希望在 PIX、D3D12 debug layer 或图形调试器里看到资源名称，当前实现还不够，需要额外把名字写入原生对象。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetName](GetName.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetState.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetState.md
index 1043ad25..76167837 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetState.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetState.md
@@ -1,31 +1,24 @@
 # D3D12Texture::SetState
 
-设置相关状态或配置。
-
 ```cpp
 void SetState(ResourceStates state) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+手工更新引擎侧缓存的资源状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 直接把 `m_state` 设为传入值。
+- 不会自动向命令列表插入 barrier，也不会验证底层资源是否真的处于该状态。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::SetState(...)。
-    (void)object;
-}
-```
+- 这是一个“状态缓存同步接口”，不是 barrier 接口。
+- 调用方应确保真实的 D3D12 资源转换已经发生，否则 `GetState()` 只会成为错误的本地记录。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetState](GetState.md)
+- [InitializeDepthStencil](InitializeDepthStencil.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetTextureType.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetTextureType.md
index df5736bf..fa6613cd 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetTextureType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/SetTextureType.md
@@ -1,31 +1,24 @@
 # D3D12Texture::SetTextureType
 
-设置相关状态或配置。
-
 ```cpp
 void SetTextureType(TextureType type);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `type` - 参数语义详见头文件声明。
+手工覆盖纹理类型缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 直接把 `m_textureType` 设为传入值。
+- 不会修改底层资源描述。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::SetTextureType(...)。
-    (void)object;
-}
-```
+- 该接口通常由设备工厂在完成资源创建后补写逻辑类型。
+- 如果传入值与底层 `D3D12_RESOURCE_DESC::Dimension` 不一致，后续解释 `DepthOrArraySize` 等字段时会产生歧义。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [GetTextureType](GetTextureType.md)
+- [GetDepth](GetDepth.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Shutdown.md
index 92285f56..00ed460e 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Texture/Shutdown.md
@@ -1,30 +1,28 @@
 # D3D12Texture::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放内部资源引用，并把对象恢复到基础空状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 调用 `m_resource.Reset()`。
+- 把 `m_state` 设回 `ResourceStates::Common`。
+- 把 `m_format` 设回 `Format::Unknown`。
+- 把 `m_textureType` 设回 `TextureType::Texture2D`。
+- 把 `m_ownsResource` 设回 `false`。
+- 不会清空 `m_name`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Texture.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Texture object;
-    // 根据上下文补齐参数后调用 D3D12Texture::Shutdown(...)。
-    (void)object;
-}
-```
+- 如果你依赖 `GetName()` 做日志或调试，注意 `Shutdown()` 后名称仍然保留。
+- 即使 `OwnsResource()` 先前为 `false`，这里仍然会释放当前 `ComPtr` 引用。
 
 ## 相关文档
 
-- [返回类总览](D3D12Texture.md)
-- [返回模块目录](../D3D12.md)
+- [OwnsResource](OwnsResource.md)
+- [GetName](GetName.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Constructor.md
index 97934bd0..beb27fff 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Constructor.md
@@ -1,28 +1,28 @@
-# OpenGLRenderPass::OpenGLRenderPass()
-
-构造对象。
+# OpenGLRenderPass::OpenGLRenderPass
 
 ```cpp
 OpenGLRenderPass();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 `OpenGLRenderPass` 对象，不分配任何 OpenGL 驱动资源。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 该构造函数本身没有显式逻辑。
+- 成员采用类内默认值初始化:
+  - `m_colorAttachmentCount = 0`
+  - `m_colorAttachments` 为空
+  - `m_hasDepthStencil = false`
+- 真实的附件描述复制发生在 [Initialize](Initialize.md)，而不是构造阶段。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-}
-```
+- 构造后应尽快调用 [Initialize](Initialize.md) 写入附件元数据。
+- 如果只是通过 `RHIDevice::CreateRenderPass()` 获取实例，通常不需要直接关心该构造函数。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLRenderPass](OpenGLRenderPass.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Destructor.md
index b86f98a4..5f5ef20c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Destructor.md
@@ -1,29 +1,24 @@
-# OpenGLRenderPass::~OpenGLRenderPass()
-
-销毁对象并释放相关资源。
+# OpenGLRenderPass::~OpenGLRenderPass
 
 ```cpp
 ~OpenGLRenderPass() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 `OpenGLRenderPass`，并释放其内部保存的附件描述数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 析构函数唯一动作是调用 [Shutdown](Shutdown.md)。
+- 不会删除任何 OpenGL 原生对象，因为该类型当前不持有 FBO、render pass 或其他驱动句柄。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 如果对象已经显式调用过 `Shutdown()`，析构时再次调用也是安全的。
+- 该析构主要负责清空 CPU 侧元数据，不承担 GPU 资源释放职责。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLRenderPass](OpenGLRenderPass.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachmentCount.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachmentCount.md
index fa09fa52..b646dbbf 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachmentCount.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachmentCount.md
@@ -1,30 +1,29 @@
 # OpenGLRenderPass::GetColorAttachmentCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetColorAttachmentCount() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 render pass 记录的颜色附件数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `Initialize()` 时写入的 `colorAttachmentCount`。
+- 在 [Shutdown](Shutdown.md) 之后返回 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-    // 根据上下文补齐参数后调用 OpenGLRenderPass::GetColorAttachmentCount(...)。
-    (void)object;
-}
-```
+- 这是一个纯粹的轻量 getter，直接返回 `m_colorAttachmentCount`。
+- 该值表示“元数据中声明的颜色附件数”，不是当前帧实际绑定到 OpenGL FBO 的附件数。
+
+## 使用建议
+
+- 在 OpenGL 后端中，这个数量主要被命令列表用于解释 clear / load 语义。
+- 如果需要知道真正的附件绑定结果，应查看 framebuffer 或命令列表的绑定流程，而不是仅依赖该值。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetColorAttachments](GetColorAttachments.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachments.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachments.md
index 502c0d5e..476f6c61 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachments.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetColorAttachments.md
@@ -1,30 +1,29 @@
 # OpenGLRenderPass::GetColorAttachments
 
-获取相关状态或对象。
-
 ```cpp
 const AttachmentDesc* GetColorAttachments() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回内部保存的颜色附件描述数组首地址。
 
-**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `std::vector<AttachmentDesc>` 内部缓冲区的起始指针。
+- 当颜色附件数量为 `0` 时，返回值没有实际使用意义，应结合 [GetColorAttachmentCount](GetColorAttachmentCount.md) 一起判断。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-    // 根据上下文补齐参数后调用 OpenGLRenderPass::GetColorAttachments(...)。
-    (void)object;
-}
-```
+- `Initialize()` 会把输入数组逐项复制到 `m_colorAttachments`，因此返回的是内部副本，不依赖外部数组生命周期。
+- 该数组仅保存 `AttachmentDesc` 元数据，不代表 OpenGL 已经创建了同名原生对象。
+
+## 使用建议
+
+- 调用方应在对象生命周期内使用该指针，不要在 `Shutdown()` 或析构后继续缓存。
+- 在 OpenGL 后端里，这些描述主要用于 [OpenGLCommandList::BeginRenderPass](../OpenGLCommandList/BeginRenderPass.md) 决定是否清屏。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [GetColorAttachmentCount](GetColorAttachmentCount.md)
+- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetDepthStencilAttachment.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetDepthStencilAttachment.md
index a77759d3..8b79c9af 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetDepthStencilAttachment.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetDepthStencilAttachment.md
@@ -1,30 +1,30 @@
 # OpenGLRenderPass::GetDepthStencilAttachment
 
-获取相关状态或对象。
-
 ```cpp
 const AttachmentDesc* GetDepthStencilAttachment() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回深度/模板附件的描述信息。
 
-**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 如果初始化时提供了 `depthStencilAttachment`，返回内部保存对象的地址。
+- 如果没有深度/模板附件，返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-    // 根据上下文补齐参数后调用 OpenGLRenderPass::GetDepthStencilAttachment(...)。
-    (void)object;
-}
-```
+- 返回值受 `m_hasDepthStencil` 控制，而不是根据格式字段动态推断。
+- `Initialize()` 会复制一份 `AttachmentDesc`，因此不依赖外部描述结构体的存活时间。
+- `Shutdown()` 会把 `m_hasDepthStencil` 复位为 `false`，之后该方法重新返回 `nullptr`。
+
+## 使用建议
+
+- 使用前应始终判空。
+- 当前 OpenGL 后端主要把这里的 `loadOp` / `stencilLoadOp` 用于 `BeginRenderPass()` 的清除逻辑。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetNativeHandle.md
index ece184aa..00f8c15a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/GetNativeHandle.md
@@ -1,30 +1,28 @@
 # OpenGLRenderPass::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+暴露底层原生句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 当前实现始终返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-    // 根据上下文补齐参数后调用 OpenGLRenderPass::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 这不是延迟创建接口，也不会尝试生成任何 OpenGL 对象。
+- 该返回结果与测试保持一致: `tests/RHI/unit/test_render_pass.cpp` 明确校验 `GetNativeHandle() == nullptr`。
+
+## 设计说明
+
+- 这恰好体现了当前 OpenGL 后端的真实情况: `OpenGLRenderPass` 只是附件元数据容器，不对应独立的 OpenGL driver object。
+- 真正的绑定和清除逻辑发生在命令列表与 framebuffer 协作阶段，而不是在 render pass 本身。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLRenderPass](OpenGLRenderPass.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Initialize.md
index 66dffd8d..4598bd29 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Initialize.md
@@ -1,33 +1,53 @@
 # OpenGLRenderPass::Initialize
 
-初始化内部状态。
-
 ```cpp
-bool Initialize(uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) override;
+bool Initialize(
+    uint32_t colorAttachmentCount,
+    const AttachmentDesc* colorAttachments,
+    const AttachmentDesc* depthStencilAttachment) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `colorAttachmentCount` - 参数语义详见头文件声明。
-- `colorAttachments` - 参数语义详见头文件声明。
-- `depthStencilAttachment` - 参数语义详见头文件声明。
+把 RHI 层传入的附件描述复制到 `OpenGLRenderPass` 内部，供后续命令列表解释 load/store 语义。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `colorAttachmentCount > 0` 时，`colorAttachments` 应指向至少同样长度的数组。
+- 该接口不做 OpenGL 上下文校验，因为当前实现不直接调用任何 GL API。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 参数说明
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-    // 根据上下文补齐参数后调用 OpenGLRenderPass::Initialize(...)。
-    (void)object;
-}
-```
+- `colorAttachmentCount`: 颜色附件数量。
+- `colorAttachments`: 颜色附件描述数组。
+- `depthStencilAttachment`: 可选的深度/模板附件描述。
+
+## 返回值
+
+- 当前实现恒定返回 `true`。
+
+## 当前实现行为
+
+- 把 `colorAttachmentCount` 保存到 `m_colorAttachmentCount`。
+- 调整 `m_colorAttachments` 大小，并逐项复制传入的颜色附件描述。
+- 如果 `depthStencilAttachment != nullptr`:
+  - 设置 `m_hasDepthStencil = true`
+  - 复制一份 `AttachmentDesc` 到 `m_depthStencilAttachment`
+- 否则仅把 `m_hasDepthStencil` 设为 `false`。
+- 不创建任何 OpenGL render pass 或 framebuffer 句柄。
+
+## 设计说明
+
+- 这和 Vulkan/D3D12 中“render pass 可能对应更强的后端对象”不同。
+- 在当前 OpenGL 后端中，render pass 的职责更接近“本次渲染阶段的附件契约说明书”，命令列表只用它来判断哪些附件需要清除。
+
+## 使用建议
+
+- 不要把 `true` 解释为“GPU 资源创建成功”；它仅表示元数据复制完成。
+- 如果你需要真正的附件绑定结果，应关注 framebuffer 创建和 `BeginRenderPass()` 的运行时行为。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLRenderPass](OpenGLRenderPass.md)
+- [Shutdown](Shutdown.md)
+- [../OpenGLCommandList/BeginRenderPass.md](../OpenGLCommandList/BeginRenderPass.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/OpenGLRenderPass.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/OpenGLRenderPass.md
index 7fe845e5..99e4e587 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/OpenGLRenderPass.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/OpenGLRenderPass.md
@@ -6,32 +6,73 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLRenderPass` public API。
+**描述**: OpenGL 后端的 render pass 元数据对象，用来保存附件描述并驱动命令列表的清除行为。
 
-## 概述
+## 概览
 
-`OpenGLRenderPass.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`OpenGLRenderPass` 的名字很容易让人联想到 Vulkan 或现代显式图形 API 中的“原生 render pass 对象”，但当前实现并不是这样。
 
-## 声明概览
+在 `XCEngine` 的 OpenGL 后端里，这个类型更接近一份 CPU 侧描述数据:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLRenderPass` | `class` | 继承自 `RHIRenderPass` 的公开声明。 |
+- 记录颜色附件数量和对应的 `AttachmentDesc`
+- 可选地记录一个深度/模板附件描述
+- 在命令列表开始渲染阶段时，为 clear/load 逻辑提供依据
 
-## 公共方法
+它本身不创建 OpenGL driver object，也不负责保存 framebuffer。
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLRenderPass()](Constructor.md) | 构造对象。 |
-| [~OpenGLRenderPass()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [GetColorAttachmentCount](GetColorAttachmentCount.md) | 获取相关状态或对象。 |
-| [GetColorAttachments](GetColorAttachments.md) | 获取相关状态或对象。 |
-| [GetDepthStencilAttachment](GetDepthStencilAttachment.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
+## 为什么这样设计
+
+这种做法是跨后端 RHI 很常见的折中方案:
+
+- 在 Vulkan / D3D12 侧，render pass 往往有更强的显式契约意义。
+- 在 OpenGL 侧，很多行为最终还是通过“绑定 framebuffer 然后执行 clear / draw”来完成。
+- 因此引擎保留统一的 `RHIRenderPass` 抽象，但允许 OpenGL 后端把它退化为元数据容器。
+
+这样做的好处是:
+
+- 上层渲染代码仍然能保持一致的 `BeginRenderPass()` 调用序列。
+- 文档和接口可以保留“附件装载/清除策略”的设计概念。
+
+代价是:
+
+- `OpenGLRenderPass` 不能像 D3D12/Vulkan 那样被理解为强语义的后端对象。
+- `GetNativeHandle()` 没有可返回的原生句柄。
+
+## 生命周期
+
+- 构造后对象为空，只保存默认状态。
+- 调用 [Initialize](Initialize.md) 后复制附件描述。
+- 调用 [Shutdown](Shutdown.md) 或析构后，内部数组和标志被清空。
+
+## 线程语义
+
+- 当前实现没有任何锁。
+- 应把它视为渲染设备初始化线程或渲染线程中的普通 RHI 对象，不应在多线程下并发初始化和销毁。
+
+## 当前实现的真实行为
+
+- 只保存 `AttachmentDesc` 副本，不创建原生对象。
+- [GetNativeHandle](GetNativeHandle.md) 始终返回 `nullptr`。
+- [OpenGLCommandList::BeginRenderPass](../OpenGLCommandList/BeginRenderPass.md) 会读取这些附件描述:
+  - 对颜色附件执行 `glClearBufferfv(GL_COLOR, ...)`
+  - 对深度附件执行 `glClearBufferfv(GL_DEPTH, ...)`
+  - 对模板附件执行 `glClearBufferfv(GL_STENCIL, ...)`
+- `tests/RHI/unit/test_render_pass.cpp` 验证了附件计数、深度附件访问、`Shutdown()` 复位和空 native handle 等行为。
+
+## 当前限制
+
+- 不保存 store-op 的完整后端语义；当前实现重点在 clear/load。
+- 不对应独立的 OpenGL 原生对象，因此无法像 Vulkan render pass 那样参与更细粒度的兼容性分析。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [GetColorAttachments](GetColorAttachments.md)
+- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)
+- [OpenGLCommandList::BeginRenderPass](../OpenGLCommandList/BeginRenderPass.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Shutdown.md
index f41158e6..8aba386c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderPass/Shutdown.md
@@ -1,30 +1,26 @@
 # OpenGLRenderPass::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清空 `OpenGLRenderPass` 当前保存的附件元数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 清空 `m_colorAttachments`。
+- 把 `m_colorAttachmentCount` 设回 `0`。
+- 把 `m_hasDepthStencil` 设回 `false`。
+- 不会主动修改 `m_depthStencilAttachment` 的历史内容，但由于 `m_hasDepthStencil` 被清零，后续接口不会再把它暴露出去。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderPass object;
-    // 根据上下文补齐参数后调用 OpenGLRenderPass::Shutdown(...)。
-    (void)object;
-}
-```
+- 可以安全重复调用；测试中也覆盖了 double shutdown 的路径。
+- 调用后，之前通过 `GetColorAttachments()` 或 `GetDepthStencilAttachment()` 获取的指针都不应继续使用。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderPass.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLRenderPass](OpenGLRenderPass.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Bind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Bind.md
index aa792594..14bd6215 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Bind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Bind.md
@@ -1,46 +1,36 @@
 # OpenGLRenderTargetView::Bind
 
-公开方法，详见头文件声明。
-
-该方法在 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 void Bind(unsigned int slot = 0);
-```
-
-**参数：**
-- `slot` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void Bind(unsigned int count, const unsigned int* framebuffers, const int* drawBuffers);
 ```
 
-**参数：**
-- `count` - 参数语义详见头文件声明。
-- `framebuffers` - 参数语义详见头文件声明。
-- `drawBuffers` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `void` - 无返回值。
+把一个或多个 framebuffer 绑定到当前 OpenGL 上下文。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+### `Bind(unsigned int slot = 0)`
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::Bind(...)。
-    (void)object;
-}
-```
+- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`。
+- `slot` 参数当前被忽略，只是为了维持接口形状。
+
+### `Bind(unsigned int count, const unsigned int* framebuffers, const int* drawBuffers)`
+
+- 当 `count == 1` 时，只绑定 `framebuffers[0]`。
+- 当 `count > 1` 时:
+  - 先绑定默认 framebuffer `0`
+  - 然后循环绑定每个 framebuffer
+  - 每次调用 `glDrawBuffers(1, &drawBuffers[i])`
+- 这种“逐个绑定并切换 draw buffer”的行为更像旧式辅助函数，并不是现代 MRT 绑定的理想抽象。
+
+## 使用建议
+
+- 单目标渲染时优先使用无参版本，它的行为最直接。
+- 多渲染目标场景更推荐走 [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md) 或 [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md) 的新路径。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
+- [Unbind](Unbind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/BindFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/BindFramebuffer.md
index e56dec4c..b8a855ce 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/BindFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/BindFramebuffer.md
@@ -1,31 +1,27 @@
 # OpenGLRenderTargetView::BindFramebuffer
 
-公开方法，详见头文件声明。
-
 ```cpp
 static void BindFramebuffer(unsigned int framebuffer);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `framebuffer` - 参数语义详见头文件声明。
+静态绑定指定的 framebuffer。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `framebuffer`: 需要绑定的 OpenGL framebuffer id。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::BindFramebuffer(...)。
-    (void)object;
-}
-```
+- 仅执行 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`。
+- 不校验 `framebuffer` 是否有效，也不保存之前的绑定状态。
+
+## 使用建议
+
+- 这是一个极薄的静态包装，适合在工具代码或测试代码中直接切换 FBO。
+- 如果你需要面向 RHI 抽象层的绑定流程，更推荐使用 [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md) 或命令列表接口。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [UnbindFramebuffer](UnbindFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Clear.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Clear.md
index f82a054b..ffc40702 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Clear.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Clear.md
@@ -1,52 +1,39 @@
 # OpenGLRenderTargetView::Clear
 
-清空内部数据。
-
-该方法在 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 void Clear(float r, float g, float b, float a);
-```
-
-**参数：**
-- `r` - 参数语义详见头文件声明。
-- `g` - 参数语义详见头文件声明。
-- `b` - 参数语义详见头文件声明。
-- `a` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void Clear(float r, float g, float b, float a, float depth, uint8_t stencil);
 ```
 
-**参数：**
-- `r` - 参数语义详见头文件声明。
-- `g` - 参数语义详见头文件声明。
-- `b` - 参数语义详见头文件声明。
-- `a` - 参数语义详见头文件声明。
-- `depth` - 参数语义详见头文件声明。
-- `stencil` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `void` - 无返回值。
+清除当前 `OpenGLRenderTargetView` 关联的 framebuffer。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+### `Clear(float r, float g, float b, float a)`
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::Clear(...)。
-    (void)object;
-}
-```
+- 绑定 `m_framebuffer`。
+- 调用 `glClearColor(r, g, b, a)`。
+- 调用 `glClear(GL_COLOR_BUFFER_BIT)`。
+
+### `Clear(float r, float g, float b, float a, float depth, uint8_t stencil)`
+
+- 绑定 `m_framebuffer`。
+- 依次设置颜色、深度和模板清除值。
+- 调用 `glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`。
+
+## 重要限制
+
+- 两个重载都不会恢复清除前的 framebuffer 绑定状态。
+- 该类型本身只附加颜色附件；如果 framebuffer 实际没有深度/模板附件，第二个重载里的深度/模板清除并不代表一定存在有效目标。
+
+## 使用建议
+
+- 在显式命令列表体系下，更推荐通过 render pass + framebuffer 的组合表达清除意图。
+- 如果直接调用该接口，调用方应自己管理前后绑定状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Constructor.md
index 11c1b466..00c7ffa9 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Constructor.md
@@ -1,28 +1,30 @@
-# OpenGLRenderTargetView::OpenGLRenderTargetView()
-
-构造对象。
+# OpenGLRenderTargetView::OpenGLRenderTargetView
 
 ```cpp
 OpenGLRenderTargetView();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 render target view 辅助对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 使用默认值初始化:
+  - `m_texture = 0`
+  - `m_framebuffer = 0`
+  - `m_mipLevel = 0`
+  - `m_width = 0`
+  - `m_height = 0`
+  - `m_type = RenderTargetType::Texture2D`
+- 不执行任何 OpenGL 调用。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-}
-```
+- 构造后应调用 [Initialize](Initialize.md) 或 [InitializeCubemap](InitializeCubemap.md)。
+- 不要把默认的 `m_width` / `m_height` 视为纹理真实尺寸，它们在当前实现中不会被后续初始化更新。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Destructor.md
index 68841d2c..0973179a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Destructor.md
@@ -1,29 +1,24 @@
-# OpenGLRenderTargetView::~OpenGLRenderTargetView()
-
-销毁对象并释放相关资源。
+# OpenGLRenderTargetView::~OpenGLRenderTargetView
 
 ```cpp
 ~OpenGLRenderTargetView();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象并删除它创建的 framebuffer。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
+- 会删除 `m_framebuffer`，并在 `m_framebuffers` 非空时批量删除其中保存的 framebuffer id。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 如果对象已经手动 `Shutdown()` 过，析构再次调用也是安全的。
+- 该析构不会删除关联的纹理对象，只删除本类型自己创建的 FBO。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [GetTexture](GetTexture.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetFramebuffer.md
index 80729fdf..69421124 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetFramebuffer.md
@@ -1,30 +1,24 @@
 # OpenGLRenderTargetView::GetFramebuffer
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetFramebuffer() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该对象内部管理的 framebuffer id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 初始化成功后返回非零 FBO id。
+- 构造后、初始化失败后或 `Shutdown()` 之后返回 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetFramebuffer(...)。
-    (void)object;
-}
-```
+- 这是直接返回成员变量的轻量 getter。
+- 返回的是该辅助类自己创建的独立 FBO，不是引擎新路径中 `OpenGLFramebuffer` 对象的句柄。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetHeight.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetHeight.md
index a313c280..b671dd1e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetHeight.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetHeight.md
@@ -1,30 +1,24 @@
 # OpenGLRenderTargetView::GetHeight
 
-获取相关状态或对象。
-
 ```cpp
 int GetHeight() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回对象记录的高度值。
 
-**返回：** `int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 当前实现始终返回成员 `m_height`。
+- 但 `Initialize()` 和 `InitializeCubemap()` 都没有给 `m_height` 赋值，因此它通常保持构造时的 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetHeight(...)。
-    (void)object;
-}
-```
+- 不要依赖该方法获取真实纹理尺寸。
+- 如果你需要宽高，应直接查询创建该 view 的纹理对象，或使用更新后的 framebuffer / resource view 路径。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetWidth](GetWidth.md)
+- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetMipLevel.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetMipLevel.md
index 571047d1..cd542860 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetMipLevel.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetMipLevel.md
@@ -1,30 +1,23 @@
 # OpenGLRenderTargetView::GetMipLevel
 
-获取相关状态或对象。
-
 ```cpp
 int GetMipLevel() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前绑定到该 RTV 的 mip 级别。
 
-**返回：** `int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回最近一次 `Initialize()` / `InitializeCubemap()` 保存到 `m_mipLevel` 的值。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetMipLevel(...)。
-    (void)object;
-}
-```
+- 这是直接返回成员变量的 getter。
+- 单元测试 `tests/RHI/OpenGL/unit/test_render_target_view.cpp` 会校验 2D 初始化后的 mip 值。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [InitializeCubemap](InitializeCubemap.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetTexture.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetTexture.md
index 0461136b..c587d2d1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetTexture.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetTexture.md
@@ -1,30 +1,25 @@
 # OpenGLRenderTargetView::GetTexture
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetTexture() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 当前关联的纹理 id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `m_texture`。
+- 在尚未初始化时通常为 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetTexture(...)。
-    (void)object;
-}
-```
+- 该值在 `Initialize()` / `InitializeCubemap()` 时写入。
+- 该接口只暴露原生纹理 id，不提供纹理对象本身的生命周期管理。
+- 单元测试会校验返回值与初始化时传入的纹理 id 一致。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetWidth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetWidth.md
index d93825f3..d4845f77 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetWidth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/GetWidth.md
@@ -1,30 +1,24 @@
 # OpenGLRenderTargetView::GetWidth
 
-获取相关状态或对象。
-
 ```cpp
 int GetWidth() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回对象记录的宽度值。
 
-**返回：** `int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 当前实现始终返回成员 `m_width`。
+- 但 `Initialize()` 和 `InitializeCubemap()` 没有更新该成员，因此通常仍为 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetWidth(...)。
-    (void)object;
-}
-```
+- 该返回值目前更像占位字段，不应被当作可靠尺寸来源。
+- 实际渲染尺寸应以纹理描述或上层 framebuffer 配置为准。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetHeight](GetHeight.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Initialize.md
index 8ad6826f..011bcff8 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Initialize.md
@@ -1,46 +1,57 @@
 # OpenGLRenderTargetView::Initialize
 
-初始化内部状态。
-
-该方法在 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 bool Initialize(unsigned int texture, const OpenGLRenderTargetViewDesc& desc);
-```
-
-**参数：**
-- `texture` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-
-**返回：** `bool` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool Initialize(unsigned int texture, int mipLevel = 0);
 ```
 
-**参数：**
-- `texture` - 参数语义详见头文件声明。
-- `mipLevel` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+为给定纹理创建一个独立的 framebuffer，并把一个颜色附件绑定到 `GL_COLOR_ATTACHMENT0`。
 
-**示例：**
+## 参数说明
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+- `texture`: OpenGL 纹理 id。
+- `desc`: 旧式 RTV 描述结构，指定纹理类型、mip、数组层或立方体面。
+- `mipLevel`: `Texture2D` 简化重载使用的 mip 级别。
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::Initialize(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- framebuffer 完整时返回 `true`。
+- `glCheckFramebufferStatus(GL_FRAMEBUFFER) != GL_FRAMEBUFFER_COMPLETE` 时返回 `false`。
+
+## 当前实现行为
+
+### `Initialize(unsigned int texture, const OpenGLRenderTargetViewDesc& desc)`
+
+- 保存 `m_texture`、`m_mipLevel` 和 `m_type`。
+- 调用 `glGenFramebuffers()` 创建独立 FBO。
+- 把目标附件固定绑定到 `GL_COLOR_ATTACHMENT0`。
+- 根据 `desc.type` 选择不同附着路径:
+  - `Texture2D`: `glFramebufferTexture2D`
+  - `Texture2DArray`: `glFramebufferTextureLayer`
+  - `Texture3D`: `glFramebufferTextureLayer`
+  - `TextureCube`: `glFramebufferTexture2D(GL_TEXTURE_CUBE_MAP_POSITIVE_X + desc.baseArraySlice, ...)`
+  - `TextureCubeArray`: `glFramebufferTextureLayer`
+- 完成后检查 FBO 完整性，并在退出前解绑 `GL_FRAMEBUFFER`。
+
+### `Initialize(unsigned int texture, int mipLevel = 0)`
+
+- 构造一个 `Texture2D` 的默认描述。
+- 然后转调主重载。
+
+## 重要限制
+
+- 该类型只处理单颜色附件。
+- 即使初始化成功，`m_width` / `m_height` 仍不会被写入。
+- 初始化失败时，函数会解绑 framebuffer 并返回 `false`，但已经创建出的 FBO id 仍依赖后续 `Shutdown()` 统一删除。
+
+## 使用建议
+
+- 在现代 RHI 流程中，更推荐使用 [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md) 与 [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md) 的组合。
+- 该类更适合兼容旧路径、快速工具渲染或测试。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeCubemap](InitializeCubemap.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/InitializeCubemap.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/InitializeCubemap.md
index b3afce53..d1f4478c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/InitializeCubemap.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/InitializeCubemap.md
@@ -1,33 +1,36 @@
 # OpenGLRenderTargetView::InitializeCubemap
 
-初始化内部状态。
-
 ```cpp
 bool InitializeCubemap(unsigned int cubemap, int face, int mipLevel = 0);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `cubemap` - 参数语义详见头文件声明。
-- `face` - 参数语义详见头文件声明。
-- `mipLevel` - 参数语义详见头文件声明。
+为立方体贴图的单个面创建一个颜色渲染目标。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数说明
 
-**示例：**
+- `cubemap`: 立方体贴图的 OpenGL 纹理 id。
+- `face`: 立方体面索引，会直接映射到 `GL_TEXTURE_CUBE_MAP_POSITIVE_X + face`。
+- `mipLevel`: 需要附着的 mip 级别。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::InitializeCubemap(...)。
-    (void)object;
-}
-```
+- framebuffer 完整时返回 `true`，否则返回 `false`。
+
+## 当前实现行为
+
+- 保存 `m_texture`、`m_mipLevel` 和 `m_type = RenderTargetType::TextureCube`。
+- 创建独立 FBO。
+- 使用 `glFramebufferTexture2D` 把指定 cube face 绑定到 `GL_COLOR_ATTACHMENT0`。
+- 检查 FBO 完整性后解绑 `GL_FRAMEBUFFER`。
+
+## 使用建议
+
+- `face` 参数当前不会额外校验范围，调用方应确保它位于立方体面的有效区间。
+- 如果你需要表达 cubemap array 或多附件渲染，建议改用新路径，而不是继续扩展这个旧辅助类。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetMipLevel](GetMipLevel.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/OpenGLRenderTargetView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/OpenGLRenderTargetView.md
index 9532286f..f66e717a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/OpenGLRenderTargetView.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/OpenGLRenderTargetView.md
@@ -6,41 +6,66 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLRenderTargetView` public API。
+**描述**: 旧式 OpenGL 颜色渲染目标辅助类，内部为单个纹理附件创建独立 framebuffer。
 
-## 概述
+## 概览
 
-`OpenGLRenderTargetView.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`OpenGLRenderTargetView` 来自较早的 OpenGL 封装路径。它的核心思路非常直接:
 
-## 声明概览
+- 接收一个已经存在的纹理 id
+- 创建一个专属 framebuffer
+- 把该纹理的某个 mip、数组层或 cubemap face 附着到 `GL_COLOR_ATTACHMENT0`
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `RenderTargetType` | `enum class` | 头文件中的公开声明。 |
-| `OpenGLRenderTargetViewDesc` | `struct` | 头文件中的公开声明。 |
-| `OpenGLRenderTargetView` | `class` | 头文件中的公开声明。 |
+这和现代显式图形 API 中的 render-target view 概念有相似之处，但在当前引擎里，它已经与更新的 `OpenGLFramebuffer + OpenGLResourceView` 方案产生职责重叠。
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLRenderTargetView()](Constructor.md) | 构造对象。 |
-| [~OpenGLRenderTargetView()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [InitializeCubemap](InitializeCubemap.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
-| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
-| [Clear](Clear.md) | 清空内部数据。 |
-| [GetFramebuffer](GetFramebuffer.md) | 获取相关状态或对象。 |
-| [GetTexture](GetTexture.md) | 获取相关状态或对象。 |
-| [GetMipLevel](GetMipLevel.md) | 获取相关状态或对象。 |
-| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
-| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
-| [BindFramebuffer](BindFramebuffer.md) | 公开方法，详见头文件声明。 |
-| [UnbindFramebuffer](UnbindFramebuffer.md) | 公开方法，详见头文件声明。 |
+可以把这个类理解成“快速创建单附件 FBO 的旧工具层”。
+
+它的优点是:
+
+- 实现非常直观
+- 测试与工具代码里使用成本低
+- 不需要先构造更完整的 framebuffer 描述
+
+它的缺点也很明显:
+
+- 只覆盖单颜色附件路径
+- 没有和统一的 descriptor / framebuffer 体系深度融合
+- `GetWidth()` / `GetHeight()` 这类字段没有真正维护
+
+如果你在构建商业级渲染架构，新的 `OpenGLFramebuffer` / `OpenGLResourceView` 路径更接近统一 RHI 的长期方案。
+
+## 生命周期
+
+- 构造时不创建任何 OpenGL 对象。
+- `Initialize()` / `InitializeCubemap()` 成功后持有一个独立 FBO。
+- `Shutdown()` 或析构时删除该 FBO。
+
+## 线程语义
+
+- 当前实现没有同步保护。
+- 所有调用都应视为依赖当前 OpenGL 上下文，通常应在拥有该上下文的渲染线程执行。
+
+## 当前实现的真实行为
+
+- 只操作颜色附件，不直接表达深度/模板附件创建。
+- `Bind(slot)` 的 `slot` 参数被忽略。
+- 多 framebuffer 的 `Bind(count, ...)` 是一套明显偏旧的辅助逻辑，不等价于现代 MRT 抽象。
+- `Clear()` 不会恢复之前的 framebuffer 绑定。
+- `GetWidth()` / `GetHeight()` 当前基本恒为 `0`。
+- 单元测试 `tests/RHI/OpenGL/unit/test_render_target_view.cpp` 只覆盖了初始化、绑定/解绑、纹理 id 和 mip 访问这些基础能力。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [InitializeCubemap](InitializeCubemap.md)
+- [Bind](Bind.md)
+- [Clear](Clear.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)
+- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Shutdown.md
index 1d1f6822..da27cf85 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Shutdown.md
@@ -1,30 +1,25 @@
 # OpenGLRenderTargetView::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+删除该对象创建的 framebuffer，并清理批量 framebuffer 缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers(1, &m_framebuffer)`，然后把它重置为 `0`。
+- 如果 `m_framebuffers` 非空，调用 `glDeleteFramebuffers(count, data)` 后清空数组。
+- 不会重置 `m_texture`、`m_mipLevel`、`m_width`、`m_height` 或 `m_type`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::Shutdown(...)。
-    (void)object;
-}
-```
+- 调用后，`GetFramebuffer()` 会变成 `0`，但 `GetTexture()` 仍可能返回旧值，因为纹理句柄没有被清空。
+- 如果你依赖“完全复位”的对象状态，应该销毁对象并重新构造，而不是只依赖 `Shutdown()`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Unbind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Unbind.md
index 0ef4e355..beb10f61 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Unbind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/Unbind.md
@@ -1,30 +1,19 @@
 # OpenGLRenderTargetView::Unbind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Unbind();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+解绑当前 framebuffer，恢复到默认 framebuffer `0`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::Unbind(...)。
-    (void)object;
-}
-```
+- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
+- 不恢复 draw buffer、viewport 或其他状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [UnbindFramebuffer](UnbindFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/UnbindFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/UnbindFramebuffer.md
index c8880519..91e80e9b 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/UnbindFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLRenderTargetView/UnbindFramebuffer.md
@@ -1,30 +1,19 @@
 # OpenGLRenderTargetView::UnbindFramebuffer
 
-公开方法，详见头文件声明。
-
 ```cpp
 static void UnbindFramebuffer();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+静态解绑当前 framebuffer。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLRenderTargetView object;
-    // 根据上下文补齐参数后调用 OpenGLRenderTargetView::UnbindFramebuffer(...)。
-    (void)object;
-}
-```
+- 仅执行 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
+- 行为与实例方法 [Unbind](Unbind.md) 一致，只是无需依赖对象实例。
 
 ## 相关文档
 
-- [返回类总览](OpenGLRenderTargetView.md)
-- [返回模块目录](../OpenGL.md)
+- [BindFramebuffer](BindFramebuffer.md)
+- [Unbind](Unbind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Constructor.md
index c2bef8c1..6e7a81b5 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Constructor.md
@@ -1,28 +1,32 @@
-# OpenGLResourceView::OpenGLResourceView()
-
-构造对象。
+# OpenGLResourceView::OpenGLResourceView
 
 ```cpp
 OpenGLResourceView();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的统一资源视图对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 构造函数会设置一组默认值:
+  - `m_viewType = ResourceViewType::RenderTarget`
+  - `m_format = Format::Unknown`
+  - `m_dimension = ResourceViewDimension::Unknown`
+  - `m_framebufferID = 0`
+  - `m_textureUnit = -1`
+  - `m_bindingPoint = -1`
+  - 各类对象指针为空
+  - buffer 相关缓存为 `0`
+- 不执行任何 OpenGL 调用。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-}
-```
+- 构造后对象还没有实际资源语义，必须调用某个 `InitializeAs...` 方法。
+- 不应把默认的 `RenderTarget` 类型误认为对象已经是一个可用 RTV。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetViewType](GetViewType.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Destructor.md
index 50e0186b..d94b8f6c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Destructor.md
@@ -1,29 +1,20 @@
-# OpenGLResourceView::~OpenGLResourceView()
-
-销毁对象并释放相关资源。
+# OpenGLResourceView::~OpenGLResourceView
 
 ```cpp
 ~OpenGLResourceView() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 `OpenGLResourceView`，并释放它占用的纹理单元或 UBO 绑定点。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
+- 如果该 view 曾经作为 UAV 或常量缓冲视图分配过绑定资源，析构时会一并释放。
+- 不会销毁底层纹理、缓冲区或 framebuffer 对象本身，这些资源由外部对象拥有。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [OpenGLResourceView](OpenGLResourceView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBindingPoint.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBindingPoint.md
index 14eec01e..c9e9596f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBindingPoint.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBindingPoint.md
@@ -1,30 +1,24 @@
 # OpenGLResourceView::GetBindingPoint
 
-获取相关状态或对象。
-
 ```cpp
 int32_t GetBindingPoint() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 占用的 uniform buffer 绑定点。
 
-**返回：** `int32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 对常量缓冲视图返回有效绑定点编号。
+- 对其他 view 类型通常返回构造默认值 `-1`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetBindingPoint(...)。
-    (void)object;
-}
-```
+- 仅 [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md) 会写入该字段。
+- `Shutdown()` 释放绑定点后会把它重置为 `-1`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBuffer.md
index 9fa15986..65dc208a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBuffer.md
@@ -1,30 +1,24 @@
 # OpenGLResourceView::GetBuffer
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetBuffer() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 关联的 OpenGL buffer id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 如果 `m_buffer` 有效，返回其 `GetID()`。
+- 否则返回 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetBuffer(...)。
-    (void)object;
-}
-```
+- 顶点缓冲、索引缓冲和常量缓冲视图都会使用该接口暴露底层 buffer id。
+- 该接口不区分 buffer 的用途，调用方应结合 [GetViewType](GetViewType.md) 判断具体语义。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetViewType](GetViewType.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferOffset.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferOffset.md
index cb9da241..a3797eed 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferOffset.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferOffset.md
@@ -1,30 +1,25 @@
 # OpenGLResourceView::GetBufferOffset
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetBufferOffset() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 记录的缓冲区偏移。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 仅 [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md) 和 [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md) 会把 `desc.bufferLocation` 写入该字段。
+- 常量缓冲视图当前不会把偏移保存在这里，因此 CBV 场景下通常仍为 `0`。
+- `Shutdown()` 会把它重置为 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetBufferOffset(...)。
-    (void)object;
-}
-```
+- 在命令列表里，该值会参与顶点/索引缓冲绑定偏移计算。
+- 不要假设它能反映 `BindBufferRange` 式的常量缓冲区范围信息；当前实现并没有做到这一层。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferSize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferSize.md
index 4752cd2e..b32279ad 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferSize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferSize.md
@@ -1,30 +1,20 @@
 # OpenGLResourceView::GetBufferSize
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetBufferSize() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 缓存的缓冲区大小。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetBufferSize(...)。
-    (void)object;
-}
-```
+- 顶点缓冲和索引缓冲初始化时，都会把 `buffer->GetSize()` 的完整结果写入该字段。
+- 这意味着它表示“底层缓冲总大小”，不是“从偏移开始的剩余可见范围”。
+- 对常量缓冲或纹理类 view，该值通常保持为 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferStride.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferStride.md
index 8bae9feb..598ed059 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferStride.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetBufferStride.md
@@ -1,30 +1,27 @@
 # OpenGLResourceView::GetBufferStride
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetBufferStride() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 记录的元素步长。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 顶点缓冲视图:
+  - 如果 `desc.structureByteStride > 0`，优先使用它。
+  - 否则退回到底层 `buffer->GetStride()`。
+- 索引缓冲视图使用 `buffer->GetStride()`。
+- 其他类型通常保持为 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetBufferStride(...)。
-    (void)object;
-}
-```
+- `OpenGLCommandList::SetVertexBuffers()` 会用这个值推导 `glVertexAttribPointer` 的步长。
+- 对索引缓冲来说，真正的索引类型仍由 [GetFormat](GetFormat.md) 决定。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetDimension.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetDimension.md
index 1c52dbf5..bc64015c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetDimension.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetDimension.md
@@ -1,30 +1,20 @@
 # OpenGLResourceView::GetDimension
 
-获取相关状态或对象。
-
 ```cpp
 ResourceViewDimension GetDimension() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 当前记录的维度信息。
 
-**返回：** `ResourceViewDimension` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetDimension(...)。
-    (void)object;
-}
-```
+- 纹理类 view 会直接采用 `ResourceViewDesc::dimension`。
+- 顶点缓冲、索引缓冲和常量缓冲视图会把它设置为 `ResourceViewDimension::Buffer`。
+- 构造后默认值为 `ResourceViewDimension::Unknown`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
+- [InitializeAsShaderResource](InitializeAsShaderResource.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFormat.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFormat.md
index 337d685e..782ccf6a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFormat.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFormat.md
@@ -1,30 +1,25 @@
 # OpenGLResourceView::GetFormat
 
-获取相关状态或对象。
-
 ```cpp
 Format GetFormat() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 记录的格式。
 
-**返回：** `Format` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 纹理类 view 优先使用 `ResourceViewDesc::format`，如果未显式指定则退回到底层纹理格式。
+- 索引缓冲视图会使用 `desc.format`，未指定时默认 `Format::R32_UInt`。
+- 顶点缓冲和常量缓冲视图当前固定保存为 `Format::Unknown`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetFormat(...)。
-    (void)object;
-}
-```
+- 在 OpenGL 后端中，这个格式更多是引擎侧元数据，不总能一一对应到真正的 OpenGL view format 对象。
+- 对索引缓冲场景，该值会影响命令列表选择 `GL_UNSIGNED_SHORT` 或 `GL_UNSIGNED_INT` 等索引类型。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebuffer.md
index c3458024..728c38b6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebuffer.md
@@ -1,30 +1,25 @@
 # OpenGLResourceView::GetFramebuffer
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetFramebuffer() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 关联的 framebuffer id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 如果 `m_framebuffer` 有效，返回 `m_framebuffer->GetFramebuffer()`。
+- 否则返回 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetFramebuffer(...)。
-    (void)object;
-}
-```
+- 该接口主要对渲染目标视图和深度/模板视图有意义。
+- 它通过 `m_framebuffer` 指针查询当前 id，而不是直接返回缓存的 `m_framebufferID`。
+- `IsValid()` 对 RTV/DSV 的校验使用的是 `m_framebufferID != 0`，这两个接口的来源略有差异，但在正常生命周期里应保持一致。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
+- [InitializeAsDepthStencil](InitializeAsDepthStencil.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebufferAttachment.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebufferAttachment.md
index 3fe72085..01f66d60 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebufferAttachment.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetFramebufferAttachment.md
@@ -1,30 +1,31 @@
 # OpenGLResourceView::GetFramebufferAttachment
 
-获取相关状态或对象。
-
 ```cpp
 const FramebufferAttachment& GetFramebufferAttachment() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 缓存的 framebuffer 附件描述。
 
-**返回：** `const FramebufferAttachment&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 仅渲染目标和深度/模板视图会在初始化时填充这个结构。
+- 缓存内容包括:
+  - 纹理 id
+  - 目标 `GLenum`
+  - mip 级别
+  - layer
+  - 附件类型
+  - 格式
+- `Shutdown()` 会把它重置为默认值。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetFramebufferAttachment(...)。
-    (void)object;
-}
-```
+- `OpenGLFramebuffer` 的统一初始化路径会消费该结构来重新组装 FBO。
+- 对 buffer 类 view，这个结构没有实际意义。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
+- [InitializeAsDepthStencil](InitializeAsDepthStencil.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetNativeHandle.md
index 561230a8..ce8d239a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetNativeHandle.md
@@ -1,30 +1,31 @@
 # OpenGLResourceView::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 对应的底层原生句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 顶点缓冲 / 索引缓冲 / 常量缓冲视图: 返回底层 buffer id。
+- 渲染目标 / 深度模板视图: 返回 framebuffer id。
+- SRV / UAV: 返回底层纹理 id。
+- 未知类型: 返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 这个接口不会创建任何新的 OpenGL 对象，只是根据 `m_viewType` 把已有 id 转成 `void*`。
+- 它暴露的是“当前这类 view 在 OpenGL 下最接近原生句柄的对象”，但不同 view 类型的含义完全不同。
+
+## 使用建议
+
+- 调用方不能把不同 `ResourceViewType` 返回的句柄当作同一种资源解释。
+- 如果需要稳定地按类型访问资源，应优先使用 [GetTexture](GetTexture.md)、[GetBuffer](GetBuffer.md)、[GetFramebuffer](GetFramebuffer.md) 这类显式接口。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetViewType](GetViewType.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTexture.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTexture.md
index 437ba0ee..1c725c73 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTexture.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTexture.md
@@ -1,30 +1,24 @@
 # OpenGLResourceView::GetTexture
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetTexture() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 关联的 OpenGL 纹理 id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 如果 `m_texture` 有效，返回其 `GetID()`。
+- 否则返回 `0`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetTexture(...)。
-    (void)object;
-}
-```
+- 该接口对 RTV、DSV、SRV、UAV 都有意义。
+- 顶点/索引/常量缓冲视图通常返回 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetTextureResource](GetTextureResource.md)
+- [GetTextureUnit](GetTextureUnit.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureResource.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureResource.md
index 030bdd39..aeb28751 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureResource.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureResource.md
@@ -1,30 +1,29 @@
 # OpenGLResourceView::GetTextureResource
 
-获取相关状态或对象。
-
 ```cpp
 const OpenGLTexture* GetTextureResource() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 `OpenGLTexture` 对象指针。
 
-**返回：** `const OpenGLTexture*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 如果该 view 基于纹理创建，返回对应的 `OpenGLTexture*`。
+- 否则返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetTextureResource(...)。
-    (void)object;
-}
-```
+- `OpenGLCommandList::TransitionBarrier()` 会通过该接口拿到纹理对象并更新其引擎侧状态。
+- `OpenGLCommandList::SetRenderTargets()` 也会读取这里的纹理宽高和纹理 id 来组装组合 framebuffer。
+
+## 使用建议
+
+- 这是比 [GetTexture](GetTexture.md) 更强的接口，因为它暴露了纹理对象本身。
+- 调用方不拥有返回对象的生命周期，不应自行销毁。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetTexture](GetTexture.md)
+- [../OpenGLTexture/OpenGLTexture.md](../OpenGLTexture/OpenGLTexture.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureUnit.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureUnit.md
index 36ebe0ad..92d20d1f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureUnit.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetTextureUnit.md
@@ -1,30 +1,20 @@
 # OpenGLResourceView::GetTextureUnit
 
-获取相关状态或对象。
-
 ```cpp
 int32_t GetTextureUnit() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 view 占用的纹理单元编号。
 
-**返回：** `int32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetTextureUnit(...)。
-    (void)object;
-}
-```
+- 对 UAV，返回通过 `OpenGLTextureUnitAllocator` 分配到的 unit。
+- 对 SRV，当前仍为 `-1`，因为初始化时不会分配纹理单元。
+- 其他类型通常也返回 `-1`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [InitializeAsShaderResource](InitializeAsShaderResource.md)
+- [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetViewType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetViewType.md
index 61babac3..8b9230f0 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetViewType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/GetViewType.md
@@ -1,30 +1,24 @@
 # OpenGLResourceView::GetViewType
 
-获取相关状态或对象。
-
 ```cpp
 ResourceViewType GetViewType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该对象当前表示的 view 类型。
 
-**返回：** `ResourceViewType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 构造时默认值是 `ResourceViewType::RenderTarget`。
+- 各种 `InitializeAs...` 方法会把它改写为对应类型。
+- 这意味着“尚未初始化的对象”在类型上看起来像 RTV，但 [IsValid](IsValid.md) 仍会返回 `false`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::GetViewType(...)。
-    (void)object;
-}
-```
+- 不应只依赖 `GetViewType()` 判断对象是否可用，必须与 `IsValid()` 结合。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [IsValid](IsValid.md)
+- [OpenGLResourceView](OpenGLResourceView.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsConstantBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsConstantBuffer.md
index 31a63ad6..af957316 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsConstantBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsConstantBuffer.md
@@ -1,33 +1,39 @@
 # OpenGLResourceView::InitializeAsConstantBuffer
 
-初始化内部状态。
-
 ```cpp
-bool InitializeAsConstantBuffer( OpenGLBuffer* buffer, const ResourceViewDesc& desc, OpenGLUniformBufferManager* manager);
+bool InitializeAsConstantBuffer(
+    OpenGLBuffer* buffer,
+    const ResourceViewDesc& desc,
+    OpenGLUniformBufferManager* manager);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffer` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `manager` - 参数语义详见头文件声明。
+把当前对象初始化为常量缓冲视图，并分配一个 uniform buffer 绑定点。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `buffer` 和 `manager` 不能为空。
+- `manager` 内必须还有可用绑定点。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsConstantBuffer(...)。
-    (void)object;
-}
-```
+- 初始化成功返回 `true`。
+- 参数为空或分配绑定点失败时返回 `false`。
+
+## 当前实现行为
+
+- 通过 `manager->Allocate()` 申请一个 binding point。
+- 把 view 类型设置为 `ConstantBuffer`，维度设置为 `Buffer`。
+- 保存 `m_buffer`、`m_bindingPoint` 和 `m_uniformBufferManager`。
+- 调用 `manager->BindBuffer(bindingPoint, buffer, 0, desc.bufferLocation)`。
+
+## 重要限制
+
+- 当前 `OpenGLUniformBufferManager::BindBuffer()` 实际使用的是 `glBindBufferBase`，会忽略传入的 offset 和 size。
+- 因此这个“常量缓冲视图”目前更像“为整块 UBO 绑定一个槽位”，而不是支持任意范围的 CBV。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetBindingPoint](GetBindingPoint.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsDepthStencil.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsDepthStencil.md
index e5becdbb..5975a880 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsDepthStencil.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsDepthStencil.md
@@ -1,33 +1,45 @@
 # OpenGLResourceView::InitializeAsDepthStencil
 
-初始化内部状态。
-
 ```cpp
-bool InitializeAsDepthStencil( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLFramebuffer* framebuffer);
+bool InitializeAsDepthStencil(
+    OpenGLTexture* texture,
+    const ResourceViewDesc& desc,
+    OpenGLFramebuffer* framebuffer);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `texture` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `framebuffer` - 参数语义详见头文件声明。
+把当前对象初始化为深度/模板视图，并缓存该附件在 framebuffer 中的附着信息。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `texture` 和 `framebuffer` 都不能为空。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsDepthStencil(...)。
-    (void)object;
-}
-```
+- 参数有效时返回 `true`，否则返回 `false`。
+
+## 当前实现行为
+
+- 设置 `m_viewType = DepthStencil`。
+- 解析格式:
+  - 如果 `desc.format` 非零，优先使用它。
+  - 否则退回到底层纹理格式。
+- 记录 `m_dimension`、`m_texture`、`m_framebuffer` 和 `m_framebufferID`。
+- 填充 `m_framebufferAttachment`:
+  - 纹理 id
+  - 目标类型
+  - mip 级别
+  - layer
+  - 附件类型为 `Depth` 或 `DepthStencil`
+  - 格式
+
+## 设计说明
+
+- 这里不会创建新的 OpenGL depth-stencil view 对象。
+- 它做的是把“统一 RHI 视图语义”映射为“现有 framebuffer + 附件元数据”的组合。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetFramebufferAttachment](GetFramebufferAttachment.md)
+- [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsIndexBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsIndexBuffer.md
index 6d76706f..1701d29b 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsIndexBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsIndexBuffer.md
@@ -1,32 +1,38 @@
 # OpenGLResourceView::InitializeAsIndexBuffer
 
-初始化内部状态。
-
 ```cpp
-bool InitializeAsIndexBuffer( OpenGLBuffer* buffer, const ResourceViewDesc& desc);
+bool InitializeAsIndexBuffer(
+    OpenGLBuffer* buffer,
+    const ResourceViewDesc& desc);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffer` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
+把当前对象初始化为索引缓冲视图。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `buffer` 不能为空。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsIndexBuffer(...)。
-    (void)object;
-}
-```
+- 成功返回 `true`，参数为空时返回 `false`。
+
+## 当前实现行为
+
+- 设置 `m_viewType = IndexBuffer`。
+- 如果 `desc.format` 已指定，使用该格式；否则默认 `Format::R32_UInt`。
+- 维度固定为 `Buffer`。
+- 记录 `m_buffer`、`m_bufferOffset = desc.bufferLocation`。
+- `m_bufferSize` 保存整个缓冲区大小。
+- `m_bufferStride` 使用底层 `buffer->GetStride()`。
+
+## 使用建议
+
+- 命令列表真正的索引类型解析依赖这个 view 保存的格式。
+- 如果底层缓冲实际是 16 位索引，文档化和创建时应明确设置正确格式，避免默认退回 32 位。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetFormat](GetFormat.md)
+- [GetBufferOffset](GetBufferOffset.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsRenderTarget.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsRenderTarget.md
index a0678911..20746a77 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsRenderTarget.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsRenderTarget.md
@@ -1,33 +1,42 @@
 # OpenGLResourceView::InitializeAsRenderTarget
 
-初始化内部状态。
-
 ```cpp
-bool InitializeAsRenderTarget( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLFramebuffer* framebuffer);
+bool InitializeAsRenderTarget(
+    OpenGLTexture* texture,
+    const ResourceViewDesc& desc,
+    OpenGLFramebuffer* framebuffer);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `texture` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `framebuffer` - 参数语义详见头文件声明。
+把当前对象初始化为颜色渲染目标视图，并缓存它在 framebuffer 中的附着方式。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `texture` 和 `framebuffer` 都不能为空。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsRenderTarget(...)。
-    (void)object;
-}
-```
+- 参数有效时返回 `true`，否则返回 `false`。
+
+## 当前实现行为
+
+- 设置 `m_viewType = RenderTarget`。
+- 解析 view 格式，优先使用 `desc.format`，否则沿用纹理格式。
+- 保存 `m_dimension`、`m_texture`、`m_framebuffer` 和 `m_framebufferID`。
+- 解析附件目标:
+  - `Texture1D` -> `GL_TEXTURE_1D`
+  - `Texture2D` -> `GL_TEXTURE_2D`
+  - `TextureCube` -> `GL_TEXTURE_CUBE_MAP_POSITIVE_X + face`
+  - `Texture2DArray` / `Texture3D` / `TextureCubeArray` -> 通过 layer 表达
+- 填充 `FramebufferAttachment`，并把附件类型标为 `Color`。
+
+## 设计说明
+
+- 该接口不创建新的 OpenGL RTV 对象。
+- 它更像“把一个纹理附件映射为统一 RHI 颜色视图，并缓存后续组装 FBO 所需的元数据”。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetFramebufferAttachment](GetFramebufferAttachment.md)
+- [GetTextureResource](GetTextureResource.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsShaderResource.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsShaderResource.md
index f1200e9c..aab28189 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsShaderResource.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsShaderResource.md
@@ -1,33 +1,38 @@
 # OpenGLResourceView::InitializeAsShaderResource
 
-初始化内部状态。
-
 ```cpp
-bool InitializeAsShaderResource( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLTextureUnitAllocator* allocator);
+bool InitializeAsShaderResource(
+    OpenGLTexture* texture,
+    const ResourceViewDesc& desc,
+    OpenGLTextureUnitAllocator* allocator);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `texture` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `allocator` - 参数语义详见头文件声明。
+把当前对象初始化为着色器资源视图。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `texture` 不能为空。
+- `allocator` 可以为空；当前实现不会立即从中分配纹理单元。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsShaderResource(...)。
-    (void)object;
-}
-```
+- `texture` 有效时返回 `true`，否则返回 `false`。
+
+## 当前实现行为
+
+- 设置 `m_viewType = ShaderResource`。
+- 保存格式、维度和底层纹理指针。
+- 把 `m_textureUnit` 设为 `-1`。
+- 仅保存 `m_textureUnitAllocator` 指针，不进行 `Allocate()`。
+
+## 设计说明
+
+- 这说明当前 OpenGL SRV 只是“纹理资源的只读视图元数据”。
+- 真正把纹理绑定到某个 texture unit 的时机，不是在这个初始化函数里。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetTextureUnit](GetTextureUnit.md)
+- [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsUnorderedAccess.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsUnorderedAccess.md
index cb841919..47dcbd21 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsUnorderedAccess.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsUnorderedAccess.md
@@ -1,33 +1,46 @@
 # OpenGLResourceView::InitializeAsUnorderedAccess
 
-初始化内部状态。
-
 ```cpp
-bool InitializeAsUnorderedAccess( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLTextureUnitAllocator* allocator);
+bool InitializeAsUnorderedAccess(
+    OpenGLTexture* texture,
+    const ResourceViewDesc& desc,
+    OpenGLTextureUnitAllocator* allocator);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `texture` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `allocator` - 参数语义详见头文件声明。
+把当前对象初始化为无序访问视图，并立即把纹理绑定为 image 资源。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `texture` 和 `allocator` 都不能为空。
+- 分配器必须仍有可用纹理单元。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsUnorderedAccess(...)。
-    (void)object;
-}
-```
+- 初始化成功返回 `true`。
+- 参数无效或 `Allocate()` 失败时返回 `false`。
+
+## 当前实现行为
+
+- 先通过 `allocator->Allocate()` 申请一个 texture unit。
+- 保存 view 类型、格式、维度、纹理指针和分配到的 unit。
+- 立即执行:
+  - `glActiveTexture(GL_TEXTURE0 + unit)`
+  - `glBindTexture(textureType, textureID)`
+  - `glBindImageTexture(unit, textureID, 0, GL_FALSE, 0, GL_READ_WRITE, GL_RGBA8)`
+
+## 重要限制
+
+- image 绑定固定使用:
+  - mip `0`
+  - `layered = GL_FALSE`
+  - layer `0`
+  - 访问模式 `GL_READ_WRITE`
+  - 格式 `GL_RGBA8`
+- 也就是说，当前实现并没有把 `ResourceViewDesc` 中的 mip、层、格式完整映射到 image view 语义。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetTextureUnit](GetTextureUnit.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsVertexBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsVertexBuffer.md
index 372f504d..9fda9874 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsVertexBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/InitializeAsVertexBuffer.md
@@ -1,32 +1,39 @@
 # OpenGLResourceView::InitializeAsVertexBuffer
 
-初始化内部状态。
-
 ```cpp
-bool InitializeAsVertexBuffer( OpenGLBuffer* buffer, const ResourceViewDesc& desc);
+bool InitializeAsVertexBuffer(
+    OpenGLBuffer* buffer,
+    const ResourceViewDesc& desc);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffer` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
+把当前对象初始化为顶点缓冲视图。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `buffer` 不能为空。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsVertexBuffer(...)。
-    (void)object;
-}
-```
+- 成功返回 `true`，参数为空时返回 `false`。
+
+## 当前实现行为
+
+- 设置 `m_viewType = VertexBuffer`。
+- 格式固定保存为 `Format::Unknown`。
+- 维度设为 `Buffer`。
+- 记录底层 buffer 指针。
+- `m_bufferOffset = desc.bufferLocation`。
+- `m_bufferSize = buffer->GetSize()`。
+- `m_bufferStride` 优先使用 `desc.structureByteStride`，否则使用底层 buffer 自身 stride。
+
+## 使用建议
+
+- 这个 view 不会创建额外的 OpenGL descriptor 对象。
+- 命令列表真正设置顶点属性时，会把这里缓存的偏移和步长与输入布局拼接起来。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetBufferStride](GetBufferStride.md)
+- [GetBufferOffset](GetBufferOffset.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/IsValid.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/IsValid.md
index de02ce35..b77dcbe1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/IsValid.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/IsValid.md
@@ -1,30 +1,28 @@
 # OpenGLResourceView::IsValid
 
-查询当前状态。
-
 ```cpp
 bool IsValid() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+检查该 view 在当前类型下是否拥有可用的底层资源。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 顶点缓冲 / 索引缓冲: `m_buffer != nullptr && m_buffer->GetID() != 0`
+- 渲染目标 / 深度模板: `m_framebufferID != 0`
+- SRV: `m_texture != nullptr && m_texture->GetID() != 0`
+- UAV: `m_texture != nullptr && m_textureUnit >= 0`
+- 常量缓冲: `m_buffer != nullptr && m_bindingPoint >= 0`
+- 其他情况返回 `false`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::IsValid(...)。
-    (void)object;
-}
-```
+- 这是比 [GetViewType](GetViewType.md) 更可靠的可用性判断。
+- 对 UAV 和 CBV 来说，可用性的关键不仅是底层资源存在，还包括绑定资源是否成功分配。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [GetViewType](GetViewType.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/OpenGLResourceView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/OpenGLResourceView.md
index a19e93e9..4527fee8 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/OpenGLResourceView.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/OpenGLResourceView.md
@@ -6,49 +6,84 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLResourceView.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLResourceView` public API。
+**描述**: OpenGL 后端统一资源视图对象，把 RHI 层的多种 view 语义映射为纹理、缓冲区、framebuffer 及其绑定元数据。
 
-## 概述
+## 概览
 
-`OpenGLResourceView.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+在 D3D12 / Vulkan 里，resource view 往往会自然让人想到独立的 descriptor 或 view object。OpenGL 不是这套模型，它更多依赖:
 
-## 声明概览
+- 纹理对象本身
+- buffer 对象本身
+- framebuffer 绑定关系
+- texture unit / image unit / uniform buffer binding point
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLResourceView` | `class` | 继承自 `RHIResourceView` 的公开声明。 |
+`OpenGLResourceView` 的职责，就是把这些分散的 OpenGL 机制整理成统一的 RHI 视图对象，让上层仍然可以用 `RenderTargetView`、`ShaderResourceView`、`ConstantBufferView` 这类抽象去表达渲染意图。
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLResourceView()](Constructor.md) | 构造对象。 |
-| [~OpenGLResourceView()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [IsValid](IsValid.md) | 查询当前状态。 |
-| [InitializeAsRenderTarget](InitializeAsRenderTarget.md) | 初始化内部状态。 |
-| [InitializeAsDepthStencil](InitializeAsDepthStencil.md) | 初始化内部状态。 |
-| [InitializeAsShaderResource](InitializeAsShaderResource.md) | 初始化内部状态。 |
-| [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md) | 初始化内部状态。 |
-| [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md) | 初始化内部状态。 |
-| [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md) | 初始化内部状态。 |
-| [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md) | 初始化内部状态。 |
-| [GetViewType](GetViewType.md) | 获取相关状态或对象。 |
-| [GetDimension](GetDimension.md) | 获取相关状态或对象。 |
-| [GetFormat](GetFormat.md) | 获取相关状态或对象。 |
-| [GetFramebuffer](GetFramebuffer.md) | 获取相关状态或对象。 |
-| [GetTextureUnit](GetTextureUnit.md) | 获取相关状态或对象。 |
-| [GetBindingPoint](GetBindingPoint.md) | 获取相关状态或对象。 |
-| [GetTexture](GetTexture.md) | 获取相关状态或对象。 |
-| [GetBuffer](GetBuffer.md) | 获取相关状态或对象。 |
-| [GetBufferOffset](GetBufferOffset.md) | 获取相关状态或对象。 |
-| [GetBufferSize](GetBufferSize.md) | 获取相关状态或对象。 |
-| [GetBufferStride](GetBufferStride.md) | 获取相关状态或对象。 |
-| [GetFramebufferAttachment](GetFramebufferAttachment.md) | 获取相关状态或对象。 |
-| [GetTextureResource](GetTextureResource.md) | 获取相关状态或对象。 |
+它不是“单一原生句柄的薄封装”，而是一个多态视图元数据对象:
+
+- RTV / DSV: 依赖现有 framebuffer，并缓存附件信息
+- SRV: 仅保存纹理和格式信息，不立即分配纹理单元
+- UAV: 分配纹理单元，并立刻绑定 image texture
+- CBV: 分配 uniform buffer binding point
+- VB / IB: 只保存 buffer、偏移、步长和格式
+
+这种设计的好处是跨后端接口统一，代价是 `GetNativeHandle()` 的真实含义会随着 `ResourceViewType` 改变。
+
+## 生命周期
+
+- 构造时对象为空，但默认 `m_viewType` 会被初始化成 `RenderTarget`。
+- 调用某个 `InitializeAs...` 方法后进入对应视图模式。
+- [Shutdown](Shutdown.md) 会释放它占用的 texture unit 或 binding point，并清空缓存元数据。
+- 析构时自动调用 `Shutdown()`。
+
+## 线程语义
+
+- 当前实现没有锁。
+- 由于涉及 OpenGL 资源和绑定点分配器，应视为依赖渲染线程 / OpenGL 上下文的对象，不适合跨线程并发读写。
+
+## 当前实现的真实行为
+
+- RTV / DSV 不创建独立 OpenGL view object，而是引用已有 `OpenGLFramebuffer` 并缓存 `FramebufferAttachment`。
+- SRV 当前只是只读纹理视图元数据，不会立即占用 texture unit。
+- UAV 会直接调用 `glBindImageTexture()`，但当前绑定参数是硬编码的 `GL_RGBA8 + mip0 + layer0 + read_write`。
+- CBV 通过 `OpenGLUniformBufferManager` 分配绑定点，但当前底层使用 `glBindBufferBase`，不支持范围绑定。
+- VB / IB 不创建额外对象，只把 buffer 信息缓存起来供命令列表消费。
+- `OpenGLCommandList` 会真实使用这些信息:
+  - `TransitionBarrier()` 通过 [GetTextureResource](GetTextureResource.md) 更新纹理状态
+  - `SetRenderTargets()` 通过 framebuffer attachment 重新组装 FBO
+  - `SetVertexBuffers()` / `SetIndexBuffer()` 读取偏移、步长和格式
+
+## 为什么这样设计
+
+这和商业引擎里常见的“跨后端统一资源视图层”是一致的思路:
+
+- 上层系统可以统一讨论 SRV / UAV / RTV / DSV / CBV
+- 底层后端各自用最接近自己的机制去实现
+
+对使用者来说，重要的不是假设所有后端都拥有完全对称的 view 模型，而是清楚知道当前 OpenGL 后端真正落到了哪一层。这个页面就是为了把这种边界说清楚。
+
+## 当前限制
+
+- `GetNativeHandle()` 不是统一类型句柄。
+- SRV 不负责即时分配 texture unit。
+- UAV 的 image 绑定参数是简化实现，不足以覆盖完整 typed / layered image view 需求。
+- CBV 没有实现真正的 offset/size range 绑定。
+- 构造后的默认 `GetViewType()` 是 `RenderTarget`，但对象并不有效。
+
+## 关键方法
+
+- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
+- [InitializeAsShaderResource](InitializeAsShaderResource.md)
+- [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md)
+- [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md)
+- [IsValid](IsValid.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)
+- [OpenGLTextureUnitAllocator](../OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md)
+- [OpenGLUniformBufferManager](../OpenGLUniformBufferManager/OpenGLUniformBufferManager.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Shutdown.md
index c1f1293f..f0fc041f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLResourceView/Shutdown.md
@@ -1,30 +1,32 @@
 # OpenGLResourceView::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放该 view 占用的绑定资源，并清空内部缓存状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_textureUnit >= 0` 且存在分配器:
+  - 调用 `UnbindTexture(m_textureUnit)`
+  - 调用 `Free(m_textureUnit)`
+  - 把 `m_textureUnit` 设为 `-1`
+- 如果 `m_bindingPoint >= 0` 且存在 UBO 管理器:
+  - 调用 `UnbindBuffer(m_bindingPoint)`
+  - 调用 `Free(m_bindingPoint)`
+  - 把 `m_bindingPoint` 设为 `-1`
+- 清空 framebuffer、纹理、buffer、附件信息和缓存的偏移/大小/步长。
+- 不会重置 `m_viewType`、`m_format` 和 `m_dimension`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLResourceView object;
-    // 根据上下文补齐参数后调用 OpenGLResourceView::Shutdown(...)。
-    (void)object;
-}
-```
+- 调用后即使某些元数据字段仍保留旧值，也不应再把对象视为有效视图；应以 [IsValid](IsValid.md) 为准。
+- 由于 `m_viewType` 不复位，调试时不要只看类型字段判断是否完成清理。
 
 ## 相关文档
 
-- [返回类总览](OpenGLResourceView.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index 44151df6..64294577 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-27 22:48:36`
+**生成时间**: `2026-03-27 23:33:00`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`