docs(api): refactor OpenGL and D3D12 binding docs

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/Constructor.md

@@ -1,28 +1,19 @@
-# D3D12PipelineLayout::D3D12PipelineLayout()
-
-构造对象。
+# D3D12PipelineLayout::D3D12PipelineLayout
 
 ```cpp
 D3D12PipelineLayout();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 D3D12 pipeline layout 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-}
-```
+- 只把内部 `m_device` 初始化为 `nullptr`。
+- 不创建 root signature。
+- 真正的初始化必须走 [`InitializeWithDevice`](InitializeWithDevice.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeWithDevice](InitializeWithDevice.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/D3D12PipelineLayout.md

@@ -6,42 +6,69 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12PipelineLayout` public API。
+**描述**: D3D12 后端的 pipeline layout 适配对象，负责把通用 RHI 的资源布局翻译为 `ID3D12RootSignature`、root parameter 与 descriptor table。
 
 ## 概述
 
-`D3D12PipelineLayout.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+在 D3D12 里，真正控制资源绑定形状的是 root signature，而不是 Vulkan 风格的 `descriptor set layout`。`D3D12PipelineLayout` 的职责，就是把引擎上层的两种布局描述方式统一落成 D3D12 能消费的 root signature:
 
-## 声明概览
+- 简化的“按总数量描述”模式。
+- 更接近 Vulkan 的 `set layout` 模式。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12PipelineLayout` | `class` | 继承自 `RHIPipelineLayout` 的公开声明。 |
+这是一种典型的商业引擎后端策略: 上层继续谈“布局”，后端再决定 root CBV、descriptor table、range、register 该怎么排。
 
-## 公共方法
+## 生命周期
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12PipelineLayout()](Constructor.md) | 构造对象。 |
-| [~D3D12PipelineLayout()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [InitializeWithDevice](InitializeWithDevice.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetRootSignature](GetRootSignature.md) | 获取相关状态或对象。 |
-| [UsesSetLayouts](UsesSetLayouts.md) | 公开方法，详见头文件声明。 |
-| [GetSetLayoutCount](GetSetLayoutCount.md) | 获取相关状态或对象。 |
-| [HasConstantBufferBinding](HasConstantBufferBinding.md) | 判断是否具备指定状态或能力。 |
-| [GetConstantBufferRootParameterIndex](GetConstantBufferRootParameterIndex.md) | 获取相关状态或对象。 |
-| [HasShaderResourceTable](HasShaderResourceTable.md) | 判断是否具备指定状态或能力。 |
-| [GetShaderResourceTableRootParameterIndex](GetShaderResourceTableRootParameterIndex.md) | 获取相关状态或对象。 |
-| [HasUnorderedAccessTable](HasUnorderedAccessTable.md) | 判断是否具备指定状态或能力。 |
-| [GetUnorderedAccessTableRootParameterIndex](GetUnorderedAccessTableRootParameterIndex.md) | 获取相关状态或对象。 |
-| [HasSamplerTable](HasSamplerTable.md) | 判断是否具备指定状态或能力。 |
-| [GetSamplerTableRootParameterIndex](GetSamplerTableRootParameterIndex.md) | 获取相关状态或对象。 |
-| [GetDesc](GetDesc.md) | 获取相关状态或对象。 |
+1. 通常由 [`D3D12Device::CreatePipelineLayout`](../D3D12Device/CreatePipelineLayout.md) 创建。
+2. 内部调用 [`InitializeWithDevice`](InitializeWithDevice.md) 构建 root parameter、descriptor range 并序列化 root signature。
+3. [`D3D12PipelineState`](../D3D12PipelineState/D3D12PipelineState.md) 和 [`D3D12CommandList`](../D3D12CommandList/D3D12CommandList.md) 在运行时查询 root parameter 索引。
+4. 销毁前调用 [`Shutdown`](Shutdown.md) 释放 `ID3D12RootSignature`。
+
+## 当前实现的真实行为
+
+### flat 模式
+
+当 `RHIPipelineLayoutDesc` 没有提供 `setLayouts` 时:
+
+- 每个常量缓冲计数都会生成一个独立的 root CBV parameter。
+- `SRV`、`UAV`、`Sampler` 各自最多生成一个 descriptor table。
+- 这些 descriptor table 各自只含一个 range，范围大小等于对应总 count。
+
+### set-aware 模式
+
+当提供 `setLayouts` 时:
+
+- 会深拷贝所有 set layout 和 binding 数组。
+- 会重新累计四类 descriptor 的总数。
+- `CBV` 按 binding 升序为每个 binding 生成一个 root CBV parameter。
+- `SRV`、`UAV`、`Sampler` 各自按 set 生成“至多一个 descriptor table”。
+- 一个 table 内可能包含多个 range，range 同样按 binding 升序组织。
+- 所有 range 当前都使用 register space `0`，不同 set 的分离依靠“连续递增的 register 编号 + 不同 root parameter 索引”完成。
+
+## 设计含义
+
+- 这让上层继续以 set / binding 思维组织资源，但实际提交给 D3D12 的是更贴近硬件模型的 root signature。
+- 对常量缓冲使用 root CBV，而不是 descriptor heap 中的 CBV table，是当前实现的一项明确取舍。
+- 这种设计减少了 CBV descriptor heap 压力，但也让 CBV 数组的表达能力更弱。
+
+## 当前限制
+
+- [`Initialize`](Initialize.md) 这个通用接口在当前类中固定返回 `false`，因为构建 root signature 必须拿到 `ID3D12Device`。
+- set-aware 模式下，`CBV` 的 `count > 1` 只会推进 register 编号，但仍只生成一个 root parameter。
+- 当前 root signature 没有使用 static sampler。
+
+## 重点方法
+
+- [InitializeWithDevice](InitializeWithDevice.md)
+- [UsesSetLayouts](UsesSetLayouts.md)
+- [HasConstantBufferBinding](HasConstantBufferBinding.md)
+- [GetConstantBufferRootParameterIndex](GetConstantBufferRootParameterIndex.md)
+- [HasShaderResourceTable](HasShaderResourceTable.md)
+- [GetShaderResourceTableRootParameterIndex](GetShaderResourceTableRootParameterIndex.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12RootSignature](../D3D12RootSignature/D3D12RootSignature.md)
+- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
+- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/Destructor.md

@@ -1,29 +1,18 @@
-# D3D12PipelineLayout::~D3D12PipelineLayout()
-
-销毁对象并释放相关资源。
+# D3D12PipelineLayout::~D3D12PipelineLayout
 
 ```cpp
 ~D3D12PipelineLayout() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象并释放内部 root signature。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数会调用 [`Shutdown`](Shutdown.md)。
+- 如果已经创建过 `ID3D12RootSignature`，会在这里释放。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetConstantBufferRootParameterIndex.md

@@ -1,45 +1,25 @@
 # D3D12PipelineLayout::GetConstantBufferRootParameterIndex
 
-获取相关状态或对象。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 uint32_t GetConstantBufferRootParameterIndex(uint32_t binding) const;
-```
-
-**参数：**
-- `binding` - 参数语义详见头文件声明。
-
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 uint32_t GetConstantBufferRootParameterIndex(uint32_t setIndex, uint32_t binding) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+查询指定 `CBV` binding 对应的 root parameter 索引。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+- 找到映射时返回 root parameter index。
+- 未命中时返回 `UINT32_MAX`。
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetConstantBufferRootParameterIndex(...)。
-    (void)object;
-}
-```
+## 当前实现行为
+
+- flat 模式下按全局 `binding` 查询。
+- set-aware 模式下，双参数版本按 `setIndex` 分开查询；单参数版本默认等价于 `setIndex = 0`。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [HasConstantBufferBinding](HasConstantBufferBinding.md)
+- [D3D12CommandList::SetGraphicsDescriptorSets](../D3D12CommandList/SetGraphicsDescriptorSets.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetDesc.md

@@ -1,30 +1,23 @@
 # D3D12PipelineLayout::GetDesc
 
-获取相关状态或对象。
-
 ```cpp
 const RHIPipelineLayoutDesc& GetDesc() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回内部保存的、已经过 D3D12 后端归一化处理的布局描述。
 
-**返回：** `const RHIPipelineLayoutDesc&` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回对内部 `m_desc` 的常量引用。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetDesc(...)。
-    (void)object;
-}
-```
+- 如果使用了 `setLayouts`，返回值中的 `setLayouts` 指向内部深拷贝数组。
+- 若原始 `desc` 未填写总数，当前实现会重新累计四类 descriptor 的数量。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeWithDevice](InitializeWithDevice.md)
+- [UsesSetLayouts](UsesSetLayouts.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetNativeHandle.md

@@ -1,30 +1,22 @@
 # D3D12PipelineLayout::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 root signature 句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `ID3D12RootSignature*`，以 `void*` 形式暴露。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 本质上等价于 [`GetRootSignature`](GetRootSignature.md)。
+- 未初始化时返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [GetRootSignature](GetRootSignature.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetRootSignature.md

@@ -1,30 +1,22 @@
 # D3D12PipelineLayout::GetRootSignature
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12RootSignature* GetRootSignature() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以强类型方式返回当前创建好的 D3D12 root signature。
 
-**返回：** `ID3D12RootSignature*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `m_rootSignature.Get()`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetRootSignature(...)。
-    (void)object;
-}
-```
+- 常用于 PSO 创建和命令列表设置 root signature 的路径。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [InitializeWithDevice](InitializeWithDevice.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetSamplerTableRootParameterIndex.md

@@ -1,43 +1,23 @@
 # D3D12PipelineLayout::GetSamplerTableRootParameterIndex
 
-获取相关状态或对象。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 uint32_t GetSamplerTableRootParameterIndex() const;
-```
-
-**参数：** 无。
-
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 uint32_t GetSamplerTableRootParameterIndex(uint32_t setIndex) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+查询 sampler descriptor table 对应的 root parameter 索引。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+- 找到时返回索引。
+- 不存在时返回 `UINT32_MAX`。
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetSamplerTableRootParameterIndex(...)。
-    (void)object;
-}
-```
+## 当前实现行为
+
+- sampler table 与 SRV / UAV table 分离，映射到独立的 root parameter。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [HasSamplerTable](HasSamplerTable.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetSetLayoutCount.md

@@ -1,30 +1,22 @@
 # D3D12PipelineLayout::GetSetLayoutCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetSetLayoutCount() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前保存的 set layout 数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回内部 `m_desc.setLayoutCount`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetSetLayoutCount(...)。
-    (void)object;
-}
-```
+- flat 模式下通常返回 `0`。
+- set-aware 模式下返回深拷贝后的 set 数量。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [UsesSetLayouts](UsesSetLayouts.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetShaderResourceTableRootParameterIndex.md

@@ -1,43 +1,24 @@
 # D3D12PipelineLayout::GetShaderResourceTableRootParameterIndex
 
-获取相关状态或对象。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 uint32_t GetShaderResourceTableRootParameterIndex() const;
-```
-
-**参数：** 无。
-
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 uint32_t GetShaderResourceTableRootParameterIndex(uint32_t setIndex) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+查询 `SRV` descriptor table 对应的 root parameter 索引。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+- 找到时返回 root parameter index。
+- 不存在时返回 `UINT32_MAX`。
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetShaderResourceTableRootParameterIndex(...)。
-    (void)object;
-}
-```
+## 当前实现行为
+
+- flat 模式下只有一个全局 SRV table。
+- set-aware 模式下，不同 set 的 SRV table root parameter 索引彼此不同。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [HasShaderResourceTable](HasShaderResourceTable.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/GetUnorderedAccessTableRootParameterIndex.md

@@ -1,43 +1,19 @@
 # D3D12PipelineLayout::GetUnorderedAccessTableRootParameterIndex
 
-获取相关状态或对象。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 uint32_t GetUnorderedAccessTableRootParameterIndex() const;
-```
-
-**参数：** 无。
-
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 uint32_t GetUnorderedAccessTableRootParameterIndex(uint32_t setIndex) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+查询 `UAV` descriptor table 的 root parameter 索引。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::GetUnorderedAccessTableRootParameterIndex(...)。
-    (void)object;
-}
-```
+- 找到时返回索引。
+- 不存在时返回 `UINT32_MAX`。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [HasUnorderedAccessTable](HasUnorderedAccessTable.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/HasConstantBufferBinding.md

@@ -1,45 +1,24 @@
 # D3D12PipelineLayout::HasConstantBufferBinding
 
-判断是否具备指定状态或能力。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 bool HasConstantBufferBinding(uint32_t binding) const;
-```
-
-**参数：**
-- `binding` - 参数语义详见头文件声明。
-
-**返回：** `bool` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool HasConstantBufferBinding(uint32_t setIndex, uint32_t binding) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+判断指定 binding 是否拥有可查询的 root CBV parameter 索引。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+- flat 模式下，单参数版本查询全局 `binding -> rootIndex` 映射。
+- set-aware 模式下，单参数版本会把查询转发到 `setIndex = 0`。
+- 双参数版本在 set-aware 模式下只对目标 set 的 `CBV` binding 表做查找。
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::HasConstantBufferBinding(...)。
-    (void)object;
-}
-```
+## 重要限制
+
+- 一个 `CBV` binding 即使 `count > 1`，当前也只对应一个 root parameter。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [GetConstantBufferRootParameterIndex](GetConstantBufferRootParameterIndex.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/HasSamplerTable.md

@@ -1,43 +1,19 @@
 # D3D12PipelineLayout::HasSamplerTable
 
-判断是否具备指定状态或能力。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 bool HasSamplerTable() const;
-```
-
-**参数：** 无。
-
-**返回：** `bool` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool HasSamplerTable(uint32_t setIndex) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+判断当前布局是否为 sampler 创建了 descriptor table。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::HasSamplerTable(...)。
-    (void)object;
-}
-```
+- flat 模式下，只要 `samplerCount > 0` 就存在全局 sampler table。
+- set-aware 模式下，每个 set 最多拥有一个 sampler table。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [GetSamplerTableRootParameterIndex](GetSamplerTableRootParameterIndex.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/HasShaderResourceTable.md

@@ -1,43 +1,20 @@
 # D3D12PipelineLayout::HasShaderResourceTable
 
-判断是否具备指定状态或能力。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 bool HasShaderResourceTable() const;
-```
-
-**参数：** 无。
-
-**返回：** `bool` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool HasShaderResourceTable(uint32_t setIndex) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+判断当前布局是否为 `SRV` 创建了 descriptor table。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::HasShaderResourceTable(...)。
-    (void)object;
-}
-```
+- flat 模式下，只要 `textureCount > 0` 就会存在一个全局 SRV table。
+- set-aware 模式下，每个 set 最多拥有一个 SRV table。
+- 单参数版本在 set-aware 模式下默认检查 `setIndex = 0`。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [GetShaderResourceTableRootParameterIndex](GetShaderResourceTableRootParameterIndex.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/HasUnorderedAccessTable.md

@@ -1,43 +1,19 @@
 # D3D12PipelineLayout::HasUnorderedAccessTable
 
-判断是否具备指定状态或能力。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 bool HasUnorderedAccessTable() const;
-```
-
-**参数：** 无。
-
-**返回：** `bool` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool HasUnorderedAccessTable(uint32_t setIndex) const;
 ```
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+判断当前布局是否为 `UAV` 创建了 descriptor table。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::HasUnorderedAccessTable(...)。
-    (void)object;
-}
-```
+- flat 模式下，只要 `uavCount > 0` 就存在全局 UAV table。
+- set-aware 模式下，每个 set 最多拥有一个 UAV table。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [GetUnorderedAccessTableRootParameterIndex](GetUnorderedAccessTableRootParameterIndex.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/Initialize.md

@@ -1,31 +1,23 @@
 # D3D12PipelineLayout::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize(const RHIPipelineLayoutDesc& desc) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `desc` - 参数语义详见头文件声明。
+实现基类接口。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 当前固定返回 `false`。
+- 原因是 D3D12 root signature 的创建必须依赖具体设备，而这个签名没有 `D3D12Device*` 参数。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+## 正确用法
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::Initialize(...)。
-    (void)object;
-}
-```
+- 普通调用方不应直接使用这个函数。
+- 应通过 [`D3D12Device::CreatePipelineLayout`](../D3D12Device/CreatePipelineLayout.md) 或直接调用 [`InitializeWithDevice`](InitializeWithDevice.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeWithDevice](InitializeWithDevice.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/InitializeWithDevice.md

@@ -1,32 +1,40 @@
 # D3D12PipelineLayout::InitializeWithDevice
 
-初始化内部状态。
-
 ```cpp
