From 0c8a3e90ec183bc9edbe23b0ffa56bdeee81f6dd Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Fri, 27 Mar 2026 22:48:58 +0800
Subject: [PATCH] docs(api): expand fence and framebuffer docs

---
 .../RHI/D3D12/D3D12Fence/Constructor.md       | 24 ++-----
 .../RHI/D3D12/D3D12Fence/D3D12Fence.md        | 51 ++++++++------
 .../RHI/D3D12/D3D12Fence/Destructor.md        | 25 ++-----
 .../RHI/D3D12/D3D12Fence/GetCompletedValue.md | 24 ++-----
 .../RHI/D3D12/D3D12Fence/GetEventHandle.md    | 23 ++----
 .../XCEngine/RHI/D3D12/D3D12Fence/GetFence.md | 24 +++----
 .../RHI/D3D12/D3D12Fence/GetNativeHandle.md   | 23 ++----
 .../RHI/D3D12/D3D12Fence/Initialize.md        | 37 +++++-----
 .../XCEngine/RHI/D3D12/D3D12Fence/Shutdown.md | 24 ++-----
 .../XCEngine/RHI/D3D12/D3D12Fence/Signal.md   | 40 +++--------
 .../api/XCEngine/RHI/D3D12/D3D12Fence/Wait.md | 26 +++----
 .../RHI/OpenGL/OpenGLFence/Constructor.md     | 24 ++-----
 .../RHI/OpenGL/OpenGLFence/Destructor.md      | 25 ++-----
 .../OpenGL/OpenGLFence/GetCompletedValue.md   | 26 +++----
 .../RHI/OpenGL/OpenGLFence/GetNativeHandle.md | 24 +++----
 .../RHI/OpenGL/OpenGLFence/Initialize.md      | 30 ++++----
 .../RHI/OpenGL/OpenGLFence/OpenGLFence.md     | 52 +++++++++-----
 .../RHI/OpenGL/OpenGLFence/Shutdown.md        | 24 ++-----
 .../XCEngine/RHI/OpenGL/OpenGLFence/Signal.md | 42 ++++-------
 .../XCEngine/RHI/OpenGL/OpenGLFence/Wait.md   | 32 ++++-----
 .../RHI/OpenGL/OpenGLFramebuffer/Bind.md      | 24 ++-----
 .../OpenGLFramebuffer/BindFramebuffer.md      | 24 ++-----
 .../OpenGL/OpenGLFramebuffer/ClearColor.md    | 32 +++------
 .../OpenGL/OpenGLFramebuffer/ClearDepth.md    | 25 ++-----
 .../OpenGLFramebuffer/ClearDepthStencil.md    | 28 +++-----
 .../OpenGL/OpenGLFramebuffer/ClearStencil.md  | 25 ++-----
 .../OpenGL/OpenGLFramebuffer/Constructor.md   | 24 ++-----
 .../OpenGL/OpenGLFramebuffer/Destructor.md    | 25 ++-----
 .../OpenGLFramebuffer/GetFramebuffer.md       | 24 ++-----
 .../RHI/OpenGL/OpenGLFramebuffer/GetHeight.md | 23 ++----
 .../OpenGLFramebuffer/GetNativeHandle.md      | 23 ++----
 .../RHI/OpenGL/OpenGLFramebuffer/GetWidth.md  | 24 ++-----
 .../OpenGL/OpenGLFramebuffer/Initialize.md    | 62 ++++++++--------
 .../RHI/OpenGL/OpenGLFramebuffer/IsValid.md   | 23 ++----
 .../OpenGLFramebuffer/OpenGLFramebuffer.md    | 70 +++++++++++--------
 .../RHI/OpenGL/OpenGLFramebuffer/Shutdown.md  | 24 ++-----
 .../RHI/OpenGL/OpenGLFramebuffer/Unbind.md    | 23 ++----
 .../OpenGLFramebuffer/UnbindFramebuffer.md    | 23 ++----
 docs/api/_meta/rebuild-status.md              |  2 +-
 39 files changed, 398 insertions(+), 730 deletions(-)

diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Constructor.md
index d3d3bf9e..e3bba03b 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Constructor.md
@@ -1,28 +1,18 @@
-# D3D12Fence::D3D12Fence()
-
-构造对象。
+# D3D12Fence::D3D12Fence
 
 ```cpp
 D3D12Fence();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空 fence 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-}
-```
+- 仅把内部 event 句柄初始化为 `nullptr`。
+- 不创建原生 fence。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/D3D12Fence.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/D3D12Fence.md
index ff26c99f..0091191a 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/D3D12Fence.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/D3D12Fence.md
@@ -6,34 +6,43 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12Fence.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Fence` public API。
+**描述**: D3D12 后端的 fence 封装，持有一个 `ID3D12Fence` 和一个 Win32 event，用于 GPU / CPU 同步。
 
 ## 概述
 
-`D3D12Fence.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+和 OpenGL 的模拟方案不同，D3D12 有原生 fence 机制。`D3D12Fence` 基本上是一个轻量封装:
 
-## 声明概览
+- `ID3D12Fence`
+- 一个 `CreateEvent()` 创建的 Win32 event
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12Fence` | `class` | 继承自 `RHIFence` 的公开声明。 |
+这让它既能参与命令队列信号链路，也能在 CPU 端通过 `SetEventOnCompletion()` 阻塞等待。
 
-## 公共方法
+## 当前实现的真实行为
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12Fence()](Constructor.md) | 构造对象。 |
-| [~D3D12Fence()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Signal](Signal.md) | 公开方法，详见头文件声明。 |
-| [Wait](Wait.md) | 公开方法，详见头文件声明。 |
-| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 |
-| [GetEventHandle](GetEventHandle.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetFence](GetFence.md) | 获取相关状态或对象。 |
+- [`Initialize`](Initialize.md) 会创建 fence 和 event。
+- [`Wait`](Wait.md) 通过 `SetEventOnCompletion()` + `WaitForSingleObject()` 等待 GPU 达到目标值。
+- [`Signal`](Signal.md) 直接调用 `ID3D12Fence::Signal()`，这是 CPU 侧 signal，不是命令队列 signal。
+- 真正用于“让 GPU queue signal 某个 fence 值”的常见路径，是 [`D3D12CommandQueue::Signal`](../D3D12CommandQueue/Signal.md)。
+
+## 设计含义
+
+- 这与商业引擎常见的做法一致: fence 对象负责同步原语本身，命令队列负责把 GPU 执行进度写入 fence。
+- 单独暴露 `Signal()` 让测试和 CPU 驱动流程也能直接推进 fence 值。
+
+## 当前限制
+
+- `Signal()` 并不等价于“GPU 已执行到这里”，除非它是由命令队列调用底层 queue signal 完成的。
+- 如果 `CreateFence()` 成功但 `CreateEvent()` 失败，`Initialize()` 会返回 `false`。
+
+## 重点方法
+
+- [Initialize](Initialize.md)
+- [Signal](Signal.md)
+- [Wait](Wait.md)
+- [GetCompletedValue](GetCompletedValue.md)
+- [GetFence](GetFence.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Destructor.md
index f0f11310..ae05249f 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Destructor.md
@@ -1,29 +1,18 @@
-# D3D12Fence::~D3D12Fence()
-
-销毁对象并释放相关资源。
+# D3D12Fence::~D3D12Fence
 
 ```cpp
 ~D3D12Fence() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 fence 对象并释放其原生资源。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数调用 [`Shutdown`](Shutdown.md)。
