From c01944871da259c2443cec3cb787a7caa164ef92 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Sat, 28 Mar 2026 00:50:49 +0800
Subject: [PATCH] docs(api): deepen OpenGL screenshot pool and queue docs

---
 .../OpenGL/OpenGLCommandQueue/Constructor.md  |  25 ++---
 .../OpenGL/OpenGLCommandQueue/Destructor.md   |  26 ++---
 .../OpenGLCommandQueue/ExecuteCommandLists.md |  15 ++-
 .../OpenGLCommandQueue/GetCompletedValue.md   |  24 ++--
 .../OpenGLCommandQueue/GetCurrentFrame.md     |  24 ++--
 .../OpenGLCommandQueue/GetNativeHandle.md     |  24 ++--
 .../GetTimestampFrequency.md                  |  26 ++---
 .../RHI/OpenGL/OpenGLCommandQueue/GetType.md  |  24 ++--
 .../OpenGLCommandQueue/OpenGLCommandQueue.md  |  64 ++++++++---
 .../RHI/OpenGL/OpenGLCommandQueue/Shutdown.md |  24 ++--
 .../RHI/OpenGL/OpenGLCommandQueue/Signal.md   |  13 ++-
 .../RHI/OpenGL/OpenGLCommandQueue/Wait.md     |  28 ++---
 .../OpenGL/OpenGLCommandQueue/WaitForIdle.md  |   8 +-
 .../WaitForPreviousFrame.md                   |  26 ++---
 .../OpenGLDescriptorPool/AllocateSet.md       |  35 +++---
 .../OpenGLDescriptorPool/Constructor.md       |  26 ++---
 .../OpenGL/OpenGLDescriptorPool/Destructor.md |  26 ++---
 .../OpenGL/OpenGLDescriptorPool/FreeSet.md    |  28 ++---
 .../GetDescriptorCount.md                     |  24 ++--
 .../OpenGLDescriptorPool/GetNativeHandle.md   |  24 ++--
 .../OpenGL/OpenGLDescriptorPool/GetType.md    |  24 ++--
 .../OpenGL/OpenGLDescriptorPool/Initialize.md |  33 +++---
 .../OpenGLDescriptorPool.md                   |  85 +++++++++++----
 .../SetTextureUnitAllocator.md                |  27 ++---
 .../OpenGL/OpenGLDescriptorPool/Shutdown.md   |  31 +++---
 .../RHI/OpenGL/OpenGLScreenshot/Capture.md    | 103 ++++++++++++------
 .../OpenGLScreenshot/OpenGLScreenshot.md      |  77 ++++++++++---
 .../RHI/OpenGL/OpenGLScreenshot/Shutdown.md   |  27 ++---
 docs/api/_meta/rebuild-status.md              |   2 +-
 29 files changed, 469 insertions(+), 454 deletions(-)

diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Constructor.md
index 3272f6f2..a4dd695f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Constructor.md
@@ -1,28 +1,19 @@
-# OpenGLCommandQueue::OpenGLCommandQueue()
-
-构造对象。
+# OpenGLCommandQueue::OpenGLCommandQueue
 
 ```cpp
 OpenGLCommandQueue();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 OpenGL 命令队列门面对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-}
-```
+- 构造函数体为空
+- 不创建任何 OpenGL 原生对象
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Destructor.md
index c2857550..c35bfe5a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Destructor.md
@@ -1,29 +1,19 @@
-# OpenGLCommandQueue::~OpenGLCommandQueue()
-
-销毁对象并释放相关资源。
+# OpenGLCommandQueue::~OpenGLCommandQueue
 
 ```cpp
 ~OpenGLCommandQueue() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁命令队列对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)
+- 因为当前类没有持久资源，所以没有额外释放逻辑
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md
index a496b71e..34d05823 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md
@@ -6,17 +6,20 @@ void ExecuteCommandLists(uint32_t count, void** lists) override;
 
 ## 作用
 
-抽象层保留的“提交命令列表”入口。
+保留统一 RHI 接口中的“提交命令列表”入口。
 
 ## 当前实现行为
 
-当前实现为空。
+- 空实现
+- 不读取 `count`
+- 不读取 `lists`
+- 不触发任何 OpenGL 提交动作
 
-## 正确理解
+## 正确认识
 
-这并不是疏漏，而是当前 OpenGL 后端架构决定的结果：`OpenGLCommandList` 上的大部分操作会立刻作用到当前上下文，因此这里不存在 D3D12/Vulkan 意义上的“统一提交时刻”。
+OpenGL 当前后端的命令大多在调用命令列表接口时就直接落到 GL 上下文中，因此这里并没有 D3D12/Vulkan 那种集中提交点。
 
 ## 相关文档
 
-- [OpenGLCommandQueue](OpenGLCommandQueue.md)
-- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
+- [Signal](Signal.md)
+- [WaitForIdle](WaitForIdle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCompletedValue.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCompletedValue.md
index 4a066ea3..0269bc72 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCompletedValue.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCompletedValue.md
@@ -1,30 +1,22 @@
 # OpenGLCommandQueue::GetCompletedValue
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetCompletedValue() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前队列的完成值。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 固定返回 `0`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 正确认识
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::GetCompletedValue(...)。
-    (void)object;
-}
-```
+这个值在当前 OpenGL 后端里不具备真实的 GPU 时间线意义，更适合作为接口占位返回值。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [GetCurrentFrame](GetCurrentFrame.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCurrentFrame.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCurrentFrame.md
index 0577ba71..dd309650 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCurrentFrame.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetCurrentFrame.md
@@ -1,30 +1,22 @@
 # OpenGLCommandQueue::GetCurrentFrame
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetCurrentFrame() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前帧序号。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 固定返回 `0`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 正确认识
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::GetCurrentFrame(...)。
-    (void)object;
-}
-```
+这说明当前类没有内部帧编号系统。它只是为了满足统一接口而提供的占位返回值。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [WaitForPreviousFrame](WaitForPreviousFrame.md)
+- [GetCompletedValue](GetCompletedValue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetNativeHandle.md
index 2ff82244..8b834bef 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetNativeHandle.md
@@ -1,30 +1,22 @@
 # OpenGLCommandQueue::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回命令队列的原生句柄表示。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 返回 `this`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::GetNativeHandle(...)。
-    (void)object;
-}
-```
+这再次说明当前类没有对应的 OpenGL 原生命令队列对象，它只是引擎接口适配层。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [GetType](GetType.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetTimestampFrequency.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetTimestampFrequency.md
index 613427b8..0ac056ee 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetTimestampFrequency.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetTimestampFrequency.md
@@ -1,30 +1,24 @@
 # OpenGLCommandQueue::GetTimestampFrequency
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetTimestampFrequency() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回时间戳频率。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 调用 `glGetInteger64v(GL_TIMESTAMP, &frequency)`
+- 如果读取结果大于 `0`，直接返回该值
+- 否则返回 `1000000000`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 需要特别注意
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::GetTimestampFrequency(...)。
-    (void)object;
-}
-```
+`GL_TIMESTAMP` 更像当前 GPU 时间戳值，而不是硬件频率寄存器。因此当前实现只是给统一接口提供一个“可用的正数返回值”，语义上并不严格等价于 D3D12 的 `GetTimestampFrequency()`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
+- [GetCompletedValue](GetCompletedValue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetType.md
index 16429b9a..63c12f90 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/GetType.md
@@ -1,30 +1,22 @@
 # OpenGLCommandQueue::GetType
 
-获取相关状态或对象。
-
 ```cpp
 CommandQueueType GetType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回命令队列类型。
 
