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

# RenderMaterialUtility

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

**类型**: `utility header`

**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`

**描述**: 把 `Material` 的 pass 元数据、逐材质常量契约、builtin forward 兼容语义、render queue 和 render state 解释成渲染提取与图形管线可直接使用的规则。

## 概览

`RenderMaterialUtility.h` 不是运行时对象，而是一组内联规则函数。它当前承担五类工作：

1. 解析“这次绘制真正要用哪份材质”。
2. 判断该材质是否匹配某个 builtin pass。
3. 暴露 shader schema 驱动的逐材质常量 payload 视图。
4. 解析 builtin forward 兼容路径要消费的 base-color 因子与贴图。
5. 把材质里的 `MaterialRenderState` 翻译成 `RHI::GraphicsPipelineDesc` 需要的状态结构。

它位于 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)、[BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 和 object-id 相关 pass 之间，是当前材质语义进入渲染链路的关键翻译层。

## `BuiltinMaterialPass`

当前公开的 builtin pass 枚举包括：

| 枚举值 | 说明 |
|------|------|
| `ForwardLit` | 默认前向绘制路径。 |
| `Unlit` | 非受光绘制路径。 |
| `DepthOnly` | 深度预写 / depth-only 通道。 |
| `ShadowCaster` | 阴影投射通道。 |
| `ObjectId` | object-id 输出通道。 |
| `Forward` | `ForwardLit` 的别名。 |

## builtin pass 元数据与资源绑定契约

当前这份头文件除了材质解析 helper，还公开了一组“shader pass 如何映射到 builtin path、资源声明如何落成 descriptor-set 计划”的契约类型：

- [PassResourceBindingLocation](PassResourceBindingLocation.md)
  统一表示一个 `set/binding` 槽位。
- [BuiltinPassResourceSemantic](BuiltinPassResourceSemantic.md)
  把 shader 资源语义收口成 builtin forward / object-id 当前识别的白名单枚举。
- [BuiltinPassResourceBindingDesc](BuiltinPassResourceBindingDesc.md)
  记录单个 builtin 语义、资源类型与绑定位置。
- [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md)
  是 `BuiltinForwardPipeline` / `BuiltinObjectIdPass` 当前真正消费的 binding-plan 结果。

与这些类型配套的 helper 包括：

- [IsForwardPassName](IsForwardPassName.md)
- [IsUnlitPassName](IsUnlitPassName.md)
- [IsDepthOnlyPassName](IsDepthOnlyPassName.md)
- [IsShadowCasterPassName](IsShadowCasterPassName.md)
- [IsObjectIdPassName](IsObjectIdPassName.md)
- [MatchesBuiltinPassName](MatchesBuiltinPassName.md)
- [ShaderPassHasExplicitBuiltinMetadata](ShaderPassHasExplicitBuiltinMetadata.md)
- [ShaderPassMatchesBuiltinPass](ShaderPassMatchesBuiltinPass.md)
- [ResolveBuiltinPassResourceSemantic](ResolveBuiltinPassResourceSemantic.md)
- [BuildLegacyBuiltinForwardPassResourceBindings](BuildLegacyBuiltinForwardPassResourceBindings.md)
- [BuildLegacyBuiltinObjectIdPassResourceBindings](BuildLegacyBuiltinObjectIdPassResourceBindings.md)
- [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md)
- [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md)

这组页面对应的是当前 builtin pipeline 的真实入口：shader pass 可以显式声明 `resources`；如果没声明，再退到 legacy fallback 绑定；最终都要先落成统一的 binding plan，后续 pass-layout / descriptor-set / pipeline-state 才能继续创建。

## 当前 pass 匹配策略

[MatchesBuiltinPass](MatchesBuiltinPass.md) 的判断顺序是：

1. 先看材质自身的 `shaderPass` 和 `LightMode` tag。
2. 如果材质没写显式 pass 元数据，再看材质引用 shader 里的 pass 名称和 `LightMode` tag。
3. 如果材质和 shader 都没写显式 builtin metadata，则把它隐式视为 `ForwardLit`。

因此这里实际把 [MaterialLoader](../../Resources/Material/MaterialLoader/MaterialLoader.md) 解析出的：

- `shaderPass`
- `tags.LightMode`
- `renderQueue`
- `renderState`

全部接进了渲染路径。

## 逐材质常量契约

同一个头文件里当前公开了两类逐材质数据和一份布局视图：

| 类型 | 说明 |
|------|------|
| [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) | builtin forward 的兼容 fallback 常量结构，当前只收口 `baseColorFactor`。 |
| [MaterialConstantLayoutView](MaterialConstantLayoutView.md) | 指向 `Material::GetConstantLayout()` 的非 owning 布局视图。 |
| [MaterialConstantPayloadView](MaterialConstantPayloadView.md) | 指向 `Material::GetConstantBufferData()` 及其布局的非 owning 视图。 |

对应 helper 的当前职责是：

- [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md)
  解析 base color 因子，优先走 shader semantic，再回退到常见别名属性名，最后可只从 opacity/alpha 补 `w` 分量。
- [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md)
  解析 base color 贴图，优先走 shader semantic，再回退到 `_MainTex`、`baseColorTexture` 等常见别名。
- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md)
  构造 builtin forward 的兼容 fallback 常量。
- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
  直接暴露当前 `Material` 已按 shader schema 生成的常量缓冲 payload 与布局视图。

`BuiltinForwardPipeline` 当前会优先用 [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
把 `Material::GetConstantBufferData()` 写入 `Material` 语义的 constant buffer 绑定；只有拿不到有效 payload 时，
才回退到 [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 生成的
`baseColorFactor` fallback。base-color 贴图仍由
[ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 单独解析。

## render state 映射

`BuildRasterizerState()`、`BuildBlendState()` 和 `BuildDepthStencilState()` 会把 `MaterialRenderState` 映射成 RHI 状态，再由 [ApplyMaterialRenderState](ApplyMaterialRenderState.md) 一次性写入 `GraphicsPipelineDesc`。

当前影响渲染结果的核心状态包括：

- 剔除模式
- 混合开关与颜色 / alpha 混合因子
- 颜色写掩码
- 深度测试 / 深度写入 / 深度比较函数

## 当前实现边界

- 它只处理 pass 归类、逐材质常量 payload 解析、builtin forward 兼容契约、render queue 和固定渲染状态，不负责 shader variant、keyword 或多 pass 编排。
- 没有显式元数据的材质会默认进入 `ForwardLit`，这是一种“先让基础路径可用”的保守回退。
- `MatchesBuiltinPass(nullptr, pass)` 只有在 `pass == ForwardLit` 时才返回 `true`。
- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) 只是暴露当前
  `Material::GetConstantBufferData()` 的借用视图，不负责重新打包、补齐字段或管理内存所有权。
- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 当前仍只收口 `baseColorFactor`，
  但它已经退到 builtin forward 的兼容 fallback 路径，不再代表 `Material` 语义 constant buffer 的主路径。

## 公开类型

| 类型 | 说明 |
|------|------|
| [BuiltinMaterialPass](BuiltinMaterialPass.md) | builtin 渲染通道枚举。 |
| [PassResourceBindingLocation](PassResourceBindingLocation.md) | 一个 `set/binding` 位置。 |
| [BuiltinPassResourceSemantic](BuiltinPassResourceSemantic.md) | builtin pass 识别的资源语义白名单。 |
| [BuiltinPassResourceBindingDesc](BuiltinPassResourceBindingDesc.md) | 单个资源绑定条目的语义化描述。 |
| [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md) | builtin pipeline 消费的绑定计划。 |
| [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) | builtin forward 的兼容 fallback 常量结构。 |
| [MaterialConstantLayoutView](MaterialConstantLayoutView.md) | schema-driven 常量布局视图。 |
| [MaterialConstantPayloadView](MaterialConstantPayloadView.md) | schema-driven 逐材质常量 payload 的借用视图。 |
| [MaterialRenderStateHash](MaterialRenderStateHash.md) | `MaterialRenderState` 的哈希 functor。 |

## 公开函数

| 函数 | 说明 |
|------|------|
| [NormalizeBuiltinPassMetadataValue](NormalizeBuiltinPassMetadataValue.md) | 统一 builtin pass 元数据的归一化规则。 |
| [IsForwardPassName](IsForwardPassName.md) | 判断名称是否匹配 forward pass。 |
| [IsUnlitPassName](IsUnlitPassName.md) | 判断名称是否匹配 unlit pass。 |
| [IsDepthOnlyPassName](IsDepthOnlyPassName.md) | 判断名称是否匹配 depth-only pass。 |
| [IsShadowCasterPassName](IsShadowCasterPassName.md) | 判断名称是否匹配 shadow-caster pass。 |
| [IsObjectIdPassName](IsObjectIdPassName.md) | 判断名称是否匹配 object-id pass。 |
| [MatchesBuiltinPassName](MatchesBuiltinPassName.md) | 判断字符串是否匹配某个 builtin pass。 |
| [ShaderPassHasExplicitBuiltinMetadata](ShaderPassHasExplicitBuiltinMetadata.md) | 判断 shader pass 是否显式声明了 builtin 元数据。 |
| [ShaderPassMatchesBuiltinPass](ShaderPassMatchesBuiltinPass.md) | 判断 shader pass 是否匹配某个 builtin pass。 |
| [ResolveBuiltinPassResourceSemantic](ResolveBuiltinPassResourceSemantic.md) | 把 shader resource binding 解析成 builtin 语义。 |
| [BuildLegacyBuiltinForwardPassResourceBindings](BuildLegacyBuiltinForwardPassResourceBindings.md) | 构造 forward 路径的 legacy fallback 绑定列表。 |
| [BuildLegacyBuiltinObjectIdPassResourceBindings](BuildLegacyBuiltinObjectIdPassResourceBindings.md) | 构造 object-id 路径的 legacy fallback 绑定列表。 |
| [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md) | 判断 builtin 语义和 shader 资源类型是否兼容。 |
| [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) | 把 shader 资源绑定解析成统一 binding plan。 |
| [FindShaderPropertyBySemantic](FindShaderPropertyBySemantic.md) | 按 semantic 查找 shader property。 |
| [ResolveMaterial](ResolveMaterial.md) | 解析当前可见物体最终应使用的材质。 |
| [ResolveMaterialRenderQueue](ResolveMaterialRenderQueue.md) | 读取材质 render queue，空材质时回退到 `Geometry`。 |
| [IsTransparentRenderQueue](IsTransparentRenderQueue.md) | 判断 queue 是否处于透明区间。 |
| [MatchesBuiltinPass](MatchesBuiltinPass.md) | 判断材质是否匹配某个 builtin pass。 |
| [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md) | 解析 builtin forward 使用的 base color 因子。 |
| [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) | 解析 builtin forward 使用的 base color 贴图。 |
| [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) | 构造 builtin forward 的兼容 fallback 常量。 |
| [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) | 返回当前 shader schema 驱动的逐材质常量 payload 视图。 |
| [BuildRasterizerState](BuildRasterizerState.md) | 构建栅格化状态。 |
| [BuildBlendState](BuildBlendState.md) | 构建混合状态。 |
| [BuildDepthStencilState](BuildDepthStencilState.md) | 构建深度状态。 |
| [ToRHICullMode](ToRHICullMode.md) | 把材质剔除模式映射到 RHI。 |
| [ToRHIComparisonFunc](ToRHIComparisonFunc.md) | 把材质比较函数映射到 RHI。 |
| [ToRHIBlendFactor](ToRHIBlendFactor.md) | 把材质混合因子映射到 RHI。 |
| [ToRHIBlendOp](ToRHIBlendOp.md) | 把材质混合操作映射到 RHI。 |
| [ApplyMaterialRenderState](ApplyMaterialRenderState.md) | 一次性写入图形管线状态。 |

## 相关文档

- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
- [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md)
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)