From 114985d698cd72df8b1151ad14e1a6b0f7556f1b Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Sat, 28 Mar 2026 00:09:30 +0800
Subject: [PATCH] docs(api): document D3D12 swap chain and descriptor heap

---
 .../D3D12/D3D12DescriptorHeap/AllocateSet.md  | 42 ++++----
 .../D3D12/D3D12DescriptorHeap/Constructor.md  | 29 +++---
 .../D3D12/D3D12DescriptorHeap/CreateDesc.md   | 35 +++----
 .../D3D12DescriptorHeap.md                    | 99 +++++++++++++------
 .../D3D12/D3D12DescriptorHeap/Destructor.md   | 25 ++---
 .../RHI/D3D12/D3D12DescriptorHeap/FreeSet.md  | 34 +++----
 .../GetCPUDescriptorHandle.md                 | 28 +++---
 .../GetCPUDescriptorHandleForHeapStart.md     | 25 ++---
 .../D3D12DescriptorHeap/GetDescriptorCount.md | 24 ++---
 .../D3D12DescriptorHeap/GetDescriptorHeap.md  | 25 ++---
 .../D3D12DescriptorHeap/GetDescriptorSize.md  | 25 ++---
 .../D3D12/D3D12DescriptorHeap/GetDevice.md    | 25 ++---
 .../GetGPUDescriptorHandle.md                 | 29 +++---
 .../GetGPUDescriptorHandleForHeapStart.md     | 36 ++++---
 .../D3D12DescriptorHeap/GetNativeHandle.md    | 24 ++---
 .../RHI/D3D12/D3D12DescriptorHeap/GetType.md  | 24 ++---
 .../D3D12/D3D12DescriptorHeap/Initialize.md   | 70 ++++++-------
 .../D3D12DescriptorHeap/IsShaderVisible.md    | 24 ++---
 .../RHI/D3D12/D3D12DescriptorHeap/Shutdown.md | 27 +++--
 .../RHI/D3D12/D3D12SwapChain/Constructor.md   | 28 +++---
 .../D3D12/D3D12SwapChain/D3D12SwapChain.md    | 85 +++++++++++-----
 .../RHI/D3D12/D3D12SwapChain/Destructor.md    | 25 ++---
 .../RHI/D3D12/D3D12SwapChain/GetBackBuffer.md | 45 +++------
 .../D3D12SwapChain/GetCurrentBackBuffer.md    | 26 ++---
 .../GetCurrentBackBufferIndex.md              | 25 ++---
 .../D3D12SwapChain/GetNativeCommandQueue.md   | 25 ++---
 .../D3D12/D3D12SwapChain/GetNativeHandle.md   | 24 ++---
 .../RHI/D3D12/D3D12SwapChain/Initialize.md    | 86 +++++++++-------
 .../RHI/D3D12/D3D12SwapChain/Present.md       | 28 ++----
 .../RHI/D3D12/D3D12SwapChain/Resize.md        | 36 +++----
 .../RHI/D3D12/D3D12SwapChain/Shutdown.md      | 31 +++---
 docs/api/_meta/rebuild-status.md              |  2 +-
 32 files changed, 502 insertions(+), 614 deletions(-)

diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/AllocateSet.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/AllocateSet.md
index 02e095f5..53401be2 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/AllocateSet.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/AllocateSet.md
@@ -1,31 +1,39 @@
 # D3D12DescriptorHeap::AllocateSet
 
