RenderMaterialUtility

命名空间: XCEngine::Rendering

类型: utility header

头文件: XCEngine/Rendering/RenderMaterialUtility.h

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

概览

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

解析“这次绘制真正要用哪份材质”。
判断该材质是否匹配某个 builtin pass。
解析 builtin forward 路径要消费的 base-color 因子与贴图。
把材质里的 MaterialRenderState 翻译成 RHI::GraphicsPipelineDesc 需要的状态结构。

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

`BuiltinMaterialPass`

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

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

当前 pass 匹配策略

MatchesBuiltinPass 的判断顺序是：

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

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

shaderPass
tags.LightMode
renderQueue
renderState

全部接进了渲染路径。

builtin forward 材质契约

同一个头文件里还公开了 BuiltinForwardMaterialData：

字段	类型	说明
`baseColorFactor`	`Math::Vector4`	builtin forward 当前消费的颜色因子。

对应 helper 的当前职责是：

ResolveBuiltinBaseColorFactor 解析 base color 因子，优先走 shader semantic，再回退到常见别名属性名，最后可只从 opacity/alpha 补 w 分量。
ResolveBuiltinBaseColorTexture 解析 base color 贴图，优先走 shader semantic，再回退到 _MainTex、baseColorTexture 等常见别名。
BuildBuiltinForwardMaterialData 把当前 builtin forward 真正要消费的材质常量打包出来。

这组 helper 当前直接被 BuiltinForwardPipeline 用来填充 per-material 常量和纹理绑定。

render state 映射

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

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

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

当前实现边界

它只处理 pass 归类、builtin forward 材质契约、render queue 和固定渲染状态，不负责 shader variant、keyword 或多 pass 编排。
没有显式元数据的材质会默认进入 ForwardLit，这是一种“先让基础路径可用”的保守回退。
MatchesBuiltinPass(nullptr, pass) 只有在 pass == ForwardLit 时才返回 true。
BuildBuiltinForwardMaterialData() 当前只打包 baseColorFactor；贴图仍由调用方单独通过 ResolveBuiltinBaseColorTexture 解析。

公开函数

函数	说明
ResolveMaterial	解析当前可见物体最终应使用的材质。
ResolveMaterialRenderQueue	读取材质 render queue，空材质时回退到 `Geometry`。
IsTransparentRenderQueue	判断 queue 是否处于透明区间。
MatchesBuiltinPass	判断材质是否匹配某个 builtin pass。
ResolveBuiltinBaseColorFactor	解析 builtin forward 使用的 base color 因子。
ResolveBuiltinBaseColorTexture	解析 builtin forward 使用的 base color 贴图。
BuildBuiltinForwardMaterialData	打包 builtin forward 当前消费的材质常量。
BuildRasterizerState	构建栅格化状态。
BuildBlendState	构建混合状态。
BuildDepthStencilState	构建深度状态。
ApplyMaterialRenderState	一次性写入图形管线状态。

5.3 KiB Raw Blame History Unescape Escape