From cd756ec9a3c662cc3bfb99d73a3c6a8212b97e92 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Sat, 28 Mar 2026 00:25:34 +0800
Subject: [PATCH] docs(api): refine D3D12 render pass and framebuffer docs

---
 .../RHI/D3D12/D3D12Framebuffer/Constructor.md | 28 +++---
 .../D3D12Framebuffer/D3D12Framebuffer.md      | 98 ++++++++++++++-----
 .../RHI/D3D12/D3D12Framebuffer/Destructor.md  | 27 ++---
 .../D3D12Framebuffer/GetDepthStencilHandle.md | 25 ++---
 .../RHI/D3D12/D3D12Framebuffer/GetHeight.md   | 25 ++---
 .../D3D12/D3D12Framebuffer/GetNativeHandle.md | 29 +++---
 .../D3D12/D3D12Framebuffer/GetRenderPass.md   | 25 ++---
 .../D3D12Framebuffer/GetRenderTargetCount.md  | 25 ++---
 .../D3D12Framebuffer/GetRenderTargetHandle.md | 26 ++---
 .../GetRenderTargetHandles.md                 | 30 +++---
 .../RHI/D3D12/D3D12Framebuffer/GetWidth.md    | 25 ++---
 .../D3D12/D3D12Framebuffer/HasDepthStencil.md | 24 ++---
 .../RHI/D3D12/D3D12Framebuffer/Initialize.md  | 57 ++++++-----
 .../RHI/D3D12/D3D12Framebuffer/IsValid.md     | 29 +++---
 .../RHI/D3D12/D3D12Framebuffer/Shutdown.md    | 28 +++---
 .../RHI/D3D12/D3D12RenderPass/Constructor.md  | 26 ++---
 .../D3D12/D3D12RenderPass/D3D12RenderPass.md  | 90 ++++++++++++-----
 .../RHI/D3D12/D3D12RenderPass/Destructor.md   | 26 ++---
 .../D3D12RenderPass/GetBeginningAccessType.md | 28 +++---
 .../GetColorAttachmentCount.md                | 24 ++---
 .../D3D12RenderPass/GetColorAttachments.md    | 25 ++---
 .../GetDepthBeginningAccessType.md            | 27 +++--
 .../GetDepthEndingAccessType.md               | 27 +++--
 .../GetDepthStencilAttachment.md              | 25 ++---
 .../D3D12RenderPass/GetEndingAccessType.md    | 30 +++---
 .../D3D12/D3D12RenderPass/GetNativeHandle.md  | 24 ++---
 .../RHI/D3D12/D3D12RenderPass/Initialize.md   | 42 ++++----
 .../RHI/D3D12/D3D12RenderPass/Shutdown.md     | 26 ++---
 docs/api/_meta/rebuild-status.md              |  2 +-
 29 files changed, 432 insertions(+), 491 deletions(-)

diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Constructor.md
index 6624d599..03a59923 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Constructor.md
@@ -1,28 +1,26 @@
-# D3D12Framebuffer::D3D12Framebuffer()
-
-构造对象。
+# D3D12Framebuffer::D3D12Framebuffer
 
 ```cpp
 D3D12Framebuffer();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 framebuffer 包装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 构造函数体为空
+- 宽高保持类内默认值 `0`
+- `m_renderPass` 为 `nullptr`
+- render target handle 数组为空
+- depth-stencil handle 为零值
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 使用说明
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-}
-```
+这个对象在构造后还不具备可用渲染语义，通常需要立即进入 [Initialize](Initialize.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [D3D12Framebuffer](D3D12Framebuffer.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/D3D12Framebuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/D3D12Framebuffer.md
index 2d29bd95..3f142419 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/D3D12Framebuffer.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/D3D12Framebuffer.md
@@ -6,38 +6,84 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12Framebuffer.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Framebuffer` public API。
+**描述**: D3D12 后端的 framebuffer 抽象，但当前实现并不对应某个原生 D3D12 对象，而是一个“渲染目标句柄与尺寸打包器”。
 
-## 概述
+## 概览
 
-`D3D12Framebuffer.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+在 Vulkan 里，framebuffer 往往是真实的 API 对象；在 D3D12 里，并不存在等价的 `ID3D12Framebuffer`。
 
-## 声明概览
+因此当前 `D3D12Framebuffer` 的职责非常具体：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12Framebuffer` | `class` | 继承自 `RHIFramebuffer` 的公开声明。 |
+- 保存一组 color RTV 的 `D3D12_CPU_DESCRIPTOR_HANDLE`
+- 可选保存一个 depth-stencil DSV 的 `D3D12_CPU_DESCRIPTOR_HANDLE`
+- 缓存宽高和关联的 [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
 
-## 公共方法
+这使得 [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 在 `BeginRenderPass(...)` 时可以一次性拿到渲染目标集合，而不需要每次都重新从视图对象中拆句柄。
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12Framebuffer()](Constructor.md) | 构造对象。 |
-| [~D3D12Framebuffer()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
-| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
-| [IsValid](IsValid.md) | 查询当前状态。 |
-| [GetRenderTargetHandle](GetRenderTargetHandle.md) | 获取相关状态或对象。 |
-| [GetDepthStencilHandle](GetDepthStencilHandle.md) | 获取相关状态或对象。 |
-| [HasDepthStencil](HasDepthStencil.md) | 判断是否具备指定状态或能力。 |
-| [GetRenderTargetCount](GetRenderTargetCount.md) | 获取相关状态或对象。 |
-| [GetRenderTargetHandles](GetRenderTargetHandles.md) | 获取相关状态或对象。 |
-| [GetRenderPass](GetRenderPass.md) | 获取相关状态或对象。 |
+## 设计定位
+
+这个类更像引擎内部的“渲染附件绑定描述”。
+
+它当前不做这些事情：
+
+- 不创建原生 D3D12 framebuffer 对象
+- 不拥有纹理或资源视图生命周期
+- 不验证 render pass 与附件之间的格式兼容性
+- 不处理附件 resize、重建或状态迁移
+
+从商业级引擎设计角度看，这种抽象是合理的。因为 D3D12 本来就把渲染目标绑定拆成了 RTV/DSV descriptor 组合，framebuffer 更多是引擎为了统一 RHI 心智模型而引入的组织层。
+
+## 生命周期
+
+- 构造后是空对象
+- [Initialize](Initialize.md) 会缓存 render pass、尺寸和 CPU descriptor handle
+- [Shutdown](Shutdown.md) 清空句柄数组并复位尺寸、render pass 指针
+- 析构时自动调用 [Shutdown](Shutdown.md)
+
+## 当前实现的真实行为
+
+- [GetNativeHandle](GetNativeHandle.md) 永远返回 `nullptr`
+- [Initialize](Initialize.md) 不做严格校验，基本只是把传入句柄抄进内部数组
+- 如果某个 `colorAttachments[i]` 为 `nullptr`，对应 handle 会保持为零值
+- [IsValid](IsValid.md) 只检查 `m_renderPass != nullptr`
+- [HasDepthStencil](HasDepthStencil.md) 只检查 `m_depthStencilHandle.ptr != 0`
+- 对象不拥有 `RHIResourceView` 和 `D3D12RenderPass`，只是保存非 owning 引用或复制后的 handle
+
+## 为什么这样设计
+
+这类设计的价值在于把“API 没有对象，但引擎需要概念”的空白补上。
+
+它带来的好处是：
+
+- 上层 RHI 能继续使用 framebuffer / render pass 这组熟悉抽象
+- D3D12 命令列表实现可以更整洁，不必每次重新拆附件参数
+- 文档和测试可以围绕统一概念展开，跨 Vulkan / D3D12 对照时也更容易理解
+
+它的代价同样明显：
+
+- 这是一个纯引擎侧约定对象，不是驱动层面的强校验边界
+- 很多兼容性问题不会在创建时暴露，而是等到真正渲染时才出问题
+
+## 当前限制
+
+- `colorAttachmentCount > 0` 且 `colorAttachments == nullptr` 时，当前实现会直接解引用空指针
+- 不检查 `colorAttachmentCount` 是否与 render pass 的 color attachment 数量匹配
+- 不检查 depth-stencil 附件是否与 render pass 需求匹配
+- 不检查宽高是否为 0，测试里也允许 0 尺寸对象存在
+- `GetRenderTargetHandles()` 返回的是内部数组指针，调用方需要自己配合 `GetRenderTargetCount()` 使用
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [GetRenderTargetHandle](GetRenderTargetHandle.md)
+- [GetRenderTargetHandles](GetRenderTargetHandles.md)
+- [GetDepthStencilHandle](GetDepthStencilHandle.md)
+- [HasDepthStencil](HasDepthStencil.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
+- [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md)
+- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Destructor.md
index afab6afe..d13fdae6 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Destructor.md
@@ -1,29 +1,20 @@
-# D3D12Framebuffer::~D3D12Framebuffer()
-
-销毁对象并释放相关资源。
+# D3D12Framebuffer::~D3D12Framebuffer
 
 ```cpp
 ~D3D12Framebuffer() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 framebuffer 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数直接调用 [Shutdown](Shutdown.md)
+- 不销毁任何原生 D3D12 对象，因为当前类没有持有这类对象
+- 不负责释放 render pass、纹理或资源视图
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [D3D12Framebuffer](D3D12Framebuffer.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetDepthStencilHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetDepthStencilHandle.md
index 8bddb36f..29cc4395 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetDepthStencilHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetDepthStencilHandle.md
@@ -1,30 +1,23 @@
 # D3D12Framebuffer::GetDepthStencilHandle
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_CPU_DESCRIPTOR_HANDLE GetDepthStencilHandle() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前缓存的 depth-stencil CPU descriptor handle。
 
-**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_depthStencilHandle`
+- 如果没有 depth-stencil 附件，返回零值 handle
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetDepthStencilHandle(...)。
-    (void)object;
-}
-```
+通常应先用 [HasDepthStencil](HasDepthStencil.md) 判断是否存在有效 DSV，再决定是否把这个 handle 传入 `OMSetRenderTargets(...)`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [HasDepthStencil](HasDepthStencil.md)
+- [GetRenderTargetHandles](GetRenderTargetHandles.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetHeight.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetHeight.md
index ae1fdb37..355ca7d0 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetHeight.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetHeight.md
@@ -1,30 +1,23 @@
 # D3D12Framebuffer::GetHeight
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetHeight() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 framebuffer 当前缓存的高度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_height`
+- 不从附件纹理重新查询真实尺寸
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetHeight(...)。
-    (void)object;
-}
-```
+和 [GetWidth](GetWidth.md) 一样，这个值只是初始化时写入的元数据，不是后端校验过的真实附件高度。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetWidth](GetWidth.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetNativeHandle.md
index 6a804ede..be2d476a 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetNativeHandle.md
@@ -1,30 +1,27 @@
 # D3D12Framebuffer::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 framebuffer 的原生句柄表示。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 始终返回 `nullptr`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetNativeHandle(...)。
-    (void)object;
-}
-```
+这正好反映了 D3D12 的现实情况：当前抽象没有对应的原生 framebuffer 句柄可返回。
+
+如果你需要的是真正参与绑定的底层数据，应使用：
+
+- [GetRenderTargetHandles](GetRenderTargetHandles.md)
+- [GetDepthStencilHandle](GetDepthStencilHandle.md)
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetRenderTargetHandles](GetRenderTargetHandles.md)
+- [GetDepthStencilHandle](GetDepthStencilHandle.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderPass.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderPass.md
index 95b85e9a..08dc4e6d 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderPass.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderPass.md
@@ -1,30 +1,23 @@
 # D3D12Framebuffer::GetRenderPass
 
-获取相关状态或对象。
-
 ```cpp
 D3D12RenderPass* GetRenderPass() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回与当前 framebuffer 关联的 render pass 指针。
 
-**返回：** `D3D12RenderPass*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回缓存的 `m_renderPass`
+- 这是一个非 owning 指针
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderPass(...)。
-    (void)object;
-}
-```
+当前 `D3D12CommandList::BeginRenderPass(...)` 仍然显式接收 `renderPass` 参数，因此这里的 getter 更多是调试和元数据访问用途，而不是唯一的数据来源。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [IsValid](IsValid.md)
+- [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetCount.md
index 62f7b6ad..420a4003 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetCount.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetCount.md
@@ -1,30 +1,19 @@
 # D3D12Framebuffer::GetRenderTargetCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetRenderTargetCount() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前缓存的颜色附件数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderTargetCount(...)。
-    (void)object;
-}
-```
+- 返回 `m_renderTargetHandles.size()`
+- 这个数量来自 [Initialize](Initialize.md) 传入的 `colorAttachmentCount`
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetRenderTargetHandle](GetRenderTargetHandle.md)
+- [GetRenderTargetHandles](GetRenderTargetHandles.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandle.md
index 2175585c..cb6b9e3a 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandle.md
@@ -1,31 +1,23 @@
 # D3D12Framebuffer::GetRenderTargetHandle
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_CPU_DESCRIPTOR_HANDLE GetRenderTargetHandle(uint32_t index) const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `index` - 参数语义详见头文件声明。
+返回指定颜色附件的 CPU descriptor handle。
 
-**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `index` 越界，返回零值 handle
+- 否则返回 `m_renderTargetHandles[index]`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderTargetHandle(...)。
-    (void)object;
-}
-```
+如果你要遍历全部 RTV，优先搭配 [GetRenderTargetCount](GetRenderTargetCount.md) 使用，避免依赖零值返回做流程控制。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetRenderTargetCount](GetRenderTargetCount.md)
+- [GetRenderTargetHandles](GetRenderTargetHandles.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandles.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandles.md
index f69a08eb..f64ea8f5 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandles.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetRenderTargetHandles.md
@@ -1,30 +1,28 @@
 # D3D12Framebuffer::GetRenderTargetHandles
 
-获取相关状态或对象。
-
 ```cpp
 const D3D12_CPU_DESCRIPTOR_HANDLE* GetRenderTargetHandles() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回内部 color RTV handle 数组的起始指针。
 
-**返回：** `const D3D12_CPU_DESCRIPTOR_HANDLE*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_renderTargetHandles.data()`
+- 不复制数据
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderTargetHandles(...)。
-    (void)object;
-}
-```
+- 必须配合 [GetRenderTargetCount](GetRenderTargetCount.md) 使用
+- 不要在 [Shutdown](Shutdown.md) 之后继续持有这个指针
+
+## 注意事项
+
+如果数组为空，`data()` 的返回值不应被解引用。调用方必须先看数量。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetRenderTargetCount](GetRenderTargetCount.md)
+- [GetRenderTargetHandle](GetRenderTargetHandle.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetWidth.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetWidth.md
index 114bf2bf..5bb3676b 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetWidth.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/GetWidth.md
@@ -1,30 +1,23 @@
 # D3D12Framebuffer::GetWidth
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetWidth() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 framebuffer 当前缓存的宽度。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_width`
+- 不从附件纹理重新查询真实尺寸
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::GetWidth(...)。
-    (void)object;
-}
-```
+这个值完全来自 [Initialize](Initialize.md) 的传参。即使附件本身尺寸不同，这里也不会自动纠正。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetHeight](GetHeight.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/HasDepthStencil.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/HasDepthStencil.md
index fadb135b..24bc65fc 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/HasDepthStencil.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/HasDepthStencil.md
@@ -1,30 +1,22 @@
 # D3D12Framebuffer::HasDepthStencil
 
-判断是否具备指定状态或能力。
-
 ```cpp
 bool HasDepthStencil() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前 framebuffer 是否缓存了非零的 depth-stencil handle。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 判断条件是 `m_depthStencilHandle.ptr != 0`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::HasDepthStencil(...)。
-    (void)object;
-}
-```
+它不检查这个 handle 是否真的仍然有效，也不检查它是否与 render pass 描述兼容。它只是一个非常轻量的“是否存在非零句柄”判断。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetDepthStencilHandle](GetDepthStencilHandle.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Initialize.md
index ac5d27de..c1c337bf 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Initialize.md
@@ -1,36 +1,47 @@
 # D3D12Framebuffer::Initialize
 
-初始化内部状态。
-
 ```cpp
-bool Initialize(class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) override;
+bool Initialize(RHIRenderPass* renderPass,
+                uint32_t width,
+                uint32_t height,
+                uint32_t colorAttachmentCount,
+                RHIResourceView** colorAttachments,
+                RHIResourceView* depthStencilAttachment) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `renderPass` - 参数语义详见头文件声明。
-- `width` - 参数语义详见头文件声明。
-- `height` - 参数语义详见头文件声明。
-- `colorAttachmentCount` - 参数语义详见头文件声明。
-- `colorAttachments` - 参数语义详见头文件声明。
-- `depthStencilAttachment` - 参数语义详见头文件声明。
+把 render pass、尺寸和资源视图对应的 CPU descriptor handle 组织成一个可供 D3D12 命令列表使用的 framebuffer 对象。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 把 `renderPass` 直接 `static_cast` 成 `D3D12RenderPass*` 并缓存到 `m_renderPass`
+- 缓存 `width` 和 `height`
+- 按 `colorAttachmentCount` 调整 `m_renderTargetHandles` 大小
+- 对每个非空 `colorAttachments[i]`，取出 [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md) 的 CPU handle 存入数组
+- 如果 `depthStencilAttachment` 非空，则缓存它的 CPU handle；否则把 depth-stencil handle 置零
+- 始终返回 `true`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 重要事实
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::Initialize(...)。
-    (void)object;
-}
-```
+这个初始化过程没有创建任何 D3D12 资源，也没有把任何对象注册到驱动层。它只是把“后续 `OMSetRenderTargets(...)` 需要的句柄集合”提前整理好。
+
+## 当前限制
+
+- 不检查 `renderPass` 是否为空
+- 不检查 `colorAttachmentCount` 与 render pass 描述是否匹配
+- 不检查 `colorAttachments` 是否为空；如果 `colorAttachmentCount > 0` 且它是空指针，会发生非法访问
+- 不检查 view 类型是否真的是 RTV / DSV
+- 不检查附件尺寸、格式、采样数是否兼容
+
+## 使用建议
+
+- 常规路径应通过 [D3D12Device](../D3D12Device/D3D12Device.md) 的 `CreateFramebuffer()` 创建
+- 不要把这里的成功返回值当成“附件组合已通过后端校验”
+- 如果需要严格兼容性约束，应在更高层或未来的创建逻辑中补验证
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetRenderTargetHandle](GetRenderTargetHandle.md)
+- [GetDepthStencilHandle](GetDepthStencilHandle.md)
+- [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/IsValid.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/IsValid.md
index f131ad0d..cc23e013 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/IsValid.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/IsValid.md
@@ -1,30 +1,27 @@
 # D3D12Framebuffer::IsValid
 
-查询当前状态。
-
 ```cpp
 bool IsValid() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断 framebuffer 当前是否被视为“有效”。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 只检查 `m_renderPass != nullptr`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 这意味着什么
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::IsValid(...)。
-    (void)object;
-}
-```
+这个判定非常宽松。下面这些问题都不会让它返回 `false`：
+
+- 宽高是 `0`
+- 某些 render target handle 仍然是零值
+- depth-stencil 缺失或不匹配
+- render pass 与附件格式不兼容
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetRenderPass](GetRenderPass.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Shutdown.md
index dc3e5242..d6c2be6b 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Framebuffer/Shutdown.md
@@ -1,30 +1,26 @@
 # D3D12Framebuffer::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清空 framebuffer 内部缓存的句柄与元数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 清空 `m_renderTargetHandles`
+- 把 `m_depthStencilHandle` 复位为零值
+- 把 `m_renderPass` 设为 `nullptr`
+- 把 `m_width` 和 `m_height` 设为 `0`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::D3D12Framebuffer object;
-    // 根据上下文补齐参数后调用 D3D12Framebuffer::Shutdown(...)。
-    (void)object;
-}
-```
+因为当前类不拥有底层资源，所以 `Shutdown()` 的职责只是“忘掉这些句柄和关联关系”，而不是回收 GPU 对象。
 
 ## 相关文档
 
-- [返回类总览](D3D12Framebuffer.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [IsValid](IsValid.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Constructor.md
index f4fc35de..e72c1747 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Constructor.md
@@ -1,28 +1,20 @@
-# D3D12RenderPass::D3D12RenderPass()
-
-构造对象。
+# D3D12RenderPass::D3D12RenderPass
 
 ```cpp
 D3D12RenderPass();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 render pass 元数据对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
-
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-}
-```
+- 构造函数体为空
+- color attachment 数量默认为 `0`
+- depth-stencil 标志默认为 `false`
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [D3D12RenderPass](D3D12RenderPass.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/D3D12RenderPass.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/D3D12RenderPass.md
index 24676baa..6ab9731a 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/D3D12RenderPass.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/D3D12RenderPass.md
@@ -6,36 +6,78 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12RenderPass.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12RenderPass` public API。
+**描述**: D3D12 后端的 render pass 元数据对象，用于保存 `AttachmentDesc` 并把 RHI 的 load/store 语义映射为 D3D12 access type。
 
-## 概述
+## 概览
 
-`D3D12RenderPass.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+和 [D3D12Framebuffer](../D3D12Framebuffer/D3D12Framebuffer.md) 一样，`D3D12RenderPass` 不是原生 D3D12 对象。
 
-## 声明概览
+它当前承担的核心职责是：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12RenderPass` | `class` | 继承自 `RHIRenderPass` 的公开声明。 |
+- 缓存 color attachment 与 depth-stencil attachment 描述
+- 为上层 RHI 保留“render pass”这一统一概念
+- 提供若干把 `LoadAction` / `StoreAction` 翻译成 `D3D12_RENDER_PASS_*_ACCESS_TYPE` 的辅助接口
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12RenderPass()](Constructor.md) | 构造对象。 |
-| [~D3D12RenderPass()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [GetColorAttachmentCount](GetColorAttachmentCount.md) | 获取相关状态或对象。 |
-| [GetColorAttachments](GetColorAttachments.md) | 获取相关状态或对象。 |
-| [GetDepthStencilAttachment](GetDepthStencilAttachment.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetBeginningAccessType](GetBeginningAccessType.md) | 获取相关状态或对象。 |
-| [GetEndingAccessType](GetEndingAccessType.md) | 获取相关状态或对象。 |
-| [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md) | 获取相关状态或对象。 |
-| [GetDepthEndingAccessType](GetDepthEndingAccessType.md) | 获取相关状态或对象。 |
+在 D3D12 中，渲染过程可以用传统 `OMSetRenderTargets(...) + Clear*View(...)` 路径完成，也可以逐步接近更显式的 render pass 访问语义。
+
+当前 XCEngine 选的是一个折中方案：
+
+- 保留 render pass 抽象，方便跨后端统一
+- 先把 attachment 元数据和访问语义整理出来
+- 但命令列表实现目前仍主要依赖手动 clear 和 `OMSetRenderTargets(...)`
+
+也就是说，`D3D12RenderPass` 目前更接近“元数据和策略对象”，而不是“驱动层 render pass 实例”。
+
+## 生命周期
+
+- 构造后为空对象
+- [Initialize](Initialize.md) 复制 attachment 描述
+- [Shutdown](Shutdown.md) 清空颜色附件并复位主要状态
+- 析构时自动调用 [Shutdown](Shutdown.md)
+
+## 当前实现的真实行为
+
+- [GetNativeHandle](GetNativeHandle.md) 永远返回 `nullptr`
+- [Initialize](Initialize.md) 不做输入合法性校验，基本只是复制描述
+- [GetBeginningAccessType](GetBeginningAccessType.md) / [GetEndingAccessType](GetEndingAccessType.md) 提供的是“映射结果”，不是驱动对象状态
+- `StoreAction::Resolve` 和 `StoreAction::StoreAndResolve` 当前都会被映射成 `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE_RESOLVE`
+- 深度访问辅助函数只看 `loadOp` / `storeOp`，不会把 `stencilLoadOp` / `stencilStoreOp` 融入返回值
+- 当前 [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 的 `BeginRenderPass(...)` 并没有直接使用这些 access type getter，而是手动依据附件描述执行 clear
+
+## 为什么这样设计
+
+这是典型的引擎抽象先行路线。
+
+这么做的好处是：
+
+- RHI 层在 Vulkan、D3D12、OpenGL 之间可以共享相近的渲染通道心智模型
+- 后端可以逐步演进，而不是一开始就把 D3D12 特性全部绑定死在命令列表实现里
+- 文档和测试可以直接围绕 attachment/load/store 语义展开
+
+代价是当前对象的很多能力只是“描述能力”，而不是“执行能力”。调用者不能把这些 getter 理解成已经驱动 GPU 的状态。
+
+## 当前限制
+
+- `colorAttachmentCount > 0` 且 `colorAttachments == nullptr` 时会发生非法访问
+- 不验证格式是否合法或是否适合 D3D12 使用
+- 不生成原生 render pass 句柄
+- 深度 access helper 不表达 stencil 独立访问语义
+- ending access 的 `StoreAndResolve` 语义被简化为 `RESOLVE`
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [GetBeginningAccessType](GetBeginningAccessType.md)
+- [GetEndingAccessType](GetEndingAccessType.md)
+- [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md)
+- [GetDepthEndingAccessType](GetDepthEndingAccessType.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12Framebuffer](../D3D12Framebuffer/D3D12Framebuffer.md)
+- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
+- [RHIRenderPass](../../RHIRenderPass/RHIRenderPass.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Destructor.md
index 8453c1f8..7d002b0d 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Destructor.md
@@ -1,29 +1,19 @@
-# D3D12RenderPass::~D3D12RenderPass()
-
-销毁对象并释放相关资源。
+# D3D12RenderPass::~D3D12RenderPass
 
 ```cpp
 ~D3D12RenderPass() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 render pass 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
-
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部直接调用 [Shutdown](Shutdown.md)
+- 不释放任何原生 D3D12 句柄，因为当前类没有持有这类句柄
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [D3D12RenderPass](D3D12RenderPass.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetBeginningAccessType.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetBeginningAccessType.md
index c450c18e..132a2af6 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetBeginningAccessType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetBeginningAccessType.md
@@ -1,31 +1,25 @@
 # D3D12RenderPass::GetBeginningAccessType
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE GetBeginningAccessType(uint32_t index) const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `index` - 参数语义详见头文件声明。
+把指定 color attachment 的 `LoadAction` 映射为 D3D12 的 beginning access type。
 
-**返回：** `D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 越界时返回 `D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE_NO_ACCESS`
+- `LoadAction::Clear` 映射为 `CLEAR`
+- `LoadAction::Load` 映射为 `PRESERVE`
+- `LoadAction::Undefined` 以及默认分支映射为 `DISCARD`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetBeginningAccessType(...)。
-    (void)object;
-}
-```
+这个 getter 提供的是“描述映射结果”。当前命令列表实现并没有直接拿它去调用原生 D3D12 render pass API，而是自己根据附件描述执行清屏逻辑。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetEndingAccessType](GetEndingAccessType.md)
+- [GetColorAttachments](GetColorAttachments.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachmentCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachmentCount.md
index be9fffe5..f7884409 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachmentCount.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachmentCount.md
@@ -1,30 +1,18 @@
 # D3D12RenderPass::GetColorAttachmentCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetColorAttachmentCount() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 color attachment 数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
-
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetColorAttachmentCount(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_colorAttachmentCount`
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetColorAttachments](GetColorAttachments.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachments.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachments.md
index 8ed9f5e1..76c5db81 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachments.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetColorAttachments.md
@@ -1,30 +1,23 @@
 # D3D12RenderPass::GetColorAttachments
 
-获取相关状态或对象。
-
 ```cpp
 const AttachmentDesc* GetColorAttachments() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回内部 color attachment 描述数组的起始指针。
 
-**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_colorAttachments.data()`
+- 不复制数据
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetColorAttachments(...)。
-    (void)object;
-}
-```
+调用方应始终配合 [GetColorAttachmentCount](GetColorAttachmentCount.md) 使用，不要在数量为 `0` 时直接解引用这个指针。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetColorAttachmentCount](GetColorAttachmentCount.md)
+- [GetBeginningAccessType](GetBeginningAccessType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthBeginningAccessType.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthBeginningAccessType.md
index 36a9cdfe..c12b9257 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthBeginningAccessType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthBeginningAccessType.md
@@ -1,30 +1,25 @@
 # D3D12RenderPass::GetDepthBeginningAccessType
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE GetDepthBeginningAccessType() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把 depth-stencil attachment 的深度 `loadOp` 映射为 D3D12 的 beginning access type。
 
-**返回：** `D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果没有 depth-stencil attachment，返回 `NO_ACCESS`
+- `LoadAction::Clear` 映射为 `CLEAR`
+- `LoadAction::Load` 映射为 `PRESERVE`
+- `LoadAction::Undefined` 以及默认分支映射为 `DISCARD`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetDepthBeginningAccessType(...)。
-    (void)object;
-}
-```
+这个接口只看 `m_depthStencilAttachment.loadOp`，不会把 `stencilLoadOp` 合并进返回值。如果你需要理解 stencil 的清除行为，应直接查看原始 attachment 描述或命令列表实现。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetDepthEndingAccessType](GetDepthEndingAccessType.md)
+- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthEndingAccessType.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthEndingAccessType.md
index 4f38408c..7b3800f1 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthEndingAccessType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthEndingAccessType.md
@@ -1,30 +1,25 @@
 # D3D12RenderPass::GetDepthEndingAccessType
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_RENDER_PASS_ENDING_ACCESS_TYPE GetDepthEndingAccessType() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把 depth-stencil attachment 的深度 `storeOp` 映射为 D3D12 的 ending access type。
 
-**返回：** `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果没有 depth-stencil attachment，返回 `NO_ACCESS`
+- `StoreAction::Store` 映射为 `PRESERVE`
+- `StoreAction::Discard` 映射为 `DISCARD`
+- `StoreAction::Undefined` 以及默认分支映射为 `NO_ACCESS`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetDepthEndingAccessType(...)。
-    (void)object;
-}
-```
+和 [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md) 一样，这里只看深度 `storeOp`，不会把 `stencilStoreOp` 纳入返回值。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md)
+- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthStencilAttachment.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthStencilAttachment.md
index 0d06f9a7..ba0f933e 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthStencilAttachment.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetDepthStencilAttachment.md
@@ -1,30 +1,19 @@
 # D3D12RenderPass::GetDepthStencilAttachment
 
-获取相关状态或对象。
-
 ```cpp
 const AttachmentDesc* GetDepthStencilAttachment() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 depth-stencil attachment 描述。
 
