docs: sync render material payload docs

docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md

@@ -34,6 +34,11 @@
 - `BaseColorTexture`：可选，且必须是唯一的 `Texture2D` 或 `TextureCube`。
 - `LinearClampSampler`：可选，且必须是唯一的 sampler。
 
+其中 `Material` 语义当前不是固定写死成某个历史布局。渲染时会先通过
+`ResolveSchemaMaterialConstantPayload(material)` 取得
+`Material::GetConstantBufferData()` 的字节视图；只有拿不到有效 payload 时，
+才会回退到内部 `FallbackPerMaterialConstants { baseColorFactor }`。
+
 布局构建阶段遇到以下情况会直接记录错误并拒绝创建该 pass layout：
 
 - 未知语义。
@@ -56,7 +61,9 @@
 
 - [BuildInputLayout](BuildInputLayout.md) 现在明确使用 `POSITION=float3`、`NORMAL=float3`、`TEXCOORD=float2`，与 `StaticMeshVertex` 对齐。
 - 材质贴图解析通过 `ResolveBuiltinBaseColorTexture(material)` 进入 builtin base-color 语义，不再依赖旧文档里的“按若干名字猜测纹理”说法。
-- 逐物体常量来自 `PerObjectConstants`；逐材质常量目前只写入 `baseColorFactor`。
+- 逐物体常量来自 `PerObjectConstants`。
+- 逐材质常量优先来自 `ResolveSchemaMaterialConstantPayload(material)` 暴露的 schema-driven payload；
+  如果 view 无效，才回退到内部 `FallbackPerMaterialConstants { baseColorFactor }`。
 - 采样器和 1x1 白色 fallback 纹理在初始化后长期复用；具体 `Texture` 和 `Mesh` 的 GPU 资源则由 [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md) 按需上传。
 
 ## 当前限制

docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md