+- 会关闭 Win32 event 并释放 `ID3D12Fence`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetCompletedValue.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetCompletedValue.md
index 48b09bdb..7ce830fb 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetCompletedValue.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetCompletedValue.md
@@ -1,30 +1,18 @@
 # D3D12Fence::GetCompletedValue
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetCompletedValue() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+查询底层 D3D12 fence 当前已完成到的值。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::GetCompletedValue(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_fence->GetCompletedValue()`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [Wait](Wait.md)
+- [Signal](Signal.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetEventHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetEventHandle.md
index 889e82d3..0d83971c 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetEventHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetEventHandle.md
@@ -1,30 +1,21 @@
 # D3D12Fence::GetEventHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetEventHandle();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 fence 内部持有的 Win32 event 句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `HANDLE`，以 `void*` 形式暴露。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::GetEventHandle(...)。
-    (void)object;
-}
-```
+- 该句柄主要用于需要直接与 Win32 等待 API 交互的场景。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [Wait](Wait.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetFence.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetFence.md
index c80b7266..e7a9541f 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetFence.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetFence.md
@@ -1,30 +1,22 @@
 # D3D12Fence::GetFence
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12Fence* GetFence() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以强类型方式返回底层 `ID3D12Fence` 指针。
 
-**返回：** `ID3D12Fence*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `m_fence.Get()`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::GetFence(...)。
-    (void)object;
-}
-```
+- 这是 `D3D12CommandQueue::Signal()` 等底层桥接代码使用的主要接口。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [D3D12CommandQueue::Signal](../D3D12CommandQueue/Signal.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetNativeHandle.md
index c65264b4..50bbfa29 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetNativeHandle.md
@@ -1,30 +1,17 @@
 # D3D12Fence::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回原生 `ID3D12Fence*`。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 以 `void*` 形式返回 `m_fence.Get()`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [GetFence](GetFence.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Initialize.md
index 1d2f5c1f..2dd63fa5 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Initialize.md
@@ -1,32 +1,33 @@
 # D3D12Fence::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize(ID3D12Device* device, uint64_t initialValue = 0);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `initialValue` - 参数语义详见头文件声明。
+创建原生 `ID3D12Fence` 与等待用的 Win32 event。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `device` 必须有效。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
+## 参数
 
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::Initialize(...)。
-    (void)object;
-}
-```
+- `device`: 用于创建 fence 的 D3D12 设备。
+- `initialValue`: fence 初始值。
+
+## 返回值
+
+- fence 和 event 都创建成功时返回 `true`。
+- 任一环节失败时返回 `false`。
+
+## 当前实现行为
+
+- 调用 `device->CreateFence(initialValue, D3D12_FENCE_FLAG_NONE, ...)`。
+- 再调用 `CreateEvent(nullptr, FALSE, FALSE, nullptr)` 创建自动复位 event。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [Wait](Wait.md)
+- [GetEventHandle](GetEventHandle.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Shutdown.md
index d455e064..b2ed74ce 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Shutdown.md
@@ -1,30 +1,18 @@
 # D3D12Fence::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放 fence 的 Win32 event 和原生 `ID3D12Fence`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::Shutdown(...)。
-    (void)object;
-}
-```
+- 如果 event 存在，则调用 `CloseHandle()`。
+- 然后 `m_fence.Reset()` 释放 COM 对象。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Signal.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Signal.md
index 578721c5..9c418670 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Signal.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Signal.md
@@ -1,43 +1,25 @@
 # D3D12Fence::Signal
 
-公开方法，详见头文件声明。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12Fence.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 void Signal() override;
-```
-
-**参数：** 无。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void Signal(uint64_t value) override;
 ```
 
-**参数：**
-- `value` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `void` - 无返回值。
+直接在 fence 对象上写入一个新值。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
+- 无参版本等价于 `Signal(1)`。
+- 有参版本直接调用 `m_fence->Signal(value)`。
 
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::Signal(...)。
-    (void)object;
-}
-```
+## 重要区别
+
+- 这是 `ID3D12Fence` 自身的 CPU 侧 signal。
+- 如果你想表达“某条 GPU 命令队列在执行到某个位置后 signal fence”，应使用 [`D3D12CommandQueue::Signal`](../D3D12CommandQueue/Signal.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [Wait](Wait.md)
+- [GetCompletedValue](GetCompletedValue.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Wait.md b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Wait.md
index d8c8ada0..11500f72 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Wait.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Fence/Wait.md
@@ -1,31 +1,23 @@
 # D3D12Fence::Wait
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Wait(uint64_t value) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `value` - 参数语义详见头文件声明。
+阻塞当前 CPU 线程，直到 fence 完成值达到指定阈值。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `value`: 目标 fence 值。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Fence.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Fence object;
-    // 根据上下文补齐参数后调用 D3D12Fence::Wait(...)。
-    (void)object;
-}
-```
+- 如果 `GetCompletedValue() >= value`，立即返回。
+- 否则调用 `SetEventOnCompletion(value, m_eventHandle)`，再 `WaitForSingleObject(m_eventHandle, INFINITE)`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Fence.md)
-- [返回模块目录](../D3D12.md)
+- [GetCompletedValue](GetCompletedValue.md)
+- [GetEventHandle](GetEventHandle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Constructor.md
index f1a35b03..a6a50b86 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Constructor.md
@@ -1,28 +1,18 @@
-# OpenGLFence::OpenGLFence()
-
-构造对象。
+# OpenGLFence::OpenGLFence
 
 ```cpp
 OpenGLFence();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空 fence 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-}
-```
+- 不创建 `GLsync`。
+- `m_signaledValue` 与 `m_completedValue` 初始化为 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Destructor.md
index 3d6f8b4c..dfc4a603 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Destructor.md
@@ -1,29 +1,18 @@
-# OpenGLFence::~OpenGLFence()
-
-销毁对象并释放相关资源。
+# OpenGLFence::~OpenGLFence
 
 ```cpp
 ~OpenGLFence() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 fence 并释放内部 `GLsync`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数调用 [`Shutdown`](Shutdown.md)。
+- 如果内部仍持有 sync，会执行 `glDeleteSync()`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetCompletedValue.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetCompletedValue.md
index aed6a810..c0eecff7 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetCompletedValue.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetCompletedValue.md
@@ -1,30 +1,24 @@
 # OpenGLFence::GetCompletedValue
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetCompletedValue() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+查询 fence 当前已完成到哪个值。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 如果没有活动中的 `GLsync`，返回 `m_completedValue`。
+- 如果 `GLsync` 已被驱动标记为 `GL_SIGNALED`，返回 `m_signaledValue`。
+- 否则返回 `m_completedValue`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-    // 根据上下文补齐参数后调用 OpenGLFence::GetCompletedValue(...)。
-    (void)object;
-}
-```
+- 该函数会查询 `GL_SYNC_STATUS`，但不会主动删除 sync，也不会把 `m_completedValue` 写回最新值。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Wait](Wait.md)
+- [Signal](Signal.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetNativeHandle.md
index 7c1a2a7b..4cd3f8ea 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetNativeHandle.md
@@ -1,30 +1,22 @@
 # OpenGLFence::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 `GLsync` 句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回内部 `GLsync`，以 `void*` 形式暴露。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-    // 根据上下文补齐参数后调用 OpenGLFence::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 如果当前还没有 sync，会立即调用 `glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0)` 创建一个新的。
+- 因此它不是纯 getter，而是带副作用的懒初始化接口。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Signal](Signal.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Initialize.md
index 77d0eb2b..a82ff186 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Initialize.md
@@ -1,31 +1,27 @@
 # OpenGLFence::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize(uint64_t initialValue = 0);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `initialValue` - 参数语义详见头文件声明。
+初始化 CPU 侧 fence 计数状态。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `initialValue`: 初始 signaled / completed 值。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-    // 根据上下文补齐参数后调用 OpenGLFence::Initialize(...)。
-    (void)object;
-}
-```
+- 当前实现始终返回 `true`。
+
+## 当前实现行为
+
+- 不会立即创建 `GLsync`。
+- 仅把 `m_signaledValue` 和 `m_completedValue` 设为 `initialValue`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Signal](Signal.md)
+- [GetCompletedValue](GetCompletedValue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/OpenGLFence.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/OpenGLFence.md
index cfc20d51..6ce2b61f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/OpenGLFence.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/OpenGLFence.md
@@ -6,32 +6,46 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLFence.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLFence` public API。
+**描述**: OpenGL 后端的同步对象封装，使用单个 `GLsync` 配合 CPU 侧计数值模拟 timeline 风格的 fence 接口。
 
 ## 概述
 