-**返回：** `CommandQueueType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 始终返回 `CommandQueueType::Direct`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::GetType(...)。
-    (void)object;
-}
-```
+这是为了和其他后端保持统一接口，而不是在 OpenGL 底层真的存在多种原生命令队列。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md
index 6e3f2acb..8e97535a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md
@@ -6,42 +6,72 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`
 
-**描述**: 为统一 RHI 抽象保留的 OpenGL 队列门面；它不是一条真实的 GPU 提交队列。
+**描述**: 为统一 RHI 抽象保留的 OpenGL 命令队列门面；它不是一条真实的 GPU 提交队列，而是一个接口适配层。
 
 ## 概览
 
-OpenGL 没有 D3D12/Vulkan 那种显式命令队列模型，所以 `OpenGLCommandQueue` 的主要价值是：
+OpenGL 没有 D3D12/Vulkan 那种显式 command queue 模型，因此 `OpenGLCommandQueue` 的存在主要是为了：
 
-- 让统一抽象层还能继续通过 `RHICommandQueue` 组织代码
-- 提供少量和 flush / finish / fence 相关的后端适配
+- 保持跨后端接口一致
+- 给测试和上层 RHI 代码一个统一的 `RHICommandQueue` 入口
+- 封装少量 `glFlush()` / `glFinish()` / fence 相关行为
+
+## 设计定位
+
+这个类应被理解为 shim，而不是调度核心。
+
+它能做的事情很有限：
+
+- 把信号语义桥接到 [OpenGLFence](../OpenGLFence/OpenGLFence.md)
+- 提供“等待 GPU 空闲”的同步入口
+- 给测试返回一个统一的 queue 类型和 native handle
+
+它当前做不了这些事：
+
+- 真正的命令列表提交
+- 真正的跨线程 GPU timeline 管理
+- 帧序号推进
 
 ## 当前实现的真实行为
 
-- `GetType()` 永远返回 `CommandQueueType::Direct`
-- `ExecuteCommandLists()` 当前为空实现
-- `Signal()` 会先调用抽象 fence 的 `Signal(value)`，再 `glFlush()`
-- `Wait()` 当前为空实现
-- `GetCompletedValue()` 当前固定返回 `0`
-- `WaitForIdle()` 调用 `glFinish()`
-- `GetTimestampFrequency()` 读取 `GL_TIMESTAMP`；这更像“当前时间戳查询”，不是严格意义上的硬件频率接口
+- [GetType](GetType.md) 永远返回 `CommandQueueType::Direct`
+- [GetNativeHandle](GetNativeHandle.md) 返回 `this`
+- [ExecuteCommandLists](ExecuteCommandLists.md) 是空实现
+- [Signal](Signal.md) 先调用 fence 的 `Signal(value)`，再执行 `glFlush()`
+- [Wait](Wait.md) 是空实现
+- [GetCompletedValue](GetCompletedValue.md) 固定返回 `0`
+- [WaitForIdle](WaitForIdle.md) 调用 `glFinish()`
+- [WaitForPreviousFrame](WaitForPreviousFrame.md) 是空实现
+- [GetCurrentFrame](GetCurrentFrame.md) 固定返回 `0`
+- [GetTimestampFrequency](GetTimestampFrequency.md) 读取 `GL_TIMESTAMP`，更像当前时间戳快照，而不是严格意义上的频率
 
-## 正确理解
+## 为什么这样设计
 
-如果从商业引擎角度看，它更像“为了保持跨后端接口整齐而保留的一层 shim”，而不是调度核心。
+这是一种很典型的“为了统一抽象而保留的后端占位层”。
+
+在商业级引擎里，只要继续支持 OpenGL，类似的 shim 往往也不可避免，因为：
+
+- 上层代码想按队列模型组织逻辑
+- 但 OpenGL 底层并没有对应对象
+
+当前实现选择了最保守的一条路：保留接口，让测试和基础流程先跑通，再逐步补更多语义。
 
 ## 当前限制
 
-- 不支持真正的命令列表提交
-- 不提供成熟的 GPU timeline 语义
-- `Wait()` / `ExecuteCommandLists()` 仍是占位实现
+- `ExecuteCommandLists()`、`Wait()`、`WaitForPreviousFrame()` 都还是占位实现
+- `GetCompletedValue()` 没有真实 GPU 进度含义
+- `GetTimestampFrequency()` 的语义并不精确
+- 没有自己的资源或生命周期状态
 
-## 重点公共方法
+## 关键方法
 
 - [ExecuteCommandLists](ExecuteCommandLists.md)
 - [Signal](Signal.md)
 - [WaitForIdle](WaitForIdle.md)
+- [GetTimestampFrequency](GetTimestampFrequency.md)
 
 ## 相关文档
 
 - [OpenGL](../OpenGL.md)
+- [OpenGLFence](../OpenGLFence/OpenGLFence.md)
 - [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Shutdown.md
index 630865f4..f20a9d4a 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Shutdown.md
@@ -1,30 +1,22 @@
 # OpenGLCommandQueue::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清理命令队列对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 空实现
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::Shutdown(...)。
-    (void)object;
-}
-```
+当前类没有自己的 OpenGL 队列对象、同步对象或帧跟踪状态，因此对象级清理为空是符合当前实现定位的。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md
index 32e14331..231afb8b 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md
@@ -6,14 +6,19 @@ void Signal(RHIFence* fence, uint64_t value) override;
 
 ## 作用
 
-给抽象 fence 写入一个值，并通过 `glFlush()` 触发驱动尽快开始处理已发出的 OpenGL 命令。
+把“队列信号”语义桥接到 fence，并刷新当前 GL 命令流。
 
 ## 当前实现行为
 
-- 若 `fence` 非空，则调用 `fence->Signal(value)`
-- 随后调用 `glFlush()`
+- 如果 `fence` 非空，调用 `fence->Signal(value)`
+- 随后执行 `glFlush()`
+
+## 设计说明
+
+真正的同步语义主要由 [OpenGLFence](../OpenGLFence/OpenGLFence.md) 实现。这里更像一个薄包装，负责保持 `RHICommandQueue` 侧的调用风格一致。
 
 ## 相关文档
 
+- [Wait](Wait.md)
 - [WaitForIdle](WaitForIdle.md)
