diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md index 2930300d..df8c7182 100644 --- a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md +++ b/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) 按需上传。 ## 当前限制 diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md index 60492c7c..521e29e5 100644 --- a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md +++ b/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 缓存。 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBuiltinForwardMaterialData.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBuiltinForwardMaterialData.md index 4ef89c95..6b5e7aac 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBuiltinForwardMaterialData.md +++ b/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) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinForwardMaterialData.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinForwardMaterialData.md new file mode 100644 index 00000000..2eae09fb --- /dev/null +++ b/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) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantPayloadView.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantPayloadView.md new file mode 100644 index 00000000..8bf22c4a --- /dev/null +++ b/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) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md index 638dee97..820b7262 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md +++ b/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) | 构建深度状态。 | diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveSchemaMaterialConstantPayload.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveSchemaMaterialConstantPayload.md new file mode 100644 index 00000000..d84b7b6f --- /dev/null +++ b/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)