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 / baseColorTexture / linearClampSampler
4. 最终计算：
   • firstDescriptorSet = 最小 set
   • descriptorSetCount = 最大 set - 最小 set + 1

失败条件

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

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

当前边界

• 这里还不会检查“是否缺少 PerObject”或“同一 set 是否混用 sampler / 非 sampler”；这些更靠后的布局规则属于 BuiltinForwardPipeline / BuiltinObjectIdPass 的后续阶段。

测试覆盖

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

• 显式 ForwardLit / Unlit shader 资源声明能正确落成 plan
• 非法 builtin 语义和非法语义 / 资源类型组合会被拒绝
• 生成的 plan 会正确计算 firstDescriptorSet 与 descriptorSetCount

相关文档

• BuiltinPassResourceBindingPlan
• RenderMaterialUtility