-- [OpenGLCommandQueue](OpenGLCommandQueue.md)
+- [OpenGLFence](../OpenGLFence/OpenGLFence.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Wait.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Wait.md
index b0e31f7e..cc7dd7ef 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Wait.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Wait.md
@@ -1,32 +1,24 @@
 # OpenGLCommandQueue::Wait
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Wait(RHIFence* fence, uint64_t value) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `fence` - 参数语义详见头文件声明。
-- `value` - 参数语义详见头文件声明。
+保留统一接口中的“队列等待 fence”入口。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 空实现
+- 不读取 `fence`
+- 不读取 `value`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 当前限制
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::Wait(...)。
-    (void)object;
-}
-```
+这意味着调用它不会真正让 OpenGL 队列语义上等待某个 fence 值。若需要等待，当前更可靠的路径仍然是直接操作 fence 或调用 [WaitForIdle](WaitForIdle.md)。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [Signal](Signal.md)
+- [WaitForIdle](WaitForIdle.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md
index 5c0364e6..871bd4fb 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md
@@ -6,17 +6,17 @@ void WaitForIdle() override;
 
 ## 作用
 
-阻塞 CPU，直到当前上下文之前发出的 OpenGL 命令全部完成。
+等待当前 OpenGL 命令流执行完成。
 
 ## 当前实现行为
 
-直接调用 `glFinish()`。
+- 直接调用 `glFinish()`
 
 ## 设计说明
 
-这是一条非常强的同步原语，适合初始化、截图、调试和测试，不适合高频帧循环。
+这是一条非常强的同步边界，适合测试、资源销毁前同步和调试验证，不适合高频运行路径。
 
 ## 相关文档
 
 - [Signal](Signal.md)
-- [OpenGLCommandQueue](OpenGLCommandQueue.md)
+- [Wait](Wait.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForPreviousFrame.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForPreviousFrame.md
index f9b4eb31..15f554a0 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForPreviousFrame.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForPreviousFrame.md
@@ -1,30 +1,22 @@
 # OpenGLCommandQueue::WaitForPreviousFrame
 
-公开方法，详见头文件声明。
-
 ```cpp
-void WaitForPreviousFrame() override;
+void WaitForPreviousFrame() override {}
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+保留统一接口中的“等待上一帧”入口。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 空实现
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLCommandQueue object;
-    // 根据上下文补齐参数后调用 OpenGLCommandQueue::WaitForPreviousFrame(...)。
-    (void)object;
-}
-```
+当前 OpenGL 后端没有自己的帧序列推进逻辑，因此这里没有和 D3D12 `frame fence` 对应的行为。
 
 ## 相关文档
 
-- [返回类总览](OpenGLCommandQueue.md)
-- [返回模块目录](../OpenGL.md)
+- [GetCurrentFrame](GetCurrentFrame.md)
+- [OpenGLCommandQueue](OpenGLCommandQueue.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/AllocateSet.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/AllocateSet.md
index 5332081a..485795a4 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/AllocateSet.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/AllocateSet.md
@@ -1,31 +1,32 @@
 # OpenGLDescriptorPool::AllocateSet
 
-公开方法，详见头文件声明。
-
 ```cpp
 RHIDescriptorSet* AllocateSet(const DescriptorSetLayoutDesc& layout) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `layout` - 参数语义详见头文件声明。
+创建一个新的 [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md)。
 
-**返回：** `RHIDescriptorSet*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_allocatedSets.size() >= m_maxSets`，返回 `nullptr`
+- 创建新的 `OpenGLDescriptorSet`
+- 调用 `newSet->Initialize(m_textureUnitAllocator, layout.bindingCount, layout)`
+- 失败时删除新对象并返回 `nullptr`
+- 成功时把它加入 `m_allocatedSets`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 与 allocator 的关系
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::AllocateSet(...)。
-    (void)object;
-}
-```
+如果 layout 中包含 `SRV`、`Sampler` 或 `UAV`，`OpenGLDescriptorSet::Initialize(...)` 会尝试从 `OpenGLTextureUnitAllocator` 申请 texture unit。也就是说，pool 只是创建入口，真正的 unit 分配发生在 set 初始化内部。
+
+## 当前限制
+
+- 没有更细粒度容量控制
+- layout 合法性基本依赖 `OpenGLDescriptorSet`
+- 如果外部绕过 [FreeSet](FreeSet.md) 直接 delete set，pool 内部跟踪会失真
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [FreeSet](FreeSet.md)
+- [SetTextureUnitAllocator](SetTextureUnitAllocator.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Constructor.md
index c48f8f2f..a27521ef 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Constructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Constructor.md
@@ -1,28 +1,20 @@
-# OpenGLDescriptorPool::OpenGLDescriptorPool()
-
-构造对象。
+# OpenGLDescriptorPool::OpenGLDescriptorPool
 
 ```cpp
 OpenGLDescriptorPool();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 OpenGL descriptor pool 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-}
