diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md
index 9742583c..741f121d 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::Bind
+# OpenGLFramebuffer::Bind()
 
 ```cpp
 void Bind();
@@ -6,13 +6,19 @@ void Bind();
 
 ## 作用
 
-把当前 FBO 绑定到 `GL_FRAMEBUFFER`。
+把当前对象的 FBO 绑定到 `GL_FRAMEBUFFER`。
 
 ## 当前实现行为
 
-- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`。
-- 不区分 `READ_FRAMEBUFFER` 与 `DRAW_FRAMEBUFFER`。
+- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`
+- 不检查 `m_framebuffer` 是否为 `0`
+- 不保存旧绑定
+
+## 设计说明
+
+`OpenGLFramebuffer` 采用的是非常直接的 OpenGL 风格 API。它不隐藏全局状态切换，而是把“绑定哪个 FBO”这件事明确暴露给调用者。
 
 ## 相关文档
 
 - [Unbind](Unbind.md)
+- [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md
index f66a7839..0bb2bbae 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::BindFramebuffer
+# OpenGLFramebuffer::BindFramebuffer()
 
 ```cpp
 static void BindFramebuffer(unsigned int framebuffer);
@@ -6,12 +6,18 @@ static void BindFramebuffer(unsigned int framebuffer);
 
 ## 作用
 
-静态辅助函数，把任意 framebuffer id 绑定到 `GL_FRAMEBUFFER`。
+以静态辅助函数形式绑定任意 FBO。
 
 ## 当前实现行为
 
-- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`。
+- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`
+- 不依赖当前对象实例
+
+## 适用场景
+
+当上层已经持有原始 FBO ID，而不想再经过实例方法时，可以使用这个静态入口。
 
 ## 相关文档
 
 - [UnbindFramebuffer](UnbindFramebuffer.md)