-bool InitializeWithDevice(D3D12Device* device, const RHIPipelineLayoutDesc& desc);
+bool InitializeWithDevice(
+    D3D12Device* device,
+    const RHIPipelineLayoutDesc& desc);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
+使用具体的 D3D12 设备创建 root signature，并建立 root parameter / descriptor table 查询映射。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `device` 不能为空。
+- `device->GetDevice()` 必须返回有效的 `ID3D12Device`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
+## 参数
 
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::InitializeWithDevice(...)。
-    (void)object;
-}
-```
+- `device`: 用于序列化并创建 root signature 的后端设备。
+- `desc`: 通用 RHI 管线布局描述。
+
+## 返回值
+
+- 成功返回 `true`。
+- 设备无效、root signature 序列化失败或 `CreateRootSignature()` 失败时返回 `false`。
+
+## 当前实现行为
+
+- 会清空旧状态并保存新的 `desc`。
+- 如果提供了 `setLayouts`，会复制 set layout 并重新累计各类 descriptor 数量。
+- 根据模式调用内部的 flat / set-aware 初始化路径生成 root parameter 与 descriptor range。
+- 最终使用 `D3D12SerializeRootSignature()` 和 `ID3D12Device::CreateRootSignature()` 创建原生对象。
+- root signature flag 固定包含 `D3D12_ROOT_SIGNATURE_FLAG_ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT`。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetRootSignature](GetRootSignature.md)
+- [GetDesc](GetDesc.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/Shutdown.md

@@ -1,30 +1,20 @@
 # D3D12PipelineLayout::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放内部 root signature，并清空缓存的布局与索引映射。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::Shutdown(...)。
-    (void)object;
-}
-```
+- `m_rootSignature.Reset()` 释放原生对象。
+- 清空 root parameter、descriptor range、set layout 副本和索引表。
+- 把设备指针、desc 以及若干 root index 重置为初始状态。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeWithDevice](InitializeWithDevice.md)
+- [Destructor](Destructor.md)

docs/api/XCEngine/RHI/D3D12/D3D12PipelineLayout/UsesSetLayouts.md

@@ -1,30 +1,19 @@
 # D3D12PipelineLayout::UsesSetLayouts
 
-公开方法，详见头文件声明。
-
 ```cpp
 bool UsesSetLayouts() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineLayout.h`，当前页面用于固定 `D3D12PipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前对象是否处于 set-aware 模式。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12PipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::D3D12PipelineLayout object;
-    // 根据上下文补齐参数后调用 D3D12PipelineLayout::UsesSetLayouts(...)。
-    (void)object;
-}
-```
+- `true`: 当前内部保存了有效的 `setLayouts`。
+- `false`: 当前使用基于总 count 的 flat 模式。
 
 ## 相关文档
 
