82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
# 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)
|