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

# BuildBuiltinForwardMaterialData

**命名空间**: `XCEngine::Rendering`

**类型**: `function`

**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`

## 签名

```cpp
BuiltinForwardMaterialData BuildBuiltinForwardMaterialData(const Resources::Material* material);
```

## 作用

构造 builtin forward 兼容路径使用的 `BuiltinForwardMaterialData`。

## 当前实现行为

当前实现非常窄，只做一件事：

1. 构造默认的 `BuiltinForwardMaterialData`
2. 用 [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md) 填充 `baseColorFactor`
3. 返回结果

也就是说，这个 helper 当前只负责兼容路径里的颜色因子，
不会把纹理、采样器或其它 schema-driven 材质属性打进这个 struct。

## 当前语义边界

- 这是 builtin forward 兼容契约的一部分，不是通用材质序列化格式。
- `BuiltinForwardPipeline` 现在会优先用
  [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
  直接消费 `Material::GetConstantBufferData()`；只有拿不到有效 payload 时，
  才会回退到这条 helper 生成的 [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md)。
- 贴图绑定不在这里返回；调用方仍需单独用 [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 解析。
- 如果未来 builtin forward 的兼容 fallback 常量扩展，
  这个 helper 和 [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) 也会一起扩展。

## 测试覆盖

`tests/Rendering/unit/test_render_scene_extractor.cpp` 当前验证了它会按 canonical 名称和别名路径正确写入 `baseColorFactor`。

## 相关文档

- [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md)
- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md)
- [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md)
- [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md)
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
- [RenderMaterialUtility](RenderMaterialUtility.md)