-- [返回类总览](D3D12PipelineLayout.md)
-- [返回模块目录](../D3D12.md)
+- [GetSetLayoutCount](GetSetLayoutCount.md)
+- [GetDesc](GetDesc.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/Constructor.md

@@ -1,28 +1,20 @@
-# D3D12ResourceView::D3D12ResourceView()
-
-构造对象。
+# D3D12ResourceView::D3D12ResourceView
 
 ```cpp
 D3D12ResourceView();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的资源视图对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-}
-```
+- 默认 `m_viewType = ShaderResource`，但这只是初始占位值。
+- 所有句柄、指针、大小和偏移都初始化为零。
+- 真正的类型和句柄要由后续 `InitializeAs*()` 写入。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/CreateDepthStencilDesc.md

@@ -1,32 +1,20 @@
 # D3D12ResourceView::CreateDepthStencilDesc
 
-创建新对象或资源。
-
 ```cpp
-static D3D12_DEPTH_STENCIL_VIEW_DESC CreateDepthStencilDesc(Format format, D3D12_DSV_DIMENSION dimension);
+static D3D12_DEPTH_STENCIL_VIEW_DESC CreateDepthStencilDesc(
+    Format format,
+    D3D12_DSV_DIMENSION dimension);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `format` - 参数语义详见头文件声明。
-- `dimension` - 参数语义详见头文件声明。
+快速构造一个最小可用的 `DSV desc`。
 
-**返回：** `D3D12_DEPTH_STENCIL_VIEW_DESC` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::CreateDepthStencilDesc(...)。
-    (void)object;
-}
-```
+- 只填写 `Format` 与 `ViewDimension`。
+- 其他联合体字段保持零初始化。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsDepthStencil](InitializeAsDepthStencil.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/CreateRenderTargetDesc.md

@@ -1,32 +1,24 @@
 # D3D12ResourceView::CreateRenderTargetDesc
 
-创建新对象或资源。
-
 ```cpp
-static D3D12_RENDER_TARGET_VIEW_DESC CreateRenderTargetDesc(Format format, D3D12_RTV_DIMENSION dimension);
+static D3D12_RENDER_TARGET_VIEW_DESC CreateRenderTargetDesc(
+    Format format,
+    D3D12_RTV_DIMENSION dimension);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `format` - 参数语义详见头文件声明。
-- `dimension` - 参数语义详见头文件声明。
+快速构造一个最小可用的 `RTV desc`。
 
-**返回：** `D3D12_RENDER_TARGET_VIEW_DESC` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 只填写 `Format` 与 `ViewDimension`。
+- 数组切片、mip、3D slice 等联合体字段仍保持零初始化。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::CreateRenderTargetDesc(...)。
-    (void)object;
-}
-```
+- 对 `Texture2DArray`、`Texture3D` 等复杂情况，调用方仍需继续补齐联合体字段。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/CreateShaderResourceDesc.md

@@ -1,33 +1,26 @@
 # D3D12ResourceView::CreateShaderResourceDesc
 
-创建新对象或资源。
-
 ```cpp
-static D3D12_SHADER_RESOURCE_VIEW_DESC CreateShaderResourceDesc(Format format, D3D12_SRV_DIMENSION dimension, uint32_t mipLevels = 0);
+static D3D12_SHADER_RESOURCE_VIEW_DESC CreateShaderResourceDesc(
+    Format format,
+    D3D12_SRV_DIMENSION dimension,
+    uint32_t mipLevels = 0);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `format` - 参数语义详见头文件声明。
-- `dimension` - 参数语义详见头文件声明。
-- `mipLevels` - 参数语义详见头文件声明。
+快速构造一个基础版 `SRV desc`。
 
-**返回：** `D3D12_SHADER_RESOURCE_VIEW_DESC` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 填写 `Format`、`ViewDimension` 和 `Shader4ComponentMapping`。
+- 只对 `Texture2D` 分支写入 `MostDetailedMip` 与 `MipLevels`。
+- `mipLevels == 0` 时会退化为 `1` 级 mip。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 当前限制
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::CreateShaderResourceDesc(...)。
-    (void)object;
-}
-```
+- 如果实际 dimension 是 `Buffer`、`TextureCube`、`Texture2DArray` 等，调用方仍需自行补齐对应 union 字段。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsShaderResource](InitializeAsShaderResource.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/CreateUnorderedAccessDesc.md

@@ -1,32 +1,20 @@
 # D3D12ResourceView::CreateUnorderedAccessDesc
 
-创建新对象或资源。
-
 ```cpp
-static D3D12_UNORDERED_ACCESS_VIEW_DESC CreateUnorderedAccessDesc(Format format, D3D12_UAV_DIMENSION dimension);
+static D3D12_UNORDERED_ACCESS_VIEW_DESC CreateUnorderedAccessDesc(
+    Format format,
+    D3D12_UAV_DIMENSION dimension);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `format` - 参数语义详见头文件声明。
-- `dimension` - 参数语义详见头文件声明。
+快速构造一个最小可用的 `UAV desc`。
 
-**返回：** `D3D12_UNORDERED_ACCESS_VIEW_DESC` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::CreateUnorderedAccessDesc(...)。
-    (void)object;
-}
-```
+- 只填写 `Format` 与 `ViewDimension`。
+- 计数器、buffer range、mip / slice 等细节仍需调用方补充。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/D3D12ResourceView.md

@@ -6,54 +6,65 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12ResourceView.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12ResourceView` public API。
+**描述**: D3D12 后端统一的资源视图对象，既封装基于 descriptor heap 的 RTV/DSV/SRV/UAV/CBV，也承载顶点缓冲和索引缓冲视图所需的地址与步长信息。
 
 ## 概述
 
-`D3D12ResourceView.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+在 D3D12 里，“view”并不是一种单一机制:
 
-## 声明概览
+- `RTV` / `DSV` / `SRV` / `UAV` / `CBV` 依赖 descriptor heap 和 descriptor handle。
+- `VBV` / `IBV` 则更像一段结构化的地址信息，不需要真实 descriptor。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12ResourceView` | `class` | 继承自 `RHIResourceView` 的公开声明。 |
+`D3D12ResourceView` 把这些差异统一封装到了同一个 RHI 对象里。上层只需要拿到一个 `RHIResourceView`，具体是 descriptor handle 还是 buffer address，由 D3D12 后端自己决定。
 
-## 公共方法
+这和商业引擎里常见的“view handle”思路一致: 渲染层谈的是“资源如何被用”，后端才决定到底是 heap slot、CPU/GPU descriptor handle，还是 GPU virtual address。
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12ResourceView()](Constructor.md) | 构造对象。 |
-| [~D3D12ResourceView()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [IsValid](IsValid.md) | 查询当前状态。 |
-| [SetViewType](SetViewType.md) | 设置相关状态或配置。 |
-| [GetViewType](GetViewType.md) | 获取相关状态或对象。 |
-| [GetDimension](GetDimension.md) | 获取相关状态或对象。 |
-| [GetFormat](GetFormat.md) | 获取相关状态或对象。 |
-| [SetOwnedHeap](SetOwnedHeap.md) | 设置相关状态或配置。 |
-| [InitializeAsRenderTarget](InitializeAsRenderTarget.md) | 初始化内部状态。 |
-| [InitializeAsDepthStencil](InitializeAsDepthStencil.md) | 初始化内部状态。 |
-| [InitializeAsShaderResource](InitializeAsShaderResource.md) | 初始化内部状态。 |
-| [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md) | 初始化内部状态。 |
-| [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md) | 初始化内部状态。 |
-| [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md) | 初始化内部状态。 |
-| [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md) | 初始化内部状态。 |
-| [GetCPUHandle](GetCPUHandle.md) | 获取相关状态或对象。 |
-| [GetGPUHandle](GetGPUHandle.md) | 获取相关状态或对象。 |
-| [GetResource](GetResource.md) | 获取相关状态或对象。 |
-| [GetHeap](GetHeap.md) | 获取相关状态或对象。 |
-| [GetSlotIndex](GetSlotIndex.md) | 获取相关状态或对象。 |
-| [GetBufferLocation](GetBufferLocation.md) | 获取相关状态或对象。 |
-| [GetBufferSize](GetBufferSize.md) | 获取相关状态或对象。 |
-| [GetBufferStride](GetBufferStride.md) | 获取相关状态或对象。 |
-| [GetBufferOffset](GetBufferOffset.md) | 获取相关状态或对象。 |
-| [CreateRenderTargetDesc](CreateRenderTargetDesc.md) | 创建新对象或资源。 |
-| [CreateDepthStencilDesc](CreateDepthStencilDesc.md) | 创建新对象或资源。 |
-| [CreateShaderResourceDesc](CreateShaderResourceDesc.md) | 创建新对象或资源。 |
-| [CreateUnorderedAccessDesc](CreateUnorderedAccessDesc.md) | 创建新对象或资源。 |
+## 生命周期
+
+1. 通常由 [`D3D12Device`](../D3D12Device/D3D12Device.md) 的 `Create*View()` 工厂函数创建。
+2. descriptor-backed view 会在初始化时写入某个 `D3D12DescriptorHeap` 槽位。
+3. 顶点 / 索引缓冲视图只缓存 GPU 地址、偏移、大小和 stride。
+4. [`Shutdown`](Shutdown.md) 只清空 view 自身状态；底层 `ID3D12Resource` 仍由纹理或缓冲对象拥有。
+
+## 当前实现的真实行为
+
+### 所有权
+
+- `m_resource` 只是裸指针，不会 `AddRef`。
+- 如果通过 [`SetOwnedHeap`](SetOwnedHeap.md) 接管了 heap，view 会在 `Shutdown()` 时释放它。
+- 如果只是借用了外部 heap，则调用方必须保证 heap 生命周期覆盖 view 的使用期。
+
+### descriptor-backed view
+
+- `InitializeAsRenderTarget()` / `DepthStencil()` / `ShaderResource()` / `UnorderedAccess()` / `ConstantBuffer()` 都会计算 `CPU descriptor handle` 并调用 `ID3D12Device::Create*View()`。
+- 这类 view 的 `GetNativeHandle()` 返回的是 `CPU descriptor handle.ptr`。
+- `GetGPUHandle()` 只有在绑定了 heap 时才有意义。
+
+### buffer view
+
+- `InitializeAsVertexBuffer()` / `InitializeAsIndexBuffer()` 不会创建 D3D12 descriptor。
+- 它们只缓存 `GPU virtual address + offset`、`size`、`stride` 和格式。
+- `GetNativeHandle()` 对这两类 view 返回底层 `ID3D12Resource*`，而不是 descriptor handle。
+
+## 当前限制
+
+- buffer view 初始化时不做越界检查，`bufferLocation` 需要调用方自己保证合法。
+- [`CreateShaderResourceDesc`](CreateShaderResourceDesc.md) 这个 helper 只完整填写了 `Texture2D` 分支。
+- `GetBuffer*()` 系列字段主要只对顶点 / 索引缓冲视图有意义。
+
+## 重点方法
+
+- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
+- [InitializeAsShaderResource](InitializeAsShaderResource.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
+- [SetOwnedHeap](SetOwnedHeap.md)
+- [GetCPUHandle](GetCPUHandle.md)
+- [GetGPUHandle](GetGPUHandle.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12DescriptorHeap](../D3D12DescriptorHeap/D3D12DescriptorHeap.md)
+- [D3D12Buffer](../D3D12Buffer/D3D12Buffer.md)
+- [D3D12Texture](../D3D12Texture/D3D12Texture.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/Destructor.md

@@ -1,29 +1,19 @@
-# D3D12ResourceView::~D3D12ResourceView()
-
-销毁对象并释放相关资源。
+# D3D12ResourceView::~D3D12ResourceView
 
 ```cpp
 ~D3D12ResourceView() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 view 对象并清理其内部状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数直接调用 [`Shutdown`](Shutdown.md)。
+- 如果 view 接管了 descriptor heap，会在这里一并释放。
+- 不会释放底层 `ID3D12Resource`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetBufferLocation.md

@@ -1,30 +1,19 @@
 # D3D12ResourceView::GetBufferLocation
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetBufferLocation() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 buffer view 使用的 GPU 虚拟地址。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetBufferLocation(...)。
-    (void)object;
-}
-```
+- 只对顶点 / 索引缓冲视图有意义。
+- 值等于底层缓冲 `GPUVirtualAddress + bufferOffset`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetBufferOffset.md

@@ -1,30 +1,18 @@
 # D3D12ResourceView::GetBufferOffset
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetBufferOffset() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 buffer view 相对底层缓冲起始地址的偏移。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetBufferOffset(...)。
-    (void)object;
-}
-```
+- 只对顶点 / 索引缓冲视图有意义。
+- 值直接来自初始化时的 `desc.bufferLocation`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetBufferLocation](GetBufferLocation.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetBufferSize.md

@@ -1,30 +1,18 @@
 # D3D12ResourceView::GetBufferSize
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetBufferSize() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 buffer view 记录的可见字节大小。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetBufferSize(...)。
-    (void)object;
-}
-```
+- 只对顶点 / 索引缓冲视图有意义。
+- 初始化时按 `buffer->GetSize() - desc.bufferLocation` 计算。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetBufferOffset](GetBufferOffset.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetBufferStride.md

@@ -1,30 +1,19 @@
 # D3D12ResourceView::GetBufferStride
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetBufferStride() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 buffer view 记录的步长信息。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetBufferStride(...)。
-    (void)object;
-}
-```
+- 顶点缓冲优先使用 `desc.structureByteStride`，否则使用底层缓冲 stride。
+- 索引缓冲直接使用底层缓冲 stride。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetCPUHandle.md

@@ -1,30 +1,19 @@
 # D3D12ResourceView::GetCPUHandle
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_CPU_DESCRIPTOR_HANDLE GetCPUHandle() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 view 记录的 CPU descriptor handle。
 
-**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetCPUHandle(...)。
-    (void)object;
-}
-```
+- descriptor-backed view 返回真实 handle。
+- 顶点 / 索引缓冲视图通常返回零句柄。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetGPUHandle](GetGPUHandle.md)
+- [GetNativeHandle](GetNativeHandle.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetDimension.md

@@ -1,30 +1,18 @@
 # D3D12ResourceView::GetDimension
 
-获取相关状态或对象。
-
 ```cpp
 ResourceViewDimension GetDimension() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 view 的维度信息。
 
-**返回：** `ResourceViewDimension` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetDimension(...)。
-    (void)object;
-}
-```
+- descriptor-backed texture view 会根据 D3D12 view dimension 转换得到。
+- 常量缓冲、顶点缓冲、索引缓冲都会标记为 `ResourceViewDimension::Buffer`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetFormat](GetFormat.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetFormat.md

@@ -1,30 +1,19 @@
 # D3D12ResourceView::GetFormat
 
-获取相关状态或对象。
-
 ```cpp
 Format GetFormat() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 view 当前记录的格式。
 
-**返回：** `Format` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetFormat(...)。
-    (void)object;
-}
-```
+- `RTV` / `DSV` / `SRV` / `UAV` 会从对应 view desc 转换得到格式。
+- 常量缓冲和顶点缓冲默认是 `Format::Unknown`。
+- 索引缓冲如果没有显式提供格式，会默认为 `Format::R32_UInt`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetGPUHandle.md

@@ -1,30 +1,24 @@
 # D3D12ResourceView::GetGPUHandle
 
-获取相关状态或对象。
-
 ```cpp
 GPUDescriptorHandle GetGPUHandle() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 view 所在 heap 槽位对应的 GPU descriptor handle。
 
