docs(rendering): expand render pass foundation docs

docs/api/XCEngine/Rendering/RenderPass/RenderPass.md

@@ -8,34 +8,24 @@
 
 **描述**: 定义轻量通用 pass 抽象 `RenderPass`、执行上下文 `RenderPassContext` 以及顺序执行容器 `RenderPassSequence`。
 
-## 概览
+## 概述
 
 `RenderPass.h` 是当前渲染基础设施里最通用的一层 pass 协议。它统一回答三件事：
 
-- pass 执行时能拿到什么上下文
+- 一个 pass 执行时能拿到什么上下文。
-- 一个 pass 至少需要实现哪些生命周期函数
+- 一个 pass 至少需要实现哪些生命周期函数。
-- 多个 pass 如何按顺序组成一个小型执行序列
+- 多个 pass 如何按顺序组成一个小型执行序列。
 
 ## 当前定义
 
-### `RenderPassContext`
+- [RenderPassContext](RenderPassContext.md)
+  统一描述当前输出 `surface`、源颜色输入和共享 `sceneData`。
+- `RenderPass`
+  抽象基类，约定所有渲染 pass 的最小生命周期接口。
+- [RenderPassSequence](RenderPassSequence.md)
+  拥有型顺序容器，负责按固定顺序初始化、执行和关闭多个 pass。
 
-`RenderPassContext` 当前包含 6 个字段：
+`RenderPass` 抽象基类当前包含 4 个核心成员：
-
-| 字段 | 说明 |
-|------|------|
-| `renderContext` | 当前后端、设备与命令列表。 |
-| `surface` | 当前 pass 的输出目标 surface。 |
-| `sceneData` | 本帧已提取的场景数据。 |
-| `sourceSurface` | fullscreen / chained pass 的输入 surface；无上游输入时可为空。 |
-| `sourceColorView` | 上游传入的颜色输入视图；无上游输入时可为空。 |
-| `sourceColorState` | `sourceColorView` 当前约定的资源状态，供自动切换或校验使用。 |
-
-前向场景 pass 往往只使用 `renderContext`、`surface` 和 `sceneData`；fullscreen post-process / final-output 链路则会继续消费 `sourceSurface`、`sourceColorView` 与 `sourceColorState`。
-
-### `RenderPass`
-
-抽象基类包含 4 个核心成员：
 
 | 成员 | 当前语义 |
 |------|------|
@@ -44,42 +34,31 @@
 | `Execute()` | 纯虚函数，执行真正的 pass 逻辑。 |
 | `Shutdown()` | 默认空实现，释放 pass 资源。 |
 
-### `RenderPassSequence`
-
-`RenderPassSequence` 是一个拥有型容器，内部以 `std::unique_ptr<RenderPass>` 顺序保存 pass。
-
-当前行为是：
-
-- `AddPass()` 会忽略空指针。
-- `GetPassCount()` 返回当前持有的 pass 数量。
-- `Initialize()` 按插入顺序调用每个 pass 的 `Initialize()`。
-- `Execute()` 按插入顺序调用每个 pass 的 `Execute()`。
-- `Shutdown()` 按逆序调用每个 pass 的 `Shutdown()`。
-
 ## 失败与回滚语义
 
-- `Initialize()` 遇到失败会立刻返回 `false`。
+- `RenderPassSequence::Initialize()` 遇到失败会立刻返回 `false`。
-- `Execute()` 遇到失败也会立刻停止后续 pass。
+- `RenderPassSequence::Execute()` 遇到失败也会停止后续 pass。
 - `RenderPassSequence` 自身不会在 `Initialize()` 失败时自动回滚已经初始化过的 pass。
-
+- 更高层调用方，例如 `CameraRenderer`，会在 sequence 初始化失败时显式再做一次 `Shutdown()` 回滚。
-更高层调用方，例如 `CameraRenderer`，会在 sequence 初始化失败时显式再做一次 `Shutdown()` 回滚。
 
 ## 测试与真实行为
 
-`tests/Rendering/unit/test_render_pass.cpp` 已覆盖：
+`tests/Rendering/unit/test_render_pass.cpp` 当前覆盖了：
 
-- 初始化和执行按插入顺序发生
+- 初始化与执行按插入顺序发生。
-- `Shutdown()` 按逆序发生
+- `Shutdown()` 按逆序发生。
-- 中间某个 pass 执行失败时，后续 pass 不再执行
+- 中间某个 pass 执行失败时，后续 pass 不再执行。
 
 ## 当前实现边界
 
-- 这套协议仍然是线性顺序执行，不是 render graph，也没有显式资源依赖建模。
+- 这套协议仍然是线性顺序执行模型，不是 render graph，也没有显式资源依赖建模。
-- `RenderPassSequence` 只管理 pass 对象，不管理共享资源或跨 pass 的状态同步。
+- `RenderPassSequence` 只管理 `RenderPass` 对象，不管理共享资源或跨 pass 的状态同步。
-- `RenderPassContext` 虽然现在已经能表达“一个输出 surface + 一路可选上游颜色输入”，但仍不适合描述更复杂的多目标或多阶段图结构。
+- `RenderPassContext` 虽然已经能表达“一个输出 `surface` + 一路可选上游颜色输入”，但还不适合描述更复杂的多目标或多阶段图结构。
 
 ## 相关文档
 
