# 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](../Builtin.md)
- [BuiltinPassTypes](../BuiltinPassTypes/BuiltinPassTypes.md)
- [BuiltinPassMetadataUtils](../BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md)
- [TryBuildBuiltinPassResourceBindingPlan](../../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md)