-**返回：** `GPUDescriptorHandle` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `m_heap != nullptr` 时，返回 `m_heap->GetGPUDescriptorHandle(m_slotIndex)`。
+- 否则返回空句柄。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetGPUHandle(...)。
-    (void)object;
-}
-```
+- 该函数不检查 heap 是否 shader-visible。
+- 对 RTV / DSV 这类通常不需要 GPU handle 的 view，返回值可能并无实际使用意义。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUHandle](GetCPUHandle.md)
+- [GetHeap](GetHeap.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetHeap.md

@@ -1,30 +1,19 @@
 # D3D12ResourceView::GetHeap
 
-获取相关状态或对象。
-
 ```cpp
 D3D12DescriptorHeap* GetHeap() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 view 关联的 descriptor heap。
 
-**返回：** `D3D12DescriptorHeap*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetHeap(...)。
-    (void)object;
-}
-```
+- descriptor-backed view 通常返回有效 heap 指针。
+- 顶点 / 索引缓冲视图通常返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [SetOwnedHeap](SetOwnedHeap.md)
+- [GetSlotIndex](GetSlotIndex.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetNativeHandle.md

@@ -1,30 +1,25 @@
 # D3D12ResourceView::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 view 的“后端原生句柄”。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 顶点 / 索引缓冲视图: 返回底层 `ID3D12Resource*`。
+- 其他 view: 返回 `CPU descriptor handle.ptr`，以 `void*` 形式暴露。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 这个返回值的具体含义取决于 `m_viewType`。
+- 调用方如果需要强类型使用，应该先知道当前 view 的类别。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetViewType](GetViewType.md)
+- [GetCPUHandle](GetCPUHandle.md)
+- [GetResource](GetResource.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetResource.md

@@ -1,30 +1,22 @@
 # D3D12ResourceView::GetResource
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12Resource* GetResource() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 D3D12 资源指针。
 
-**返回：** `ID3D12Resource*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回内部保存的裸 `ID3D12Resource*`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetResource(...)。
-    (void)object;
-}
-```
+- 该对象不拥有资源所有权。
+- 调用方必须确保资源生命周期长于 view 的使用周期。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetSlotIndex.md

@@ -1,30 +1,18 @@
 # D3D12ResourceView::GetSlotIndex
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetSlotIndex() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 view 在当前 heap 中使用的槽位编号。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetSlotIndex(...)。
-    (void)object;
-}
-```
+- 对 descriptor-backed view，这是写入 descriptor 的实际 slot。
+- 对顶点 / 索引缓冲视图，这个值通常保持默认 `0`，没有实际含义。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetHeap](GetHeap.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/GetViewType.md

@@ -1,30 +1,17 @@
 # D3D12ResourceView::GetViewType
 
-获取相关状态或对象。
-
 ```cpp
 ResourceViewType GetViewType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 view 的逻辑类别。
 
-**返回：** `ResourceViewType` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::GetViewType(...)。
-    (void)object;
-}
-```
+- 返回内部 `m_viewType`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [SetViewType](SetViewType.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/InitializeAsConstantBuffer.md

@@ -1,35 +1,26 @@
 # D3D12ResourceView::InitializeAsConstantBuffer
 
-初始化内部状态。
-
 ```cpp
-void InitializeAsConstantBuffer(ID3D12Device* device, ID3D12Resource* resource, const D3D12_CONSTANT_BUFFER_VIEW_DESC* desc, D3D12DescriptorHeap* heap, uint32_t slotIndex);
+void InitializeAsConstantBuffer(
+    ID3D12Device* device,
+    ID3D12Resource* resource,
+    const D3D12_CONSTANT_BUFFER_VIEW_DESC* desc,
+    D3D12DescriptorHeap* heap,
+    uint32_t slotIndex);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `resource` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `heap` - 参数语义详见头文件声明。
-- `slotIndex` - 参数语义详见头文件声明。
+把当前对象初始化为 `CBV`，并在指定 heap 槽位写入 constant buffer view descriptor。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::InitializeAsConstantBuffer(...)。
-    (void)object;
-}
-```
+- 将 view type 设为 `ConstantBuffer`。
+- 维度固定记为 `Buffer`，格式固定为 `Format::Unknown`。
+- 调用 `CreateConstantBufferView()` 写入 descriptor。
+- 不会把 `BufferLocation`、`Size`、`Stride` 再额外缓存到 `GetBuffer*()` 字段里。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUHandle](GetCPUHandle.md)
+- [GetBufferLocation](GetBufferLocation.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/InitializeAsDepthStencil.md

@@ -1,35 +1,23 @@
 # D3D12ResourceView::InitializeAsDepthStencil
 
-初始化内部状态。
-
 ```cpp
-void InitializeAsDepthStencil(ID3D12Device* device, ID3D12Resource* resource, const D3D12_DEPTH_STENCIL_VIEW_DESC* desc, D3D12DescriptorHeap* heap, uint32_t slotIndex);
+void InitializeAsDepthStencil(
+    ID3D12Device* device,
+    ID3D12Resource* resource,
+    const D3D12_DEPTH_STENCIL_VIEW_DESC* desc,
+    D3D12DescriptorHeap* heap,
+    uint32_t slotIndex);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `resource` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `heap` - 参数语义详见头文件声明。
-- `slotIndex` - 参数语义详见头文件声明。
+把当前对象初始化为 `DSV`，并在指定 heap 槽位写入 depth-stencil view descriptor。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::InitializeAsDepthStencil(...)。
-    (void)object;
-}
-```
+- 与 [`InitializeAsRenderTarget`](InitializeAsRenderTarget.md) 类似，但调用的是 `CreateDepthStencilView()`。
+- format 和 dimension 从 `D3D12_DEPTH_STENCIL_VIEW_DESC` 解析。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUHandle](GetCPUHandle.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/InitializeAsIndexBuffer.md

@@ -1,32 +1,23 @@
 # D3D12ResourceView::InitializeAsIndexBuffer
 
-初始化内部状态。
-
 ```cpp
-void InitializeAsIndexBuffer(D3D12Buffer* buffer, const ResourceViewDesc& desc);
+void InitializeAsIndexBuffer(
+    D3D12Buffer* buffer,
+    const ResourceViewDesc& desc);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffer` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
+把当前对象初始化为索引缓冲视图元数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::InitializeAsIndexBuffer(...)。
-    (void)object;
-}
-```
+- 不创建 descriptor。
+- `m_bufferLocation` 和 `m_bufferSize` 的计算方式与顶点缓冲类似。
+- 如果 `desc.format == 0`，索引格式默认使用 `Format::R32_UInt`。
+- `m_bufferStride` 直接取缓冲自身 stride。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetFormat](GetFormat.md)
+- [GetBufferLocation](GetBufferLocation.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/InitializeAsRenderTarget.md

@@ -1,35 +1,30 @@
 # D3D12ResourceView::InitializeAsRenderTarget
 
-初始化内部状态。
-
 ```cpp
-void InitializeAsRenderTarget(ID3D12Device* device, ID3D12Resource* resource, const D3D12_RENDER_TARGET_VIEW_DESC* desc, D3D12DescriptorHeap* heap, uint32_t slotIndex);
+void InitializeAsRenderTarget(
+    ID3D12Device* device,
+    ID3D12Resource* resource,
+    const D3D12_RENDER_TARGET_VIEW_DESC* desc,
+    D3D12DescriptorHeap* heap,
+    uint32_t slotIndex);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `resource` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `heap` - 参数语义详见头文件声明。
-- `slotIndex` - 参数语义详见头文件声明。
+把当前对象初始化为 `RTV`，并在指定 heap 槽位写入 render target view descriptor。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 设置 view type、format、dimension、resource、heap 和 slot。
+- 使用 `heap->GetCPUDescriptorHandleForHeapStart() + slotIndex * descriptorSize` 计算目标句柄。
+- 调用 `ID3D12Device::CreateRenderTargetView()` 写入 descriptor。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 前置条件
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::InitializeAsRenderTarget(...)。
-    (void)object;
-}
-```
+- `device`、`resource`、`heap` 都应有效。
+- `slotIndex` 必须落在 heap 可用范围内。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUHandle](GetCPUHandle.md)
+- [SetOwnedHeap](SetOwnedHeap.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/InitializeAsShaderResource.md

@@ -1,35 +1,24 @@
 # D3D12ResourceView::InitializeAsShaderResource
 
-初始化内部状态。
-
 ```cpp
-void InitializeAsShaderResource(ID3D12Device* device, ID3D12Resource* resource, const D3D12_SHADER_RESOURCE_VIEW_DESC* desc, D3D12DescriptorHeap* heap, uint32_t slotIndex);
+void InitializeAsShaderResource(
+    ID3D12Device* device,
+    ID3D12Resource* resource,
+    const D3D12_SHADER_RESOURCE_VIEW_DESC* desc,
+    D3D12DescriptorHeap* heap,
+    uint32_t slotIndex);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `resource` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `heap` - 参数语义详见头文件声明。
-- `slotIndex` - 参数语义详见头文件声明。
+把当前对象初始化为 `SRV`，并在指定 heap 槽位写入 shader resource view descriptor。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::InitializeAsShaderResource(...)。
-    (void)object;
-}
-```
+- 记录格式、维度、resource、heap、slot。
+- 计算 CPU handle 后调用 `CreateShaderResourceView()`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUHandle](GetCPUHandle.md)
+- [GetGPUHandle](GetGPUHandle.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/InitializeAsUnorderedAccess.md

@@ -1,35 +1,25 @@
 # D3D12ResourceView::InitializeAsUnorderedAccess
 
-初始化内部状态。
-
 ```cpp
-void InitializeAsUnorderedAccess(ID3D12Device* device, ID3D12Resource* resource, const D3D12_UNORDERED_ACCESS_VIEW_DESC* desc, D3D12DescriptorHeap* heap, uint32_t slotIndex);
+void InitializeAsUnorderedAccess(
+    ID3D12Device* device,
+    ID3D12Resource* resource,
+    const D3D12_UNORDERED_ACCESS_VIEW_DESC* desc,
+    D3D12DescriptorHeap* heap,
+    uint32_t slotIndex);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `resource` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
-- `heap` - 参数语义详见头文件声明。
-- `slotIndex` - 参数语义详见头文件声明。
+把当前对象初始化为 `UAV`，并在指定 heap 槽位写入 unordered access view descriptor。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::InitializeAsUnorderedAccess(...)。
-    (void)object;
-}
-```
+- 计算目标 `CPU descriptor handle`。
+- 调用 `CreateUnorderedAccessView(resource, nullptr, desc, handle)`。
+- 当前实现没有使用 counter resource。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUHandle](GetCPUHandle.md)
+- [GetGPUHandle](GetGPUHandle.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/InitializeAsVertexBuffer.md

@@ -1,32 +1,28 @@
 # D3D12ResourceView::InitializeAsVertexBuffer
 
-初始化内部状态。
-
 ```cpp
-void InitializeAsVertexBuffer(D3D12Buffer* buffer, const ResourceViewDesc& desc);
+void InitializeAsVertexBuffer(
+    D3D12Buffer* buffer,
+    const ResourceViewDesc& desc);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffer` - 参数语义详见头文件声明。
-- `desc` - 参数语义详见头文件声明。
+把当前对象初始化为顶点缓冲视图元数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 不会创建 D3D12 descriptor。
+- `m_bufferLocation = buffer->GetGPUVirtualAddress() + desc.bufferLocation`。
+- `m_bufferSize = buffer->GetSize() - desc.bufferLocation`。
+- `m_bufferStride` 优先使用 `desc.structureByteStride`，否则使用缓冲自身 stride。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 当前限制
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::InitializeAsVertexBuffer(...)。
-    (void)object;
-}
-```
+- 没有对 `desc.bufferLocation > buffer->GetSize()` 做保护。
+- 需要调用方保证偏移合法。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetBufferLocation](GetBufferLocation.md)
+- [GetBufferStride](GetBufferStride.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/IsValid.md

@@ -1,30 +1,24 @@
 # D3D12ResourceView::IsValid
 
-查询当前状态。
-
 ```cpp
 bool IsValid() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前 view 是否已具备可用的后端状态。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 顶点 / 索引缓冲视图: 只要 `m_resource != nullptr` 即视为有效。
