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

# RenderMaterialUtility

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

**类型**: `compatibility topic`

**描述**: 旧的 `RenderMaterialUtility.h` 已经拆分；当前材质解析、builtin pass 契约和 render-state 映射分别落在 `Builtin/*` 与 `Materials/*` 目录下。

## 拆分结果

当前源码中不再存在单一的 `RenderMaterialUtility.h`。原来的职责已经拆到这些头文件：

- `XCEngine/Rendering/Builtin/BuiltinPassTypes.h`
- `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
- `XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils.h`
- `XCEngine/Rendering/Builtin/BuiltinPassContract.h`
- `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
- `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`

因此这页只保留为兼容入口，用来解释“原先归在 RenderMaterialUtility 名下的文档现在分别去哪了”。

## 当前分层

### Builtin pass 契约

这些页面描述 builtin pass 名称、资源语义和 binding-plan 构建规则：

- [BuiltinMaterialPass](BuiltinMaterialPass.md)
- [PassResourceBindingLocation](PassResourceBindingLocation.md)
- [BuiltinPassResourceSemantic](BuiltinPassResourceSemantic.md)
- [BuiltinPassResourceBindingDesc](BuiltinPassResourceBindingDesc.md)
- [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md)
- [NormalizeBuiltinPassMetadataValue](NormalizeBuiltinPassMetadataValue.md)
- [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)
- [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md)
- [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md)

### 材质解析

这些页面描述材质选择、builtin fallback 常量以及 schema-driven 常量布局：

- [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md)
- [FindShaderPropertyBySemantic](FindShaderPropertyBySemantic.md)
- [MaterialConstantLayoutView](MaterialConstantLayoutView.md)
- [MaterialConstantPayloadView](MaterialConstantPayloadView.md)
- [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md)
- [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md)
- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md)
- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
- [ResolveMaterial](ResolveMaterial.md)
- [ResolveMaterialRenderQueue](ResolveMaterialRenderQueue.md)
- [IsTransparentRenderQueue](IsTransparentRenderQueue.md)
- [MatchesBuiltinPass](MatchesBuiltinPass.md)

### Render-state 映射

这些页面描述 `MaterialRenderState` 到 RHI 状态的转换：

- [ToRHICullMode](ToRHICullMode.md)
- [ToRHIComparisonFunc](ToRHIComparisonFunc.md)
- [ToRHIBlendFactor](ToRHIBlendFactor.md)
- [ToRHIBlendOp](ToRHIBlendOp.md)
- [BuildRasterizerState](BuildRasterizerState.md)
- [BuildBlendState](BuildBlendState.md)
- [BuildDepthStencilState](BuildDepthStencilState.md)
- [ApplyMaterialRenderState](ApplyMaterialRenderState.md)
- [MaterialRenderStateHash](MaterialRenderStateHash.md)

## 当前边界

- 旧的 legacy binding builder 接口已经移除，当前文档不再保留对应页面。
- `RenderMaterialUtility` 现在更适合被理解成一个主题集合，而不是单个公开头文件。
- 需要从真实源码入口追踪时，优先看 [Builtin](../Builtin/Builtin.md) 和 [Materials](../Materials/Materials.md)。

## 相关文档

- [Rendering](../Rendering.md)
- [Builtin](../Builtin/Builtin.md)
- [Materials](../Materials/Materials.md)
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)