docs(api): align render material resolve docs

docs/api/XCEngine/Rendering/Materials/Materials.md

@@ -24,7 +24,8 @@
 - shader pass / builtin pass 语义匹配
 - material render state 转换
 - builtin base-color / alpha-cutoff / skybox 材质数据解析
-- schema-driven 逐材质常量 payload 暴露
+- schema-driven 与 depth-style 逐材质常量 payload 暴露
+- structured/raw material buffer binding 视图解析
 - `VisibleRenderItem` 最终材质与 render queue 解析
 
 ## 相关文档

docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md

@@ -6,27 +6,30 @@
 
 **头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
 
-**描述**: 渲染材质解析辅助头，负责把 `Material`、`MeshRendererComponent` 与 `VisibleRenderItem` 翻译成 builtin pass 可直接消费的材质、常量、render queue 与 skybox 语义。
+**描述**: 渲染材质解析辅助头，负责把 `Material`、`MeshRendererComponent` 与 `VisibleRenderItem` 翻译成 builtin pass 可直接消费的常量、buffer 视图、render queue 与 skybox 语义。
 
 ## 头文件中的主要类型
 
-- `BuiltinForwardMaterialData`
 - `BuiltinSkyboxTextureMode`
 - `BuiltinSkyboxMaterialData`
+- `BuiltinDepthStyleMaterialConstants`
 - `MaterialConstantLayoutView`
 - `MaterialConstantPayloadView`
+- `MaterialBufferResourceView`
 
 ## 当前公开能力
 
-这份头文件当前主要承接四类解析：
+这份头文件当前主要承接五类解析：
 
-1. builtin pass 匹配
-2. base-color / alpha-cutoff / skybox 材质数据解析
-3. schema-driven 逐材质常量 payload 暴露
-4. `VisibleRenderItem` 最终材质与 render queue 解析
+1. semantic-driven 的 shader property / skybox / alpha-cutoff 解析
+2. schema-driven 与 depth-style 两类逐材质常量 payload 组装
+3. material buffer binding 到 `MaterialBufferResourceView` 的解析
+4. `MeshRendererComponent` / `Mesh` / `VisibleRenderItem` 的最终材质与 render queue 解析
+5. builtin pass 匹配
 
 ## 关键 helper
 
+- `IsMaterialBufferResourceType(...)`
 - `FindShaderPropertyBySemantic(...)`
 - `ResolveBuiltinBaseColorFactor(...)`
 - `ResolveBuiltinBaseColorTexture(...)`
@@ -42,14 +45,14 @@
 - `ResolveSkyboxRotationDegrees(...)`
 - `BuildBuiltinSkyboxMaterialData(...)`
 - `ResolveSchemaMaterialConstantPayload(...)`
+- `BuildBuiltinDepthStyleMaterialConstants(...)`
+- `ResolveBuiltinDepthStyleMaterialConstantPayload(...)`
+- `TryResolveMaterialBufferResourceView(...)`
 - `ResolveMaterial(...)`
 - `TryResolveRenderQueueTagValue(...)`
 - `TryResolveShaderPassRenderQueue(...)`
 - `ResolveMaterialRenderQueue(...)`
 - `IsTransparentRenderQueue(...)`
-- `HasLegacyMaterialBuiltinPassHints(...)`
-- `LegacyMaterialBuiltinPassHintsMatch(...)`
-- `CanUseLegacyMaterialPassFallback(...)`
 - `MatchesBuiltinPass(...)`
 
 ## 当前实现边界
@@ -57,13 +60,18 @@
 - 它只负责材质语义解析，不直接创建 descriptor set 或 pipeline state。
 - `ResolveSchemaMaterialConstantPayload(...)` 暴露的是借用视图，不负责重新打包或持有内存；只有常量布局和常量 buffer 都非空时才会返回有效 payload。
 - `MaterialConstantPayloadView::IsValid()` 还要求 `layout.size == size`，因此文档使用时应把它视为“布局与字节载荷配对成功”的结果，而不只是 data 指针非空。
+- `ResolveBuiltinDepthStyleMaterialConstantPayload(...)` 返回的 view 同样是借用视图；底层数据来自调用方提供的 `outConstants` 与 `outLayout`。
+- `MaterialBufferResourceView` 当前只覆盖 structured/raw buffer 的 SRV / UAV 视图，不负责 texture 或 sampler 资源。
+- `TryResolveMaterialBufferResourceView(...)` 只有在 `binding.resourceType` 属于 material buffer 类型、材质中存在同名 buffer binding 且 stride / dimension 合法时才会成功。
+- `ResolveMaterial(...)` 当前按“精确材质槽位 -> mesh 默认材质槽位 -> slot 0 回退”的顺序解析最终材质。
 - `ResolveMaterialRenderQueue(...)` 当前优先尊重材质自身 `renderQueue` 覆盖；只有它仍等于默认 `Geometry` 队列时，才会继续读取显式 `shaderPass` 或 shader pass `Queue` tag。
 - `ResolveSkyboxTextureMode(...)` 先尝试 panoramic，再尝试 cubemap；如果两者都能解析到，当前会优先返回 `Panoramic`。
-- `MatchesBuiltinPass(...)` 会先看 shader 是否已经声明显式 builtin metadata；只有缺少这层 metadata 时，才会回退到 `Material::GetShaderPass()` / `LightMode` 这套兼容提示，并最终把完全无提示的材质视作 `ForwardLit`。
+- `MatchesBuiltinPass(...)` 当前只遍历 shader 的 `ShaderPass` 列表，并把真正的匹配规则委托给 [BuiltinPassMetadataUtils](../../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) 的 `ShaderPassMatchesBuiltinPass(...)`。
 
 ## 相关文档
 
 - [Materials](../Materials.md)
 - [RenderMaterialStateUtils](../RenderMaterialStateUtils/RenderMaterialStateUtils.md)
 - [Builtin](../../Builtin/Builtin.md)
+- [BuiltinPassMetadataUtils](../../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md)
 - [RenderMaterialUtility](../../RenderMaterialUtility/RenderMaterialUtility.md)

docs/api/_meta/rebuild-status.md

@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-04-10 17:30:33`
+**生成时间**: `2026-04-10 17:36:16`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`