-`OpenGLFence.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+OpenGL 没有 D3D12 那种原生 timeline fence 接口，更多是一次性的 `GLsync` 栅栏。`OpenGLFence` 的实现方式，是把:
 
-## 声明概览
+- 一个可被替换的 `GLsync`
+- 一个“最近 signal 的值”
+- 一个“最近确认完成的值”
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLFence` | `class` | 继承自 `RHIFence` 的公开声明。 |
+组合起来，向 RHI 暴露出近似 timeline fence 的 API 形状。
 
-## 公共方法
+这类适配在跨后端引擎里很常见，但要明确一点: 它的接口看起来像 timeline fence，不代表底层语义真的和 D3D12 / Vulkan 完全一致。
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLFence()](Constructor.md) | 构造对象。 |
-| [~OpenGLFence()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Signal](Signal.md) | 公开方法，详见头文件声明。 |
-| [Wait](Wait.md) | 公开方法，详见头文件声明。 |
-| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
+## 当前实现的真实行为
+
+- 对象内部同一时间只维护一个 `GLsync`。
+- 每次 [`Signal`](Signal.md) 新值时，如果旧 `GLsync` 还存在，会先等待并删除旧同步对象。
+- [`Wait`](Wait.md) 等待成功后，会把 `m_completedValue` 直接更新为当前 `m_signaledValue`。
+- [`GetNativeHandle`](GetNativeHandle.md) 在还没有 sync 时会懒创建一个新的 `GLsync`。
+
+## 设计取舍
+
+- 这种实现足够支撑当前引擎的基础“提交后等待完成”流程。
+- 代价是它不能同时保留多段独立的 in-flight timeline 历史。
+
+## 当前限制
+
+- 不是严格意义上的 timeline fence。
+- 如果通过 [`OpenGLDevice::CreateFence`](../OpenGLDevice/CreateFence.md) 创建，`initialValue > 0` 当前只会被折叠成 `1`，不会保留原始数值。
+- `GetNativeHandle()` 本身带有副作用: 可能会额外插入新的 `GLsync`。
+
+## 重点方法
+
+- [Initialize](Initialize.md)
+- [Signal](Signal.md)
+- [Wait](Wait.md)
+- [GetCompletedValue](GetCompletedValue.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLCommandQueue](../OpenGLCommandQueue/OpenGLCommandQueue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Shutdown.md
index 6e13d34e..d91093f6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Shutdown.md
@@ -1,30 +1,18 @@
 # OpenGLFence::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放内部同步对象并重置计数状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-    // 根据上下文补齐参数后调用 OpenGLFence::Shutdown(...)。
-    (void)object;
-}
-```
+- 如果 `m_sync` 存在，则调用 `glDeleteSync()` 并清空指针。
+- 把 `m_signaledValue` 和 `m_completedValue` 都重置为 `0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Signal.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Signal.md
index 6a16c7f9..8f63b6ce 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Signal.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Signal.md
@@ -1,43 +1,27 @@
 # OpenGLFence::Signal
 
