BuiltinForwardPipeline

命名空间: XCEngine::Rendering::Pipelines

类型: class

头文件: XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h

描述: 当前内建的前向主渲染管线实现。它会按 shader pass 的资源声明动态构建 PassResourceLayout、descriptor set 与 RHIPipelineState，并通过 RenderPassSequence 顺序执行 opaque、skybox、volumetric 和 transparent 阶段。

概览

BuiltinForwardPipeline 已经不再是“固定几套 descriptor set + 单一 pipeline layout”的旧模型。当前实现有三条关键缓存链路：

m_passResourceLayouts：以 (shader*, passName) 为 key，缓存每个 shader pass 的资源布局、pipeline layout、静态 descriptor set 和语义位置。
m_pipelineStates：以 (shader*, passName, material render state) 为 key，缓存真正的图形 pipeline state。
m_dynamicDescriptorSets：以 (passLayout, setIndex, objectId, material) 为 key，缓存逐物体或逐材质的 descriptor set。

当前构造函数会向 m_passSequence 依次注册：

BuiltinForwardOpaquePass
BuiltinForwardSkyboxPass
BuiltinVolumetricPass
BuiltinForwardTransparentPass

因此它已经不再是“单 opaque pass”的过渡版前向路径，而是一条正式的多阶段 builtin forward sequence。

当前资源契约

BuiltinForwardPipeline 当前要求 resolved shader pass 显式声明 resources。

如果 resources.Empty()，实现会直接报错，而不是自动生成 legacy fallback binding plan。

随后会通过 TryBuildBuiltinPassResourceBindingPlan 把显式资源声明收口成 BuiltinPassResourceBindingPlan。

当前可识别的 forward 语义只有四个：

PerObject：必需，且必须是唯一的 constant buffer。
Material：可选，且必须是唯一的 constant buffer。
BaseColorTexture：可选，且必须是唯一的 Texture2D 或 TextureCube。
LinearClampSampler：可选，且必须是唯一的 sampler。

其中 Material 语义当前不是固定写死成某个历史布局。渲染时会先通过 ResolveSchemaMaterialConstantPayload(material) 取得 Material::GetConstantBufferData() 的字节视图；只有拿不到有效 payload 时，才会回退到内部 FallbackPerMaterialConstants { baseColorFactor, alphaCutoffParams }。

binding-plan 解析之后，布局构建阶段还会继续拒绝以下情况：

未知语义。
非法 set index。
在同一个 set 中混用 sampler 与非 sampler 绑定。
在同一个 set 中出现重复 binding。
缺少 PerObject。

当前渲染流程

Initialize 通过 m_passSequence.Initialize(context) 进入 pass 生命周期。
Render 把 RenderContext、RenderSurface 和 RenderSceneData 打包成 RenderPassContext，再交给 m_passSequence.Execute(...)。
BuiltinForwardOpaquePass 处理主场景 opaque 物体。
BuiltinForwardSkyboxPass 在环境允许时绘制天空盒。
BuiltinVolumetricPass 遍历 RenderSceneData::visibleVolumes，绘制当前已接入的体对象。
BuiltinForwardTransparentPass 再处理透明阶段。

当前实现细节

BuildInputLayout 现在明确使用 POSITION=float3、NORMAL=float3、TEXCOORD=float2，与 StaticMeshVertex 对齐。
材质贴图解析通过 ResolveBuiltinBaseColorTexture(material) 进入 builtin base-color 语义，不再依赖旧文档里的“按若干名字猜测纹理”说法。
逐物体常量来自 PerObjectConstants。
逐材质常量优先来自 ResolveSchemaMaterialConstantPayload(material) 暴露的 schema-driven payload；如果 view 无效，才回退到内部 FallbackPerMaterialConstants { baseColorFactor, alphaCutoffParams }。
采样器和 1x1 白色 fallback 纹理在初始化后长期复用；具体 Texture 和 Mesh 的 GPU 资源则由 RenderResourceCache 按需上传。
体对象阶段当前已经正式接入 BuiltinVolumetricPass，因此 RenderSceneData 不再只有 visibleItems 一条几何主链。

当前限制

当前虽然已经有 opaque / skybox / volumetric / transparent 四段 sequence，但仍不是延迟渲染、RenderGraph 或更通用的多管线框架。
资源语义是白名单模型，超出 PerObject / Material / BaseColorTexture / LinearClampSampler 的声明不会被接受。
Render() 层面不会因为单个物体 DrawVisibleItem() 失败而整体返回 false；当前调用点仍然以“尽量继续绘制其余物体”为主。

公开方法

方法	说明
Constructor	创建管线对象，并注册默认的 opaque pass。
Destructor	析构时调用 `Shutdown()`。
BuildInputLayout	返回 builtin forward 使用的静态网格输入布局。
Initialize	初始化 pass sequence，并在需要时准备共享 GPU 资源。
Shutdown	关闭 pass sequence，释放 pass layout、descriptor set、pipeline state 与 fallback 资源。
Render	把 `RenderSceneData` 绘制到目标 `RenderSurface`。

6.0 KiB Raw Blame History Unescape Escape