diff --git a/docs/api/XCEngine/Rendering/Materials/Materials.md b/docs/api/XCEngine/Rendering/Materials/Materials.md index b9c35dac..6ae4e117 100644 --- a/docs/api/XCEngine/Rendering/Materials/Materials.md +++ b/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 解析 ## 相关文档 diff --git a/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md b/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md index 878ac661..423ad0ba 100644 --- a/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md +++ b/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) diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md index 3ca6dd8c..d3508da1 100644 --- a/docs/api/_meta/rebuild-status.md +++ b/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`