@@ -35,7 +35,10 @@ bool Render(
 2. 写入 `PerObjectConstants`，其中包含投影矩阵、视图矩阵、`localToWorld`、逆矩阵和主方向光数据。
 3. 基于材质解析实际要使用的 shader/pass。
 4. 获取或创建该 `(shader*, passName)` 对应的 `PassResourceLayout`。
-5. 解析 base-color 纹理视图与逐材质常量。
+5. 先解析逐材质常量 payload：
+   - 优先用 `ResolveSchemaMaterialConstantPayload(material)` 取得 schema-driven 字节视图。
+   - 若 view 无效，则用 `BuildBuiltinForwardMaterialData(material)` 构造仅含 `baseColorFactor` 的 fallback 常量。
+   - base-color 纹理视图仍单独通过 `ResolveBuiltinBaseColorTexture(material)` 解析。
 6. 逐 set 绑定 descriptor：
    - 含 `PerObject / Material / Texture` 的 set 走动态 descriptor set 缓存。
    - 只含 sampler 的 set 走静态 descriptor set 缓存。

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

@@ -14,7 +14,7 @@ BuiltinForwardMaterialData BuildBuiltinForwardMaterialData(const Resources::Mate
 
 ## 作用
 
-把 builtin forward 当前真正消费的材质常量打包成 `BuiltinForwardMaterialData`。
+构造 builtin forward 兼容路径使用的 `BuiltinForwardMaterialData`。
 
 ## 当前实现行为
 
@@ -24,13 +24,19 @@ BuiltinForwardMaterialData BuildBuiltinForwardMaterialData(const Resources::Mate
 2. 用 [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md) 填充 `baseColorFactor`
 3. 返回结果
 
-也就是说，当前 builtin forward 材质常量块里只公开收口了颜色因子，没有把纹理、采样器或其它材质属性打进这个 struct。
+也就是说，这个 helper 当前只负责兼容路径里的颜色因子，
+不会把纹理、采样器或其它 schema-driven 材质属性打进这个 struct。
 
 ## 当前语义边界
 
-- 这是 builtin forward 私有契约的一部分，不是通用材质序列化格式。
+- 这是 builtin forward 兼容契约的一部分，不是通用材质序列化格式。
+- `BuiltinForwardPipeline` 现在会优先用
+  [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
+  直接消费 `Material::GetConstantBufferData()`；只有拿不到有效 payload 时，
+  才会回退到这条 helper 生成的 [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md)。
 - 贴图绑定不在这里返回；调用方仍需单独用 [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 解析。
-- 如果未来 builtin forward 的 per-material 常量扩展，这个 helper 和 `BuiltinForwardMaterialData` 也会一起扩展。
+- 如果未来 builtin forward 的兼容 fallback 常量扩展，
+  这个 helper 和 [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) 也会一起扩展。
 
 ## 测试覆盖
 
@@ -38,6 +44,8 @@ BuiltinForwardMaterialData BuildBuiltinForwardMaterialData(const Resources::Mate
 
 ## 相关文档
 
+- [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md)
+- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
 - [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md)
 - [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md)
 - [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)

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

@@ -0,0 +1,43 @@
+# BuiltinForwardMaterialData
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `struct`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+**描述**: `BuiltinForwardPipeline` 在拿不到 schema-driven 材质常量 payload 时使用的兼容逐材质常量结构。
+
+## 概述
+
+`BuiltinForwardMaterialData` 不是通用 `Material` 常量缓冲格式。  
+它当前只描述 builtin forward 兼容路径里最小的一份逐材质数据：`baseColorFactor`。
+
+[BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 负责生成它。  
+按当前 `BuiltinForwardPipeline` 实现，只有当
+[ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) 返回无效 view 时，
+管线才会把这份数据拷贝进内部 `FallbackPerMaterialConstants`，再写入 `Material` 语义的 constant buffer。
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `baseColorFactor` | `Math::Vector4` | builtin forward 兼容路径当前保留的颜色因子。 |
+
+## 当前语义边界
+
+- 它不拥有 GPU 资源，也不包含纹理、采样器或其它 schema-driven 材质字段。
+- 它不是序列化格式，也不保证与任意 shader 的 `Material` constant buffer 布局完全一致。
+- shader schema payload 可用时，渲染管线会优先直接消费 `Material::GetConstantBufferData()`。
+
+## 当前使用位置
+
+- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 负责从 `Material` 解析并生成它。
+- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 只在 schema payload 缺失时使用它作为 fallback。
+
+## 相关文档
+
+- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md)
+- [MaterialConstantPayloadView](MaterialConstantPayloadView.md)
+- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
+- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)

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

@@ -0,0 +1,50 @@
+# MaterialConstantPayloadView
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `struct`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+**描述**: 指向 schema-driven 材质常量缓冲字节的非 owning 视图，用于把 `Material::GetConstantBufferData()` 直接写入渲染 descriptor set。
+
+## 概述
+
+`MaterialConstantPayloadView` 只是一个轻量视图，不负责构造、复制或持有常量缓冲。  
+按当前实现，它通常由 [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) 返回，
+直接指向 `Material` 内部的 `constantBufferData` 数组。
+
+`BuiltinForwardPipeline` 会把它传给 `GetOrCreateDynamicDescriptorSet(...)`，并在需要 `Material`
+constant buffer 的 set 上调用 `WriteConstant(binding, data, size)` 写入 descriptor set。
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data` | `const void*` | 指向常量缓冲字节首地址。 |
+| `size` | `size_t` | 当前 payload 字节数。 |
+
+## `IsValid()` 语义
+
+- 当前判定条件是 `data != nullptr && size > 0`。
+- `Material` 没有 shader、没有生成常量缓冲，或常量缓冲为空时，resolver 会返回无效 view。
+- 无效 view 本身不是错误；当前 `BuiltinForwardPipeline` 会在这种情况下回退到 `BuiltinForwardMaterialData`。
+
+## 所有权与生命周期
+
+- 它不拥有 `data` 指向的内存。
+- 当前 view 指向 `Material::GetConstantBufferData()` 的内部数组；`Material` 销毁或常量缓冲重建后，旧 view 不再可靠。
+- 调用方应把它当成“本次绘制阶段即时消费”的借用数据，而不是长期缓存的稳定块。
+
+## 测试覆盖
+
+`tests/Rendering/unit/test_render_scene_extractor.cpp` 当前验证了：  
+当 `Material` 绑定 shader 并生成 `_BaseColor` 常量时，
+[ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) 会返回有效的 `16` 字节 payload view。
+
+## 相关文档
+
+- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
+- [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md)
+- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
+- [RenderMaterialUtility](RenderMaterialUtility.md)

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

@@ -6,16 +6,17 @@
 
 **头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
 
-**描述**: 把 `Material` 的 pass 元数据、builtin forward 材质契约、render queue 和 render state 解释成渲染提取与图形管线可直接使用的规则。
+**描述**: 把 `Material` 的 pass 元数据、逐材质常量契约、builtin forward 兼容语义、render queue 和 render state 解释成渲染提取与图形管线可直接使用的规则。
 
 ## 概览
 
-`RenderMaterialUtility.h` 不是运行时对象，而是一组内联规则函数。它当前承担四类工作：
+`RenderMaterialUtility.h` 不是运行时对象，而是一组内联规则函数。它当前承担五类工作：
 
 1. 解析“这次绘制真正要用哪份材质”。
 2. 判断该材质是否匹配某个 builtin pass。
-3. 解析 builtin forward 路径要消费的 base-color 因子与贴图。
-4. 把材质里的 `MaterialRenderState` 翻译成 `RHI::GraphicsPipelineDesc` 需要的状态结构。
+3. 暴露 shader schema 驱动的逐材质常量 payload 视图。
+4. 解析 builtin forward 兼容路径要消费的 base-color 因子与贴图。
+5. 把材质里的 `MaterialRenderState` 翻译成 `RHI::GraphicsPipelineDesc` 需要的状态结构。
 
 它位于 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)、[BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 和 object-id 相关 pass 之间，是当前材质语义进入渲染链路的关键翻译层。
 
@@ -49,13 +50,14 @@
 
 全部接进了渲染路径。
 
-## builtin forward 材质契约
+## 逐材质常量契约
 
-同一个头文件里还公开了 `BuiltinForwardMaterialData`：
+同一个头文件里当前公开了两类逐材质数据：
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `baseColorFactor` | `Math::Vector4` | builtin forward 当前消费的颜色因子。 |
+| 类型 | 说明 |
+|------|------|
+| [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) | builtin forward 的兼容 fallback 常量结构，当前只收口 `baseColorFactor`。 |
+| [MaterialConstantPayloadView](MaterialConstantPayloadView.md) | 指向 `Material::GetConstantBufferData()` 的非 owning 字节视图。 |
 
 对应 helper 的当前职责是：
 
@@ -64,9 +66,15 @@
 - [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md)
   解析 base color 贴图，优先走 shader semantic，再回退到 `_MainTex`、`baseColorTexture` 等常见别名。
 - [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md)
-  把当前 builtin forward 真正要消费的材质常量打包出来。
+  构造 builtin forward 的兼容 fallback 常量。
+- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
+  直接暴露当前 `Material` 已按 shader schema 生成的常量缓冲字节视图。
 
-这组 helper 当前直接被 `BuiltinForwardPipeline` 用来填充 per-material 常量和纹理绑定。
+`BuiltinForwardPipeline` 当前会优先用 [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
+把 `Material::GetConstantBufferData()` 写入 `Material` 语义的 constant buffer 绑定；只有拿不到有效 payload 时，
+才回退到 [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 生成的
+`baseColorFactor` fallback。base-color 贴图仍由
+[ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 单独解析。
 
 ## render state 映射
 
@@ -81,10 +89,20 @@
 
 ## 当前实现边界
 
-- 它只处理 pass 归类、builtin forward 材质契约、render queue 和固定渲染状态，不负责 shader variant、keyword 或多 pass 编排。
+- 它只处理 pass 归类、逐材质常量 payload 解析、builtin forward 兼容契约、render queue 和固定渲染状态，不负责 shader variant、keyword 或多 pass 编排。
 - 没有显式元数据的材质会默认进入 `ForwardLit`，这是一种“先让基础路径可用”的保守回退。
 - `MatchesBuiltinPass(nullptr, pass)` 只有在 `pass == ForwardLit` 时才返回 `true`。
-- `BuildBuiltinForwardMaterialData()` 当前只打包 `baseColorFactor`；贴图仍由调用方单独通过 [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 解析。
+- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) 只是暴露当前
+  `Material::GetConstantBufferData()` 的借用视图，不负责重新打包、补齐字段或管理内存所有权。
+- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 当前仍只收口 `baseColorFactor`，
+  但它已经退到 builtin forward 的兼容 fallback 路径，不再代表 `Material` 语义 constant buffer 的主路径。
+
+## 公开类型
+
+| 类型 | 说明 |
+|------|------|
+| [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) | builtin forward 的兼容 fallback 常量结构。 |
+| [MaterialConstantPayloadView](MaterialConstantPayloadView.md) | schema-driven 逐材质常量 payload 的借用视图。 |
 
 ## 公开函数
 
@@ -96,7 +114,8 @@
 | [MatchesBuiltinPass](MatchesBuiltinPass.md) | 判断材质是否匹配某个 builtin pass。 |
 | [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md) | 解析 builtin forward 使用的 base color 因子。 |
 | [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) | 解析 builtin forward 使用的 base color 贴图。 |
-| [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) | 打包 builtin forward 当前消费的材质常量。 |
+| [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) | 构造 builtin forward 的兼容 fallback 常量。 |
+| [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) | 返回当前 shader schema 驱动的逐材质常量 payload 视图。 |
 | [BuildRasterizerState](BuildRasterizerState.md) | 构建栅格化状态。 |
 | [BuildBlendState](BuildBlendState.md) | 构建混合状态。 |
 | [BuildDepthStencilState](BuildDepthStencilState.md) | 构建深度状态。 |

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

@@ -0,0 +1,54 @@
+# ResolveSchemaMaterialConstantPayload
+
+**命名空间**: `XCEngine::Rendering`
+
+**类型**: `function`
+
+**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
+
+## 签名
+
+```cpp
+MaterialConstantPayloadView ResolveSchemaMaterialConstantPayload(const Resources::Material* material);
+```
+
+## 作用
+
+返回当前 `Material` 已按 shader schema 生成的逐材质 constant-buffer payload 视图。
+
+## 当前实现行为
+
+当前实现按下面顺序判定：
+
+1. 如果 `material == nullptr`，返回无效 view。
+2. 如果 `material->GetShader() == nullptr`，返回无效 view。
+3. 读取 `material->GetConstantBufferData()`。
+4. 如果常量缓冲为空，返回无效 view。
+5. 否则返回 `{ constantBufferData.Data(), constantBufferData.Size() }`。
+
+## 当前语义要点
+
+- 这条 helper 不做重新打包，也不推断 fallback 字段；它只暴露 `Material` 当前已经准备好的字节块。
+- 返回值是借用视图，不拥有 `Material` 内部数组。
+- 它只处理 `Material` constant buffer payload，不解析纹理、采样器或 render state。
+
+## 当前调用链
+
+- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 在绘制可见项时先调用它。
+- 如果 view 无效，`BuiltinForwardPipeline` 才会回退到
+  [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 生成的
+  `baseColorFactor` fallback。
+
+## 测试覆盖
+
+`tests/Rendering/unit/test_render_scene_extractor.cpp` 中的
+`RenderMaterialUtility_Test.ExposesSchemaDrivenMaterialConstantPayload`
+当前验证了它会返回有效 payload，并且字节内容与材质默认 `_BaseColor` 常量一致。
+
+## 相关文档
+
+- [MaterialConstantPayloadView](MaterialConstantPayloadView.md)
+- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md)
+- [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md)
+- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
+- [RenderMaterialUtility](RenderMaterialUtility.md)