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

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，不适合表达更复杂的多目标或多阶段图结构。

相关文档

• 当前模块
• CameraRenderRequest
• CameraRenderer
• Passes