-公开方法，详见头文件声明。
-
-该方法在 `XCEngine/RHI/OpenGL/OpenGLFence.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 void Signal() override;
-```
-
-**参数：** 无。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void Signal(uint64_t value) override;
 ```
 
-**参数：**
-- `value` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `void` - 无返回值。
+插入一条新的 OpenGL 同步点，并记录对应的 fence 值。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
+- 无参版本等价于 `Signal(1)`。
+- 如果旧 `GLsync` 还存在，会先等待它完成并删除，再创建新的 `GLsync`。
+- 在创建新 sync 前会先调用 `glFlush()`。
+- `m_signaledValue` 被更新为传入值。
 
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-    // 根据上下文补齐参数后调用 OpenGLFence::Signal(...)。
-    (void)object;
-}
-```
+## 当前限制
+
+- 不强制值单调递增。
+- 因为旧 sync 会被替换，它不能保留多段未完成 timeline 的历史。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Wait](Wait.md)
+- [GetCompletedValue](GetCompletedValue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Wait.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Wait.md
index b43098db..b4f9bb48 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Wait.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Wait.md
@@ -1,31 +1,29 @@
 # OpenGLFence::Wait
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Wait(uint64_t value) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `value` - 参数语义详见头文件声明。
+在 CPU 侧等待 fence 达到指定值。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `value`: 希望等待到的 fence 值。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLFence object;
-    // 根据上下文补齐参数后调用 OpenGLFence::Wait(...)。
-    (void)object;
-}
-```
+- 如果 `m_completedValue >= value`，直接返回。
+- 如果内部存在 `GLsync`，会调用 `glClientWaitSync(..., GL_TIMEOUT_IGNORED)` 阻塞等待，然后删除该 sync。
+- 等待结束后，把 `m_completedValue` 更新为当前 `m_signaledValue`。
+
+## 当前限制
+
+- 它并不会验证“当前 signaled 值是否真的大于等于请求值”。
+- 这再次说明它是“单 sync + 计数缓存”的模拟方案，而不是真 timeline fence。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFence.md)
-- [返回模块目录](../OpenGL.md)
+- [Signal](Signal.md)
+- [GetCompletedValue](GetCompletedValue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md
index 671573b0..9742583c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md
@@ -1,30 +1,18 @@
 # OpenGLFramebuffer::Bind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Bind();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前 FBO 绑定到 `GL_FRAMEBUFFER`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::Bind(...)。
-    (void)object;
-}
-```
+- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`。
+- 不区分 `READ_FRAMEBUFFER` 与 `DRAW_FRAMEBUFFER`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Unbind](Unbind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md
index 0f45c083..f66a7839 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md
@@ -1,31 +1,17 @@
 # OpenGLFramebuffer::BindFramebuffer
 
-公开方法，详见头文件声明。
-
 ```cpp
 static void BindFramebuffer(unsigned int framebuffer);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `framebuffer` - 参数语义详见头文件声明。
