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

MatchesBuiltinPass

命名空间: XCEngine::Rendering

类型: function

头文件: XCEngine/Rendering/RenderMaterialUtility.h

签名

bool MatchesBuiltinPass(const Resources::Material* material, BuiltinMaterialPass pass);

作用

判断一份材质是否应当进入某个 builtin pass。

当前实现行为

当前判断顺序是：

1. 如果 material == nullptr，只有 pass == BuiltinMaterialPass::ForwardLit 时返回 true。
2. 读取材质自身的 GetShaderPass() 和 GetTag("LightMode")。
3. 只要材质自己写了显式 pass 元数据，就要求这些元数据都匹配目标 builtin pass。
4. 如果材质自己没写显式元数据，再检查材质引用的 shader：
   • 逐个遍历 shader pass
   • 只要某个 shader pass 的名称或 LightMode 能匹配目标 builtin pass，就返回 true
   • 如果 shader 里存在显式 builtin metadata，但没有任何一个匹配，则返回 false
5. 如果材质和 shader 都没有显式 builtin metadata，则把它隐式视为 ForwardLit。

当前识别的 builtin pass 名称

按 MatchesBuiltinPassName() 当前规则：

• ForwardLit / Forward：接受空字符串、forward、forwardbase、forwardlit、forwardonly
• Unlit：接受 unlit、forwardunlit、srpdefaultunlit
• DepthOnly：接受 depthonly、depth
• ShadowCaster：接受 shadowcaster、shadow
• ObjectId：接受 objectid、editorobjectid

所有比较都会先做 Trim().ToLower() 归一化。

真实语义

• 材质级元数据优先级高于 shader 级元数据。
• shader 里如果显式声明了其它 builtin pass，就会关闭“隐式 ForwardLit 回退”。
• 这使得 object-id、unlit、depth-only 一类材质可以通过 shaderPass 或 LightMode 明确进入对应路径，而不是被默认前向通道误收。

测试覆盖

tests/Rendering/unit/test_render_scene_extractor.cpp 当前验证了：

• ForwardLit、Unlit、DepthOnly、ObjectId 的匹配结果
• shader pass 名称也能驱动 builtin pass 匹配
• 显式 shader metadata 会关闭隐式 forward fallback

相关文档

• RenderMaterialUtility
• ResolveMaterial