3.3 KiB
3.3 KiB
RenderPass
命名空间: XCEngine::Rendering
类型: header-overview
头文件: XCEngine/Rendering/RenderPass.h
描述: 定义轻量通用 pass 抽象 RenderPass、执行上下文 RenderPassContext 以及顺序执行容器 RenderPassSequence。
概览
RenderPass.h 是当前渲染基础设施里最通用的一层 pass 协议。它统一回答三件事：
- pass 执行时能拿到什么上下文
- 一个 pass 至少需要实现哪些生命周期函数
- 多个 pass 如何按顺序组成一个小型执行序列
当前定义
RenderPassContext
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 个核心成员：
| 成员 | 当前语义 |
|---|---|
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，会在 sequence 初始化失败时显式再做一次 Shutdown() 回滚。
测试与真实行为
tests/Rendering/unit/test_render_pass.cpp 已覆盖：
- 初始化和执行按插入顺序发生
Shutdown()按逆序发生- 中间某个 pass 执行失败时，后续 pass 不再执行
当前实现边界
- 这套协议仍然是线性顺序执行，不是 render graph，也没有显式资源依赖建模。
RenderPassSequence只管理 pass 对象，不管理共享资源或跨 pass 的状态同步。RenderPassContext虽然现在已经能表达“一个输出 surface + 一路可选上游颜色输入”，但仍不适合描述更复杂的多目标或多阶段图结构。