XCEngine/docs/api/XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md

BuiltinPassLayoutUtils

命名空间: XCEngine::Rendering

类型: utility header

头文件: XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils.h

描述: builtin pass 资源布局辅助头，负责把 shader resources 列表解析成 BuiltinPassResourceBindingPlan，再进一步构建 descriptor-set layout 元数据。

当前公开能力

这份头文件主要提供两段式转换：

1. TryBuildBuiltinPassResourceBindingPlan(...) 把 shader resources 收口成 builtin 语义化 binding plan。
2. TryBuildBuiltinPassSetLayouts(...) 把 binding plan 继续落成每个 descriptor set 的布局元数据。

除此之外，还提供：

• ToBuiltinPassDescriptorType(...)
• ResolveBuiltinPassDescriptorHeapType(...)
• IsBuiltinPassShaderVisibleSet(...)
• CountBuiltinPassHeapDescriptors(...)
• RefreshBuiltinPassSetLayoutMetadata(...)
• RefreshBuiltinPassSetLayouts(...)

当前约束

• 拒绝未知 builtin 语义。
• 拒绝语义与 shader 资源类型不兼容的组合。
• 拒绝重复的 builtin 语义。
• 拒绝重复的 set/binding 组合。
• 拒绝在同一个 descriptor set 中混用 sampler 和非 sampler 资源。

当前调用链

• BuiltinForwardPipeline 用它为每个 resolved shader pass 生成 pipeline layout 和 descriptor sets。
• BuiltinObjectIdPass 用它校验 object-id shader 的 PerObject 资源契约。
• BuiltinDepthStylePassBase 用它为 depth-only / shadow-caster / alpha-test 变体准备共享布局。

当前实现边界

• 它只负责 builtin pass 白名单语义，不是通用 shader 反射层。
• 最终“某个 pass 缺少必需语义”这类规则，仍由具体 pass 或 pipeline 在更高层决定。

相关文档

• Builtin
• BuiltinPassTypes
• BuiltinPassMetadataUtils
• TryBuildBuiltinPassResourceBindingPlan