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、BuiltinForwardPipeline 和 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 统一表示一个 set/binding 槽位。
• BuiltinPassResourceSemantic 把 shader 资源语义收口成 builtin forward / object-id 当前识别的白名单枚举。
• BuiltinPassResourceBindingDesc 记录单个 builtin 语义、资源类型与绑定位置。
• BuiltinPassResourceBindingPlan 是 BuiltinForwardPipeline / BuiltinObjectIdPass 当前真正消费的 binding-plan 结果。

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

• IsForwardPassName
• IsUnlitPassName
• IsDepthOnlyPassName
• IsShadowCasterPassName
• IsObjectIdPassName
• MatchesBuiltinPassName
• ShaderPassHasExplicitBuiltinMetadata
• ShaderPassMatchesBuiltinPass
• ResolveBuiltinPassResourceSemantic
• BuildLegacyBuiltinForwardPassResourceBindings
• BuildLegacyBuiltinObjectIdPassResourceBindings
• IsBuiltinPassResourceTypeCompatible
• TryBuildBuiltinPassResourceBindingPlan

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

当前 pass 匹配策略

MatchesBuiltinPass 的判断顺序是：

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

因此这里实际把 MaterialLoader 解析出的：

• shaderPass
• tags.LightMode
• renderQueue
• renderState

全部接进了渲染路径。

逐材质常量契约

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

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

对应 helper 的当前职责是：

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

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

render state 映射

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

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

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

当前实现边界

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

公开类型

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

公开函数

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

相关文档

• CameraRenderer
• RenderSceneExtractor
• VisibleRenderObject
• BuiltinForwardPipeline