62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
# MatchesBuiltinPass
|
||
|
||
**命名空间**: `XCEngine::Rendering`
|
||
|
||
**类型**: `function`
|
||
|
||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||
|
||
## 签名
|
||
|
||
```cpp
|
||
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](RenderMaterialUtility.md)
|
||
- [ResolveMaterial](ResolveMaterial.md)
|