docs(api): deepen OpenGL swap chain shader and framebuffer docs

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)