chore: sync workspace state

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

@@ -0,0 +1,76 @@
+# RenderMaterialUtility
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `utility header`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+**描述**: 把 `Material` 的渲染语义翻译成当前渲染层和 RHI 能直接消费的选择规则与状态描述。
+
+## 概览
+
+`RenderMaterialUtility.h` 不是一个运行时对象，而是一组内联工具函数与辅助枚举。它解决的是“材质资源层”和“实际绘制层”之间的翻译问题：
+
+- 先决定这次绘制到底用哪份 `Material`。
+- 再判断这份材质是否属于当前内建 pass。
+- 然后把材质里的 render state 翻译成 RHI 描述结构。
+
+这类 utility header 在商业引擎里很常见，因为材质解析、render queue 判定、RHI 状态映射本质上都是无状态规则，不值得再包成有生命周期的服务对象。
+
+## 公开概念
+
+### BuiltinMaterialPass
+
+当前只定义了一个内建 pass：
+
+| 枚举值 | 说明 |
+|------|------|
+| `BuiltinMaterialPass::Forward` | 表示默认前向绘制通道。 |
+
+### 当前前向 pass 识别规则
+
+按 `MatchesBuiltinPass()` 当前实现，以下值会被视为前向 pass：
+
+- 空字符串
+- `forward`
+- `forwardbase`
+- `forwardlit`
+- `forwardonly`
+
+比较前会先做 `Trim().ToLower()` 归一化，并同时检查 `GetShaderPass()` 与 `GetTag("LightMode")`。
+
+## 设计要点
+
+- 材质选择逻辑单独抽出来，可以让 `RenderSceneExtractor` 和具体管线共用同一套规则。
+- render queue 和透明度判定放在这里，可以保证排序语义不散落在多个调用点。
+- RHI 状态构建函数把资源层枚举翻译成后端无关描述，这比直接在管线里读 `Material` 细节更干净。
+
+## 当前实现边界
+
+- 只覆盖当前引擎已有的 `MaterialRenderState` 字段，不负责 shader variant、keyword 或多 pass 编排。
+- 默认值是“可用但保守”的最小实现，例如栅格化默认 `CullMode::None`、深度默认开启且比较函数为 `Less`。
+- `MatchesBuiltinPass(nullptr, ...)` 当前返回 `true`，这意味着“没有材质”在 pass 过滤阶段不会被拦掉。
+
+## 公开函数
+
+| 函数 | 说明 |
+|------|------|
+| [ResolveMaterial](ResolveMaterial.md) | 按当前约定解析可见物体实际使用的材质。 |
+| [ResolveMaterialRenderQueue](ResolveMaterialRenderQueue.md) | 读取材质 render queue，空材质时回退到 `Geometry`。 |
+| [IsTransparentRenderQueue](IsTransparentRenderQueue.md) | 判断一个 queue 是否属于透明区间。 |
+| [MatchesBuiltinPass](MatchesBuiltinPass.md) | 判断材质是否匹配当前内建 pass。 |
+| [BuildRasterizerState](BuildRasterizerState.md) | 从材质构建栅格化状态。 |
+| [BuildBlendState](BuildBlendState.md) | 从材质构建混合状态。 |
+| [BuildDepthStencilState](BuildDepthStencilState.md) | 从材质构建深度模板状态。 |
+| [ApplyMaterialRenderState](ApplyMaterialRenderState.md) | 一次性把材质状态写入 `GraphicsPipelineDesc`。 |
+
+## 其他辅助函数
+
+头文件里还提供了 `ToRHICullMode`、`ToRHIComparisonFunc`、`ToRHIBlendFactor`、`ToRHIBlendOp`、`MaterialRenderStateHash` 等内联辅助工具。它们主要服务于状态映射与缓存键构建，当前更适合被视为实现支撑件，而不是高层调用入口。
+
+## 相关文档
+
+- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
+- [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md)
+- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)