-公开方法，详见头文件声明。
-
 ```cpp
 RHIDescriptorSet* AllocateSet(const DescriptorSetLayoutDesc& layout) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `layout` - 参数语义详见头文件声明。
+按给定 layout 从当前 heap 中顺序分配一个 descriptor set 视图区域。
 
-**返回：** `RHIDescriptorSet*` - 返回值语义详见头文件声明。
+## 参数说明
 
-**示例：**
+- `layout`: descriptor set 布局描述。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::AllocateSet(...)。
-    (void)object;
-}
-```
+- 分配成功时返回新的 `D3D12DescriptorSet*`。
+- 剩余空间不足或初始化失败时返回 `nullptr`。
+
+## 当前实现行为
+
+- 先扫描 layout，计算当前 heap 真正需要的 descriptor 数量:
+  - `CBV_SRV_UAV` heap 只统计 `SRV` 和 `UAV`
+  - `Sampler` heap 只统计 `Sampler`
+  - `CBV` 当前不占用该 heap 的 descriptor 空间
+- 如果 `m_nextFreeOffset + requiredDescriptors > m_numDescriptors`，返回 `nullptr`。
+- 否则用当前 `m_nextFreeOffset` 作为新 set 的起始偏移。
+- 创建 `D3D12DescriptorSet` 并调用其 `Initialize()`。
+- 成功后把新 set 记录到 `m_allocatedSets`，并推进 `m_nextFreeOffset`。
+
+## 设计说明
+
+- 这本质上是一个 bump allocator。
+- 它不会搜索空洞，也不会重用已经释放 set 的 offset。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [FreeSet](FreeSet.md)
+- [GetDescriptorCount](GetDescriptorCount.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Constructor.md
index 09d9c784..9d4f4ef6 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Constructor.md
@@ -1,28 +1,23 @@
-# D3D12DescriptorHeap::D3D12DescriptorHeap()
-
-构造对象。
+# D3D12DescriptorHeap::D3D12DescriptorHeap
 
 ```cpp
 D3D12DescriptorHeap();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 D3D12 descriptor heap 包装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-}
-```
+- 构造函数会设置默认值:
+  - `m_type = DescriptorHeapType::CBV_SRV_UAV`
+  - `m_numDescriptors = 0`
+  - `m_descriptorSize = 0`
+  - `m_nextFreeOffset = 0`
+  - `m_shaderVisible = false`
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [D3D12DescriptorHeap](D3D12DescriptorHeap.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/CreateDesc.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/CreateDesc.md
index 201cf3d1..5bff2393 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/CreateDesc.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/CreateDesc.md
@@ -1,33 +1,24 @@
 # D3D12DescriptorHeap::CreateDesc
 
-创建新对象或资源。
-
 ```cpp
-static D3D12_DESCRIPTOR_HEAP_DESC CreateDesc(DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false);
+static D3D12_DESCRIPTOR_HEAP_DESC CreateDesc(
+    DescriptorHeapType type,
+    uint32_t numDescriptors,
+    bool shaderVisible = false);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `type` - 参数语义详见头文件声明。
-- `numDescriptors` - 参数语义详见头文件声明。
-- `shaderVisible` - 参数语义详见头文件声明。
+构造一个标准的 `D3D12_DESCRIPTOR_HEAP_DESC`。
 
-**返回：** `D3D12_DESCRIPTOR_HEAP_DESC` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::CreateDesc(...)。
-    (void)object;
-}
-```
+- 把 `DescriptorHeapType` 转换为原生 `D3D12_DESCRIPTOR_HEAP_TYPE`。
+- 填入 `NumDescriptors`。
+- 根据 `shaderVisible` 选择 `D3D12_DESCRIPTOR_HEAP_FLAG_SHADER_VISIBLE` 或 `NONE`。
+- `NodeMask` 固定为 `0`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [IsShaderVisible](IsShaderVisible.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/D3D12DescriptorHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/D3D12DescriptorHeap.md
index 5be99185..a97e6f16 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/D3D12DescriptorHeap.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/D3D12DescriptorHeap.md
@@ -6,42 +6,81 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12DescriptorHeap` public API。
+**描述**: D3D12 后端的 descriptor heap / descriptor pool 封装，同时承担原生 heap 访问和简单 descriptor set 顺序分配职责。
 
-## 概述
+## 概览
 
-`D3D12DescriptorHeap.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`D3D12DescriptorHeap` 在当前引擎里是一个双重角色对象:
 
-## 声明概览
+- 它本身包装了一个真实的 `ID3D12DescriptorHeap`
+- 同时又作为 `RHIDescriptorPool`，负责为 `D3D12DescriptorSet` 分配连续 descriptor 区间
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12DescriptorHeap` | `class` | 继承自 `RHIDescriptorPool` 的公开声明。 |
+这在工程上很常见，因为 D3D12 的 descriptor heap 和“描述符池”语义天然接近，但也意味着文档必须把“原生 heap 对象”和“分配策略”两层东西分开说明。
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12DescriptorHeap()](Constructor.md) | 构造对象。 |
-| [~D3D12DescriptorHeap()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetDevice](GetDevice.md) | 获取相关状态或对象。 |
-| [GetDescriptorHeap](GetDescriptorHeap.md) | 获取相关状态或对象。 |
-| [GetCPUDescriptorHandle](GetCPUDescriptorHandle.md) | 获取相关状态或对象。 |
-| [GetGPUDescriptorHandle](GetGPUDescriptorHandle.md) | 获取相关状态或对象。 |
-| [GetDescriptorCount](GetDescriptorCount.md) | 获取相关状态或对象。 |
-| [GetType](GetType.md) | 获取相关状态或对象。 |
-| [IsShaderVisible](IsShaderVisible.md) | 查询当前状态。 |
-| [GetDescriptorSize](GetDescriptorSize.md) | 获取相关状态或对象。 |
-| [GetCPUDescriptorHandleForHeapStart](GetCPUDescriptorHandleForHeapStart.md) | 获取相关状态或对象。 |
-| [GetGPUDescriptorHandleForHeapStart](GetGPUDescriptorHandleForHeapStart.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [CreateDesc](CreateDesc.md) | 创建新对象或资源。 |
-| [AllocateSet](AllocateSet.md) | 公开方法，详见头文件声明。 |
-| [FreeSet](FreeSet.md) | 公开方法，详见头文件声明。 |
+当前实现是一个简单、可用的顺序分配器:
+
+- 可以创建不同类型的 heap
+- 可以按 layout 分配 descriptor set
+- 可以计算 CPU / GPU descriptor handle
+
+但它不是完整的可回收 allocator:
+
+- 没有 free list
+- 没有碎片整理
+- `FreeSet()` 不回收 offset
+
+## 生命周期
+
+- 构造后为空对象。
+- [Initialize](Initialize.md) 成功后持有 `ID3D12DescriptorHeap`。
+- [AllocateSet](AllocateSet.md) 会在堆内顺序切分 descriptor 区间。
+- [Shutdown](Shutdown.md) 释放 heap 和内部追踪状态。
+- 析构时自动调用 `Shutdown()`。
+
+## 线程语义
+
+- 当前实现没有锁。
+- 不应把它当作并发分配器使用。
+
+## 当前实现的真实行为
+
+- `Initialize(const DescriptorPoolDesc&)` 只是转调另一重载。
+- `GetCPUDescriptorHandle(index)` / `GetGPUDescriptorHandle(index)` 直接按 `index * descriptorSize` 做地址偏移，不检查越界。
+- `GetGPUDescriptorHandle...` 系列接口不会检查 heap 是否 shader-visible。
+- `AllocateSet()` 对 `CBV` 绑定当前不会消耗 descriptor heap 空间，这与 `D3D12DescriptorSet` 中常量缓冲单独上传的实现一致。
+- `FreeSet()` 会删除 set 对象并把它从 `m_allocatedSets` 中移除，但不会回退 `m_nextFreeOffset`。
+- `Shutdown()` 只 `clear()` 已分配 set 指针数组，不会逐个 delete 它们。
+
+## 为什么这样设计
+
+这套实现反映了当前引擎的 D3D12 资源绑定策略:
+
+- `SRV` / `UAV` / `Sampler` 通过真正的 descriptor heap 区间绑定
+- `CBV` 更多依赖单独的常量缓冲上传路径和 root binding
+
+好处是实现简单，容易和现在的 `D3D12DescriptorSet` 对上。
+代价是这个 heap/pool 抽象并不是通用、可回收、长期稳定的 descriptor allocator。
+
+## 当前限制
+
+- 不是可复用池，而是 bump allocator。
+- `Shutdown()` 不负责 delete 仍被跟踪的 set 对象。
+- 多个 handle getter 在未初始化、越界或非 shader-visible 场景下没有保护。
+- `FreeSet()` 删除 set 后不会回收 descriptor 空间。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [AllocateSet](AllocateSet.md)
+- [FreeSet](FreeSet.md)
+- [GetCPUDescriptorHandle](GetCPUDescriptorHandle.md)
+- [GetGPUDescriptorHandle](GetGPUDescriptorHandle.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12DescriptorSet](../D3D12DescriptorSet/D3D12DescriptorSet.md)
+- [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Destructor.md
index 06cd9880..0b15bf97 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Destructor.md
@@ -1,29 +1,18 @@
-# D3D12DescriptorHeap::~D3D12DescriptorHeap()
-
-销毁对象并释放相关资源。
+# D3D12DescriptorHeap::~D3D12DescriptorHeap
 
 ```cpp
 ~D3D12DescriptorHeap() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象并释放内部 descriptor heap。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [AllocateSet](AllocateSet.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/FreeSet.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/FreeSet.md
index dc2737b7..6f3e07b4 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/FreeSet.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/FreeSet.md
@@ -1,31 +1,31 @@
 # D3D12DescriptorHeap::FreeSet
 
-公开方法，详见头文件声明。
-
 ```cpp
 void FreeSet(RHIDescriptorSet* set) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `set` - 参数语义详见头文件声明。
+释放一个此前由当前 heap 分配的 descriptor set 对象。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `set`: 需要释放的 set。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::FreeSet(...)。
-    (void)object;
-}
-```
+- `set == nullptr` 时直接返回。
+- 在线性遍历 `m_allocatedSets` 找到对应指针后:
+  - 从数组中移除该指针
+  - 直接 `delete set`
+- 如果没有找到该指针，则什么都不做。
+
+## 重要限制
+
+- 不会回收该 set 占用的 descriptor offset。
+- 因此释放对象只影响生命周期，不会增加后续可分配容量。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [AllocateSet](AllocateSet.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandle.md
index 8aa0b870..31cea363 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandle.md
@@ -1,31 +1,25 @@
 # D3D12DescriptorHeap::GetCPUDescriptorHandle
 
-获取相关状态或对象。
-
 ```cpp
 CPUDescriptorHandle GetCPUDescriptorHandle(uint32_t index);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `index` - 参数语义详见头文件声明。
+返回指定 descriptor 槽位的 CPU handle。
 
-**返回：** `CPUDescriptorHandle` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 取 heap 起始 CPU handle。
+- 按 `index * m_descriptorSize` 做指针偏移。
+- 再包装为引擎自己的 `CPUDescriptorHandle`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
+## 重要限制
 
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetCPUDescriptorHandle(...)。
-    (void)object;
-}
-```
+- 没有越界检查。
+- 未初始化时也没有空指针保护。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUDescriptorHandleForHeapStart](GetCPUDescriptorHandleForHeapStart.md)
+- [GetDescriptorSize](GetDescriptorSize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandleForHeapStart.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandleForHeapStart.md
index 384050d5..7d5a4d5d 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandleForHeapStart.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetCPUDescriptorHandleForHeapStart.md
@@ -1,30 +1,19 @@
 # D3D12DescriptorHeap::GetCPUDescriptorHandleForHeapStart
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandleForHeapStart() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 heap 起始位置的原生 CPU descriptor handle。
 
-**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetCPUDescriptorHandleForHeapStart(...)。
-    (void)object;
-}
-```
+- 直接调用 `m_descriptorHeap->GetCPUDescriptorHandleForHeapStart()`。
+- 没有空指针保护。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUDescriptorHandle](GetCPUDescriptorHandle.md)
+- [GetDescriptorHeap](GetDescriptorHeap.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorCount.md
index 36e1fbc1..1e1cf7fb 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorCount.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorCount.md
@@ -1,30 +1,18 @@
 # D3D12DescriptorHeap::GetDescriptorCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetDescriptorCount() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 heap 配置的 descriptor 总数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetDescriptorCount(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_numDescriptors`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [AllocateSet](AllocateSet.md)
+- [GetDescriptorSize](GetDescriptorSize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorHeap.md
index 6fb9ab82..23e7f132 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorHeap.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorHeap.md
@@ -1,30 +1,19 @@
 # D3D12DescriptorHeap::GetDescriptorHeap
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12DescriptorHeap* GetDescriptorHeap() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层原生 descriptor heap 指针。
 
-**返回：** `ID3D12DescriptorHeap*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetDescriptorHeap(...)。
-    (void)object;
-}
-```
+- 初始化成功后返回有效 `ID3D12DescriptorHeap*`。
+- 否则返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorSize.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorSize.md
index 2e0777c2..44e3b224 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorSize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDescriptorSize.md
@@ -1,30 +1,19 @@
 # D3D12DescriptorHeap::GetDescriptorSize
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetDescriptorSize() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 heap 类型对应的 descriptor 步长。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetDescriptorSize(...)。
-    (void)object;
-}
-```
+- 该值在初始化时通过 `device->GetDescriptorHandleIncrementSize()` 查询并缓存。
+- 此接口仅返回缓存值。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetCPUDescriptorHandle](GetCPUDescriptorHandle.md)
+- [GetGPUDescriptorHandle](GetGPUDescriptorHandle.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDevice.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDevice.md
index 653ad5f9..edcb4a26 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDevice.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetDevice.md
@@ -1,30 +1,19 @@
 # D3D12DescriptorHeap::GetDevice
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12Device* GetDevice() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回创建该 heap 的原生 D3D12 设备指针。
 
-**返回：** `ID3D12Device*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetDevice(...)。
-    (void)object;
-}
-```
+- 初始化成功后返回有效 `ID3D12Device*`。
+- `Shutdown()` 后返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetDescriptorHeap](GetDescriptorHeap.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandle.md
index 51775e2c..7759924b 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandle.md
@@ -1,31 +1,26 @@
 # D3D12DescriptorHeap::GetGPUDescriptorHandle
 
-获取相关状态或对象。
-
 ```cpp
 GPUDescriptorHandle GetGPUDescriptorHandle(uint32_t index);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `index` - 参数语义详见头文件声明。
+返回指定 descriptor 槽位的 GPU handle。
 
-**返回：** `GPUDescriptorHandle` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 取 heap 起始 GPU handle。
+- 按 `index * m_descriptorSize` 做偏移。
+- 再包装为引擎的 `GPUDescriptorHandle`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
+## 重要限制
 
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetGPUDescriptorHandle(...)。
-    (void)object;
-}
-```
+- 没有越界检查。
+- 没有检查 heap 是否 `shaderVisible`。
+- 对 RTV / DSV 这类非 shader-visible heap，调用方仍可能拿到没有实际绑定意义的值。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetGPUDescriptorHandleForHeapStart](GetGPUDescriptorHandleForHeapStart.md)
+- [IsShaderVisible](IsShaderVisible.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandleForHeapStart.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandleForHeapStart.md
index 9ad4312c..c8d656cc 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandleForHeapStart.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetGPUDescriptorHandleForHeapStart.md
@@ -1,30 +1,34 @@
 # D3D12DescriptorHeap::GetGPUDescriptorHandleForHeapStart
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandleForHeapStart() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 descriptor heap 起始位置的原生 GPU descriptor handle。
 
-**返回：** `D3D12_GPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。
+这个接口主要服务于 shader-visible heap 场景。在需要把整段 descriptor 区间绑定到命令列表，或者在起始句柄基础上继续按 descriptor size 做偏移时，它提供了最底层的 D3D12 入口。
 
-**示例：**
+## 当前实现行为
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
+- 直接调用 `m_descriptorHeap->GetGPUDescriptorHandleForHeapStart()`
+- 不检查 `m_descriptorHeap` 是否为空
+- 不检查当前 heap 是否为 shader-visible
+- 不做任何范围或状态保护，调用者需要自己保证对象已经成功初始化
 
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetGPUDescriptorHandleForHeapStart(...)。
-    (void)object;
-}
-```
+## 使用建议
+
+- 只在 [Initialize](Initialize.md) 成功之后调用
+- 只在 [IsShaderVisible](IsShaderVisible.md) 返回 `true` 的 heap 上把这个句柄用于 GPU 绑定
+- 如果只是访问某个具体槽位，优先使用 [GetGPUDescriptorHandle](GetGPUDescriptorHandle.md)
+
+## 设计说明
+
+这个接口暴露的是原生 D3D12 句柄，而不是更高层的安全包装。这样做的好处是后端层可以零额外抽象成本地接入命令列表绑定流程；代价是文档必须明确指出，它不会替你处理空对象、错误 heap 类型或未初始化状态。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetGPUDescriptorHandle](GetGPUDescriptorHandle.md)
+- [GetDescriptorSize](GetDescriptorSize.md)
+- [IsShaderVisible](IsShaderVisible.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetNativeHandle.md
index d9964cee..5b56cd78 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetNativeHandle.md
@@ -1,30 +1,18 @@
 # D3D12DescriptorHeap::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以统一接口形式暴露底层 `ID3D12DescriptorHeap*`。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_descriptorHeap.Get()`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetDescriptorHeap](GetDescriptorHeap.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetType.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetType.md
index 72288211..cb098052 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/GetType.md
@@ -1,30 +1,18 @@
 # D3D12DescriptorHeap::GetType
 
-获取相关状态或对象。
-
 ```cpp
 DescriptorHeapType GetType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 heap 的逻辑类型。
 
-**返回：** `DescriptorHeapType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::GetType(...)。
-    (void)object;
-}
-```
+- 直接返回缓存的 `m_type`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [IsShaderVisible](IsShaderVisible.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Initialize.md
index 66b989e1..5fa2bd4e 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Initialize.md
@@ -1,47 +1,51 @@
 # D3D12DescriptorHeap::Initialize
 
-初始化内部状态。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
-bool Initialize(ID3D12Device* device, DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false);
-```
+bool Initialize(
+    ID3D12Device* device,
+    DescriptorHeapType type,
+    uint32_t numDescriptors,
+    bool shaderVisible = false);
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `type` - 参数语义详见头文件声明。
-- `numDescriptors` - 参数语义详见头文件声明。
-- `shaderVisible` - 参数语义详见头文件声明。
-
-**返回：** `bool` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool Initialize(const DescriptorPoolDesc& desc) override;
 ```
 
-**参数：**
-- `desc` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+创建一个原生 D3D12 descriptor heap，并初始化内部分配状态。
 
-**示例：**
+## 参数说明
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
+- `device`: D3D12 设备。
+- `type`: heap 类型。
+- `numDescriptors`: descriptor 数量。
+- `shaderVisible`: 是否创建成 shader-visible heap。
+- `desc`: 统一的 descriptor pool 描述。
 
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::Initialize(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 创建成功返回 `true`。
+- `CreateDescriptorHeap()` 失败时返回 `false`。
+
+## 当前实现行为
+
+### `Initialize(ID3D12Device*, DescriptorHeapType, uint32_t, bool)`
+
+- 构造 `D3D12_DESCRIPTOR_HEAP_DESC`。
+- 调用 `device->CreateDescriptorHeap(...)`。
+- 成功后缓存:
+  - `m_device`
+  - `m_type`
+  - `m_numDescriptors`
+  - `m_shaderVisible`
+  - `m_descriptorSize`
+  - `m_nextFreeOffset = 0`
+
+### `Initialize(const DescriptorPoolDesc& desc)`
+
+- 只是转调另一重载，把 `desc.device` 强转为 `ID3D12Device*`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [CreateDesc](CreateDesc.md)
+- [AllocateSet](AllocateSet.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/IsShaderVisible.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/IsShaderVisible.md
index 425f8eb3..e9b23181 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/IsShaderVisible.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/IsShaderVisible.md
@@ -1,30 +1,18 @@
 # D3D12DescriptorHeap::IsShaderVisible
 
-查询当前状态。
-
 ```cpp
 bool IsShaderVisible() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该 heap 是否创建为 shader-visible。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::IsShaderVisible(...)。
