docs: sync render material payload docs

This commit is contained in:
2026-04-03 16:14:15 +08:00
parent 2c2e1fab1c
commit 545112b497
7 changed files with 204 additions and 20 deletions

View File

@@ -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)