+- [RenderPassContext](RenderPassContext.md)
+- [RenderPassSequence](RenderPassSequence.md)
 - [当前模块](../Rendering.md)
 - [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
 - [CameraRenderer](../Execution/CameraRenderer/CameraRenderer.md)

docs/api/XCEngine/Rendering/RenderPass/RenderPassContext.md

@@ -0,0 +1,43 @@
+# RenderPassContext
+
+描述单个 `RenderPass` 执行时可见的共享上下文。
+```cpp
+struct RenderPassContext {
+    const RenderContext& renderContext;
+    const RenderSurface& surface;
+    const RenderSceneData& sceneData;
+    const RenderSurface* sourceSurface = nullptr;
+    RHI::RHIResourceView* sourceColorView = nullptr;
+    RHI::ResourceStates sourceColorState = RHI::ResourceStates::Common;
+};
+```
+
+## 字段
+
+| 字段 | 说明 |
+|------|------|
+| `renderContext` | 当前 backend、device、command list / queue 等运行时上下文。 |
+| `surface` | 当前 pass 的输出目标 `RenderSurface`。 |
+| `sceneData` | 本帧已提取好的场景数据。 |
+| `sourceSurface` | fullscreen / chained pass 的上游 `RenderSurface`；没有上游输入时可为空。 |
+| `sourceColorView` | 上游传入的颜色输入视图；没有上游输入时可为空。 |
+| `sourceColorState` | `sourceColorView` 当前约定的资源状态，供自动切换或状态校验使用。 |
+
+## 当前语义
+
+- 前向场景 pass 往往只消费 `renderContext`、`surface` 与 `sceneData`。
+- fullscreen post-process / final-output 链路会继续消费 `sourceSurface`、`sourceColorView` 与 `sourceColorState`。
+- `surface` 描述的是“这一次 pass 输出到哪里”，`sourceSurface` / `sourceColorView` 描述的是“这一次 pass 从哪里读颜色输入”。
+
+## 当前实现边界
+
+- 当前只支持一路可选的上游颜色输入，不支持多个输入 surface 或多纹理输入槽位的统一建模。
+- 深度附件、render area、sample 描述等输出约束不在这里展开，而是继续由 [RenderSurface](../RenderSurface/RenderSurface.md) 表达。
+- `RenderPassContext` 只是协议对象，不拥有这些资源的生命周期。
+
+## 相关文档
+
+- [RenderPass](RenderPass.md)
+- [RenderPassSequence](RenderPassSequence.md)
+- [RenderSurface](../RenderSurface/RenderSurface.md)
+- [RenderContext](../RenderContext/RenderContext.md)

docs/api/XCEngine/Rendering/RenderPass/RenderPassSequence.md

@@ -0,0 +1,56 @@
+# RenderPassSequence
+
+描述按固定顺序持有并执行多个 `RenderPass` 的拥有型容器。
+```cpp
+class RenderPassSequence {
+public:
+    void AddPass(std::unique_ptr<RenderPass> pass);
+    size_t GetPassCount() const;
+    bool Empty() const;
+    bool Initialize(const RenderContext& context);
+    void Shutdown();
+    bool Execute(const RenderPassContext& context);
+    bool ExecutePass(size_t index, const RenderPassContext& context);
+};
+```
+
+## 公开方法
+
+| 方法 | 当前语义 |
+|------|------|
+| `AddPass()` | 追加一个 pass；传入 `nullptr` 时直接忽略。 |
+| `GetPassCount()` | 返回当前持有的 pass 数量。 |
+| `Empty()` | 判断当前序列是否为空。 |
+| `Initialize()` | 按插入顺序调用每个 pass 的 `Initialize()`；遇到失败立即返回 `false`。 |
+| `Shutdown()` | 按逆序调用每个 pass 的 `Shutdown()`。 |
+| `Execute()` | 按插入顺序调用每个 pass 的 `Execute()`；遇到失败立即停止。 |
+| `ExecutePass()` | 只执行指定索引的单个 pass；索引越界或该位置为空时返回 `false`。 |
+
+## 失败与回滚语义
+
+- `Initialize()` 失败时，`RenderPassSequence` 不会自动回滚已经初始化过的 pass。
+- `Execute()` 失败时，后续 pass 不再执行，但当前序列仍保留，调用方可以选择显式 `Shutdown()`。
+- `Shutdown()` 总是按逆序发生，以匹配常见的资源依赖释放顺序。
+
+## 测试覆盖
+
+`tests/Rendering/unit/test_render_pass.cpp` 当前已经验证：
+
+- 初始化按插入顺序发生。
+- 执行按插入顺序发生。
+- 关闭按逆序发生。
+- 中间某个 pass 返回失败时，后续 pass 不再执行。
+
+`ExecutePass()` 当前没有独立测试，但它的实现只是对索引和空指针做检查后转发到单个 `RenderPass::Execute()`。
+
+## 当前实现边界
+
+- 它是线性容器，不会重排 pass，也不做依赖分析。
+- 共享资源、跨 pass 过渡和中间 surface 分配都不由 `RenderPassSequence` 统一管理。
+- 当前实现用 `std::unique_ptr<RenderPass>` 持有 pass，因此所有权在加入序列时转移给容器。
+
+## 相关文档
+
+- [RenderPass](RenderPass.md)
+- [RenderPassContext](RenderPassContext.md)
+- [Passes](../Passes/Passes.md)