+静态辅助函数，把任意 framebuffer id 绑定到 `GL_FRAMEBUFFER`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::BindFramebuffer(...)。
-    (void)object;
-}
-```
+- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [UnbindFramebuffer](UnbindFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md
index 54c87c78..228890f9 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md
@@ -1,35 +1,25 @@
 # OpenGLFramebuffer::ClearColor
 
-清空内部数据。
-
 ```cpp
 void ClearColor(int attachmentIndex, float r, float g, float b, float a);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `attachmentIndex` - 参数语义详见头文件声明。
-- `r` - 参数语义详见头文件声明。
-- `g` - 参数语义详见头文件声明。
-- `b` - 参数语义详见头文件声明。
-- `a` - 参数语义详见头文件声明。
+清除指定颜色附件。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `attachmentIndex`: 颜色附件序号。
+- `r` / `g` / `b` / `a`: 清除颜色。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearColor(...)。
-    (void)object;
-}
-```
+- 先绑定当前 FBO。
+- 调用 `glClearBufferfv(GL_COLOR, attachmentIndex, &r)` 执行清除。
+- 不恢复之前的 framebuffer 绑定状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [ClearDepth](ClearDepth.md)
+- [ClearDepthStencil](ClearDepthStencil.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md
index ee2a39d7..417d70d8 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md
@@ -1,31 +1,18 @@
 # OpenGLFramebuffer::ClearDepth
 
-清空内部数据。
-
 ```cpp
 void ClearDepth(float depth);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `depth` - 参数语义详见头文件声明。
+清除当前 framebuffer 的深度附件。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearDepth(...)。
-    (void)object;
-}
-```
+- 先绑定当前 FBO。
+- 调用 `glClearDepth(depth)`，随后执行 `glClear(GL_DEPTH_BUFFER_BIT)`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.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 2ad17a4f..99d87ac1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepthStencil.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepthStencil.md
@@ -1,32 +1,20 @@
 # OpenGLFramebuffer::ClearDepthStencil
 
-清空内部数据。
-
 ```cpp
 void ClearDepthStencil(float depth, uint8_t stencil);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `depth` - 参数语义详见头文件声明。
-- `stencil` - 参数语义详见头文件声明。
+同时清除深度和模板附件。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearDepthStencil(...)。
-    (void)object;
-}
-```
+- 先绑定当前 FBO。
+- 设置 `glClearDepth(depth)` 与 `glClearStencil(stencil)`。
+- 调用 `glClear(GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [ClearDepth](ClearDepth.md)
+- [ClearStencil](ClearStencil.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md
index cb8015ff..dc988500 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md
@@ -1,31 +1,18 @@
 # OpenGLFramebuffer::ClearStencil
 
-清空内部数据。
-
 ```cpp
 void ClearStencil(uint8_t stencil);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `stencil` - 参数语义详见头文件声明。
+清除当前 framebuffer 的模板附件。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearStencil(...)。
-    (void)object;
-}
-```
+- 先绑定当前 FBO。
+- 调用 `glClearStencil(stencil)`，随后执行 `glClear(GL_STENCIL_BUFFER_BIT)`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.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 c43ce84e..6f324a14 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Constructor.md
@@ -1,28 +1,18 @@
-# OpenGLFramebuffer::OpenGLFramebuffer()
-
-构造对象。
+# OpenGLFramebuffer::OpenGLFramebuffer
 
 ```cpp
 OpenGLFramebuffer();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空 FBO 包装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-}
-```
+- 把 framebuffer id、宽高和 sample 数初始化为 `0 / 0 / 1`。
+- 不创建真实 OpenGL framebuffer。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md
index 2b967359..4b1afc9d 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md
@@ -1,29 +1,18 @@
-# OpenGLFramebuffer::~OpenGLFramebuffer()
-
-销毁对象并释放相关资源。
+# OpenGLFramebuffer::~OpenGLFramebuffer
 
 ```cpp
 ~OpenGLFramebuffer() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象并释放内部 FBO。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数调用 [`Shutdown`](Shutdown.md)。
+- 如果已经创建过 framebuffer，会执行 `glDeleteFramebuffers()`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md
index 54a8e5e8..d9fa9fab 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md
@@ -1,30 +1,18 @@
 # OpenGLFramebuffer::GetFramebuffer
 
-获取相关状态或对象。
-
 ```cpp
 unsigned int GetFramebuffer() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回内部保存的 OpenGL framebuffer id。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::GetFramebuffer(...)。
-    (void)object;
-}
-```
+- 返回 `m_framebuffer`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [BindFramebuffer](BindFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md
index 2ead2b4c..520769a6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md
@@ -1,30 +1,17 @@
 # OpenGLFramebuffer::GetHeight
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetHeight() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 framebuffer 的逻辑高度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::GetHeight(...)。
-    (void)object;
-}
-```
+- 返回内部记录的 `m_height`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetWidth](GetWidth.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md
index 829c3b08..753a8a80 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md
@@ -1,30 +1,17 @@
 # OpenGLFramebuffer::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回原生 OpenGL framebuffer id。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 返回 `m_framebuffer`，以 `void*` 形式暴露。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetFramebuffer](GetFramebuffer.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md
index 3199a899..380a2bca 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md
@@ -1,30 +1,18 @@
 # OpenGLFramebuffer::GetWidth
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetWidth() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 framebuffer 的逻辑宽度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::GetWidth(...)。
-    (void)object;
-}
-```
+- 返回内部记录的 `m_width`。
+- 该值来自初始化参数，而不是运行时向 OpenGL 查询。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [GetHeight](GetHeight.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md
index 91be1969..d559c6ce 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md
@@ -1,49 +1,47 @@
 # OpenGLFramebuffer::Initialize
 
-初始化内部状态。
-
-该方法在 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 bool Initialize(const FramebufferDesc& desc);
+
+bool Initialize(
+    RHIRenderPass* renderPass,
+    uint32_t width,
+    uint32_t height,
+    uint32_t colorAttachmentCount,
+    RHIResourceView** colorAttachments,
+    RHIResourceView* depthStencilAttachment) override;
 ```
 