-    (void)object;
-}
-```
+- 直接返回缓存的 `m_shaderVisible`。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetGPUDescriptorHandle](GetGPUDescriptorHandle.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Shutdown.md
index 95a111bc..d32d2fbc 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorHeap/Shutdown.md
@@ -1,30 +1,25 @@
 # D3D12DescriptorHeap::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorHeap.h`，当前页面用于固定 `D3D12DescriptorHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放底层 descriptor heap，并清空内部分配状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- `Reset()` 设备和 descriptor heap 引用。
+- `clear()` `m_allocatedSets`。
+- 把 `m_numDescriptors`、`m_descriptorSize`、`m_nextFreeOffset` 设为 `0`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>
+## 重要限制
 
-void Example() {
-    XCEngine::RHI::D3D12DescriptorHeap object;
-    // 根据上下文补齐参数后调用 D3D12DescriptorHeap::Shutdown(...)。
-    (void)object;
-}
-```
+- 当前不会逐个 delete `m_allocatedSets` 中仍被追踪的 set 对象。
+- 如果调用方没有先释放这些 set，可能留下泄漏或悬空生命周期关系。
 
 ## 相关文档
 
-- [返回类总览](D3D12DescriptorHeap.md)
-- [返回模块目录](../D3D12.md)
+- [FreeSet](FreeSet.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Constructor.md
index 114f5b3d..bff2b4a7 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Constructor.md
@@ -1,28 +1,22 @@
-# D3D12SwapChain::D3D12SwapChain()
-
-构造对象。
+# D3D12SwapChain::D3D12SwapChain
 
 ```cpp
 D3D12SwapChain();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 D3D12 交换链封装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
-
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-}
-```
+- 构造函数会把:
+  - `m_width = 0`
+  - `m_height = 0`
+  - `m_bufferCount = 2`
+- 原生 swap chain、命令队列和 back buffer 数组都处于空状态。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [D3D12SwapChain](D3D12SwapChain.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/D3D12SwapChain.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/D3D12SwapChain.md
index 6dd5702b..aaa053fc 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/D3D12SwapChain.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/D3D12SwapChain.md
@@ -6,35 +6,74 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12SwapChain.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12SwapChain` public API。
+**描述**: D3D12 后端的交换链封装，负责创建 DXGI swap chain，并把 back buffer 包装成 `D3D12Texture`。
 
-## 概述
+## 概览
 
-`D3D12SwapChain.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`D3D12SwapChain` 在当前引擎里的职责主要有两层:
 
-## 声明概览
+- 管理一个 `IDXGISwapChain3`
+- 把 swap chain 的 back buffer 接入统一的 `RHITexture` 世界
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12SwapChain` | `class` | 继承自 `RHISwapChain` 的公开声明。 |
+这使得上层渲染代码可以把窗口交换链 back buffer 当作普通纹理去创建 RTV、作为 framebuffer 附件使用。
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12SwapChain()](Constructor.md) | 构造对象。 |
-| [~D3D12SwapChain()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md) | 获取相关状态或对象。 |
-| [GetCurrentBackBuffer](GetCurrentBackBuffer.md) | 获取相关状态或对象。 |
-| [GetBackBuffer](GetBackBuffer.md) | 获取相关状态或对象。 |
-| [GetNativeCommandQueue](GetNativeCommandQueue.md) | 获取相关状态或对象。 |
-| [Present](Present.md) | 公开方法，详见头文件声明。 |
-| [Resize](Resize.md) | 公开方法，详见头文件声明。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
+当前实现更偏“先把最基本的呈现路径接起来”，而不是完整的商业级 swap chain 生命周期管理系统。
+
+它能做的事:
+
+- 创建或包装 swap chain
+- 返回当前 back buffer
+- 执行 Present
+
+它当前明显没做好的事也很多:
+
+- resize 后的 back buffer 重建
+- 中间失败时的资源回滚
+- back buffer 包装引用管理
+
+这些问题文档必须明确写出来。
+
+## 生命周期
+
+- 构造后为空对象。
+- [Initialize](Initialize.md) 成功后持有 `IDXGISwapChain3`，并缓存若干 `D3D12Texture` back buffer 包装对象。
+- [Shutdown](Shutdown.md) 当前只释放 swap chain 本身。
+- 析构时自动调用 `Shutdown()`。
+
+## 线程语义
+
+- 当前封装没有锁。
+- 一般应把它视为渲染主线程或呈现线程拥有的对象。
+
+## 当前实现的真实行为
+
+- `Initialize(factory, queue, hwnd, ...)` 使用的是 `IDXGIFactory4::CreateSwapChain()` + 旧式 `DXGI_SWAP_CHAIN_DESC` 路径，而不是 `CreateSwapChainForHwnd()`。
+- back buffer 格式固定为 `DXGI_FORMAT_R8G8B8A8_UNORM`，采样固定为 `1x`。
+- 两个初始化重载都会通过 `GetBuffer()` 把 back buffer 包装为 `D3D12Texture`。
+- `Resize()` 只调用 `ResizeBuffers()` 并更新宽高，不会重新获取新的 back buffer 资源。
+- `Shutdown()` 只 `Reset()` swap chain，不会清空 back buffer 包装数组和命令队列引用。
+
+## 当前限制
+
+- 初始化时通过 `GetBuffer(raw*) -> InitializeFromExisting(raw*)` 包装 back buffer，但当前实现没有对临时 `raw*` 做显式 `Release()`，会留下额外引用。
+- `Resize()` 后 `m_backBuffers` 仍指向旧资源包装，逻辑上已经过期。
+- `Initialize(IDXGISwapChain*, width, height)` 不会同步 `m_commandQueue`，也不会查询真实 buffer count。
+- 多个方法没有对 `m_swapChain` 做空指针保护。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
+- [GetBackBuffer](GetBackBuffer.md)
+- [Present](Present.md)
+- [Resize](Resize.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12Texture](../D3D12Texture/D3D12Texture.md)
+- [D3D12Device](../D3D12Device/D3D12Device.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Destructor.md
index 0bd1d04a..81477b49 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Destructor.md
@@ -1,29 +1,18 @@
-# D3D12SwapChain::~D3D12SwapChain()
-
-销毁对象并释放相关资源。
+# D3D12SwapChain::~D3D12SwapChain
 
 ```cpp
 ~D3D12SwapChain() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁交换链对象并释放其内部资源引用。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
-
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetBackBuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetBackBuffer.md
index 40d2d8f4..c7eec569 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetBackBuffer.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetBackBuffer.md
@@ -1,44 +1,29 @@
 # D3D12SwapChain::GetBackBuffer
 
-获取相关状态或对象。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12SwapChain.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
 D3D12Texture& GetBackBuffer(uint32_t index);
-```
-
-**参数：**
-- `index` - 参数语义详见头文件声明。
-
-**返回：** `D3D12Texture&` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 const D3D12Texture& GetBackBuffer(uint32_t index) const;
 ```
 
-**参数：**
-- `index` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `const D3D12Texture&` - 返回值语义详见头文件声明。
+按索引返回指定的 back buffer 包装对象。
 
-**示例：**
+## 参数说明
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
+- `index`: back buffer 索引。
 
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::GetBackBuffer(...)。
-    (void)object;
-}
-```
+## 当前实现行为
+
+- 使用 `assert(index < m_backBuffers.size())` 做范围检查。
+- 检查通过后直接返回 `m_backBuffers[index]`。
+
+## 重要限制
+
+- 这是调试断言，不是发布版错误处理。
+- 如果在 [Resize](Resize.md) 之后仍直接访问旧缓存，这里拿到的可能是逻辑上已经失效的旧资源包装。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
+- [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBuffer.md
index 4090ba33..b1e709cc 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBuffer.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBuffer.md
@@ -1,30 +1,20 @@
 # D3D12SwapChain::GetCurrentBackBuffer
 
-获取相关状态或对象。
-
 ```cpp
 RHITexture* GetCurrentBackBuffer() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前交换链活动 back buffer 的统一 `RHITexture` 视图。
 
-**返回：** `RHITexture*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
-
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::GetCurrentBackBuffer(...)。
-    (void)object;
-}
-```
+- 先调用 [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)。
+- 再调用 [GetBackBuffer](GetBackBuffer.md) 返回对应 `D3D12Texture`。
+- 最终以 `RHITexture*` 形式返回该对象地址。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)
+- [GetBackBuffer](GetBackBuffer.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBufferIndex.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBufferIndex.md
index 23143f4f..952ab0c4 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBufferIndex.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetCurrentBackBufferIndex.md
@@ -1,30 +1,19 @@
 # D3D12SwapChain::GetCurrentBackBufferIndex
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetCurrentBackBufferIndex() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 DXGI 当前认为活动的 back buffer 索引。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
-
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::GetCurrentBackBufferIndex(...)。
-    (void)object;
-}
-```
+- 直接调用 `m_swapChain->GetCurrentBackBufferIndex()`。
+- 没有空指针保护。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
+- [Present](Present.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeCommandQueue.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeCommandQueue.md
index 0ea5e0ea..415801b4 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeCommandQueue.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeCommandQueue.md
@@ -1,30 +1,19 @@
 # D3D12SwapChain::GetNativeCommandQueue
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12CommandQueue* GetNativeCommandQueue() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回与该交换链关联的原生命令队列。
 
-**返回：** `ID3D12CommandQueue*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
-
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::GetNativeCommandQueue(...)。
-    (void)object;
-}
-```
+- 通过 `Initialize(factory, queue, ...)` 路径成功初始化后返回有效队列。
+- 通过 `Initialize(IDXGISwapChain*, width, height)` 路径初始化时，当前实现不会写入 `m_commandQueue`，因此这里通常返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeHandle.md
index c1be9dfb..a1fb537d 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/GetNativeHandle.md
@@ -1,30 +1,18 @@
 # D3D12SwapChain::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以统一接口形式暴露底层 `IDXGISwapChain3*`。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
-
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 返回 `m_swapChain.Get()` 转换后的 `void*`。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeCommandQueue](GetNativeCommandQueue.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Initialize.md
index 49c7be38..60b50a1b 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Initialize.md
@@ -1,51 +1,63 @@
 # D3D12SwapChain::Initialize
 
-初始化内部状态。
-
-该方法在 `XCEngine/RHI/D3D12/D3D12SwapChain.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
-
 ```cpp
-bool Initialize(IDXGIFactory4* factory, ID3D12CommandQueue* commandQueue, HWND windowHandle, uint32_t width, uint32_t height, uint32_t bufferCount = 2);
-```
+bool Initialize(
+    IDXGIFactory4* factory,
+    ID3D12CommandQueue* commandQueue,
+    HWND windowHandle,
+    uint32_t width,
+    uint32_t height,
+    uint32_t bufferCount = 2);
 
