docs(api): expand fence and framebuffer docs

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)