XCEngine/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md

# RenderMaterialResolve

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

**类型**: `utility header`

**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`

**描述**: 渲染材质解析辅助头，负责把 `Material`、`MeshRendererComponent` 与 `VisibleRenderItem` 翻译成 builtin pass 可直接消费的常量、buffer 视图、render queue 与 skybox 语义。

## 头文件中的主要类型

- `BuiltinSkyboxTextureMode`
- `BuiltinSkyboxMaterialData`
- `BuiltinDepthStyleMaterialConstants`
- `MaterialConstantLayoutView`
- `MaterialConstantPayloadView`
- `MaterialBufferResourceView`

## 当前公开能力

这份头文件当前主要承接五类解析：

1. semantic-driven 的 shader property / skybox / alpha-cutoff 解析
2. schema-driven 与 depth-style 两类逐材质常量 payload 组装
3. material buffer binding 到 `MaterialBufferResourceView` 的解析
4. `MeshRendererComponent` / `Mesh` / `VisibleRenderItem` 的最终材质与 render queue 解析
5. builtin pass 匹配

## 关键 helper

- `IsMaterialBufferResourceType(...)`
- `FindShaderPropertyBySemantic(...)`
- `ResolveBuiltinBaseColorFactor(...)`
- `ResolveBuiltinBaseColorTexture(...)`
- `ResolveBuiltinAlphaCutoff(...)`
- `BuildBuiltinForwardMaterialData(...)`
- `IsCubemapSkyboxTextureType(...)`
- `IsPanoramicSkyboxTextureType(...)`
- `ResolveSkyboxPanoramicTexture(...)`
- `ResolveSkyboxCubemapTexture(...)`
- `ResolveSkyboxTextureMode(...)`
- `ResolveSkyboxTint(...)`
- `ResolveSkyboxExposure(...)`
- `ResolveSkyboxRotationDegrees(...)`
- `BuildBuiltinSkyboxMaterialData(...)`
- `ResolveSchemaMaterialConstantPayload(...)`
- `BuildBuiltinDepthStyleMaterialConstants(...)`
- `ResolveBuiltinDepthStyleMaterialConstantPayload(...)`
- `TryResolveMaterialBufferResourceView(...)`
- `ResolveMaterial(...)`
- `TryResolveRenderQueueTagValue(...)`
- `TryResolveShaderPassRenderQueue(...)`
- `ResolveMaterialRenderQueue(...)`
- `IsTransparentRenderQueue(...)`
- `MatchesBuiltinPass(...)`

## 当前实现边界

- 它只负责材质语义解析，不直接创建 descriptor set 或 pipeline state。
- `ResolveSchemaMaterialConstantPayload(...)` 暴露的是借用视图，不负责重新打包或持有内存；只有常量布局和常量 buffer 都非空时才会返回有效 payload。
- `MaterialConstantPayloadView::IsValid()` 还要求 `layout.size == size`，因此文档使用时应把它视为“布局与字节载荷配对成功”的结果，而不只是 data 指针非空。
- `ResolveBuiltinDepthStyleMaterialConstantPayload(...)` 返回的 view 同样是借用视图；底层数据来自调用方提供的 `outConstants` 与 `outLayout`。
- `MaterialBufferResourceView` 当前只覆盖 structured/raw buffer 的 SRV / UAV 视图，不负责 texture 或 sampler 资源。
- `TryResolveMaterialBufferResourceView(...)` 只有在 `binding.resourceType` 属于 material buffer 类型、材质中存在同名 buffer binding 且 stride / dimension 合法时才会成功。
- `ResolveMaterial(...)` 当前按“精确材质槽位 -> mesh 默认材质槽位 -> slot 0 回退”的顺序解析最终材质。
- `ResolveMaterialRenderQueue(...)` 当前优先尊重材质自身 `renderQueue` 覆盖；只有它仍等于默认 `Geometry` 队列时，才会继续读取显式 `shaderPass` 或 shader pass `Queue` tag。
- `ResolveSkyboxTextureMode(...)` 先尝试 panoramic，再尝试 cubemap；如果两者都能解析到，当前会优先返回 `Panoramic`。
- `MatchesBuiltinPass(...)` 当前只遍历 shader 的 `ShaderPass` 列表，并把真正的匹配规则委托给 [BuiltinPassMetadataUtils](../../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) 的 `ShaderPassMatchesBuiltinPass(...)`。

## 相关文档

- [Materials](../Materials.md)
- [RenderMaterialStateUtils](../RenderMaterialStateUtils/RenderMaterialStateUtils.md)
- [Builtin](../../Builtin/Builtin.md)
- [BuiltinPassMetadataUtils](../../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md)
- [RenderMaterialUtility](../../RenderMaterialUtility/RenderMaterialUtility.md)