# RenderPass

**命名空间**: `XCEngine::Rendering`

**类型**: `header-overview`

**头文件**: `XCEngine/Rendering/RenderPass.h`

**描述**: 定义轻量通用 pass 抽象 `RenderPass`、执行上下文 `RenderPassContext` 以及顺序执行容器 `RenderPassSequence`。

## 概览

`RenderPass.h` 是当前渲染基础设施里最通用的一层 pass 协议。

它统一回答三件事：

- pass 执行时能拿到什么上下文
- 一个 pass 最少需要实现哪些生命周期函数
- 多个 pass 如何按顺序组成一个小型执行序列

## 当前定义

### `RenderPassContext`

`RenderPassContext` 只是三个引用的聚合：

- `renderContext`
- `surface`
- `sceneData`

### `RenderPass`

抽象基类包含四个核心成员：

| 成员 | 当前语义 |
|------|------|
| `GetName()` | 返回 pass 的人类可读名称。 |
| `Initialize()` | 默认返回 `true`，需要时准备一次性资源。 |
| `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`
- `Execute()` 遇到失败也会立即停止后续 pass
- `RenderPassSequence` 自身不会在 `Initialize()` 失败时自动回滚已经初始化过的 pass

当前更高层调用方，例如 `CameraRenderer`，会额外包一层 helper：若 sequence 初始化失败，就主动执行一次 `Shutdown()` 回滚。

## 测试验证的真实行为

`tests/Rendering/unit/test_render_pass.cpp` 已覆盖：

- 初始化和执行按插入顺序发生
- `Shutdown()` 按逆序发生
- 中间某个 pass 执行失败时，后续 pass 不再执行

## 当前实现边界

- 这套协议仍然是线性顺序执行，不是 render graph，也没有显式资源依赖建模。
- `RenderPassSequence` 只管理 pass 对象，不管理共享资源或跨 pass 的状态同步。
- `RenderPassContext` 暂时只暴露一个目标表面和一份 `RenderSceneData`，不适合表达更复杂的多目标或多阶段图结构。

## 相关文档

- [当前模块](../Rendering.md)
- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)
- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
- [Passes](../Passes/Passes.md)