XCEngine/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md

TryBuildBuiltinPassResourceBindingPlan

命名空间: XCEngine::Rendering

类型: function

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

签名

bool TryBuildBuiltinPassResourceBindingPlan(
    const Containers::Array<Resources::ShaderResourceBindingDesc>& bindings,
    BuiltinPassResourceBindingPlan& outPlan,
    Containers::String* outError = nullptr);

作用

把 shader 显式声明的资源绑定列表解析成 builtin pipeline 可直接消费的统一 binding plan。

当前实现行为

1. 先把 outPlan 重置为空。
2. 如果 bindings.Empty()，直接返回 true，保留空 plan。
3. 逐条绑定执行：
   • 通过 ResolveBuiltinPassResourceSemantic 解析 builtin 语义
   • 通过 IsBuiltinPassResourceTypeCompatible 校验语义与资源类型
   • 拒绝同一 builtin 语义重复出现
   • 拒绝同一 set/binding 对重复出现
   • 回填 bindings、usesConstantBuffers、usesTextures、usesSamplers
   • 更新 perObject、material、lighting、shadowReceiver、纹理与采样器槽位
4. 最终计算：
   • firstDescriptorSet = 最小 set
   • descriptorSetCount = 最大 set - 最小 set + 1

失败条件

当前会返回 false，并在 outError 可用时写入错误字符串：

• 解析出 Unknown 语义
• 语义与 shader 资源类型不兼容
• 同一 builtin 语义出现多次
• 同一 set/binding 对出现多次

当前边界

• 它只解析调用方传入的显式 bindings 列表，不再负责生成 legacy fallback 绑定描述。
• 这里还不会检查“是否缺少 PerObject”或“同一 set 是否混用 sampler / 非 sampler”；这些更靠后的布局规则属于 BuiltinForwardPipeline / BuiltinObjectIdPass 的后续阶段。

测试覆盖

tests/Rendering/unit/test_builtin_forward_pipeline.cpp 当前验证了：

• 显式 ForwardLit / Unlit shader 资源声明能正确落成 plan
• 显式 object-id / depth-style 资源声明也能正确落成 plan
• 语义重复、set/binding 重复和语义/类型不兼容时会返回失败

相关文档

• BuiltinPassResourceBindingPlan
• RenderMaterialUtility