-**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
-
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetDepthStencilAttachment(...)。
-    (void)object;
-}
-```
+- 如果 `m_hasDepthStencil` 为 `true`，返回 `&m_depthStencilAttachment`
+- 否则返回 `nullptr`
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md)
+- [GetDepthEndingAccessType](GetDepthEndingAccessType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetEndingAccessType.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetEndingAccessType.md
index 09cb0f38..fb6b1b94 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetEndingAccessType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetEndingAccessType.md
@@ -1,31 +1,27 @@
 # D3D12RenderPass::GetEndingAccessType
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_RENDER_PASS_ENDING_ACCESS_TYPE GetEndingAccessType(uint32_t index) const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `index` - 参数语义详见头文件声明。
+把指定 color attachment 的 `StoreAction` 映射为 D3D12 的 ending access type。
 
-**返回：** `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 越界时返回 `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE_NO_ACCESS`
+- `StoreAction::Store` 映射为 `PRESERVE`
+- `StoreAction::Discard` 映射为 `DISCARD`
+- `StoreAction::Resolve` 映射为 `RESOLVE`
+- `StoreAction::StoreAndResolve` 当前也映射为 `RESOLVE`
+- `StoreAction::Undefined` 以及默认分支映射为 `NO_ACCESS`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetEndingAccessType(...)。
-    (void)object;
-}
-```
+`StoreAndResolve` 在当前接口里丢失了“同时保留与 resolve”的细粒度语义，因为这里返回的只是 access type，而不是完整 resolve 参数结构。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetBeginningAccessType](GetBeginningAccessType.md)
+- [D3D12RenderPass](D3D12RenderPass.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetNativeHandle.md
index c560ad8a..c70ff8ee 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/GetNativeHandle.md
@@ -1,30 +1,22 @@
 # D3D12RenderPass::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 render pass 的原生句柄表示。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 始终返回 `nullptr`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::GetNativeHandle(...)。
-    (void)object;
-}
-```
+这说明当前 `D3D12RenderPass` 只是引擎元数据对象，不对应可返回的原生 D3D12 render pass 句柄。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [D3D12RenderPass](D3D12RenderPass.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Initialize.md
index b2389cf3..e6a7e449 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Initialize.md
@@ -1,33 +1,35 @@
 # D3D12RenderPass::Initialize
 
-初始化内部状态。
-
 ```cpp
-bool Initialize(uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) override;
+bool Initialize(uint32_t colorAttachmentCount,
+                const AttachmentDesc* colorAttachments,
+                const AttachmentDesc* depthStencilAttachment) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `colorAttachmentCount` - 参数语义详见头文件声明。
-- `colorAttachments` - 参数语义详见头文件声明。
-- `depthStencilAttachment` - 参数语义详见头文件声明。
+复制 render pass 所需的 attachment 描述。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 把 `colorAttachmentCount` 写入 `m_colorAttachmentCount`
+- 调整 `m_colorAttachments` 大小并逐项复制 `colorAttachments`
+- 如果 `depthStencilAttachment` 非空，则复制它并把 `m_hasDepthStencil` 设为 `true`
+- 如果 `depthStencilAttachment` 为空，则只把 `m_hasDepthStencil` 设为 `false`
+- 始终返回 `true`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 当前限制
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::Initialize(...)。
-    (void)object;
-}
-```
+- 不检查 `colorAttachments` 是否为空
+- 不检查格式、采样数或 load/store 组合是否合法
+- 不创建任何原生 D3D12 对象
+
+## 设计说明
+
+这一步本质上是“保存一份附件策略描述”。真正的 clear / bind 行为要到命令列表阶段才会发生。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [GetColorAttachments](GetColorAttachments.md)
+- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
+- [GetBeginningAccessType](GetBeginningAccessType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Shutdown.md
index 38e0bad3..3c4bab0d 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12RenderPass/Shutdown.md
@@ -1,30 +1,24 @@
 # D3D12RenderPass::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+清空 render pass 内部缓存的 attachment 描述。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 清空 `m_colorAttachments`
+- 把 `m_colorAttachmentCount` 设为 `0`
+- 把 `m_hasDepthStencil` 设为 `false`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12RenderPass object;
-    // 根据上下文补齐参数后调用 D3D12RenderPass::Shutdown(...)。
-    (void)object;
-}
-```
+当前实现没有显式把 `m_depthStencilAttachment` 复位为默认值，但由于 `m_hasDepthStencil` 会被清为 `false`，外部通过 [GetDepthStencilAttachment](GetDepthStencilAttachment.md) 已无法再访问这份旧描述。
 
 ## 相关文档
 
-- [返回类总览](D3D12RenderPass.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index bedc28e2..21136e59 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-28 00:17:57`
+**生成时间**: `2026-03-28 00:24:57`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`