chore: sync workspace state

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

@@ -0,0 +1,50 @@
+# ApplyMaterialRenderState
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+void ApplyMaterialRenderState(
+    const Resources::Material* material,
+    RHI::GraphicsPipelineDesc& pipelineDesc);
+```
+
+## 作用
+
+把材质对应的栅格化、混合和深度状态一次性写入 `GraphicsPipelineDesc`。
+
+## 当前实现行为
+
+当前实现非常直接：
+
+```cpp
+pipelineDesc.rasterizerState = BuildRasterizerState(material);
+pipelineDesc.blendState = BuildBlendState(material);
+pipelineDesc.depthStencilState = BuildDepthStencilState(material);
+```
+
+也就是说，这个函数本身不加任何额外策略，只是统一调用三组状态构建函数。
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `material` | 材质，可为空。 |
+| `pipelineDesc` | 待写入的图形管线描述。 |
+
+## 适用场景
+
+- 在 builtin forward pipeline 组装 draw call 或 PSO 描述时，把材质 render state 映射成后端无关结构。
+- 在未来要做状态缓存时，也适合作为统一的预处理入口。
+
+## 相关文档
+
+- [RenderMaterialUtility](RenderMaterialUtility.md)
+- [BuildRasterizerState](BuildRasterizerState.md)
+- [BuildBlendState](BuildBlendState.md)
+- [BuildDepthStencilState](BuildDepthStencilState.md)

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

@@ -0,0 +1,32 @@
+# BuildBlendState
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+RHI::BlendDesc BuildBlendState(const Resources::Material* material);
+```
+
+## 作用
+
+从材质的混合配置构建 RHI 侧 `BlendDesc`。
+
+## 当前实现行为
+
+- `material == nullptr` 时返回零初始化的 `BlendDesc`。
+- 有材质时，会把 `blendEnable`、颜色/Alpha 的源因子、目标因子、混合操作以及 `colorWriteMask` 全部映射到 RHI 描述。
+
+## 注意事项
+
+- 当前映射完全依赖 `MaterialRenderState`，不会做额外策略补丁。
+- 如果调用方传空材质，得到的是“无显式混合配置”的默认描述，而不是一套行业标准透明配置。
+
+## 相关文档
+
+- [BuildDepthStencilState](BuildDepthStencilState.md)
+- [ApplyMaterialRenderState](ApplyMaterialRenderState.md)

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

@@ -0,0 +1,37 @@
+# BuildDepthStencilState
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+RHI::DepthStencilStateDesc BuildDepthStencilState(const Resources::Material* material);
+```
+
+## 作用
+
+从材质构建深度/模板状态描述。
+
+## 当前实现行为
+
+默认值为：
+
+- `depthTestEnable = true`
+- `depthWriteEnable = true`
+- `depthFunc = Less`
+- `stencilEnable = false`
+
+如果 `material != nullptr`，会用材质的 `depthTestEnable`、`depthWriteEnable` 和 `depthFunc` 覆盖对应字段。当前没有从材质暴露模板状态细节。
+
+## 设计含义
+
+当前实现强调“默认可用的基础深度语义”，还不是完整的 render state authoring 系统。对一个仍在演进中的引擎来说，这样的默认值足以支撑基础前向渲染，但文档里必须明确它还没覆盖完整模板工作流。
+
+## 相关文档
+
+- [BuildBlendState](BuildBlendState.md)
+- [ApplyMaterialRenderState](ApplyMaterialRenderState.md)

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

@@ -0,0 +1,37 @@
+# BuildRasterizerState
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+RHI::RasterizerDesc BuildRasterizerState(const Resources::Material* material);
+```
+
+## 作用
+
+把材质的栅格化相关设置翻译成 RHI 侧的 `RasterizerDesc`。
+
+## 当前实现行为
+
+默认值为：
+
+- `fillMode = Solid`
+- `cullMode = None`
+- `frontFace = CounterClockwise`
+- `depthClipEnable = true`
+
+如果 `material != nullptr`，当前只会用材质里的 `renderState.cullMode` 覆盖 `cullMode`；其他字段仍保持默认值。
+
+## 设计含义
+
+这说明当前材质系统对栅格化状态的暴露还比较克制，主要先解决剔除模式映射，尚未扩展到 fill mode 或 front face 的材质级可配置。
+
+## 相关文档
+
+- [ApplyMaterialRenderState](ApplyMaterialRenderState.md)
+- [BuildBlendState](BuildBlendState.md)

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

