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

# TryBuildBuiltinPassResourceBindingPlan

**命名空间**: `XCEngine::Rendering`

**类型**: `function`

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

## 签名

```cpp
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](ResolveBuiltinPassResourceSemantic.md) 解析 builtin 语义
   - 通过 [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md) 校验语义与资源类型
   - 拒绝同一 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](BuiltinPassResourceBindingPlan.md)
- [RenderMaterialUtility](RenderMaterialUtility.md)