-```
+- `m_type` 初始化为 `DescriptorHeapType::CBV_SRV_UAV`
+- `m_maxSets` 初始化为 `0`
+- `m_textureUnitAllocator` 初始化为 `nullptr`
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [OpenGLDescriptorPool](OpenGLDescriptorPool.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Destructor.md
index 6de6da59..b8465df7 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Destructor.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Destructor.md
@@ -1,29 +1,19 @@
-# OpenGLDescriptorPool::~OpenGLDescriptorPool()
-
-销毁对象并释放相关资源。
+# OpenGLDescriptorPool::~OpenGLDescriptorPool
 
 ```cpp
 ~OpenGLDescriptorPool() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 descriptor pool 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)
+- 不会自动 delete `m_allocatedSets` 里仍然存在的 set 对象
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [FreeSet](FreeSet.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/FreeSet.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/FreeSet.md
index 26db6767..a2d6ae84 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/FreeSet.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/FreeSet.md
@@ -1,31 +1,25 @@
 # OpenGLDescriptorPool::FreeSet
 
-公开方法，详见头文件声明。
-
 ```cpp
 void FreeSet(RHIDescriptorSet* set) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `set` - 参数语义详见头文件声明。
+释放由当前 pool 跟踪的 descriptor set。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果 `set == nullptr`，直接返回
+- 在线性遍历 `m_allocatedSets` 中查找匹配指针
+- 找到后从数组移除，并执行 `delete set`
+- 如果没找到，则不做任何事
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::FreeSet(...)。
-    (void)object;
-}
-```
+这里不会先调用 `set->Shutdown()`；它依赖 set 自己的析构逻辑完成清理。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [AllocateSet](AllocateSet.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetDescriptorCount.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetDescriptorCount.md
index 3be57f3f..076597a6 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetDescriptorCount.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetDescriptorCount.md
@@ -1,30 +1,22 @@
 # OpenGLDescriptorPool::GetDescriptorCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetDescriptorCount() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 pool 记录的容量值。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 返回 `m_maxSets`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::GetDescriptorCount(...)。
-    (void)object;
-}
-```
+在当前 OpenGL 实现里，这个值应理解为“最多能分配多少个 set”，不是“总 descriptor 数”。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [AllocateSet](AllocateSet.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetNativeHandle.md
index 47fdb53c..34898ad0 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetNativeHandle.md
@@ -1,30 +1,22 @@
 # OpenGLDescriptorPool::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 pool 的原生句柄表示。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 返回 `this`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::GetNativeHandle(...)。
-    (void)object;
-}
-```
+这再次说明当前类没有与之对应的 OpenGL 原生对象，它只是引擎侧抽象。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLDescriptorPool](OpenGLDescriptorPool.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetType.md
index 3ec4e237..6d1c25e7 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetType.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/GetType.md
@@ -1,30 +1,22 @@
 # OpenGLDescriptorPool::GetType
 
-获取相关状态或对象。
-
 ```cpp
 DescriptorHeapType GetType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 pool 记录的 descriptor heap 类型。
 
-**返回：** `DescriptorHeapType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_type`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::GetType(...)。
-    (void)object;
-}
-```
+即使 OpenGL 没有原生 descriptor heap 分类，这个字段仍然有价值，因为它帮助 RHI 上层保留统一心智模型，也影响 descriptor set 的使用约定。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [OpenGLDescriptorPool](OpenGLDescriptorPool.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Initialize.md
index 2afc7ebd..c3604683 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Initialize.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Initialize.md
@@ -1,31 +1,30 @@
 # OpenGLDescriptorPool::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize(const DescriptorPoolDesc& desc) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `desc` - 参数语义详见头文件声明。
+初始化 pool 的基础配置。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- `m_type = desc.type`
+- `m_maxSets = desc.descriptorCount`
+- 始终返回 `true`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 重要说明
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::Initialize(...)。
-    (void)object;
-}
-```
+当前 `desc.descriptorCount` 并不是“总 descriptor 数量”，而是“允许分配的 set 上限”。
+
+## 当前限制
+
+- 不校验 `desc.descriptorCount`
+- 忽略 `desc.shaderVisible`
+- 不涉及任何 OpenGL 原生对象创建
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [GetDescriptorCount](GetDescriptorCount.md)
+- [AllocateSet](AllocateSet.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/OpenGLDescriptorPool.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/OpenGLDescriptorPool.md
index 08875391..ffa971c5 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/OpenGLDescriptorPool.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/OpenGLDescriptorPool.md
@@ -6,34 +6,75 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLDescriptorPool` public API。
+**描述**: OpenGL 后端的 descriptor pool 抽象，但当前实现本质上是 `OpenGLDescriptorSet` 的拥有容器和 texture unit 分配入口。
 
-## 概述
+## 概览
 
-`OpenGLDescriptorPool.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+OpenGL 没有 D3D12/Vulkan 那种原生 descriptor pool / descriptor set 体系，所以 `OpenGLDescriptorPool` 是一个纯引擎侧抽象。
 
-## 声明概览
+它当前主要承担这些职责：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLDescriptorPool` | `class` | 继承自 `RHIDescriptorPool` 的公开声明。 |
+- 记录 pool 类型
+- 限制最多可分配多少个 descriptor set
+- 为新建的 [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md) 注入 `OpenGLTextureUnitAllocator`
+- 跟踪当前由自己分配出去的 set 指针
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLDescriptorPool()](Constructor.md) | 构造对象。 |
-| [~OpenGLDescriptorPool()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetDescriptorCount](GetDescriptorCount.md) | 获取相关状态或对象。 |
-| [GetType](GetType.md) | 获取相关状态或对象。 |
-| [AllocateSet](AllocateSet.md) | 公开方法，详见头文件声明。 |
-| [FreeSet](FreeSet.md) | 公开方法，详见头文件声明。 |
-| [SetTextureUnitAllocator](SetTextureUnitAllocator.md) | 设置相关状态或配置。 |
+这里最容易误解的一点是 `DescriptorPoolDesc.descriptorCount`。
+
+在 D3D12 里，它更像 heap 容量；在当前 OpenGL 实现里，它被当成：
+
+- `m_maxSets`
+- 也就是“最多允许创建多少个 set”
+
+而不是“总 descriptor 数量”。
+
+## 生命周期
+
+- 构造后默认类型为 `CBV_SRV_UAV`，`m_maxSets = 0`
+- [Initialize](Initialize.md) 记录类型和 set 上限
+- [AllocateSet](AllocateSet.md) 创建并跟踪新的 `OpenGLDescriptorSet`
+- [FreeSet](FreeSet.md) 删除被跟踪的 set
+- [Shutdown](Shutdown.md) 只清空跟踪信息，不负责 delete 仍在表中的 set
+
+## 当前实现的真实行为
+
+- [GetNativeHandle](GetNativeHandle.md) 返回 `this`
+- [GetDescriptorCount](GetDescriptorCount.md) 返回 `m_maxSets`
+- [Initialize](Initialize.md) 忽略 `shaderVisible`
+- [AllocateSet](AllocateSet.md) 只有在 `m_allocatedSets.size() < m_maxSets` 时才允许分配
+- 如果 layout 包含 `SRV` / `Sampler` / `UAV`，创建 set 时依赖 `OpenGLTextureUnitAllocator`
+- [Shutdown](Shutdown.md) 不 delete 仍然存活的 set，只是 `clear()` 指针列表并置空 allocator
+
+## 为什么这样设计
+
+OpenGL 后端没有必要模拟一份沉重的 descriptor heap 系统。当前实现选的是更实用的一条路线：
+
+- 把 descriptor set 继续保留为跨后端统一抽象
+- 用 pool 负责 set 的创建和数量管理
+- 用 texture unit allocator 负责真正的纹理单元资源
+
+这种设计简单、够用，而且和当前 `OpenGLDescriptorSet` 的绑定实现配合自然。
+
+## 当前限制
+
+- `descriptorCount` 语义和其他后端不同
+- 不是 descriptor 级资源池，而是 set 数量上限
+- `Shutdown()` 不会 delete 已分配 set
+- 没有线程安全
+- 没有碎片、复用策略或更细粒度配额
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [AllocateSet](AllocateSet.md)
+- [FreeSet](FreeSet.md)
+- [SetTextureUnitAllocator](SetTextureUnitAllocator.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md)
+- [OpenGLTextureUnitAllocator](../OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/SetTextureUnitAllocator.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/SetTextureUnitAllocator.md
index f3d17353..7fa3e13e 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/SetTextureUnitAllocator.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/SetTextureUnitAllocator.md
@@ -1,31 +1,24 @@
 # OpenGLDescriptorPool::SetTextureUnitAllocator
 
-设置相关状态或配置。
-
 ```cpp
 void SetTextureUnitAllocator(OpenGLTextureUnitAllocator* allocator);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `allocator` - 参数语义详见头文件声明。
+为后续创建的 descriptor set 指定 texture unit allocator。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 直接保存 `allocator` 指针
+- 不做所有权接管
+- 不会反向更新已创建的 set
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 使用场景
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::SetTextureUnitAllocator(...)。
-    (void)object;
-}
-```
+通常由 [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md) 在创建 pool 后立即调用，用来把设备级的 texture unit allocator 注入到 pool。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [AllocateSet](AllocateSet.md)
+- [OpenGLTextureUnitAllocator](../OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Shutdown.md
index 2956ffbd..d235c51f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorPool/Shutdown.md
@@ -1,30 +1,29 @@
 # OpenGLDescriptorPool::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h`，当前页面用于固定 `OpenGLDescriptorPool` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清空 pool 的内部跟踪状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- `m_allocatedSets.clear()`
+- `m_textureUnitAllocator = nullptr`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorPool.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorPool object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorPool::Shutdown(...)。
-    (void)object;
-}
-```
+当前实现不会：
+
+- delete `m_allocatedSets` 中仍然存在的 set
+- 重置 `m_type`
+- 重置 `m_maxSets`
+
+因此正确的使用方式仍然是先显式释放各个 set，再销毁 pool。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorPool.md)
-- [返回模块目录](../OpenGL.md)
+- [FreeSet](FreeSet.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Capture.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Capture.md
index c22b8fba..ff7cba5c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Capture.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Capture.md
@@ -1,63 +1,94 @@
 # OpenGLScreenshot::Capture
 
-公开方法，详见头文件声明。
+```cpp
+bool Capture(RHIDevice* device, RHISwapChain* swapChain, const char* filename) override;
+static bool Capture(OpenGLDevice& device,
+                    OpenGLSwapChain& swapChain,
+                    const char* filename);
+static bool Capture(OpenGLDevice& device,
+                    OpenGLSwapChain& swapChain,
+                    const char* filename,
+                    int width,
+                    int height);
+```
 
-该方法在 `XCEngine/RHI/OpenGL/OpenGLScreenshot.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。
+## 作用
 
-## 重载 1: 声明
+从 OpenGL 当前呈现目标读取像素并写成 PPM 文件。
+
+## 核心流程
+
+三个公开重载最终都汇合到同一套同步读回流程：
+
+1. 切换当前上下文 `device.MakeContextCurrent()`
+2. 分配 RGB 像素缓冲
+3. 调用 `glFinish()`
+4. 配置 `GL_PACK_*` 像素打包状态
+5. 根据当前 back buffer 情况选择读取路径
+6. 调用 `glReadPixels(...)`
+7. 以 `P6` PPM 格式写盘，并在写盘时做上下翻转
+
+## 重载 1: RHI 入口
 
 ```cpp
 bool Capture(RHIDevice* device, RHISwapChain* swapChain, const char* filename) override;
 ```
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `swapChain` - 参数语义详见头文件声明。
-- `filename` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+- 直接把 `device` 转成 `OpenGLDevice*`
+- 直接把 `swapChain` 转成 `OpenGLSwapChain*`
+- 然后转发到 OpenGL 包装对象重载
 
-## 重载 2: 声明
+### 注意事项
+
+- 没有运行时类型检查
+- 没有空指针保护
+
+## 重载 2: 使用 swap chain 尺寸
 
 ```cpp
-static bool Capture(OpenGLDevice& device, OpenGLSwapChain& swapChain, const char* filename);
+static bool Capture(OpenGLDevice& device,
+                    OpenGLSwapChain& swapChain,
+                    const char* filename);
 ```
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `swapChain` - 参数语义详见头文件声明。
-- `filename` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+- 直接使用 `swapChain.GetWidth()` 和 `swapChain.GetHeight()`
+- 然后调用完整尺寸重载
 
-## 重载 3: 声明
+## 重载 3: 显式尺寸
 
 ```cpp
-static bool Capture(OpenGLDevice& device, OpenGLSwapChain& swapChain, const char* filename, int width, int height);
+static bool Capture(OpenGLDevice& device,
+                    OpenGLSwapChain& swapChain,
+                    const char* filename,
+                    int width,
+                    int height);
 ```
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `swapChain` - 参数语义详见头文件声明。
-- `filename` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+- 分配 `width * height * 3` 字节的 RGB 缓冲
+- 如果内存分配失败，记录错误日志并返回 `false`
+- 判断当前 back buffer 是否可以走纹理读取路径：
+  - `backBufferTexture != nullptr`
+  - `backBufferTexture->GetID() != 0`
+  - `backBufferTexture->GetState() != ResourceStates::Common`
+- 纹理路径下会创建临时 `GL_READ_FRAMEBUFFER`，把纹理挂到 `GL_COLOR_ATTACHMENT0` 后读取
+- 否则直接 `glReadBuffer(GL_BACK)` 读取默认后备缓冲
+- 打开输出文件失败时返回 `false`
+- 写文件时从最后一行开始写，实现图像垂直翻转
 
-**示例：**
+## 输出格式
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLScreenshot.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLScreenshot object;
-    // 根据上下文补齐参数后调用 OpenGLScreenshot::Capture(...)。
-    (void)object;
-}
-```
+- 固定输出 `P6` PPM
+- 只写 RGB
+- 不写 alpha
+- 不压缩
 
 ## 相关文档
 
-- [返回类总览](OpenGLScreenshot.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLScreenshot](OpenGLScreenshot.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/OpenGLScreenshot.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/OpenGLScreenshot.md
index 7af220eb..60de4933 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/OpenGLScreenshot.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/OpenGLScreenshot.md
@@ -6,26 +6,75 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLScreenshot.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLScreenshot` public API。
+**描述**: OpenGL 后端的截图工具类，负责从默认帧缓冲或当前 back buffer 纹理读取像素，并保存为 PPM 文件。
 