+- 其他 view: 需要 `m_handle.ptr != 0` 且 `m_resource != nullptr`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::IsValid(...)。
-    (void)object;
-}
-```
+- 对 buffer view 不要求存在 descriptor heap。
+- 对 descriptor-backed view，会同时检查 handle 和 resource。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/SetOwnedHeap.md

@@ -1,31 +1,24 @@
 # D3D12ResourceView::SetOwnedHeap
 
-设置相关状态或配置。
-
 ```cpp
-void SetOwnedHeap(std::unique_ptr<class D3D12DescriptorHeap> heap);
+void SetOwnedHeap(std::unique_ptr<D3D12DescriptorHeap> heap);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `heap` - 参数语义详见头文件声明。
+把 descriptor heap 的所有权转移给当前 view。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `heap`: 要被接管的 heap。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::SetOwnedHeap(...)。
-    (void)object;
-}
-```
+- 内部执行 `m_ownedHeap = std::move(heap)`。
+- 同时把 `m_heap` 指向 `m_ownedHeap.get()`。
+- 之后 view 会负责在 [`Shutdown`](Shutdown.md) 时释放这个 heap。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetHeap](GetHeap.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/SetViewType.md

@@ -1,31 +1,23 @@
 # D3D12ResourceView::SetViewType
 
-设置相关状态或配置。
-
 ```cpp
 void SetViewType(ResourceViewType type);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `type` - 参数语义详见头文件声明。
+手动覆盖 view 类型标记。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 仅修改 `m_viewType` 字段。
+- 不会同步重建 descriptor，不会修改 format、dimension 或缓冲地址。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::SetViewType(...)。
-    (void)object;
-}
-```
+- 更适合作为内部辅助函数使用。
+- 普通调用方应优先使用对应的 `InitializeAs*()`。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [GetViewType](GetViewType.md)

docs/api/XCEngine/RHI/D3D12/D3D12ResourceView/Shutdown.md

@@ -1,30 +1,20 @@
 # D3D12ResourceView::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12ResourceView.h`，当前页面用于固定 `D3D12ResourceView` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清空 view 自身保存的 descriptor / buffer view 元数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12ResourceView.h>