+- [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md
index 228890f9..100093b2 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::ClearColor
+# OpenGLFramebuffer::ClearColor()
 
 ```cpp
 void ClearColor(int attachmentIndex, float r, float g, float b, float a);
@@ -10,16 +10,22 @@ void ClearColor(int attachmentIndex, float r, float g, float b, float a);
 
 ## 参数
 
-- `attachmentIndex`: 颜色附件序号。
-- `r` / `g` / `b` / `a`: 清除颜色。
+- `attachmentIndex`: 颜色附件槽位
+- `r` / `g` / `b` / `a`: 清屏颜色
 
 ## 当前实现行为
 
-- 先绑定当前 FBO。
-- 调用 `glClearBufferfv(GL_COLOR, attachmentIndex, &r)` 执行清除。
-- 不恢复之前的 framebuffer 绑定状态。
+- 先把当前对象绑定到 `GL_FRAMEBUFFER`
+- 调用 `glClearBufferfv(GL_COLOR, attachmentIndex, &r)`
+- 依赖四个局部参数在栈上的连续布局，作为 RGBA 数组传入
+- 不恢复调用前的 FBO 绑定
+
+## 注意事项
+
+这是一条后端便捷接口，不是命令列表级的延迟录制命令。调用它会立即修改当前 OpenGL 状态。
 
 ## 相关文档
 
 - [ClearDepth](ClearDepth.md)
 - [ClearDepthStencil](ClearDepthStencil.md)
+- [Bind](Bind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md
index 417d70d8..1de854d1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::ClearDepth
+# OpenGLFramebuffer::ClearDepth()
 
 ```cpp
 void ClearDepth(float depth);
@@ -6,13 +6,16 @@ void ClearDepth(float depth);
 
 ## 作用
 
-清除当前 framebuffer 的深度附件。
+清除当前 FBO 的深度缓冲。
 
 ## 当前实现行为
 
-- 先绑定当前 FBO。
-- 调用 `glClearDepth(depth)`，随后执行 `glClear(GL_DEPTH_BUFFER_BIT)`。
+- 绑定 `m_framebuffer`
+- 调用 `glClearDepth(depth)`
+- 再调用 `glClear(GL_DEPTH_BUFFER_BIT)`
+- 不恢复之前的 FBO 绑定
 
 ## 相关文档
 
+- [ClearStencil](ClearStencil.md)
 - [ClearDepthStencil](ClearDepthStencil.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepthStencil.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepthStencil.md
index 99d87ac1..9e864c41 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepthStencil.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepthStencil.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::ClearDepthStencil
+# OpenGLFramebuffer::ClearDepthStencil()
 
 ```cpp
 void ClearDepthStencil(float depth, uint8_t stencil);
@@ -6,13 +6,19 @@ void ClearDepthStencil(float depth, uint8_t stencil);
 
 ## 作用
 
-同时清除深度和模板附件。
+同时清除深度和模板缓冲。
 
 ## 当前实现行为
 
-- 先绑定当前 FBO。
-- 设置 `glClearDepth(depth)` 与 `glClearStencil(stencil)`。
-- 调用 `glClear(GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`。
+- 绑定 `m_framebuffer`
+- 调用 `glClearDepth(depth)`
+- 调用 `glClearStencil(stencil)`
+- 最后执行 `glClear(GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`
+- 不恢复旧绑定
+
+## 设计说明
+
+把深度与模板打包清除是很常见的 FBO 操作，尤其适合与 `DepthStencil` 附件语义对应。
 
 ## 相关文档
 
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md
index dc988500..f522f632 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::ClearStencil
+# OpenGLFramebuffer::ClearStencil()
 
 ```cpp
 void ClearStencil(uint8_t stencil);
@@ -6,13 +6,16 @@ void ClearStencil(uint8_t stencil);
 
 ## 作用
 
-清除当前 framebuffer 的模板附件。
+清除当前 FBO 的模板缓冲。
 
 ## 当前实现行为
 
-- 先绑定当前 FBO。
-- 调用 `glClearStencil(stencil)`，随后执行 `glClear(GL_STENCIL_BUFFER_BIT)`。
+- 绑定 `m_framebuffer`
+- 调用 `glClearStencil(stencil)`
+- 调用 `glClear(GL_STENCIL_BUFFER_BIT)`
+- 不恢复之前的 FBO 绑定
 
 ## 相关文档
 
+- [ClearDepth](ClearDepth.md)
 - [ClearDepthStencil](ClearDepthStencil.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Constructor.md
index 6f324a14..0d45997f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Constructor.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::OpenGLFramebuffer
+# OpenGLFramebuffer::OpenGLFramebuffer()
 
 ```cpp
 OpenGLFramebuffer();
@@ -6,13 +6,15 @@ OpenGLFramebuffer();
 
 ## 作用
 
-构造一个空 FBO 包装对象。
+构造一个尚未创建 FBO 的帧缓冲对象。
 
 ## 当前实现行为
 
-- 把 framebuffer id、宽高和 sample 数初始化为 `0 / 0 / 1`。
-- 不创建真实 OpenGL framebuffer。
+- 把 `m_framebuffer` 置为 `0`
+- 把 `m_width`、`m_height` 置为 `0`
+- 把 `m_samples` 初始化为 `1`
 
 ## 相关文档
 
 - [Initialize](Initialize.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md
index 4b1afc9d..20f708fd 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::~OpenGLFramebuffer
+# OpenGLFramebuffer::~OpenGLFramebuffer()
 
 ```cpp
 ~OpenGLFramebuffer() override;
@@ -6,13 +6,13 @@
 
 ## 作用
 
-销毁对象并释放内部 FBO。
+析构并释放当前 FBO。
 
 ## 当前实现行为
 
-- 析构函数调用 [`Shutdown`](Shutdown.md)。
-- 如果已经创建过 framebuffer，会执行 `glDeleteFramebuffers()`。
+- 析构函数直接调用 [Shutdown](Shutdown.md)
 
 ## 相关文档
 
 - [Shutdown](Shutdown.md)
+- [OpenGLFramebuffer](OpenGLFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md
index d9fa9fab..55b174bf 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::GetFramebuffer
+# OpenGLFramebuffer::GetFramebuffer()
 
 ```cpp
 unsigned int GetFramebuffer() const;
@@ -6,13 +6,17 @@ unsigned int GetFramebuffer() const;
 
 ## 作用
 
-返回内部保存的 OpenGL framebuffer id。
+返回底层 OpenGL FBO ID。
 
-## 返回值
+## 当前实现行为
 
-- 返回 `m_framebuffer`。
+- 直接返回成员 `m_framebuffer`
+
+## 使用场景
+
+当后端需要把这个对象与其他 OpenGL 专用代码联动，例如手动 `glBindFramebuffer`、调试 FBO 状态或组合命令列表内部逻辑时，这个方法很有用。
 
 ## 相关文档
 
 - [GetNativeHandle](GetNativeHandle.md)
-- [BindFramebuffer](BindFramebuffer.md)
+- [Bind](Bind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md
index 520769a6..db693501 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::GetHeight
+# OpenGLFramebuffer::GetHeight()
 
 ```cpp
 uint32_t GetHeight() const override;
@@ -6,12 +6,15 @@ uint32_t GetHeight() const override;
 
 ## 作用
 
-返回 framebuffer 的逻辑高度。
+返回当前对象记录的 FBO 高度。
 
 ## 当前实现行为
 
-- 返回内部记录的 `m_height`。
+- 返回 `static_cast<uint32_t>(m_height)`
+- 这个值在 [Initialize](Initialize.md) 成功进入时写入
+- [Shutdown](Shutdown.md) 后会重置为 `0`
 
 ## 相关文档
 
 - [GetWidth](GetWidth.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md
index 753a8a80..acd06888 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::GetNativeHandle
+# OpenGLFramebuffer::GetNativeHandle()
 
 ```cpp
 void* GetNativeHandle() override;
@@ -6,12 +6,18 @@ void* GetNativeHandle() override;
 
 ## 作用
 
-返回原生 OpenGL framebuffer id。
+以统一 RHI 句柄形式返回底层 FBO。
 
-## 返回值
+## 当前实现行为
 
-- 返回 `m_framebuffer`，以 `void*` 形式暴露。
+- 把 `m_framebuffer` 转成 `uintptr_t`
+- 再转成 `void*` 返回
+
+## 注意事项
+
+这个句柄本质上是 OpenGL 对象名，不是独立的原生指针对象。
 
 ## 相关文档
 
 - [GetFramebuffer](GetFramebuffer.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md
index 380a2bca..0abfe835 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::GetWidth
+# OpenGLFramebuffer::GetWidth()
 
 ```cpp
 uint32_t GetWidth() const override;
@@ -6,13 +6,15 @@ uint32_t GetWidth() const override;
 
 ## 作用
 
-返回 framebuffer 的逻辑宽度。
+返回当前对象记录的 FBO 宽度。
 
 ## 当前实现行为
 
-- 返回内部记录的 `m_width`。
-- 该值来自初始化参数，而不是运行时向 OpenGL 查询。
+- 返回 `static_cast<uint32_t>(m_width)`
+- 宽度来自最近一次 [Initialize](Initialize.md) 成功进入时的参数
+- [Shutdown](Shutdown.md) 后会重置为 `0`
 
 ## 相关文档
 
 - [GetHeight](GetHeight.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md
index d559c6ce..d894ba22 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md
@@ -1,47 +1,73 @@
-# OpenGLFramebuffer::Initialize
+# OpenGLFramebuffer::Initialize()
 
 ```cpp
 bool Initialize(const FramebufferDesc& desc);
-
-bool Initialize(
-    RHIRenderPass* renderPass,
-    uint32_t width,
-    uint32_t height,
-    uint32_t colorAttachmentCount,
-    RHIResourceView** colorAttachments,
-    RHIResourceView* depthStencilAttachment) override;
+bool Initialize(RHIRenderPass* renderPass,
+                uint32_t width,
+                uint32_t height,
+                uint32_t colorAttachmentCount,
+                RHIResourceView** colorAttachments,
+                RHIResourceView* depthStencilAttachment) override;
 ```
 
 ## 作用
 
-创建并填充一个 OpenGL framebuffer object。
+根据显式附件描述或统一 RHI 资源视图创建一个 OpenGL FBO。
 
-## 当前实现行为
+## 重载 1: 原生 `FramebufferDesc`
 
-### `Initialize(const FramebufferDesc& desc)`
+```cpp
+bool Initialize(const FramebufferDesc& desc);
+```
 
-- 复制 `FramebufferDesc` 到内部成员。
-- 创建 FBO 并附着最多 `16` 个颜色附件。
-- 根据 depth / stencil 附件类型选择合适的 attachment point。
-- 如果没有颜色附件，会把 `glDrawBuffer` 和 `glReadBuffer` 设为 `GL_NONE`。
-- 调用 `glCheckFramebufferStatus(GL_FRAMEBUFFER)` 验证完整性。
+### 当前实现行为
 
-### `Initialize(RHIRenderPass*, ...)`
+- 把 `width`、`height`、`samples` 和完整 `desc` 缓存到对象成员
+- 调用 `glGenFramebuffers` 创建 FBO
+- 绑定到 `GL_FRAMEBUFFER`
+- 最多处理前 `16` 个颜色附件
+- 根据附件的 `target`、`mipLevel`、`layer` 选择：
+  - `glFramebufferTextureLayer`
+  - `glFramebufferTexture1D`
+  - `glFramebufferTexture2D`
+  - `glFramebufferTexture`
+- 深度附件与模板附件会根据 `FramebufferAttachmentType` 决定挂到：
+  - `GL_DEPTH_ATTACHMENT`
+  - `GL_DEPTH_STENCIL_ATTACHMENT`
+  - `GL_STENCIL_ATTACHMENT`
+- 有颜色附件时调用 `glDrawBuffers`
+- 无颜色附件时设置 `glDrawBuffer(GL_NONE)` 与 `glReadBuffer(GL_NONE)`
+- 最后做 `glCheckFramebufferStatus(GL_FRAMEBUFFER)` 完整性检查
 
-- 当前忽略 `renderPass` 参数。
-- 从 `OpenGLResourceView::GetFramebufferAttachment()` 提取附件信息。
-- 同样创建 FBO、设置 draw buffer，并检查完整性。
+### 注意事项
 
-## 返回值
+- `samples` 目前只被记录，不会驱动单独的多重采样附件创建逻辑
+- 如果完整性检查失败，函数返回 `false`，但对象释放仍依赖后续 [Shutdown](Shutdown.md) 或析构
 
-- FBO 完整时返回 `true`。
-- `glCheckFramebufferStatus()` 不是 `GL_FRAMEBUFFER_COMPLETE` 时返回 `false`。
+## 重载 2: 统一 RHI 入口
 
-## 当前限制
+```cpp
+bool Initialize(RHIRenderPass* renderPass,
+                uint32_t width,
+                uint32_t height,
+                uint32_t colorAttachmentCount,
+                RHIResourceView** colorAttachments,
+                RHIResourceView* depthStencilAttachment) override;
+```
 
-- 创建失败时不会在函数内部立即删除刚生成的 FBO id，通常由后续析构统一释放。
+### 当前实现行为
+
+- `renderPass` 当前被显式忽略
+- 把尺寸写入成员，`m_samples` 固定设为 `1`
+- 从 `OpenGLResourceView` 中取出 `FramebufferAttachment` 描述
+- 使用与原生重载相同的 FBO 绑定和完整性检查流程
+
+## 设计说明
+
+这两个入口体现了当前 OpenGL 后端的一个核心思路：虽然 RHI 层保留了 render pass / resource view 抽象，但落到 OpenGL 时，真正起作用的仍然是“把哪些纹理附件挂到哪个 FBO 上”。
 
 ## 相关文档
 
-- [IsValid](IsValid.md)
+- [OpenGLFramebuffer](OpenGLFramebuffer.md)
+- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
 - [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/IsValid.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/IsValid.md
index e073e798..c61b15cb 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/IsValid.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/IsValid.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::IsValid
+# OpenGLFramebuffer::IsValid()
 
 ```cpp
 bool IsValid() const override;
@@ -6,16 +6,17 @@ bool IsValid() const override;
 
 ## 作用
 
-判断当前对象是否持有非零 FBO id。
-
-## 返回值
-
-- `m_framebuffer != 0` 时返回 `true`。
+判断对象是否已经持有一个非零 FBO。
 
 ## 当前实现行为
 
-- 这是一个轻量检查，不会再次执行 `glCheckFramebufferStatus()`。
+- 直接检查 `m_framebuffer != 0`
+
+## 注意事项
+
+它不重新执行 `glCheckFramebufferStatus`，也不验证附件当前是否仍然完整。
 
 ## 相关文档
 
 - [Initialize](Initialize.md)
+- [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md
index 21d0688d..0e86cfe4 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md
@@ -6,43 +6,59 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`
 
-**描述**: OpenGL 后端的 framebuffer 对象封装，用于把颜色、深度、模板附件组织成一个可绑定的 FBO。
+**描述**: OpenGL 后端的帧缓冲对象封装器，用来把颜色、深度、模板附件组装成一个可绑定的 FBO。
 
-## 概述
+## 概览
 
-和 Vulkan / D3D12 的 render pass + framebuffer 分层不同，OpenGL 更偏向直接操作 framebuffer object。`OpenGLFramebuffer` 的职责，是把引擎内部的附件描述或资源视图组合成一个实际的 FBO，并提供基础的绑定与清屏操作。
+在现代显式 API 里，`RenderPass`、`Framebuffer`、附件 load/store 规则通常是分层设计的；而在 OpenGL 里，最核心的实体往往就是 FBO 本身。`OpenGLFramebuffer` 的职责正是把这两种模型接起来。
 
-它可以理解为 OpenGL 后端里的“附件包”:
+当前类支持两种输入方式：
 
-- 你先描述要挂哪些 texture / layer / mip。
-- 它负责创建 FBO、附着附件并检查完整性。
-- 命令列表或截图逻辑再在这个 FBO 上执行绘制、清理和 blit。
+- 直接使用 `FramebufferDesc`
+- 通过统一 RHI 的 `RHIResourceView` 列表构建
+
+无论入口如何，最终落地行为都是“创建一个 FBO，然后把纹理/层级/数组切片按规则挂载上去”。
+
+## 主要职责
+
+- 创建并拥有底层 FBO
+- 维护宽高与采样数元数据
+- 把颜色、深度、模板附件挂到正确的 attachment point
+- 暴露 [Bind](Bind.md)、[Unbind](Unbind.md) 和清除辅助方法
 
 ## 当前实现的真实行为
 
-### 两种初始化路径
+- 颜色附件最多处理 `16` 个
+- `renderPass` 参数当前不参与实际创建逻辑
+- `m_samples` 只做缓存，不驱动 MSAA FBO 特殊路径
+- 清除方法都会立即绑定当前 FBO，并且不恢复旧绑定
+- [IsValid](IsValid.md) 只检查 FBO ID 是否非零
 
-- [`Initialize(const FramebufferDesc&)`](Initialize.md) 直接按 `FramebufferDesc` 组装附件。
-- [`Initialize(RHIRenderPass*, ...)`](Initialize.md) 从 `RHIResourceView` 数组提取附件信息。
+## 设计背景
 
-### 附件绑定策略
+商业级引擎在 OpenGL 后端通常会把 FBO 当成“运行时组合点”，而不是硬搬 Vulkan/D3D12 的 render pass 规则。原因很现实：
 
-- 最多处理 `16` 个颜色附件。
-- 根据 attachment 的 target / layer / mip，选择 `glFramebufferTexture1D`、`glFramebufferTexture2D`、`glFramebufferTextureLayer` 或 `glFramebufferTexture`。
-- 深度附件如果标记为 `DepthStencil`，会绑定到 `GL_DEPTH_STENCIL_ATTACHMENT`。
+- OpenGL 的原生对象就是 FBO
+- 附件绑定粒度高，组合方式灵活
+- 用 FBO 作为后端真实实体，最容易和统一 RHI 抽象做映射
 
-### render pass 参数
+当前实现沿用了这种思路：RHI 继续保留更高层接口，OpenGL 后端则把真正的工作落在 FBO 组装上。
 
-- `Initialize(RHIRenderPass*, ...)` 当前会忽略 `renderPass` 本身。
-- 也就是说，这个类在 OpenGL 后端更接近“附件集合对象”，而不是对 Vulkan / D3D12 render pass 语义的完全镜像。
+## 生命周期
+
+- [OpenGLFramebuffer()](Constructor.md) 初始化为空对象
+- [Initialize](Initialize.md) 创建 FBO 并附着资源
+- [Bind](Bind.md) / [Unbind](Unbind.md) 用于直接切换绑定
+- [Shutdown](Shutdown.md) 删除 FBO 并重置尺寸缓存
 
 ## 当前限制
 
-- `Clear*()` 系列函数会直接修改当前 FBO 绑定状态，不会恢复之前的 framebuffer。
-- `IsValid()` 只检查 FBO id 是否非零，不会再次验证完整性。
-- 创建失败时返回 `false`，但由调用方或析构来最终清理对象。
+- 没有 render pass load/store 语义建模
+- 没有自动恢复前一绑定状态
+- `samples` 目前没有形成完整的多重采样管理
+- 对附件兼容性的错误信息较少，只靠 `glCheckFramebufferStatus`
 
-## 重点方法
+## 关键方法
 
 - [Initialize](Initialize.md)
 - [Bind](Bind.md)
@@ -52,6 +68,6 @@
 
 ## 相关文档
 
-- [OpenGL](../OpenGL.md)
+- [OpenGLRenderTargetView](../OpenGLRenderTargetView/OpenGLRenderTargetView.md)
+- [OpenGLDepthStencilView](../OpenGLDepthStencilView/OpenGLDepthStencilView.md)
 - [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
-- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Shutdown.md
index 50e1c442..75d17cd7 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Shutdown.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::Shutdown
+# OpenGLFramebuffer::Shutdown()
 
 ```cpp
 void Shutdown() override;
@@ -6,13 +6,21 @@ void Shutdown() override;
 
 ## 作用
 
-删除内部 framebuffer object 并重置尺寸状态。
+释放当前 FBO 并重置尺寸缓存。
 
 ## 当前实现行为
 
-- 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers()`。
-- 把宽高重置为 `0`，sample 数重置为 `1`。
+- 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers(1, &m_framebuffer)`
+- 把 `m_framebuffer` 置为 `0`
+- 把 `m_width`、`m_height` 重置为 `0`
+- 把 `m_samples` 重置为 `1`
+- 不清空 `m_desc`
+
+## 注意事项
+
+如果上层还保留旧附件关系的语义，只看对象内部 `m_desc` 可能与当前 FBO 生命周期不同步，因为 `Shutdown()` 没有重置这份描述缓存。
 
 ## 相关文档
 
 - [Destructor](Destructor.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md
index df7e5862..981f4d4a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::Unbind
+# OpenGLFramebuffer::Unbind()
 
 ```cpp
 void Unbind();
@@ -6,12 +6,17 @@ void Unbind();
 
 ## 作用
 
-解绑当前 framebuffer，把 `GL_FRAMEBUFFER` 绑定回默认 framebuffer `0`。
+把 `GL_FRAMEBUFFER` 绑定切回默认帧缓冲 `0`。
 
 ## 当前实现行为
 
-- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
+- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`
+
+## 设计说明
+
+OpenGL 后端里“解绑 FBO”通常就意味着回到默认窗口帧缓冲，这和 D3D12/Vulkan 里“结束 render pass”不是一回事。文档里需要明确这层概念差异。
 
 ## 相关文档
 
 - [Bind](Bind.md)
+- [UnbindFramebuffer](UnbindFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md
index 309e2fb1..6dca235e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md
@@ -1,4 +1,4 @@
-# OpenGLFramebuffer::UnbindFramebuffer
+# OpenGLFramebuffer::UnbindFramebuffer()
 
 ```cpp
 static void UnbindFramebuffer();
@@ -6,12 +6,13 @@ static void UnbindFramebuffer();
 
 ## 作用
 
-静态辅助函数，把 `GL_FRAMEBUFFER` 解绑回默认 framebuffer。
+静态解绑当前 `GL_FRAMEBUFFER`。
 
 ## 当前实现行为
 
-- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
+- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`
 
 ## 相关文档
 
 - [BindFramebuffer](BindFramebuffer.md)
+- [Unbind](Unbind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md
index e580e192..1f2a63a1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md
@@ -1,35 +1,112 @@
-# OpenGLShader::Compile
+# OpenGLShader::Compile()
 
 ```cpp
-bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override;
+bool Compile(const void* sourceData,
+             size_t sourceSize,
+             const char* entryPoint,
+             const char* target) override;
 bool Compile(const char* vertexSource, const char* fragmentSource);
-bool Compile(const char* vertexSource, const char* fragmentSource, const char* geometrySource);
+bool Compile(const char* vertexSource,
+             const char* fragmentSource,
+             const char* geometrySource);
 bool Compile(const char* source, ShaderType type);
 ```
 
 ## 作用
 
-从源码字符串编译并链接 OpenGL shader/program。
+把 GLSL 源码编译并链接成可用的 OpenGL program。
 
-## 当前实现行为
+## 重载 1: 通用 RHI 入口
 
-- `sourceData` 重载：
-  - 只接受文本源码
-  - 先用 `target` 推断 type
-  - 若失败，再尝试根据 GLSL 源码特征启发式判断 type
-- graphics 多阶段重载：
-  - 分别创建 shader object
-  - 编译
-  - attach 到同一个 program
-  - link
-- `Compile(const char*, ShaderType)`：
-  - 适合单阶段 program / compute path / 逐阶段 attach 逻辑
+```cpp
+bool Compile(const void* sourceData,
+             size_t sourceSize,
+             const char* entryPoint,
+             const char* target) override;
+```
 
-## 注意事项
+### 当前实现行为
 
-这里的“类型推断”是启发式的，不应视为稳定资产编译系统。
+- `sourceData == nullptr` 或 `sourceSize == 0` 时直接返回 `false`
+- `entryPoint` 被显式忽略
+- 把字节流拷贝成 `std::string`
+- 先尝试根据 `target` 解析 `ShaderType`
+- 若失败，再根据源码中的 GLSL 特征词推断：
+  - `gl_Position` 推断为 Vertex
+  - `gl_FragCoord` / `gl_FragColor` 等推断为 Fragment
+  - `layout(local_size_x` 等推断为 Compute
+  - `EmitVertex` / `gl_in[` 推断为 Geometry
+- 推断成功后，转发到 `Compile(const char*, ShaderType)`
+
+### 注意事项
+
+- 这条路径只支持 GLSL 文本，不负责 HLSL 到 GLSL 的翻译
+- 类型推断本质上是启发式逻辑，不是强约束编译管线
+
+## 重载 2: 顶点 + 片元
+
+```cpp
+bool Compile(const char* vertexSource, const char* fragmentSource);
+```
+
+### 当前实现行为
+
+- 创建 `GL_VERTEX_SHADER` 与 `GL_FRAGMENT_SHADER`
+- 分别 `glShaderSource`、`glCompileShader`
+- 任一阶段编译失败时直接返回 `false`
+- 编译通过后创建新的 `m_program`
+- attach 两个 shader 并 link
+- link 成功后删除临时 shader 对象
+- 把 `m_uniformsCached` 置为 `false`
+
+### 注意事项
+
+- 这条路径不会更新 `m_type`
+- 如果对象之前已经持有旧 `m_program`，当前实现不会先 `Shutdown()`，因此重复编译不属于严格意义上的“就地重编译”
+- 失败路径没有对所有临时 OpenGL 对象做完整清理
+
+## 重载 3: 顶点 + 片元 + 几何
+
+```cpp
+bool Compile(const char* vertexSource,
+             const char* fragmentSource,
+             const char* geometrySource);
+```
+
+### 当前实现行为
+
+- 与双阶段重载流程相同，只是额外创建并编译 `GL_GEOMETRY_SHADER`
+- link 成功后删除 vertex / fragment / geometry 三个 shader 对象
+- 同样会把 `m_uniformsCached` 置为 `false`
+
+## 重载 4: 单阶段编译
+
+```cpp
+bool Compile(const char* source, ShaderType type);
+```
+
+### 当前实现行为
+
+- 按 `type` 创建对应 shader：
+  - Vertex
+  - Fragment
+  - Geometry
+  - Compute
+  - TessControl
+  - TessEvaluation
+- 若 `m_program == 0`，先创建 program
+- attach 当前阶段 shader 并立即 link
+- 成功后删除临时 shader
+- 把 `m_type` 设置为传入的 `type`
+- 把 `m_uniformsCached` 置为 `false`
+
+### 设计说明
+
+这条路径允许“先创建 program，再逐阶段 attach + link”的简单装配流程，所以 `OpenGLDevice::CreateShader(...)` 的通用 GLSL 路径可以只给一份源码，再由 `target` / 内容推断阶段类型。
 
 ## 相关文档
 
 - [CompileFromFile](CompileFromFile.md)
-- [Use](Use.md)
+- [CompileCompute](CompileCompute.md)
+- [GetType](GetType.md)
+- [OpenGLShader](OpenGLShader.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md
index 0cdf098a..0a1e7fce 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md
@@ -1,4 +1,4 @@
-# OpenGLShader::CompileCompute
+# OpenGLShader::CompileCompute()
 
 ```cpp
 bool CompileCompute(const char* computeSource);
@@ -6,16 +6,30 @@ bool CompileCompute(const char* computeSource);
 
 ## 作用
 
-编译并链接一个 compute program。
+编译并链接一个 compute shader program。
 
 ## 当前实现行为
 
 - 创建 `GL_COMPUTE_SHADER`
-- 编译后 attach 到新 program
-- link
-- 成功后把 `m_type` 设为 `ShaderType::Compute`
+- 传入 `computeSource` 后执行编译
+- 编译失败则返回 `false`
+- 创建新的 `m_program`
+- attach compute shader 并 link
+- link 成功后删除临时 shader 对象
+- 把 `m_type` 设置为 `ShaderType::Compute`
+- 把 `m_uniformsCached` 置为 `false`
+
+## 设计说明
+
+虽然 [Compile](Compile.md) 的单阶段重载也能处理 `ShaderType::Compute`，但 `CompileCompute()` 提供了更直接、更少推断步骤的入口，适合作为后端专用工具方法使用。
+
+## 注意事项
+
+- 和其他编译入口一样，当前实现不会先销毁旧 `m_program`
+- 失败日志通过标准输出打印，而不是引擎统一日志系统
 
 ## 相关文档
 
 - [Compile](Compile.md)
 - [Use](Use.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md
index e943681b..258da93e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md
@@ -1,33 +1,75 @@
-# OpenGLShader::CompileFromFile
+# OpenGLShader::CompileFromFile()
 
 ```cpp
-bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override;
+bool CompileFromFile(const wchar_t* filePath,
+                     const char* entryPoint,
+                     const char* target) override;
 bool CompileFromFile(const char* vertexPath, const char* fragmentPath);
-bool CompileFromFile(const char* vertexPath, const char* fragmentPath, const char* geometryPath);
+bool CompileFromFile(const char* vertexPath,
+                     const char* fragmentPath,
+                     const char* geometryPath);
 ```
 
 ## 作用
 
-从文件读取 GLSL 源码并构建 OpenGL program。
+从文件读取 GLSL 源码并编译成可用 program。
 
-## 当前实现行为
+## 重载 1: 通用 RHI 文件入口
 
-- `wchar_t*` 重载：
-  - 把路径转为窄字符串
-  - 根据 `target` 或文件扩展名推断 shader type
-  - 读取整个文件
-  - 走单阶段 `Compile(source, type)` 路径
-- 多文件 graphics 重载：
-  - 分别读取顶点/片元/几何着色器文件
-  - 再执行多阶段编译和链接
+```cpp
+bool CompileFromFile(const wchar_t* filePath,
+                     const char* entryPoint,
+                     const char* target) override;
+```
 
-## 失败路径
+### 当前实现行为
 
-- 文件打不开返回 `false`
-- 无法推断 shader type 返回 `false`
-- 任一编译或链接失败返回 `false`
+- `filePath == nullptr` 时直接返回 `false`
+- `entryPoint` 被忽略
+- 使用内部 `NarrowAscii()` 把 `wchar_t*` 路径逐字符截断成窄字符
+- 打开文本文件并读入完整源码
+- 优先根据 `target` 推断 shader 类型
+- 若 `target` 不能提供信息，再根据文件扩展名推断：
+  - `.vert` / `.vs.glsl`
+  - `.frag` / `.fs.glsl`
+  - `.geom` / `.gs.glsl`
+  - `.comp` / `.cs.glsl`
+  - `.tesc`
+  - `.tese`
+- 推断成功后转发到 [Compile](Compile.md) 的单阶段重载
+
+### 注意事项
+
+- 路径转换是 ASCII 风格截断，不适合复杂宽字符路径
+- 没有 include 处理、宏展开或 shader 预处理阶段
+
+## 重载 2: 顶点 + 片元文件
+
+```cpp
+bool CompileFromFile(const char* vertexPath, const char* fragmentPath);
+```
+
+### 当前实现行为
+
+- 分别读取两个文件
+- 任一文件打不开则返回 `false`
+- 读入后调用 `Compile(vertexSource, fragmentSource)`
+
+## 重载 3: 顶点 + 片元 + 几何文件
+
+```cpp
+bool CompileFromFile(const char* vertexPath,
+                     const char* fragmentPath,
+                     const char* geometryPath);
+```
+
+### 当前实现行为
+
+- 与双文件重载相同，只是增加 geometry 文件读取
+- 读入成功后调用三阶段 [Compile](Compile.md)
 
 ## 相关文档
 
 - [Compile](Compile.md)
-- [CompileCompute](CompileCompute.md)
+- [GetType](GetType.md)
+- [OpenGLShader](OpenGLShader.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Constructor.md
index 21435f2a..7fb831e4 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Constructor.md
@@ -1,28 +1,24 @@
 # OpenGLShader::OpenGLShader()
 
-构造对象。
-
 ```cpp
 OpenGLShader();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个尚未编译 program 的 shader 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 把 `m_program` 置为 `0`
+- 把 `m_uniformsCached` 置为 `false`
+- `m_type` 依赖成员默认值，初始为 `ShaderType::Vertex`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-}
-```
+初始 `m_type` 并不意味着对象已经拥有 vertex shader program；它只是默认成员值。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [IsValid](IsValid.md)
+- [Compile](Compile.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Destructor.md
index 47d63125..c163de6f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Destructor.md
@@ -1,29 +1,19 @@
 # OpenGLShader::~OpenGLShader()
 
-销毁对象并释放相关资源。
-
 ```cpp
 ~OpenGLShader() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 shader 对象并释放其 program。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数直接调用 [Shutdown](Shutdown.md)
+- 如果 `m_program != 0`，会在 `Shutdown()` 中执行 `glDeleteProgram`
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [OpenGLShader](OpenGLShader.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetID.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetID.md
index 80e96476..149b9da9 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetID.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetID.md
@@ -1,30 +1,23 @@
-# OpenGLShader::GetID
-
-获取相关状态或对象。
+# OpenGLShader::GetID()
 
 ```cpp
 unsigned int GetID() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 OpenGL program ID。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_program`
+- `0` 表示当前没有成功创建 program
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 使用场景
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::GetID(...)。
-    (void)object;
-}
-```
+集成测试、后端专用工具和 [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md) 会直接消费这个值，把它传给 `glUseProgram` 或 [AttachShader](../OpenGLPipelineState/AttachShader.md)。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [Use](Use.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetNativeHandle.md
index 9bf015f9..feffe8b6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetNativeHandle.md
@@ -1,30 +1,23 @@
-# OpenGLShader::GetNativeHandle
-
-获取相关状态或对象。
+# OpenGLShader::GetNativeHandle()
 
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以统一 RHI 句柄形式返回底层 program。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 把 `m_program` 转成 `uintptr_t`
+- 再转成 `void*` 返回
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::GetNativeHandle(...)。
-    (void)object;
-}
-```
+这个“native handle”本质上就是 OpenGL program ID，而不是独立的 COM/驱动对象指针。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [GetID](GetID.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetType.md
index 919ce493..ae3557aa 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetType.md
@@ -1,30 +1,26 @@
-# OpenGLShader::GetType
-
-获取相关状态或对象。
+# OpenGLShader::GetType()
 
 ```cpp
 ShaderType GetType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回对象当前记录的 shader 类型。
 
-**返回：** `ShaderType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回成员 `m_type`
+- `CompileCompute()` 会把它设为 `Compute`
+- `Compile(const char*, ShaderType)` 会把它设为传入类型
+- 顶点/片元或顶点/片元/几何这两类图形 program 重载不会更新它
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::GetType(...)。
-    (void)object;
-}
-```
+这意味着 `GetType()` 对“完整 graphics program”并不是强语义描述。一个已经成功编译的 vertex + fragment program，`GetType()` 仍可能保持默认的 `Vertex`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [Compile](Compile.md)
+- [CompileCompute](CompileCompute.md)
+- [OpenGLShader](OpenGLShader.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfo.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfo.md
index 278e932b..58d72b09 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfo.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfo.md
@@ -1,31 +1,25 @@
-# OpenGLShader::GetUniformInfo
-
-获取相关状态或对象。
+# OpenGLShader::GetUniformInfo()
 
 ```cpp
 const UniformInfo* GetUniformInfo(const char* name) const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+按名称查询单个 uniform 的反射信息。
 
-**返回：** `const UniformInfo*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 先调用 [GetUniformInfos](GetUniformInfos.md) 对应的缓存流程
+- 对 `m_uniformInfos` 做线性遍历
+- 名称匹配成功时返回指向缓存元素的指针
+- 否则返回 `nullptr`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::GetUniformInfo(...)。
-    (void)object;
-}
-```
+这里强调的是“足够可用的查询接口”，而不是高性能反射数据库。对于运行时材质系统来说，通常在 program 创建后查询少量 uniform 信息已经够用。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [GetUniformInfos](GetUniformInfos.md)
+- [GetUniformLocation](GetUniformLocation.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfos.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfos.md
index f2e4a0cc..3a59777c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfos.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformInfos.md
@@ -1,30 +1,34 @@
-# OpenGLShader::GetUniformInfos
-
-获取相关状态或对象。
+# OpenGLShader::GetUniformInfos()
 
 ```cpp
 const std::vector<UniformInfo>& GetUniformInfos() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 program 的 uniform 反射结果集合。
 
-**返回：** `const std::vector<UniformInfo>&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 首次调用时执行 `CacheUniformInfos()`
+- 通过 `glGetProgramInterfaceiv(..., GL_UNIFORM, GL_ACTIVE_RESOURCES, ...)` 枚举 uniform
+- 对每个资源读取：
+  - 名称长度
+  - 类型
+  - 偏移
+  - 数组大小
+- 根据部分常见 GL 类型估算 `size`
+- 把结果缓存到 `m_uniformInfos`
+- 后续调用直接返回缓存
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 需要特别注意
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::GetUniformInfos(...)。
-    (void)object;
-}
-```
+- `bindPoint` 当前使用的是枚举到的资源索引，不等同于显式 layout binding
+- `size` 只覆盖部分常见标量、向量、矩阵类型，其他类型可能得到 `0`
+- 这套缓存会在成功编译后重置，并在 [Shutdown](Shutdown.md) 时清空
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [GetUniformInfo](GetUniformInfo.md)
+- [GetUniformLocation](GetUniformLocation.md)
+- [OpenGLShader](OpenGLShader.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformLocation.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformLocation.md
index 79c3de7a..b5f83c36 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformLocation.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/GetUniformLocation.md
@@ -1,31 +1,24 @@
-# OpenGLShader::GetUniformLocation
-
-获取相关状态或对象。
+# OpenGLShader::GetUniformLocation()
 
 ```cpp
 int GetUniformLocation(const char* name) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+查询指定 uniform 在 program 中的位置。
 
-**返回：** `int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接调用 `glGetUniformLocation(m_program, name)`
+- 不依赖反射缓存
+- 返回 OpenGL 原生位置值
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 适用场景
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::GetUniformLocation(...)。
-    (void)object;
-}
-```
+当上层已经知道要设置哪个 uniform，并且只想直接调用 `glUniform*` 时，这个方法比先走 [GetUniformInfo](GetUniformInfo.md) 更直接。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [Use](Use.md)
+- [GetUniformInfo](GetUniformInfo.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/IsValid.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/IsValid.md
index f8f91824..e4c38a0f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/IsValid.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/IsValid.md
@@ -1,30 +1,22 @@
-# OpenGLShader::IsValid
-
-查询当前状态。
+# OpenGLShader::IsValid()
 
 ```cpp
 bool IsValid() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前对象是否已经持有一个非零的 OpenGL program。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接检查 `m_program != 0`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::IsValid(...)。
-    (void)object;
-}
-```
+它只验证“是否有 program ID”，不验证链接结果是否仍然可用，也不检查 program 是否匹配当前上下文状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [GetID](GetID.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md
index de389baa..d1c38f9e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md
@@ -6,42 +6,70 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLShader.h`
 
-**描述**: OpenGL 后端的着色器/程序封装，负责 GLSL 编译、链接、基础反射和 program 使用。
+**描述**: OpenGL 后端的 shader / program 封装器，负责 GLSL 源码读取、编译、链接，以及一套轻量级的 uniform 反射查询。
 
 ## 概览
 
-`OpenGLShader` 同时承担了“单阶段 shader 编译器”和“完整 graphics/compute program 封装器”两种职责：
+`OpenGLShader` 当前同时承担两类职责：
 
-- 多阶段 graphics program：通过顶点/片元或顶点/片元/几何路径构建
-- 单阶段 shader：通过 `Compile(const void*, size_t, ...)` 或 `Compile(const char*, ShaderType)` 推断类型后编译并链接
-- compute program：通过 [`CompileCompute`](CompileCompute.md) 构建
+- 单阶段 shader 的编译入口
+- 完整 graphics / compute program 的最终持有者
+
+它不是“离线 shader 资产系统”，也不是“可复用的原生 shader object 缓存”。当前实现更偏向运行时直接把 GLSL 文本编译成 program，然后尽快给命令列表和管线状态对象使用。
+
+## 主要能力
+
+- 直接从字符串编译 vertex / fragment / geometry / compute
+- 从文件读取 GLSL 源码
+- 通过 `target`、扩展名或源码内容推断阶段类型
+- 暴露 program ID 给后端专用路径
+- 懒加载 uniform 反射信息
 
 ## 当前实现的真实行为
 
-- [`CompileFromFile`](CompileFromFile.md) 会根据 `target` 或文件扩展名推断 shader type
-- [`Compile`](Compile.md) 的 `sourceData` 路径会根据 `target` 或 GLSL 源码特征猜测 shader type
-- `Compile(const char*, ShaderType)` 会把 shader attach 到 `m_program` 上并立即 link
-- `GetUniformInfos()` 通过 `glGetProgramInterfaceiv(GL_UNIFORM, ...)` 做反射
-- `Use()` 只是 `glUseProgram(m_program)`
+- [CompileFromFile](CompileFromFile.md) 的通用 RHI 入口会忽略 `entryPoint`
+- [Compile](Compile.md) 的通用 RHI 入口同样忽略 `entryPoint`
+- 单文件 / 单源码编译路径依赖启发式类型推断
+- 图形 program 的双阶段/三阶段重载不会更新 `m_type`
+- 失败日志通过 `std::cout` 输出
+- 当前实现不保证“重复编译同一对象”时的资源清理完整性
 
-## 设计说明
+## 设计背景
 
-当前实现追求的是“足够统一、足够易用”，而不是做一套完整的 shader asset pipeline。因此类型推断里存在明显的启发式逻辑，文档里必须明确说明，不应把它误解成强约束编译系统。
+在跨后端 RHI 里，D3D12/Vulkan 往往会把 shader bytecode、pipeline 创建和反射拆得更细；而 OpenGL 更常见的运行时模型是“把 GLSL 文本直接交给驱动编译”。`OpenGLShader` 采用的是后一种思路：
+
+- 先保证最短路径可编译、可绑定、可调试
+- 再通过 `GetUniformInfos()` 提供最基本的反射
+- 把复杂的 shader 资产管线留给更高层系统未来扩展
+
+这种设计对原型阶段、测试样例和教学型 API 文档尤其友好，因为调用链短、可见性高。
+
+## 生命周期
+
+- [OpenGLShader()](Constructor.md) 初始化为空 program
+- 通过 [Compile](Compile.md)、[CompileFromFile](CompileFromFile.md) 或 [CompileCompute](CompileCompute.md) 创建 program
+- 通过 [Use](Use.md) 绑定到当前上下文
+- 通过 [GetUniformInfos](GetUniformInfos.md) / [GetUniformLocation](GetUniformLocation.md) 查询反射信息
+- [Shutdown](Shutdown.md) 删除 program 并清空缓存
 
 ## 当前限制
 
-- `Compile(const void*, size_t, ...)` 只处理 GLSL 文本，不负责 HLSL 到 GLSL 转译
-- shader type 推断带启发式性质，失败时会直接返回 `false`
-- 链接错误和编译错误当前主要输出到标准输出
+- 只支持 GLSL 文本编译
+- 没有 include、宏预处理、变体缓存或离线编译
+- `GetType()` 对图形 program 不是严格可靠的语义来源
+- 失败路径的临时对象清理较粗糙
+- 路径窄化逻辑不适合复杂 Unicode 文件名
 
-## 重点公共方法
+## 关键方法
 
-- [CompileFromFile](CompileFromFile.md)
 - [Compile](Compile.md)
+- [CompileFromFile](CompileFromFile.md)
 - [CompileCompute](CompileCompute.md)
 - [Use](Use.md)
+- [GetUniformInfos](GetUniformInfos.md)
 
 ## 相关文档
 
 - [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)
 - [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Shutdown.md
index 6c9dec38..cd6c2a1d 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Shutdown.md
@@ -1,30 +1,26 @@
-# OpenGLShader::Shutdown
-
-关闭并清理内部状态。
+# OpenGLShader::Shutdown()
 
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放当前 program 和 uniform 缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_program != 0`，调用 `glDeleteProgram(m_program)`
+- 把 `m_program` 置为 `0`
+- 清空 `m_uniformInfos`
+- 把 `m_uniformsCached` 置为 `false`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLShader object;
-    // 根据上下文补齐参数后调用 OpenGLShader::Shutdown(...)。
-    (void)object;
-}
-```
+对于 `OpenGLShader`，`Shutdown()` 不只是释放 GPU program，也是把反射缓存完全作废。任何新的编译结果都应该重新建立 uniform 视图。
 
 ## 相关文档
 
-- [返回类总览](OpenGLShader.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [Compile](Compile.md)
+- [GetUniformInfos](GetUniformInfos.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md
index 07677527..f4e55ea9 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md
@@ -1,4 +1,4 @@
-# OpenGLShader::Use
+# OpenGLShader::Use()
 
 ```cpp
 void Use() const;
@@ -6,13 +6,19 @@ void Use() const;
 
 ## 作用
 
-把当前 shader program 设为活动 program。
+把当前 program 绑定为活动 shader program。
 
 ## 当前实现行为
 
-直接调用 `glUseProgram(m_program)`。
+- 直接执行 `glUseProgram(m_program)`
+- 不检查 `m_program` 是否为 `0`
+- 不做上下文切换
+
+## 何时使用
+
+在后端专用 OpenGL 代码里，`Use()` 是最直接的 program 绑定方式。若走统一 RHI 流程，则更常见的入口是 [OpenGLPipelineState::Bind](../OpenGLPipelineState/Bind.md)。
 
 ## 相关文档
 
-- [Compile](Compile.md)
-- [OpenGLPipelineState::Bind](../OpenGLPipelineState/Bind.md)
+- [GetID](GetID.md)
+- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Constructor.md
index b9217e32..733c8d48 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Constructor.md
@@ -1,28 +1,25 @@
 # OpenGLSwapChain::OpenGLSwapChain()
 
-构造对象。
-
 ```cpp
 OpenGLSwapChain();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个尚未绑定窗口与设备的 OpenGL 交换链包装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 把 `m_device`、`m_hwnd`、`m_backBufferTexture` 置为 `nullptr`
+- 把 `m_width`、`m_height` 置为 `0`
+- 不创建 OpenGL 上下文
+- 不分配默认帧缓冲，也不创建纹理
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-}
-```
+构造函数保持“零成本”，真正的窗口接入与资源分配都放在 [Initialize](Initialize.md) 中完成。这种分层更适合测试，也更符合引擎里“先 new，再显式 Initialize”的对象生命周期。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLSwapChain](OpenGLSwapChain.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Destructor.md
index 8cf3ef71..c414a7e0 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Destructor.md
@@ -1,29 +1,24 @@
 # OpenGLSwapChain::~OpenGLSwapChain()
 
-销毁对象并释放相关资源。
-
 ```cpp
 ~OpenGLSwapChain() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象，并尝试释放当前交换链包装器持有的资源。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 析构函数内部直接调用 [Shutdown](Shutdown.md)
+- 如果 `m_backBufferTexture` 仍然存在，会在 `Shutdown()` 中被删除
+- 不会主动查询窗口系统状态，也不会销毁窗口本身
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+如果上层已经显式调用过 `Shutdown()`，析构时再次进入该流程也是安全的，因为实现对空指针做了保护。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [OpenGLSwapChain](OpenGLSwapChain.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBuffer.md
index d89fbad3..af1c8351 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBuffer.md
@@ -1,30 +1,30 @@
-# OpenGLSwapChain::GetCurrentBackBuffer
-
-获取相关状态或对象。
+# OpenGLSwapChain::GetCurrentBackBuffer()
 
 ```cpp
 RHITexture* GetCurrentBackBuffer() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对外暴露的 back buffer 纹理对象。
 
-**返回：** `RHITexture*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回成员 `m_backBufferTexture`
+- 返回类型是 `RHITexture*`，但实际对象类型是 `OpenGLTexture`
+- 如果尚未初始化或已经关闭，返回值可能为 `nullptr`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::GetCurrentBackBuffer(...)。
-    (void)object;
-}
-```
+OpenGL 默认窗口帧缓冲本身不适合作为统一的 `RHITexture` 直接暴露，所以当前后端维护了一张代理纹理。上层渲染代码、RTV 创建、截图流程都通过这张纹理继续复用跨后端接口。
+
+## 注意事项
+
+- 这不是 Win32/WGL 默认帧缓冲句柄本身
+- [Present](Present.md) 只有在这张纹理有效且资源状态满足当前实现约定时，才会把它 blit 到默认帧缓冲
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [Present](Present.md)
+- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)
+- [OpenGLSwapChain](OpenGLSwapChain.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBufferIndex.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBufferIndex.md
index e57a287c..c46f36fa 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBufferIndex.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetCurrentBackBufferIndex.md
@@ -1,30 +1,29 @@
-# OpenGLSwapChain::GetCurrentBackBufferIndex
-
-获取相关状态或对象。
+# OpenGLSwapChain::GetCurrentBackBufferIndex()
 
 ```cpp
 uint32_t GetCurrentBackBufferIndex() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 back buffer 索引。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 固定返回 `0`
+- 不随 [Present](Present.md) 调用变化
+- 不维护真正的双缓冲或多缓冲轮换状态
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::GetCurrentBackBufferIndex(...)。
-    (void)object;
-}
-```
+这是为了满足 `RHISwapChain` 统一接口而保留的占位实现。对 OpenGL 后端来说，当前对象更像“单一窗口呈现入口”，而不是真实的多缓冲交换链。
+
+## 注意事项
+
+如果上层逻辑假设索引会像 D3D12/Vulkan 一样轮换，就会得到错误结论。当前 OpenGL 路径应视为单 back buffer 语义。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
+- [Present](Present.md)
+- [OpenGLSwapChain](OpenGLSwapChain.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetHeight.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetHeight.md
index cfce53f4..1fad5d3a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetHeight.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetHeight.md
@@ -1,30 +1,24 @@
-# OpenGLSwapChain::GetHeight
-
-获取相关状态或对象。
+# OpenGLSwapChain::GetHeight()
 
 ```cpp
 int GetHeight() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回交换链对象当前缓存的高度。
 
-**返回：** `int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回成员 `m_height`
+- 这个值来源于 [Initialize](Initialize.md) 或 [Resize](Resize.md)
+- 不会实时查询窗口客户区尺寸
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::GetHeight(...)。
-    (void)object;
-}
-```
+由于 [Resize](Resize.md) 只更新缓存值而不重建内部纹理，所以这里返回的高度可能与 `m_backBufferTexture` 实际尺寸不一致。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [GetWidth](GetWidth.md)
+- [Resize](Resize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetNativeHandle.md
index e463b2dd..248f569c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetNativeHandle.md
@@ -1,30 +1,24 @@
-# OpenGLSwapChain::GetNativeHandle
-
-获取相关状态或对象。
+# OpenGLSwapChain::GetNativeHandle()
 
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层原生窗口句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_hwnd`
+- 在 Win32 路径下，这个值本质上是 `HWND`
+- 返回值类型被擦除为 `void*`，以便匹配通用 RHI 接口
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::GetNativeHandle(...)。
-    (void)object;
-}
-```
+对于显式图形 API，`GetNativeHandle()` 往往返回 swap chain 或平台 surface。当前 OpenGL 实现里更有价值的原生对象是窗口本身，因为真正的呈现由窗口上下文和系统 `SwapBuffers` 驱动。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [SwapBuffers](SwapBuffers.md)
+- [OpenGLSwapChain](OpenGLSwapChain.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetWidth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetWidth.md
index 5a45a38e..d4ed3c22 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetWidth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/GetWidth.md
@@ -1,30 +1,24 @@
-# OpenGLSwapChain::GetWidth
-
-获取相关状态或对象。
+# OpenGLSwapChain::GetWidth()
 
 ```cpp
 int GetWidth() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回交换链对象当前缓存的宽度。
 
-**返回：** `int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回成员 `m_width`
+- 这个值由 [Initialize](Initialize.md) 和 [Resize](Resize.md) 写入
+- 不会主动同步窗口系统或内部纹理的真实宽度
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::GetWidth(...)。
-    (void)object;
-}
-```
+在当前实现里，它表示“逻辑呈现尺寸”，不是严格意义上的默认帧缓冲查询结果。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [GetHeight](GetHeight.md)
+- [Resize](Resize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Initialize.md
index 6302b971..7c81d115 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Initialize.md
@@ -1,34 +1,50 @@
-# OpenGLSwapChain::Initialize
-
-初始化内部状态。
+# OpenGLSwapChain::Initialize()
 
 ```cpp
 bool Initialize(OpenGLDevice* device, HWND window, int width, int height);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `window` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
+把交换链包装器绑定到指定的 OpenGL 设备和窗口，并按需创建 back buffer 代理纹理。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `device`: 呈现所依赖的 `OpenGLDevice`
+- `window`: Win32 窗口句柄
+- `width`: 初始宽度
+- `height`: 初始高度
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::Initialize(...)。
-    (void)object;
-}
-```
+`bool`。当前实现始终返回 `true`。
+
+## 当前实现行为
+
+- 直接缓存 `device`、`window`、`width`、`height`
+- 如果 `m_backBufferTexture` 为空，则 new 一个 `OpenGLTexture`
+- 纹理固定按以下参数初始化：
+  - 类型 `OpenGLTextureType::Texture2D`
+  - 尺寸 `width x height`
+  - `depth = 1`
+  - `mipLevels = 1`
+  - 格式 `OpenGLFormat::RGBA8`
+  - 初始数据 `nullptr`
+- 不会检查 `device` 或 `window` 是否为空
+- 不会调用 `MakeContextCurrent()`
+- 不会检查 `OpenGLTexture::Initialize(...)` 的返回值
+
+## 设计说明
+
+这里创建的是“供引擎上层引用的 back buffer 代理纹理”，不是 WGL 默认帧缓冲本体。这样做可以让 `GetCurrentBackBuffer()`、截图和资源视图创建继续沿用统一的纹理接口。
+
+## 注意事项
+
+- 如果对象已经初始化过，再次调用不会自动重建纹理
+- 因此重复初始化到新尺寸时，缓存的 `m_width` / `m_height` 可能和旧纹理尺寸不一致
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
+- [Resize](Resize.md)
+- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/OpenGLSwapChain.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/OpenGLSwapChain.md
index 85045660..fe5766dc 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/OpenGLSwapChain.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/OpenGLSwapChain.md
@@ -6,38 +6,75 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLSwapChain` public API。
+**描述**: Win32 OpenGL 后端的交换链包装器；它把默认窗口帧缓冲与一个可选的 back buffer 代理纹理统一到 `RHISwapChain` 抽象下。
 
-## 概述
+## 概览
 
-`OpenGLSwapChain.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+在 D3D12 或 Vulkan 里，swap chain 往往意味着“由驱动管理的多张呈现图像”。当前 `OpenGLSwapChain` 不是这种模型。
 
-## 声明概览
+它的真实工作方式更接近：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `PresentMode` | `enum class` | 头文件中的公开声明。 |
-| `SurfaceFormat` | `enum class` | 头文件中的公开声明。 |
-| `OpenGLSwapChain` | `class` | 继承自 `RHISwapChain` 的公开声明。 |
+- 窗口系统拥有默认帧缓冲
+- 引擎另外维护一张 `OpenGLTexture` 作为 `GetCurrentBackBuffer()` 的返回对象
+- [Present](Present.md) 视情况把这张纹理 blit 到默认帧缓冲
+- 最后调用 Win32 `SwapBuffers`
 
-## 公共方法
+这种设计的重点不是模拟一份完整的显式 API 交换链，而是让上层渲染框架、测试基架和截图工具继续通过统一的 `RHISwapChain` 接口工作。
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLSwapChain()](Constructor.md) | 构造对象。 |
-| [~OpenGLSwapChain()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Present](Present.md) | 公开方法，详见头文件声明。 |
-| [SwapBuffers](SwapBuffers.md) | 公开方法，详见头文件声明。 |
-| [Resize](Resize.md) | 公开方法，详见头文件声明。 |
-| [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md) | 获取相关状态或对象。 |
-| [GetCurrentBackBuffer](GetCurrentBackBuffer.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
-| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
+## 主要职责
+
+- 记录 `OpenGLDevice*`、`HWND` 和当前逻辑尺寸
+- 按需创建一张 `RGBA8` 的 back buffer 代理纹理
+- 对外暴露 [GetCurrentBackBuffer](GetCurrentBackBuffer.md) 与 [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)
+- 在 [Present](Present.md) 中把代理纹理复制到默认帧缓冲
+- 通过 [SwapBuffers](SwapBuffers.md) 调用系统呈现
+
+## 当前实现的真实行为
+
+- 只覆盖 Win32 路径，`GetNativeHandle()` 返回 `HWND`
+- `PresentMode` / `SurfaceFormat` 两个枚举当前只停留在头文件层面，没有参与实际创建流程
+- [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md) 永远返回 `0`
+- [Resize](Resize.md) 只更新缓存宽高，不重建 `m_backBufferTexture`
+- [Present](Present.md) 忽略 `syncInterval` 与 `flags`
+- 当 `m_backBufferTexture` 不满足当前约定条件时，`Present()` 只会直接交换默认窗口缓冲
+- [Shutdown](Shutdown.md) 释放代理纹理并断开设备/窗口引用，但不会把宽高清零
+
+## 设计背景
+
+OpenGL 的默认窗口帧缓冲由上下文和窗口系统维护，不能像显式 API 那样把每一张 back buffer 都作为标准资源对象稳定暴露。当前实现采用“代理纹理 + Present 时复制”的策略，主要收益有两点：
+
+- 上层系统仍然可以把 back buffer 当作 `RHITexture` 使用
+- 资源视图、截图、离屏渲染等路径可以复用统一的纹理与视图抽象
+
+这是一种很典型的跨后端工程折中：先保证 API 统一和可用性，再逐步增强平台特性。
+
+## 生命周期
+
+- [OpenGLSwapChain()](Constructor.md) 把成员初始化为空状态
+- [Initialize](Initialize.md) 缓存设备/窗口并创建代理纹理
+- 渲染期间通过 [GetCurrentBackBuffer](GetCurrentBackBuffer.md) 暴露纹理给 RTV、截图和测试流程
+- [Present](Present.md) 负责把代理纹理内容提交到默认窗口帧缓冲
+- [Shutdown](Shutdown.md) 释放代理纹理
+
+## 当前限制
+
+- 不是实际多缓冲 swap chain
+- 不提供轮换帧索引
+- 不支持真正的 vsync / mailbox / fifo 策略切换
+- `Resize()` 与内部纹理尺寸可能失配
+- 缺少严格的错误处理和状态校验
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [Present](Present.md)
+- [SwapBuffers](SwapBuffers.md)
+- [Resize](Resize.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)
+- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)
+- [OpenGLScreenshot](../OpenGLScreenshot/OpenGLScreenshot.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Present.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Present.md
index d1170804..bc122208 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Present.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Present.md
@@ -1,32 +1,47 @@
-# OpenGLSwapChain::Present
-
-公开方法，详见头文件声明。
+# OpenGLSwapChain::Present()
 
 ```cpp
 void Present(uint32_t syncInterval = 1, uint32_t flags = 0) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `syncInterval` - 参数语义详见头文件声明。
-- `flags` - 参数语义详见头文件声明。
+把当前可呈现内容提交到窗口系统。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `syncInterval`: 保留给统一接口；当前未使用
+- `flags`: 保留给统一接口；当前未使用
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::Present(...)。
-    (void)object;
-}
-```
+- 先忽略 `syncInterval` 和 `flags`
+- 如果 `m_device` 非空，先调用 `m_device->MakeContextCurrent()`
+- 然后检查是否满足“从代理纹理 blit 到默认帧缓冲”的条件：
+  - `m_backBufferTexture != nullptr`
+  - `m_backBufferTexture->GetID() != 0`
+  - `m_backBufferTexture->GetState() != ResourceStates::Common`
+- 如果满足条件：
+  - 创建临时 `GL_READ_FRAMEBUFFER`
+  - 把代理纹理挂到 `GL_COLOR_ATTACHMENT0`
+  - 设置 `glReadBuffer(GL_COLOR_ATTACHMENT0)`
+  - 把绘制目标切回默认帧缓冲 `0`
+  - 调用 `glBlitFramebuffer(...)` 复制颜色内容
+  - 删除临时 FBO
+- 无论是否走 blit 路径，最后都会调用 Win32 `::SwapBuffers(m_device->GetPresentationDC())`
+
+## 设计说明
+
+这里的关键点是：当前 OpenGL 后端允许上层先渲染到一张普通纹理，再在 Present 阶段把纹理内容搬回默认窗口帧缓冲。这种结构更容易和跨后端 `RHITexture` / `RHIResourceView` 抽象保持一致。
+
+## 注意事项
+
+- 当前没有真正实现垂直同步控制
+- `MakeContextCurrent()` 的返回值没有被检查
+- 如果代理纹理仍处于 `ResourceStates::Common`，实现会跳过 blit，直接交换默认窗口缓冲
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [SwapBuffers](SwapBuffers.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
+- [OpenGLScreenshot](../OpenGLScreenshot/OpenGLScreenshot.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Resize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Resize.md
index 3d777ad1..53cd01f6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Resize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Resize.md
@@ -1,32 +1,36 @@
-# OpenGLSwapChain::Resize
-
-公开方法，详见头文件声明。
+# OpenGLSwapChain::Resize()
 
 ```cpp
 void Resize(uint32_t width, uint32_t height) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
+更新交换链对象记录的逻辑尺寸。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `width`: 新宽度
+- `height`: 新高度
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::Resize(...)。
-    (void)object;
-}
-```
+- 仅把 `m_width` 更新为 `width`
+- 仅把 `m_height` 更新为 `height`
+- 不重建 `m_backBufferTexture`
+- 不调用任何 Win32 或 OpenGL 窗口尺寸同步逻辑
+
+## 设计说明
+
+当前实现把 `Resize()` 当成“状态通知”而不是“完整重建流程”。这对最小可运行后端足够，但和商业引擎里真正的 swap chain 重建仍有明显差距。
+
+## 注意事项
+
+- 调用后 [GetWidth](GetWidth.md) / [GetHeight](GetHeight.md) 会变化
+- 但 `GetCurrentBackBuffer()` 返回纹理的真实尺寸可能仍是旧值
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [GetWidth](GetWidth.md)
+- [GetHeight](GetHeight.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Shutdown.md
index 6d9c4788..7be7a427 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/Shutdown.md
@@ -1,30 +1,31 @@
-# OpenGLSwapChain::Shutdown
-
-关闭并清理内部状态。
+# OpenGLSwapChain::Shutdown()
 
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放交换链包装器当前持有的资源。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_backBufferTexture` 非空，则 `delete` 它
+- 把 `m_backBufferTexture` 置为 `nullptr`
+- 把 `m_hwnd` 置为 `nullptr`
+- 把 `m_device` 置为 `nullptr`
+- 不会修改 `m_width` 和 `m_height`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::Shutdown(...)。
-    (void)object;
-}
-```
+`Shutdown()` 只负责对象自己拥有的资源。窗口和 OpenGL 上下文都不由这个类创建，也就不在这里销毁。
+
+## 注意事项
+
+- 调用后 [GetCurrentBackBuffer](GetCurrentBackBuffer.md) 会返回 `nullptr`
+- 如果上层希望对象回到完全“未初始化”状态，还需要自行重置尺寸语义
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/SwapBuffers.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/SwapBuffers.md
index 0d964fd9..fcb78381 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/SwapBuffers.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLSwapChain/SwapBuffers.md
@@ -1,30 +1,25 @@
-# OpenGLSwapChain::SwapBuffers
-
-公开方法，详见头文件声明。
+# OpenGLSwapChain::SwapBuffers()
 
 ```cpp
 void SwapBuffers();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+直接调用窗口系统的缓冲交换函数。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_device` 非空，则执行 `::SwapBuffers(m_device->GetPresentationDC())`
+- 不做额外 blit
+- 不切换上下文
+- 不处理同步策略
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
+## 何时使用
 
-void Example() {
-    XCEngine::RHI::OpenGLSwapChain object;
-    // 根据上下文补齐参数后调用 OpenGLSwapChain::SwapBuffers(...)。
-    (void)object;
-}
-```
+这是比 [Present](Present.md) 更底层的调用。当前代码里真正对外暴露的统一入口仍然是 `Present()`；`SwapBuffers()` 更适合作为内部辅助方法或调试使用。
 
 ## 相关文档
 
-- [返回类总览](OpenGLSwapChain.md)
-- [返回模块目录](../OpenGL.md)
+- [Present](Present.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index e3092c39..8f5de51a 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-28 00:49:41`
+**生成时间**: `2026-03-28 01:09:27`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`