@@ -0,0 +1,37 @@
+# IsTransparentRenderQueue
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+bool IsTransparentRenderQueue(Core::int32 renderQueue);
+```
+
+## 作用
+
+判断一个 queue 是否属于透明物体区间。
+
+## 当前实现行为
+
+当前规则非常直接：
+
+```cpp
+return renderQueue >=
+    static_cast<Core::int32>(Resources::MaterialRenderQueue::Transparent);
+```
+
+也就是说，`Transparent` 及其之后的 queue 都会被视为透明队列。
+
+## 用途
+
+`RenderSceneExtractor` 当前就依赖这条规则，把不透明物体做前到后排序，把透明物体做后到前排序。
+
+## 相关文档
+
+- [ResolveMaterialRenderQueue](ResolveMaterialRenderQueue.md)
+- [RenderSceneExtractor](../RenderSceneExtractor/Extract.md)

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

@@ -0,0 +1,41 @@
+# MatchesBuiltinPass
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+bool MatchesBuiltinPass(const Resources::Material* material, BuiltinMaterialPass pass);
+```
+
+## 作用
+
+判断材质是否匹配当前内建渲染通道。
+
+## 当前实现行为
+
+当前只对 `BuiltinMaterialPass::Forward` 做了明确逻辑：
+
+- 如果 `material == nullptr`，直接返回 `true`。
+- 先检查 `material->GetShaderPass()`。
+- 再检查 `material->GetTag("LightMode")`。
+- 这两个字段只要非空且不属于 `forward / forwardbase / forwardlit / forwardonly`，就返回 `false`。
+- 两边都通过时返回 `true`。
+
+## 设计含义
+
+这是一套偏宽松的前向通道匹配策略。它允许：
+
+- 完全没写 pass 元数据的简单材质先跑起来。
+- 使用不同命名习惯但语义接近的前向 pass 被统一接纳。
+
+代价是当前还谈不上完整的多 pass 调度系统，更接近“builtin forward pipeline 的白名单过滤器”。
+
+## 相关文档
+
+- [RenderMaterialUtility](RenderMaterialUtility.md)
+- [ResolveMaterial](ResolveMaterial.md)

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)

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

@@ -0,0 +1,57 @@
+# ResolveMaterial
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+const Resources::Material* ResolveMaterial(
+    const Components::MeshRendererComponent* meshRenderer,
+    const Resources::Mesh* mesh,
+    Core::uint32 materialIndex);
+
+const Resources::Material* ResolveMaterial(const VisibleRenderItem& visibleItem);
+```
+
+## 作用
+
+根据 `MeshRendererComponent`、`Mesh` 和 section/material 索引，解析本次绘制真正应当使用的材质。
+
+## 当前实现行为
+
+三参数重载当前按以下顺序回退：
+
+1. `meshRenderer` 的 `materialIndex` 槽位。
+2. `mesh` 自带材质数组的 `materialIndex` 槽位。
+3. `meshRenderer` 的第 0 个材质。
+4. `mesh` 的第 0 个材质。
+5. 全部都没有则返回 `nullptr`。
+
+`VisibleRenderItem` 重载会先看 `visibleItem.material`；只有它为空时，才走上面的回退链。
+
+## 设计含义
+
+这是一种偏商业引擎的“组件覆盖优先，资源默认值兜底”策略：
+
+- `MeshRendererComponent` 代表场景实例级覆盖。
+- `Mesh` 自带材质更像资源默认值。
+- `VisibleRenderItem.material` 则是提取阶段已经确认好的最终覆盖结果。
+
+## 返回值
+
+- 返回解析到的 `Material*`。
+- 如果所有来源都没有材质，返回 `nullptr`。
+
+## 注意事项
+
+- 返回空材质不一定会导致后续流程中断；当前很多工具函数会对空材质提供默认行为。
+- 这套规则是当前实现契约，未来如果引擎引入 submesh override stack，解析优先级可能扩展。
+
+## 相关文档
+
+- [RenderMaterialUtility](RenderMaterialUtility.md)
+- [MatchesBuiltinPass](MatchesBuiltinPass.md)

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

@@ -0,0 +1,31 @@
+# ResolveMaterialRenderQueue
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+Core::int32 ResolveMaterialRenderQueue(const Resources::Material* material);
+```
+
+## 作用
+
+读取材质的 render queue；如果没有材质，则回退到默认的几何队列。
+
+## 当前实现行为
+
+- `material != nullptr` 时返回 `material->GetRenderQueue()`。
+- `material == nullptr` 时返回 `MaterialRenderQueue::Geometry`。
+
+## 设计意义
+
+这让“无材质物体”仍然可以参与当前排序流程，而不是在 queue 判定阶段立刻失去语义。
+
+## 相关文档
+
+- [IsTransparentRenderQueue](IsTransparentRenderQueue.md)
+- [ResolveMaterial](ResolveMaterial.md)