-
-void Example() {
-    XCEngine::RHI::D3D12ResourceView object;
-    // 根据上下文补齐参数后调用 D3D12ResourceView::Shutdown(...)。
-    (void)object;
-}
-```
+- 清零 `CPU handle`、resource 指针、heap 指针、slot、buffer 地址与大小等字段。
+- 如果 `m_ownedHeap` 存在，会先调用其 `Shutdown()` 再释放。
+- 不会销毁底层纹理或缓冲资源。
 
 ## 相关文档
 
-- [返回类总览](D3D12ResourceView.md)
-- [返回模块目录](../D3D12.md)
+- [SetOwnedHeap](SetOwnedHeap.md)
+- [Destructor](Destructor.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/Bind.md

@@ -1,30 +1,35 @@
 # OpenGLDescriptorSet::Bind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Bind() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+按照“直接使用声明 binding 编号”的规则，把当前 set 中缓存的资源绑定到 OpenGL 全局状态。
 
-**返回：** `void` - 无返回值。
+## 前置条件
 
-**示例：**
+- 需要已经通过 [`Initialize`](Initialize.md) 完成布局初始化。
+- 如果要绑定纹理或采样器，通常应先调用 [`Update`](Update.md) / [`UpdateSampler`](UpdateSampler.md)。
+- 如果要绑定常量缓冲，通常应先调用 [`WriteConstant`](WriteConstant.md)。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::Bind(...)。
-    (void)object;
-}
-```
+- 如果常量数据处于 dirty 状态，会先创建或更新内部 UBO。
+- 对每个 `CBV` binding，调用 `glBindBufferBase(GL_UNIFORM_BUFFER, binding + i, m_constantBuffer)`。
+- 对 `SRV` / `UAV` / `Sampler`，使用初始化时申请的 texture unit 逐个绑定。
+- 普通纹理路径统一调用 `glBindTexture(GL_TEXTURE_2D, textureId)`。
+- 绑定完成后将内部 `m_bound` 置为 `true`。
+
+## 失败与限制
+
+- 此路径不会参考 [`OpenGLPipelineLayout`](../OpenGLPipelineLayout/OpenGLPipelineLayout.md) 的重映射。
+- `UAV` 在该函数里并不走 `glBindImageTexture()`，更适合兼容旧式直接 binding 编号的调用方式。
+- 不会验证 shader 当前是否真的使用了这些 binding。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [BindWithPipelineLayout](BindWithPipelineLayout.md)
+- [Unbind](Unbind.md)
+- [WriteConstant](WriteConstant.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/BindWithPipelineLayout.md

@@ -1,32 +1,43 @@
 # OpenGLDescriptorSet::BindWithPipelineLayout
 
-公开方法，详见头文件声明。
-
 ```cpp
-void BindWithPipelineLayout(const OpenGLPipelineLayout* pipelineLayout, uint32_t setIndex);
+void BindWithPipelineLayout(
+    const OpenGLPipelineLayout* pipelineLayout,
+    uint32_t setIndex);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `pipelineLayout` - 参数语义详见头文件声明。
-- `setIndex` - 参数语义详见头文件声明。
+结合 `pipelineLayout` 把当前 descriptor set 绑定到真正的 OpenGL binding point。这是现代 RHI 路径下的主要绑定函数。
 
-**返回：** `void` - 无返回值。
+## 前置条件
 
-**示例：**
+- descriptor set 已初始化。
+- `setIndex` 应与当前 draw / dispatch 使用的 set 槽位一致。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 参数
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::BindWithPipelineLayout(...)。
-    (void)object;
-}
-```
+- `pipelineLayout`: 提供 `set + binding -> GL binding point` 的映射规则。
+- `setIndex`: 当前 set 在 pipeline layout 中的索引。
+
+## 当前实现行为
+
+- 如果常量数据 dirty，会先上传共享 UBO。
+- `CBV` 通过 `OpenGLPipelineLayout::GetConstantBufferBindingPoint()` 获取实际 binding point。
+- `SRV` 通过 `glActiveTexture(GL_TEXTURE0 + bindingPoint)` 绑定为采样纹理。
+- `UAV` 通过 `glBindImageTexture(bindingPoint, textureId, 0, GL_FALSE, 0, GL_READ_WRITE, GL_RGBA8)` 绑定。
+- `Sampler` 通过 `glBindSampler(bindingPoint, samplerId)` 绑定。
+- 如果 `pipelineLayout == nullptr` 或 layout 不使用 set layout，则回退为使用原始 `binding` 编号。
+
+## 当前限制
+
+- `SRV` 仍然固定按 `GL_TEXTURE_2D` 绑定。
+- `UAV` 固定使用 `GL_RGBA8`，并且固定使用 mip `0`、layer `0`。
+- 该函数不会检查 shader 反射结果与 layout 是否一致。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [OpenGLPipelineLayout](../OpenGLPipelineLayout/OpenGLPipelineLayout.md)
+- [Bind](Bind.md)
+- [OpenGLCommandList::SetGraphicsDescriptorSets](../OpenGLCommandList/SetGraphicsDescriptorSets.md)
+- [OpenGLCommandList::SetComputeDescriptorSets](../OpenGLCommandList/SetComputeDescriptorSets.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/Constructor.md

@@ -1,28 +1,21 @@
-# OpenGLDescriptorSet::OpenGLDescriptorSet()
-
-构造对象。
+# OpenGLDescriptorSet::OpenGLDescriptorSet
 
 ```cpp
 OpenGLDescriptorSet();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 descriptor set 容器，但不立即分配任何 OpenGL 资源。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-}
-```
+- 将 allocator、layout 指针和状态标记初始化为空或零值。
+- 不申请 texture unit。
+- 不创建 UBO。
+- 真正的资源分配发生在 [`Initialize`](Initialize.md) 或首次常量上传时。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/Destructor.md

@@ -1,29 +1,19 @@
-# OpenGLDescriptorSet::~OpenGLDescriptorSet()
-
-销毁对象并释放相关资源。
+# OpenGLDescriptorSet::~OpenGLDescriptorSet
 
 ```cpp
 ~OpenGLDescriptorSet() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象，并尝试释放内部持有的 OpenGL 相关状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部直接调用 [`Shutdown`](Shutdown.md)。
+- 如果对象已经初始化过，会删除内部 UBO，并归还申请过的 texture unit。
+- 不销毁外部传入的 `RHIResourceView`、`RHISampler` 或 `OpenGLPipelineLayout`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/GetBindingCount.md

@@ -1,30 +1,23 @@
 # OpenGLDescriptorSet::GetBindingCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetBindingCount() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 descriptor set 保存的 layout binding 数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `m_bindings.size()`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::GetBindingCount(...)。
-    (void)object;
-}
-```
+- 数量来自 [`Initialize`](Initialize.md) 时复制的 layout。
+- 它不表示“已经写入了多少资源”，也不表示“已经分配了多少 GPU descriptor”。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [GetBindings](GetBindings.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/GetBindingPoint.md

@@ -1,31 +1,30 @@
 # OpenGLDescriptorSet::GetBindingPoint
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetBindingPoint(uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `binding` - 参数语义详见头文件声明。
+返回某个 binding 在本对象内部申请到的第一个 texture unit。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `binding`: layout 中声明的 binding 编号。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::GetBindingPoint(...)。
-    (void)object;
-}
-```
+- 找到并且该 binding 拥有 texture unit 时，返回第一个 unit。
+- 其他情况返回 `0`。
+
+## 当前实现行为
+
+- 这里返回的是对象初始化时从 allocator 申请到的 unit。
+- 它不是 [`BindWithPipelineLayout`](BindWithPipelineLayout.md) 使用的最终 pipeline layout 重映射结果。
+- 该接口目前主要被测试代码用于验证不同 binding 是否分配到了不同 unit。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [Bind](Bind.md)
+- [BindWithPipelineLayout](BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/GetBindings.md

@@ -1,30 +1,24 @@
 # OpenGLDescriptorSet::GetBindings
 
-获取相关状态或对象。
-
 ```cpp
 const DescriptorSetLayoutBinding* GetBindings() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 descriptor set 内部保存的 layout binding 数组首地址。
 
-**返回：** `const DescriptorSetLayoutBinding*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 成功初始化后返回内部拷贝的 `DescriptorSetLayoutBinding` 数组。
+- 没有 binding 时返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::GetBindings(...)。
-    (void)object;
-}
-```
+- 返回的是 `Initialize()` 时复制出的 `m_layoutBindings`，而不是调用方传入的原始指针。
+- 指针在 [`Shutdown`](Shutdown.md) 之后失效。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [GetBindingCount](GetBindingCount.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/GetConstantBufferData.md

@@ -1,30 +1,24 @@
 # OpenGLDescriptorSet::GetConstantBufferData
 
-获取相关状态或对象。
-
 ```cpp
 void* GetConstantBufferData() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回共享常量缓冲的 CPU 侧字节缓存首地址。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `m_constantBufferData.data()`。
+- 当缓存为空时，返回值不应被解引用。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::GetConstantBufferData(...)。
-    (void)object;
-}
-```
+- 返回的是 CPU 内存，不是 UBO 的 GPU 映射地址。
+- 可用于调试、测试或在绑定前检查写入结果。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [WriteConstant](WriteConstant.md)
+- [GetConstantBufferSize](GetConstantBufferSize.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/GetConstantBufferSize.md

@@ -1,30 +1,23 @@
 # OpenGLDescriptorSet::GetConstantBufferSize
 
-获取相关状态或对象。
-
 ```cpp
 size_t GetConstantBufferSize() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前共享常量缓冲 CPU 缓存的字节大小。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回 `m_constantBufferData.size()`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::GetConstantBufferSize(...)。
-    (void)object;
-}
-```
+- 它反映的是 CPU 侧暂存区大小。
+- 不代表 shader 中实际声明的 UBO 大小，也不表示 GPU 端发生了多少次上传。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [GetConstantBufferData](GetConstantBufferData.md)
+- [WriteConstant](WriteConstant.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/Initialize.md

@@ -1,33 +1,47 @@
 # OpenGLDescriptorSet::Initialize
 
-初始化内部状态。
-
 ```cpp
-bool Initialize(OpenGLTextureUnitAllocator* allocator, uint32_t count, const DescriptorSetLayoutDesc& layout);
+bool Initialize(
+    OpenGLTextureUnitAllocator* allocator,
+    uint32_t count,
+    const DescriptorSetLayoutDesc& layout);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `allocator` - 参数语义详见头文件声明。
-- `count` - 参数语义详见头文件声明。
-- `layout` - 参数语义详见头文件声明。
+根据 descriptor set layout 初始化内部 binding 描述，并为需要的纹理类 binding 申请 OpenGL unit。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `layout.bindings` 在调用期间必须有效。
+- 如果 layout 中包含 `SRV`、`UAV` 或 `Sampler`，则 `allocator` 不能为空。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 参数
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::Initialize(...)。
-    (void)object;
-}
-```
+- `allocator`: texture / image / sampler unit 分配器。
+- `count`: 当前实现未使用，保留自通用 RHI 接口。
+- `layout`: set 的 binding 布局描述。
+
+## 返回值
+
+- 成功返回 `true`。
+- 申请 texture unit 失败，或需要分配 unit 但 `allocator == nullptr` 时返回 `false`。
+
+## 当前实现行为
+
+- 深拷贝 `layout` 到 `m_layoutBindings`。
+- 为每个 binding 建立 `DescriptorBinding` 记录。
+- `SRV`、`UAV`、`Sampler` 会为每个元素申请一个 texture unit。
+- `CBV` 不申请 unit。
+- 初始化失败时会立即调用 [`Shutdown`](Shutdown.md) 回滚已经分配的资源。
+
+## 失败与限制
+
+- `count` 参数不会影响内部数组大小或资源数量。
+- 当前没有校验 layout 中是否存在重复 binding 编号。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [GetBindings](GetBindings.md)
+- [GetBindingCount](GetBindingCount.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/IsConstantDirty.md

@@ -1,30 +1,24 @@
 # OpenGLDescriptorSet::IsConstantDirty
 
-查询当前状态。
-
 ```cpp
 bool IsConstantDirty() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+查询常量缓存是否自上次上传或清理后被修改过。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `true`: 下一次绑定前通常需要重新上传 UBO。
+- `false`: 当前没有新的常量改动需要上传。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::IsConstantDirty(...)。
-    (void)object;
-}
-```
+- 该状态仅由 [`WriteConstant`](WriteConstant.md)、内部上传逻辑和 [`MarkConstantClean`](MarkConstantClean.md) 维护。
+- 它不检查 GPU 端内容是否真的与 shader 预期一致。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [WriteConstant](WriteConstant.md)
+- [MarkConstantClean](MarkConstantClean.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/MarkConstantClean.md

@@ -1,30 +1,25 @@
 # OpenGLDescriptorSet::MarkConstantClean
 
-公开方法，详见头文件声明。
-
 ```cpp
 void MarkConstantClean() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+手动把常量 dirty 标志清为干净状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 仅执行 `m_constantBufferDirty = false`。
+- 不会触发上传。
+- 不会释放 UBO，也不会修改 CPU 缓存内容。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 适用场景
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::MarkConstantClean(...)。
-    (void)object;
-}
-```
+- 主要适合测试或外部流程需要显式重置 dirty 标志的场景。
+- 正常渲染路径下，通常由内部上传逻辑自动清理。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [IsConstantDirty](IsConstantDirty.md)
+- [WriteConstant](WriteConstant.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/OpenGLDescriptorSet.md

@@ -6,42 +6,72 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLDescriptorSet` public API。
+**描述**: OpenGL 后端对 RHI `descriptor set` 抽象的适配层，负责缓存纹理、采样器和常量数据，并在绑定阶段把它们映射到 OpenGL 的全局 binding point。
 
 ## 概述
 
-`OpenGLDescriptorSet.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+OpenGL 没有 Vulkan / D3D12 那样原生的 `descriptor set` 对象，只有全局的 texture unit、sampler slot、UBO binding point 和 image unit。`OpenGLDescriptorSet` 的职责，就是把引擎上层仍然使用的“按 set / binding 组织资源”工作流，翻译成 OpenGL 能接受的状态切换。
 
-## 声明概览
+这类设计在商业引擎里很常见: 上层继续按材质、pass、set 来组织资源，后端再根据平台差异落成真正的绑定命令。这样做的好处是:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `DescriptorBinding` | `struct` | 头文件中的公开声明。 |
-| `OpenGLDescriptorSet` | `class` | 继承自 `RHIDescriptorSet` 的公开声明。 |
+- 渲染层不需要为 OpenGL 单独改写一套资源绑定模型。
+- 同一份 shader / material 代码更容易在 D3D12、Vulkan、OpenGL 之间复用。
+- `OpenGLCommandList` 可以在 draw / dispatch 前统一消费 `RHIDescriptorSet`。
 
-## 公共方法
+## 生命周期
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLDescriptorSet()](Constructor.md) | 构造对象。 |
-| [~OpenGLDescriptorSet()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
-| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
-| [BindWithPipelineLayout](BindWithPipelineLayout.md) | 公开方法，详见头文件声明。 |
-| [Update](Update.md) | 更新运行时状态。 |
-| [UpdateSampler](UpdateSampler.md) | 更新运行时状态。 |
-| [WriteConstant](WriteConstant.md) | 公开方法，详见头文件声明。 |
-| [GetBindingCount](GetBindingCount.md) | 获取相关状态或对象。 |
-| [GetBindings](GetBindings.md) | 获取相关状态或对象。 |
-| [GetConstantBufferData](GetConstantBufferData.md) | 获取相关状态或对象。 |
-| [GetConstantBufferSize](GetConstantBufferSize.md) | 获取相关状态或对象。 |
-| [IsConstantDirty](IsConstantDirty.md) | 查询当前状态。 |
-| [MarkConstantClean](MarkConstantClean.md) | 公开方法，详见头文件声明。 |
-| [GetBindingPoint](GetBindingPoint.md) | 获取相关状态或对象。 |
+1. 由 [`OpenGLDescriptorPool`](../OpenGLDescriptorPool/OpenGLDescriptorPool.md) 分配对象，并调用 [`Initialize`](Initialize.md) 复制 layout。
+2. 通过 [`Update`](Update.md)、[`UpdateSampler`](UpdateSampler.md)、[`WriteConstant`](WriteConstant.md) 写入资源。
+3. 图形或计算命令通过 [`BindWithPipelineLayout`](BindWithPipelineLayout.md) 把当前 set 映射到实际 GL binding point。
+4. 销毁前调用 [`Shutdown`](Shutdown.md) 释放 texture unit 和内部 UBO。
+
+## 当前实现的真实行为
+
+### layout 与资源分配
+
+- 初始化时会深拷贝 `DescriptorSetLayoutDesc`。
+- 只有 `SRV`、`UAV`、`Sampler` 会向 `OpenGLTextureUnitAllocator` 申请 unit。
+- `CBV` 不占用 texture unit，而是共用一个懒上传的 UBO。
+- `Initialize()` 的 `count` 参数当前没有被使用，实际以 `layout.bindingCount` 为准。
+
+### 常量缓冲策略
+
+- [`WriteConstant`](WriteConstant.md) 把数据写进一个共享的 `std::vector<uint8_t>`。
+- 首次绑定前，如果 dirty，则会创建一个单独的 `GL_UNIFORM_BUFFER` 并整块上传。
+- 当前实现里所有 `CBV` binding 都绑定同一个 UBO 对象。
+- `WriteConstant()` 的 `binding` 参数当前不会切换到“每个 binding 一块独立常量缓冲”的模式，它只是保留了 RHI 级 API 形状。
+
+### 绑定路径
+
+- [`Bind`](Bind.md) 走“直接使用声明 binding 编号”的旧路径，更接近裸 OpenGL 资源绑定。
+- [`BindWithPipelineLayout`](BindWithPipelineLayout.md) 才是 `OpenGLCommandList::SetGraphicsDescriptorSets()` / `SetComputeDescriptorSets()` 使用的主路径。
+- 该主路径会借助 [`OpenGLPipelineLayout`](../OpenGLPipelineLayout/OpenGLPipelineLayout.md) 把 `set + binding` 映射到连续的 OpenGL binding point。
+
+### 当前限制
+
+- `Update()` / `UpdateSampler()` 只更新每个 binding 的第 `0` 个元素，未提供数组元素级写入接口。
+- 纹理绑定路径默认按 `GL_TEXTURE_2D` 处理普通采样纹理，没有根据真实 texture target 细分。
+- `UAV` 绑定固定使用 `glBindImageTexture(..., GL_RGBA8)`，当前没有从 view format 推导 image format。
+- [`Unbind`](Unbind.md) 主要是 [`Bind`](Bind.md) 的对称清理函数，并不完整回滚 `BindWithPipelineLayout()` 的重映射结果。
+
+## 线程语义
+
+- 没有内部锁。
+- 更安全的使用方式，是在拥有当前 OpenGL 上下文的线程上完成 `Update*()`、`WriteConstant()` 和 `Bind*()`。
+
+## 重点方法
+
+- [Initialize](Initialize.md)
+- [Bind](Bind.md)
+- [BindWithPipelineLayout](BindWithPipelineLayout.md)
+- [Update](Update.md)
+- [UpdateSampler](UpdateSampler.md)
+- [WriteConstant](WriteConstant.md)
+- [GetBindingPoint](GetBindingPoint.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLPipelineLayout](../OpenGLPipelineLayout/OpenGLPipelineLayout.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
+- [OpenGLDescriptorPool](../OpenGLDescriptorPool/OpenGLDescriptorPool.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/Shutdown.md

@@ -1,30 +1,26 @@
 # OpenGLDescriptorSet::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放 descriptor set 内部持有的 OpenGL 对象和 allocator 资源。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 如果内部创建过 UBO，则调用 `glDeleteBuffers()` 删除。
+- 遍历所有 binding，把已经申请的 texture unit 归还给 allocator。
+- 清空 binding 缓存、layout 拷贝和 dirty / bound 状态。
+- 不会销毁外部资源视图或采样器对象。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 失败与限制
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::Shutdown(...)。
-    (void)object;
-}
-```
+- 该函数假定当前线程可以安全访问 OpenGL 上下文。
+- 对未初始化对象调用是安全的，效果等同于清空内部状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [Destructor](Destructor.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/Unbind.md

@@ -1,30 +1,26 @@
 # OpenGLDescriptorSet::Unbind
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Unbind() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清理当前 set 在 OpenGL 全局状态上留下的直接绑定。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 对每个 `CBV` binding 调用 `glBindBufferBase(..., 0)` 解绑。
+- 遍历初始化时申请的 texture unit，把 `GL_TEXTURE_2D` 和 sampler 解绑为 `0`。
+- 将内部 `m_bound` 置为 `false`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前限制
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::Unbind(...)。
-    (void)object;
-}
-```
+- 它主要是 [`Bind`](Bind.md) 的对称清理函数。
+- 如果上一轮绑定走的是 [`BindWithPipelineLayout`](BindWithPipelineLayout.md)，这里并不会按 pipeline layout 的重映射结果逐个撤销 image / sampler / UBO 绑定。
+- `OpenGLCommandList` 当前也不会在每次 draw 后主动调用这个函数。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [BindWithPipelineLayout](BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/Update.md

@@ -1,32 +1,33 @@
 # OpenGLDescriptorSet::Update
 
-更新运行时状态。
-
 ```cpp
 void Update(uint32_t offset, RHIResourceView* view) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `offset` - 参数语义详见头文件声明。
-- `view` - 参数语义详见头文件声明。
+把一个资源视图写入指定 binding 的纹理槽缓存。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `offset`: 实际上表示 binding 编号，而不是字节偏移。
+- `view`: 要写入的资源视图。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::Update(...)。
-    (void)object;
-}
-```
+- `view == nullptr` 时直接返回。
+- 按 binding 编号查找内部 `DescriptorBinding`。
+- 将 `view` 强制转换为 `OpenGLResourceView`，并读取 `GetTexture()`。
+- 只写入该 binding 的第 `0` 个纹理元素。
+
+## 失败与限制
+
+- 如果找不到 binding，或该 binding 没有 `textureIds` 数组，会静默返回。
+- 当前没有数组元素索引参数，因此 `count > 1` 的 binding 无法逐元素更新。
+- 该函数不检查传入 view 的真实 `ResourceViewType` 是否与 layout 完全匹配。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [UpdateSampler](UpdateSampler.md)
+- [Bind](Bind.md)
+- [BindWithPipelineLayout](BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/UpdateSampler.md

@@ -1,32 +1,31 @@
 # OpenGLDescriptorSet::UpdateSampler
 
-更新运行时状态。
-
 ```cpp
 void UpdateSampler(uint32_t offset, RHISampler* sampler) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `offset` - 参数语义详见头文件声明。
-- `sampler` - 参数语义详见头文件声明。
+把一个采样器对象写入指定 binding 的 sampler 缓存。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `offset`: 当前实现中表示 binding 编号。
+- `sampler`: 要写入的采样器对象。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::UpdateSampler(...)。
-    (void)object;
-}
-```
+- `sampler == nullptr` 时直接返回。
+- 把对象强制转换为 `OpenGLSampler`，读取 `GetID()`。
+- 只更新目标 binding 的第 `0` 个 sampler 元素。
+
+## 失败与限制
+
+- 找不到 binding 或该 binding 没有 sampler 数组时会静默返回。
+- 不支持对 sampler 数组中的任意索引单独写入。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [Update](Update.md)
+- [Bind](Bind.md)
+- [BindWithPipelineLayout](BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLDescriptorSet/WriteConstant.md

@@ -1,34 +1,39 @@
 # OpenGLDescriptorSet::WriteConstant
 
-公开方法，详见头文件声明。
-
 ```cpp
-void WriteConstant(uint32_t binding, const void* data, size_t size, size_t offset = 0) override;
+void WriteConstant(
+    uint32_t binding,
+    const void* data,
+    size_t size,
+    size_t offset = 0) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h`，当前页面用于固定 `OpenGLDescriptorSet` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `binding` - 参数语义详见头文件声明。
-- `data` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
-- `offset` - 参数语义详见头文件声明。
+把常量数据写入 descriptor set 的 CPU 侧暂存缓冲，并标记为 dirty。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `binding`: 保留自通用 RHI 语义，当前实现不会据此切换不同 UBO。
+- `data`: 要写入的原始字节数据。
+- `size`: 写入字节数。
+- `offset`: 写入到共享常量缓冲中的字节偏移。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLDescriptorSet.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLDescriptorSet object;
-    // 根据上下文补齐参数后调用 OpenGLDescriptorSet::WriteConstant(...)。
-    (void)object;
-}
-```
+- 如果 `offset + size` 超过当前缓存大小，会先扩容 `m_constantBufferData`。
+- 直接 `memcpy` 到共享字节数组。
+- 将 `m_constantBufferDirty` 标记为 `true`。
+- 真正上传到 GPU 的时机是下一次 [`Bind`](Bind.md) 或 [`BindWithPipelineLayout`](BindWithPipelineLayout.md)。
+
+## 当前限制
+
+- 所有 `CBV` binding 共用同一块 UBO。
+- `binding` 参数当前不参与物理分区，也不会自动为不同 binding 维护 offset 表。
 
 ## 相关文档
 
-- [返回类总览](OpenGLDescriptorSet.md)
-- [返回模块目录](../OpenGL.md)
+- [GetConstantBufferData](GetConstantBufferData.md)
+- [GetConstantBufferSize](GetConstantBufferSize.md)
+- [IsConstantDirty](IsConstantDirty.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/Constructor.md

@@ -1,28 +1,19 @@
-# OpenGLPipelineLayout::OpenGLPipelineLayout()
-
-构造对象。
+# OpenGLPipelineLayout::OpenGLPipelineLayout
 
 ```cpp
 OpenGLPipelineLayout() = default;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 pipeline layout 元数据对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-}
-```
+- 使用编译器默认构造。
+- 不会自动初始化映射表。
+- 真正的布局复制与 binding point 计算发生在 [`Initialize`](Initialize.md)。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/Destructor.md

@@ -1,29 +1,19 @@
-# OpenGLPipelineLayout::~OpenGLPipelineLayout()
-
-销毁对象并释放相关资源。
+# OpenGLPipelineLayout::~OpenGLPipelineLayout
 
 ```cpp
 ~OpenGLPipelineLayout() override = default;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 依赖成员对象自身析构释放 CPU 侧容器。
+- 不会显式调用 [`Shutdown`](Shutdown.md)。
+- 因为它不持有 OpenGL 驱动对象，这种默认析构方式是可行的。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/GetConstantBufferBindingPoint.md

@@ -1,32 +1,24 @@
 # OpenGLPipelineLayout::GetConstantBufferBindingPoint
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetConstantBufferBindingPoint(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+查询某个常量缓冲 binding 在 OpenGL 中应使用的实际 binding point。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- set-aware 模式下返回映射后的连续 binding point。
+- flat 模式下，如果 `setIndex == 0`，直接返回 `binding`。
+- 找不到映射时返回 `UINT32_MAX`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::GetConstantBufferBindingPoint(...)。
-    (void)object;
-}
-```
+- 不同 set 会被映射到不同的全局 binding point，即使它们声明了相同的 binding 编号。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [HasConstantBufferBinding](HasConstantBufferBinding.md)
+- [OpenGLDescriptorSet::BindWithPipelineLayout](../OpenGLDescriptorSet/BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/GetDesc.md

@@ -1,30 +1,24 @@
 # OpenGLPipelineLayout::GetDesc
 
-获取相关状态或对象。
-
 ```cpp
 const RHIPipelineLayoutDesc& GetDesc() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回内部保存的、已经过后端归一化处理的 pipeline layout 描述。
 
-**返回：** `const RHIPipelineLayoutDesc&` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回对内部 `m_desc` 的常量引用。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::GetDesc(...)。
-    (void)object;
-}
-```
+- 在 set-aware 模式下，`setLayouts` 指向的是内部深拷贝后的数组。
+- `constantBufferCount`、`textureCount`、`uavCount`、`samplerCount` 也可能是重新累计后的值。
+- 调用 [`Shutdown`](Shutdown.md) 后，这个引用不再可用。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetSetLayoutCount](GetSetLayoutCount.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/GetNativeHandle.md

@@ -1,30 +1,24 @@
 # OpenGLPipelineLayout::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回后端原生句柄。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 已初始化时返回 `this`。
+- 未初始化时返回 `nullptr`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- OpenGL 没有原生的 pipeline layout 对象，因此这里返回的并不是驱动句柄。
+- 这个接口主要用于维持跨后端统一的 RHI 形状。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetDesc](GetDesc.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/GetSamplerBindingPoint.md

@@ -1,32 +1,25 @@
 # OpenGLPipelineLayout::GetSamplerBindingPoint
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetSamplerBindingPoint(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+查询 sampler binding 在 OpenGL sampler unit 空间中的实际编号。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- set-aware 模式下返回映射后的 sampler unit。
+- flat 模式下 `setIndex == 0` 时直接返回 `binding`。
+- 未命中时返回 `UINT32_MAX`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::GetSamplerBindingPoint(...)。
-    (void)object;
-}
-```
+- sampler 的编号空间独立于 SRV / UAV。
+- 这让同一个 `binding = 0` 可以分别映射为 `texture unit 0`、`image unit 0`、`sampler unit 0`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [HasSamplerBinding](HasSamplerBinding.md)
+- [OpenGLDescriptorSet::BindWithPipelineLayout](../OpenGLDescriptorSet/BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/GetSetLayoutCount.md

@@ -1,30 +1,23 @@
 # OpenGLPipelineLayout::GetSetLayoutCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetSetLayoutCount() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前保存的 set layout 数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 返回内部 `m_desc.setLayoutCount`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::GetSetLayoutCount(...)。
-    (void)object;
-}
-```
+- 在 flat 模式下通常为 `0`。
+- 在 set-aware 模式下，数量来自 `Initialize()` 深拷贝后的内部描述。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [UsesSetLayouts](UsesSetLayouts.md)
+- [GetDesc](GetDesc.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/GetShaderResourceBindingPoint.md

@@ -1,32 +1,24 @@
 # OpenGLPipelineLayout::GetShaderResourceBindingPoint
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetShaderResourceBindingPoint(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+查询采样纹理 binding 在 OpenGL texture unit 空间中的实际编号。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- set-aware 模式下返回内部计算出的连续 texture unit。
+- flat 模式下 `setIndex == 0` 时直接返回 `binding`。
+- 未命中时返回 `UINT32_MAX`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::GetShaderResourceBindingPoint(...)。
-    (void)object;
-}
-```
+- 该映射与 `CBV`、`UAV`、`Sampler` 的 binding point 计数器彼此独立。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [HasShaderResourceBinding](HasShaderResourceBinding.md)
+- [OpenGLDescriptorSet::BindWithPipelineLayout](../OpenGLDescriptorSet/BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/GetUnorderedAccessBindingPoint.md

@@ -1,32 +1,24 @@
 # OpenGLPipelineLayout::GetUnorderedAccessBindingPoint
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetUnorderedAccessBindingPoint(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+查询 `UAV` / image binding 在 OpenGL image unit 空间中的实际编号。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- set-aware 模式下返回重排后的 image unit。
+- flat 模式下 `setIndex == 0` 时直接返回 `binding`。
+- 未命中时返回 `UINT32_MAX`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::GetUnorderedAccessBindingPoint(...)。
-    (void)object;
-}
-```
+- 当前只是做编号重映射，不涉及 image format、访问权限或 mip / layer 细节。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [HasUnorderedAccessBinding](HasUnorderedAccessBinding.md)
+- [OpenGLDescriptorSet::BindWithPipelineLayout](../OpenGLDescriptorSet/BindWithPipelineLayout.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/HasConstantBufferBinding.md

@@ -1,32 +1,29 @@
 # OpenGLPipelineLayout::HasConstantBufferBinding
 
-判断是否具备指定状态或能力。
-
 ```cpp
 bool HasConstantBufferBinding(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+判断某个 set 中是否存在常量缓冲 binding 映射。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `setIndex`: 目标 set 索引。
+- `binding`: 目标 binding 编号。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::HasConstantBufferBinding(...)。
-    (void)object;
-}
-```
+- set-aware 模式下，只有映射表中真的存在该 binding 才返回 `true`。
+- flat 模式下，只要 `setIndex == 0` 就返回 `true`。
+
+## 当前实现行为
+
+- 在 flat 模式下并不会严格检查 `binding` 是否超出 count。
+- 这意味着它更像“当前模式是否允许按 binding 直接访问”，而不是严格的边界验证函数。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [GetConstantBufferBindingPoint](GetConstantBufferBindingPoint.md)
+- [UsesSetLayouts](UsesSetLayouts.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/HasSamplerBinding.md

@@ -1,32 +1,18 @@
 # OpenGLPipelineLayout::HasSamplerBinding
 
-判断是否具备指定状态或能力。
-
 ```cpp
 bool HasSamplerBinding(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+判断某个 set 中是否存在 sampler binding 的映射。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::HasSamplerBinding(...)。
-    (void)object;
-}
-```
+- set-aware 模式下按映射表判断。
+- flat 模式下，只要 `setIndex == 0` 就返回 `true`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [GetSamplerBindingPoint](GetSamplerBindingPoint.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/HasShaderResourceBinding.md

@@ -1,32 +1,22 @@
 # OpenGLPipelineLayout::HasShaderResourceBinding
 
-判断是否具备指定状态或能力。
-
 ```cpp
 bool HasShaderResourceBinding(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+判断某个 set 中是否存在采样纹理 binding 的映射。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- set-aware 模式下按映射表判断。
+- flat 模式下，只要 `setIndex == 0` 就返回 `true`。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::HasShaderResourceBinding(...)。
-    (void)object;
-}
-```
+- 与常量缓冲版本一样，flat 模式不会按 texture 数量做严格越界校验。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [GetShaderResourceBindingPoint](GetShaderResourceBindingPoint.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/HasUnorderedAccessBinding.md

@@ -1,32 +1,18 @@
 # OpenGLPipelineLayout::HasUnorderedAccessBinding
 
-判断是否具备指定状态或能力。
-
 ```cpp
 bool HasUnorderedAccessBinding(uint32_t setIndex, uint32_t binding) const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `setIndex` - 参数语义详见头文件声明。
-- `binding` - 参数语义详见头文件声明。
+判断某个 set 中是否存在 `UAV` / image binding 的映射。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::HasUnorderedAccessBinding(...)。
-    (void)object;
-}
-```
+- set-aware 模式下按映射表判断。
+- flat 模式下，只要 `setIndex == 0` 就返回 `true`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [GetUnorderedAccessBindingPoint](GetUnorderedAccessBindingPoint.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/Initialize.md

@@ -1,31 +1,34 @@
 # OpenGLPipelineLayout::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize(const RHIPipelineLayoutDesc& desc) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `desc` - 参数语义详见头文件声明。
+复制 pipeline layout 描述，并为 OpenGL 后端生成查询用的 binding point 映射。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `desc`: 通用 RHI 管线布局描述，可使用 count 方式，也可使用 `setLayouts` 方式。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::Initialize(...)。
-    (void)object;
-}
-```
+- 当前实现始终返回 `true`。
+
+## 当前实现行为
+
+- 先保存原始 `desc`，然后清空旧的映射和深拷贝缓存。
+- 如果提供了 `setLayouts`，会重新拷贝所有 set layout 并重新累计各类 descriptor 数量。
+- 对 `CBV`、`SRV`、`UAV`、`Sampler` 四类资源分别独立分配连续 binding point。
+- 映射顺序按 set 顺序遍历，set 内再按 binding 升序遍历。
+- 初始化完成后 `GetNativeHandle()` 会返回 `this`。
+
+## 失败与限制
+
+- 当前没有做参数合法性检查，例如重复 binding、空 binding 数组配合非零 count 等情况。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [UsesSetLayouts](UsesSetLayouts.md)
+- [GetDesc](GetDesc.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/OpenGLPipelineLayout.md

@@ -6,40 +6,70 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`
 
-**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLPipelineLayout` public API。
+**描述**: OpenGL 后端的 pipeline layout 适配对象，负责把 `set + binding` 关系重排成 OpenGL 的全局 binding point。
 
 ## 概述
 
-`OpenGLPipelineLayout.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+OpenGL 的 UBO、采样纹理、image、sampler 都共享各自的全局编号空间，而不是按 `descriptor set` 分组。`OpenGLPipelineLayout` 的存在价值，就是让引擎上层依然能写出更接近 Vulkan / D3D12 的资源布局，再由 OpenGL 后端把它们压平到各自的全局 binding space。
 
-## 声明概览
+可以把它理解成一张“绑定点翻译表”:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `OpenGLPipelineLayout` | `class` | 继承自 `RHIPipelineLayout` 的公开声明。 |
+- 上层看到的是 `setIndex + binding`。
+- OpenGL 真正需要的是 `uniform block binding`、`texture unit`、`image unit`、`sampler unit`。
 
-## 公共方法
+这种做法的收益，是材质系统和命令列表代码不必为 OpenGL 退化成手写的裸 binding 规则。
 
-| 方法 | 描述 |
-|------|------|
-| [OpenGLPipelineLayout()](Constructor.md) | 构造对象。 |
-| [~OpenGLPipelineLayout()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [UsesSetLayouts](UsesSetLayouts.md) | 公开方法，详见头文件声明。 |
-| [GetSetLayoutCount](GetSetLayoutCount.md) | 获取相关状态或对象。 |
-| [HasConstantBufferBinding](HasConstantBufferBinding.md) | 判断是否具备指定状态或能力。 |
-| [GetConstantBufferBindingPoint](GetConstantBufferBindingPoint.md) | 获取相关状态或对象。 |
-| [HasShaderResourceBinding](HasShaderResourceBinding.md) | 判断是否具备指定状态或能力。 |
-| [GetShaderResourceBindingPoint](GetShaderResourceBindingPoint.md) | 获取相关状态或对象。 |
-| [HasUnorderedAccessBinding](HasUnorderedAccessBinding.md) | 判断是否具备指定状态或能力。 |
-| [GetUnorderedAccessBindingPoint](GetUnorderedAccessBindingPoint.md) | 获取相关状态或对象。 |
-| [HasSamplerBinding](HasSamplerBinding.md) | 判断是否具备指定状态或能力。 |
-| [GetSamplerBindingPoint](GetSamplerBindingPoint.md) | 获取相关状态或对象。 |
-| [GetDesc](GetDesc.md) | 获取相关状态或对象。 |
+## 生命周期
+
+1. 由 [`OpenGLDevice::CreatePipelineLayout`](../OpenGLDevice/CreatePipelineLayout.md) 创建。
+2. [`Initialize`](Initialize.md) 复制 layout，并计算每个 set 的 binding point 映射。
+3. [`OpenGLDescriptorSet`](../OpenGLDescriptorSet/OpenGLDescriptorSet.md) 在 [`BindWithPipelineLayout`](../OpenGLDescriptorSet/BindWithPipelineLayout.md) 中查询这些映射。
+4. 销毁前可调用 [`Shutdown`](Shutdown.md) 清空 CPU 侧缓存。
+
+## 当前实现的真实行为
+
+### 两种工作模式
+
+- 如果 `desc.setLayouts != nullptr` 且 `setLayoutCount > 0`，进入“set-aware”模式。
+- 否则进入“flat”模式。
+
+### set-aware 模式
+
+- 会深拷贝所有 `DescriptorSetLayoutDesc` 和 `DescriptorSetLayoutBinding`。
+- 会重新累加 `constantBufferCount`、`textureCount`、`uavCount`、`samplerCount`。
+- 对每一种 descriptor 类型分别维护独立的连续 binding point 计数器。
+- 同一类型内部，按 binding 编号升序分配 binding point。
+- 不同 set 之间会继续递增，因此可以把跨 set 的重名 binding 编号拆开。
+
+### flat 模式
+
+- 不建立 per-set 映射表。
+- getter 直接把 `binding` 当作实际 binding point 返回。
+- 只有 `setIndex == 0` 被视为有效。
+
+## 设计取舍
+
+- 这是纯 CPU 侧对象，不对应 OpenGL 驱动里的原生 pipeline layout 句柄。
+- 它更像商业引擎里“资源布局元数据”的后端特化版本。
+- 这样做的代价是: shader 反射与实际 layout 一致性，当前仍由调用方自己保证。
+
+## 当前限制
+
+- 不检查当前 shader program 是否真的声明了这些 binding。
+- 不使用 stage visibility 做更细粒度裁剪。
+- `Has*Binding()` 在 flat 模式下只验证 `setIndex == 0`，不会根据 count 严格判断某个 binding 是否越界。
+
+## 重点方法
+
+- [Initialize](Initialize.md)
+- [UsesSetLayouts](UsesSetLayouts.md)
+- [GetConstantBufferBindingPoint](GetConstantBufferBindingPoint.md)
+- [GetShaderResourceBindingPoint](GetShaderResourceBindingPoint.md)
+- [GetUnorderedAccessBindingPoint](GetUnorderedAccessBindingPoint.md)
+- [GetSamplerBindingPoint](GetSamplerBindingPoint.md)
 
 ## 相关文档
 
-- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [OpenGL](../OpenGL.md)
+- [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/Shutdown.md

@@ -1,30 +1,20 @@
 # OpenGLPipelineLayout::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清空内部保存的布局描述、映射表和初始化标志。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::Shutdown(...)。
-    (void)object;
-}
-```
+- 重置 `m_desc`。
+- 清空 set layout 副本、binding point 映射和初始化标志。
+- 因为它是纯 CPU 元数据对象，所以没有 OpenGL 驱动资源需要释放。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetNativeHandle](GetNativeHandle.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineLayout/UsesSetLayouts.md

@@ -1,30 +1,23 @@
 # OpenGLPipelineLayout::UsesSetLayouts
 
-公开方法，详见头文件声明。
-
 ```cpp
 bool UsesSetLayouts() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h`，当前页面用于固定 `OpenGLPipelineLayout` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前 pipeline layout 是否处于 set-aware 模式。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `true`: `m_desc.setLayoutCount > 0` 且 `m_desc.setLayouts != nullptr`。
+- `false`: 当前使用 flat 模式。
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineLayout.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineLayout object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineLayout::UsesSetLayouts(...)。
-    (void)object;
-}
-```
+- 这个判断基于内部保存的 `m_desc`，而不是调用方传入对象的原始地址。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineLayout.md)
-- [返回模块目录](../OpenGL.md)
+- [Initialize](Initialize.md)
+- [GetSetLayoutCount](GetSetLayoutCount.md)

docs/api/_meta/rebuild-status.md

@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-27 22:08:19`
+**生成时间**: `2026-03-27 22:39:17`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`