-**参数：**
-- `factory` - 参数语义详见头文件声明。
-- `commandQueue` - 参数语义详见头文件声明。
-- `windowHandle` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
-- `bufferCount` - 参数语义详见头文件声明。
-
-**返回：** `bool` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool Initialize(IDXGISwapChain* swapChain, uint32_t width, uint32_t height);
 ```
 
-**参数：**
-- `swapChain` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
+## 作用
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+创建或包装一个 DXGI swap chain，并缓存其 back buffer 纹理包装对象。
 
-**示例：**
+## 参数说明
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
+- `factory`: DXGI factory。
+- `commandQueue`: 呈现队列。
+- `windowHandle`: 输出窗口句柄。
+- `width` / `height`: 交换链尺寸。
+- `bufferCount`: back buffer 数量。
+- `swapChain`: 已存在的原生 DXGI swap chain。
 
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::Initialize(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 初始化成功返回 `true`。
+- DXGI 创建或 `QueryInterface` 失败时返回 `false`。
+
+## 当前实现行为
+
+### `Initialize(factory, commandQueue, windowHandle, width, height, bufferCount)`
+
+- 构造旧式 `DXGI_SWAP_CHAIN_DESC`:
+  - 格式固定 `DXGI_FORMAT_R8G8B8A8_UNORM`
+  - `DXGI_SWAP_EFFECT_FLIP_DISCARD`
+  - `SampleDesc.Count = 1`
+  - `Windowed = TRUE`
+- 调用 `factory->CreateSwapChain(commandQueue, ...)`。
+- 再通过 `QueryInterface` 转成 `IDXGISwapChain3`。
+- 缓存 `m_commandQueue`、宽高和 `m_bufferCount`。
+- `resize(m_backBuffers, m_bufferCount)` 后逐个 `GetBuffer()`，再用 `D3D12Texture::InitializeFromExisting(resource, false)` 包装。
+
+### `Initialize(IDXGISwapChain* swapChain, uint32_t width, uint32_t height)`
+
+- 只做 `QueryInterface` 到 `IDXGISwapChain3`。
+- 缓存宽高。
+- 使用当前已有的 `m_bufferCount` 值去 `resize(m_backBuffers)`，默认通常仍是 `2`。
+- 然后同样逐个 `GetBuffer()` 包装 back buffer。
+
+## 重要限制
+
+- 两个重载当前都没有对通过 `GetBuffer()` 获得的临时 `ID3D12Resource*` 做显式 `Release()`。
+- 第二个重载不会查询真实 buffer count，也不会缓存命令队列。
+- 初始化失败时不会立刻回滚前面已经成功创建或获取的对象。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [GetBackBuffer](GetBackBuffer.md)
+- [Resize](Resize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Present.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Present.md
index 82971e13..b4619297 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Present.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Present.md
@@ -1,32 +1,24 @@
 # D3D12SwapChain::Present
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Present(uint32_t syncInterval = 1, uint32_t flags = 0) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `syncInterval` - 参数语义详见头文件声明。
-- `flags` - 参数语义详见头文件声明。
+提交当前 back buffer 到显示系统。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `syncInterval`: DXGI 呈现同步间隔。
+- `flags`: DXGI 呈现标志。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::Present(...)。
-    (void)object;
-}
-```
+- 直接调用 `m_swapChain->Present(syncInterval, flags)`。
+- 不检查返回 `HRESULT`。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)
+- [Resize](Resize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Resize.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Resize.md
index 741ebfa4..b57d37ed 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Resize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Resize.md
@@ -1,32 +1,32 @@
 # D3D12SwapChain::Resize
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Resize(uint32_t width, uint32_t height) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
+调整交换链缓冲区尺寸。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `width` / `height`: 新尺寸。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::Resize(...)。
-    (void)object;
-}
-```
+- 直接调用 `m_swapChain->ResizeBuffers(m_bufferCount, width, height, DXGI_FORMAT_R8G8B8A8_UNORM, 0)`。
+- 然后更新 `m_width` 和 `m_height`。
+
+## 重要限制
+
+- 当前实现不会释放并重新获取新的 back buffer 资源。
+- `m_backBuffers` 因此仍然保留 resize 前的旧 `D3D12Texture` 包装，逻辑上已经过期。
+
+## 使用建议
+
+- 在当前代码状态下，resize 后如果上层仍继续使用旧 back buffer 包装和对应 RTV，存在明显风险。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Shutdown.md
index e962dd7c..10739e57 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12SwapChain/Shutdown.md
@@ -1,30 +1,29 @@
 # D3D12SwapChain::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12SwapChain.h`，当前页面用于固定 `D3D12SwapChain` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放底层 DXGI swap chain 引用。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 仅调用 `m_swapChain.Reset()`。
+- 不会清空:
+  - `m_commandQueue`
+  - `m_backBuffers`
+  - `m_width`
+  - `m_height`
+  - `m_bufferCount`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12SwapChain object;
-    // 根据上下文补齐参数后调用 D3D12SwapChain::Shutdown(...)。
-    (void)object;
-}
-```
+- `Shutdown()` 后不应再访问 [GetCurrentBackBuffer](GetCurrentBackBuffer.md) 或 [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)。
+- 当前 back buffer 包装数组仍会保留旧对象，需要调用方注意生命周期边界。
 
 ## 相关文档
 
-- [返回类总览](D3D12SwapChain.md)
-- [返回模块目录](../D3D12.md)
+- [Destructor](Destructor.md)
+- [GetBackBuffer](GetBackBuffer.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index 751db62f..507b97c1 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-27 23:56:05`
+**生成时间**: `2026-03-28 00:08:45`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`