-## 概述
+## 概览
 
-`OpenGLScreenshot.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`OpenGLScreenshot` 和 [D3D12Screenshot](../../D3D12/D3D12Screenshot/D3D12Screenshot.md) 一样，属于“调试和测试优先”的同步截图工具，而不是完整的产品级截图系统。
 
-## 声明概览
+它当前支持两条读图路径：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLScreenshot` | `class` | 继承自 `RHIScreenshot` 的公开声明。 |
+- 如果 swap chain 当前 back buffer 能被当作纹理读取，就临时创建一个 `GL_READ_FRAMEBUFFER` 并从颜色附件读取
+- 否则直接从 `GL_BACK` 读默认后备缓冲
 
-## 公共方法
+随后它会把像素翻转后按 `P6` PPM 格式写到磁盘。
 
-| 方法 | 描述 |
-|------|------|
-| [Capture](Capture.md) | 公开方法，详见头文件声明。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
+## 设计定位
+
+这个类的目标非常明确：
+
+- 给 RHI 集成测试提供统一截图出口
+- 给 OpenGL 示例和调试流程提供最小依赖的抓图工具
+- 尽量不引入额外图像编码依赖
+
+因此它的实现风格也很直接：
+
+- 同步 `glFinish()`
+- 直接 `glReadPixels(...)`
+- 直接 `fopen` / `fwrite`
+
+## 当前实现的真实行为
+
+- [Capture](Capture.md) 会先 `device.MakeContextCurrent()`
+- 像素缓冲按 `width * height * 3` 分配，只读取 RGB
+- 截图前会调用 `glFinish()`
+- 如果 back buffer 纹理存在且 `GetState() != ResourceStates::Common`，会走临时 FBO 读取路径
+- 否则从 `GL_BACK` 读取
+- 写文件时会按 OpenGL 常见坐标系差异，把图像做上下翻转
+- [Shutdown](Shutdown.md) 是空实现，因为对象本身没有持久资源
+
+## 需要注意的实现细节
+
+- 头文件里声明了私有 `SavePPM(...)`，但当前源码没有实现也没有使用它
+- 截图逻辑假定输出是 8-bit RGB，不处理 HDR、浮点格式或压缩格式
+- RHI 接口重载内部直接 `static_cast` 到 `OpenGLDevice*` / `OpenGLSwapChain*`
+
+## 为什么这样设计
+
+在商业级引擎里，截图系统通常会进一步拆成：
+
+- 异步像素传输
+- 编码线程
+- PNG/JPG/EXR 等多格式输出
+- 调试工具链集成
+
+但在底层 RHI 验证阶段，先保证“结果可抓、问题可定位、依赖够少”更重要。`OpenGLScreenshot` 正是这类早期实现。
+
+## 当前限制
+
+- 全程同步，`glFinish()` 开销明显
+- 只输出 PPM
+- 没有颜色空间、HDR 或 alpha 处理
+- 类型转换依赖调用方保证处在 OpenGL 后端上下文
+
+## 关键方法
+
+- [Capture](Capture.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLSwapChain](../OpenGLSwapChain/OpenGLSwapChain.md)
+- [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)
+- [RHIScreenshot](../../RHIScreenshot/RHIScreenshot.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Shutdown.md
index c05ce2b4..9aeba20c 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Shutdown.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLScreenshot/Shutdown.md
@@ -1,30 +1,23 @@
 # OpenGLScreenshot::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
-void Shutdown() override;
+void Shutdown() override {}
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLScreenshot.h`，当前页面用于固定 `OpenGLScreenshot` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+满足 [RHIScreenshot](../../RHIScreenshot/RHIScreenshot.md) 接口要求的清理入口。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 空实现
+- 不释放任何资源
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLScreenshot.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLScreenshot object;
-    // 根据上下文补齐参数后调用 OpenGLScreenshot::Shutdown(...)。
-    (void)object;
-}
-```
+当前截图流程所需的内存、临时 FBO 和文件句柄都在 [Capture](Capture.md) 调用内部即时创建并释放，因此对象级别没有需要持久清理的状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLScreenshot.md)
-- [返回模块目录](../OpenGL.md)
+- [Capture](Capture.md)
+- [OpenGLScreenshot](OpenGLScreenshot.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index 5bf00993..e3092c39 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-28 00:40:20`
+**生成时间**: `2026-03-28 00:49:41`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`