diff --git a/docs/api/XCEngine/Rendering/RenderPass/RenderPass.md b/docs/api/XCEngine/Rendering/RenderPass/RenderPass.md index 3f0cd7dd..5975870b 100644 --- a/docs/api/XCEngine/Rendering/RenderPass/RenderPass.md +++ b/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 个字段： - -| 字段 | 说明 | -|------|------| -| `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 个核心成员： +`RenderPass` 抽象基类当前包含 4 个核心成员： | 成员 | 当前语义 | |------|------| @@ -44,42 +34,31 @@ | `Execute()` | 纯虚函数，执行真正的 pass 逻辑。 | | `Shutdown()` | 默认空实现，释放 pass 资源。 | -### `RenderPassSequence` - -`RenderPassSequence` 是一个拥有型容器，内部以 `std::unique_ptr` 顺序保存 pass。 - -当前行为是： - -- `AddPass()` 会忽略空指针。 -- `GetPassCount()` 返回当前持有的 pass 数量。 -- `Initialize()` 按插入顺序调用每个 pass 的 `Initialize()`。 -- `Execute()` 按插入顺序调用每个 pass 的 `Execute()`。 -- `Shutdown()` 按逆序调用每个 pass 的 `Shutdown()`。 - ## 失败与回滚语义 -- `Initialize()` 遇到失败会立刻返回 `false`。 -- `Execute()` 遇到失败也会立刻停止后续 pass。 +- `RenderPassSequence::Initialize()` 遇到失败会立刻返回 `false`。 +- `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()` 按逆序发生 -- 中间某个 pass 执行失败时，后续 pass 不再执行 +- 初始化与执行按插入顺序发生。 +- `Shutdown()` 按逆序发生。 +- 中间某个 pass 执行失败时，后续 pass 不再执行。 ## 当前实现边界 -- 这套协议仍然是线性顺序执行，不是 render graph，也没有显式资源依赖建模。 -- `RenderPassSequence` 只管理 pass 对象，不管理共享资源或跨 pass 的状态同步。 -- `RenderPassContext` 虽然现在已经能表达“一个输出 surface + 一路可选上游颜色输入”，但仍不适合描述更复杂的多目标或多阶段图结构。 +- 这套协议仍然是线性顺序执行模型，不是 render graph，也没有显式资源依赖建模。 +- `RenderPassSequence` 只管理 `RenderPass` 对象，不管理共享资源或跨 pass 的状态同步。 +- `RenderPassContext` 虽然已经能表达“一个输出 `surface` + 一路可选上游颜色输入”，但还不适合描述更复杂的多目标或多阶段图结构。 ## 相关文档 +- [RenderPassContext](RenderPassContext.md) +- [RenderPassSequence](RenderPassSequence.md) - [当前模块](../Rendering.md) - [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md) - [CameraRenderer](../Execution/CameraRenderer/CameraRenderer.md) diff --git a/docs/api/XCEngine/Rendering/RenderPass/RenderPassContext.md b/docs/api/XCEngine/Rendering/RenderPass/RenderPassContext.md new file mode 100644 index 00000000..01de149e --- /dev/null +++ b/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) diff --git a/docs/api/XCEngine/Rendering/RenderPass/RenderPassSequence.md b/docs/api/XCEngine/Rendering/RenderPass/RenderPassSequence.md new file mode 100644 index 00000000..add64165 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPass/RenderPassSequence.md @@ -0,0 +1,56 @@ +# RenderPassSequence + +描述按固定顺序持有并执行多个 `RenderPass` 的拥有型容器。 +```cpp +class RenderPassSequence { +public: + void AddPass(std::unique_ptr 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` 持有 pass，因此所有权在加入序列时转移给容器。 + +## 相关文档 + +- [RenderPass](RenderPass.md) +- [RenderPassContext](RenderPassContext.md) +- [Passes](../Passes/Passes.md)