-**参数：**
-- `desc` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+创建并填充一个 OpenGL framebuffer object。
 
-## 重载 2: 声明
+## 当前实现行为
 
-```cpp
-bool Initialize(class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) override;
-```
+### `Initialize(const FramebufferDesc& desc)`
 
-**参数：**
-- `renderPass` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
-- `colorAttachmentCount` - 参数语义详见头文件声明。
-- `colorAttachments` - 参数语义详见头文件声明。
-- `depthStencilAttachment` - 参数语义详见头文件声明。
+- 复制 `FramebufferDesc` 到内部成员。
+- 创建 FBO 并附着最多 `16` 个颜色附件。
+- 根据 depth / stencil 附件类型选择合适的 attachment point。
+- 如果没有颜色附件，会把 `glDrawBuffer` 和 `glReadBuffer` 设为 `GL_NONE`。
+- 调用 `glCheckFramebufferStatus(GL_FRAMEBUFFER)` 验证完整性。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+### `Initialize(RHIRenderPass*, ...)`
 
-**示例：**
+- 当前忽略 `renderPass` 参数。
+- 从 `OpenGLResourceView::GetFramebufferAttachment()` 提取附件信息。
+- 同样创建 FBO、设置 draw buffer，并检查完整性。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::Initialize(...)。
-    (void)object;
-}
-```
+- FBO 完整时返回 `true`。
+- `glCheckFramebufferStatus()` 不是 `GL_FRAMEBUFFER_COMPLETE` 时返回 `false`。
+
+## 当前限制
+
+- 创建失败时不会在函数内部立即删除刚生成的 FBO id，通常由后续析构统一释放。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [IsValid](IsValid.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 d5d31ff2..e073e798 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/IsValid.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/IsValid.md
@@ -1,30 +1,21 @@
 # OpenGLFramebuffer::IsValid
 
-查询当前状态。
-
 ```cpp
 bool IsValid() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前对象是否持有非零 FBO id。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `m_framebuffer != 0` 时返回 `true`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::IsValid(...)。
-    (void)object;
-}
-```
+- 这是一个轻量检查，不会再次执行 `glCheckFramebufferStatus()`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md
index 6d4d7da7..21d0688d 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md
@@ -6,44 +6,52 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLFramebuffer` public API。
+**描述**: OpenGL 后端的 framebuffer 对象封装，用于把颜色、深度、模板附件组织成一个可绑定的 FBO。
 
 ## 概述
 
-`OpenGLFramebuffer.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+和 Vulkan / D3D12 的 render pass + framebuffer 分层不同，OpenGL 更偏向直接操作 framebuffer object。`OpenGLFramebuffer` 的职责，是把引擎内部的附件描述或资源视图组合成一个实际的 FBO，并提供基础的绑定与清屏操作。
 
-## 声明概览
+它可以理解为 OpenGL 后端里的“附件包”:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `FramebufferAttachmentType` | `enum class` | 头文件中的公开声明。 |
-| `FramebufferAttachment` | `struct` | 头文件中的公开声明。 |
-| `FramebufferDesc` | `struct` | 头文件中的公开声明。 |
-| `OpenGLFramebuffer` | `class` | 继承自 `RHIFramebuffer` 的公开声明。 |
+- 你先描述要挂哪些 texture / layer / mip。
+- 它负责创建 FBO、附着附件并检查完整性。
+- 命令列表或截图逻辑再在这个 FBO 上执行绘制、清理和 blit。
 
-## 公共方法
+## 当前实现的真实行为
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLFramebuffer()](Constructor.md) | 构造对象。 |
-| [~OpenGLFramebuffer()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
-| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
-| [IsValid](IsValid.md) | 查询当前状态。 |
-| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
-| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
-| [ClearColor](ClearColor.md) | 清空内部数据。 |
-| [ClearDepth](ClearDepth.md) | 清空内部数据。 |
-| [ClearStencil](ClearStencil.md) | 清空内部数据。 |
-| [ClearDepthStencil](ClearDepthStencil.md) | 清空内部数据。 |
-| [GetFramebuffer](GetFramebuffer.md) | 获取相关状态或对象。 |
-| [BindFramebuffer](BindFramebuffer.md) | 公开方法，详见头文件声明。 |
-| [UnbindFramebuffer](UnbindFramebuffer.md) | 公开方法，详见头文件声明。 |
+### 两种初始化路径
+
+- [`Initialize(const FramebufferDesc&)`](Initialize.md) 直接按 `FramebufferDesc` 组装附件。
+- [`Initialize(RHIRenderPass*, ...)`](Initialize.md) 从 `RHIResourceView` 数组提取附件信息。
+
+### 附件绑定策略
+
+- 最多处理 `16` 个颜色附件。
+- 根据 attachment 的 target / layer / mip，选择 `glFramebufferTexture1D`、`glFramebufferTexture2D`、`glFramebufferTextureLayer` 或 `glFramebufferTexture`。
+- 深度附件如果标记为 `DepthStencil`，会绑定到 `GL_DEPTH_STENCIL_ATTACHMENT`。
+
+### render pass 参数
+
+- `Initialize(RHIRenderPass*, ...)` 当前会忽略 `renderPass` 本身。
+- 也就是说，这个类在 OpenGL 后端更接近“附件集合对象”，而不是对 Vulkan / D3D12 render pass 语义的完全镜像。
+
+## 当前限制
+
+- `Clear*()` 系列函数会直接修改当前 FBO 绑定状态，不会恢复之前的 framebuffer。
+- `IsValid()` 只检查 FBO id 是否非零，不会再次验证完整性。
+- 创建失败时返回 `false`，但由调用方或析构来最终清理对象。
+
+## 重点方法
+
+- [Initialize](Initialize.md)
+- [Bind](Bind.md)
+- [ClearColor](ClearColor.md)
+- [ClearDepthStencil](ClearDepthStencil.md)
+- [GetFramebuffer](GetFramebuffer.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.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 5f763362..50e1c442 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Shutdown.md
@@ -1,30 +1,18 @@
 # OpenGLFramebuffer::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+删除内部 framebuffer object 并重置尺寸状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::Shutdown(...)。
-    (void)object;
-}
-```
+- 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers()`。
+- 把宽高重置为 `0`，sample 数重置为 `1`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md
index 857a0c53..df7e5862 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md
@@ -1,30 +1,17 @@
 # OpenGLFramebuffer::Unbind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Unbind();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+解绑当前 framebuffer，把 `GL_FRAMEBUFFER` 绑定回默认 framebuffer `0`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::Unbind(...)。
-    (void)object;
-}
-```
+- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md
index 7a7b8f17..309e2fb1 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md
@@ -1,30 +1,17 @@
 # OpenGLFramebuffer::UnbindFramebuffer
 
-公开方法，详见头文件声明。
-
 ```cpp
 static void UnbindFramebuffer();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+静态辅助函数，把 `GL_FRAMEBUFFER` 解绑回默认 framebuffer。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLFramebuffer object;
-    // 根据上下文补齐参数后调用 OpenGLFramebuffer::UnbindFramebuffer(...)。
-    (void)object;
-}
-```
+- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLFramebuffer.md)
-- [返回模块目录](../OpenGL.md)
+- [BindFramebuffer](BindFramebuffer.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index 94d49d65..44151df6 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-27 22:39:17`
+**生成时间**: `2026-03-27 22:48:36`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`