From dc5b5d2c48b2a2c376977042bf88bd314efa097d Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Sat, 4 Apr 2026 17:41:50 +0800 Subject: [PATCH] Archive shader material closure plan --- .../Resources/Material/Material/ClearTags.md | 25 +++ .../Material/Material/Constructor.md | 34 ++-- .../Resources/Material/Material/Destructor.md | 26 +-- .../Material/Material/FindConstantField.md | 25 +++ .../Resources/Material/Material/GetBool.md | 26 +-- .../Material/Material/GetChangeVersion.md | 26 +++ .../Material/GetConstantBufferData.md | 28 ++- .../Material/Material/GetConstantLayout.md | 26 +++ .../Resources/Material/Material/GetFloat.md | 27 +-- .../Resources/Material/Material/GetFloat2.md | 26 +-- .../Resources/Material/Material/GetFloat3.md | 26 +-- .../Resources/Material/Material/GetFloat4.md | 26 +-- .../Resources/Material/Material/GetGUID.md | 26 +-- .../Resources/Material/Material/GetInt.md | 26 +-- .../Material/Material/GetMemorySize.md | 36 ++-- .../Resources/Material/Material/GetName.md | 26 +-- .../Resources/Material/Material/GetPath.md | 26 +-- .../Material/Material/GetProperties.md | 27 +++ .../Material/Material/GetRenderQueue.md | 21 +++ .../Material/Material/GetRenderState.md | 21 +++ .../Resources/Material/Material/GetShader.md | 20 ++ .../Material/Material/GetShaderPass.md | 20 ++ .../Resources/Material/Material/GetTag.md | 21 +++ .../Material/Material/GetTagCount.md | 21 +++ .../Resources/Material/Material/GetTagName.md | 20 ++ .../Material/Material/GetTagValue.md | 20 ++ .../Resources/Material/Material/GetTags.md | 21 +++ .../Material/Material/GetTextureBindings.md | 22 +++ .../Resources/Material/Material/GetType.md | 25 +-- .../Material/Material/HasProperty.md | 27 +-- .../Resources/Material/Material/HasTag.md | 21 +++ .../Resources/Material/Material/IsValid.md | 27 ++- .../Resources/Material/Material/Material.md | 176 +++++++++++------- .../Material/Material/MaterialBlendFactor.md | 39 ++++ .../Material/Material/MaterialBlendOp.md | 27 +++ .../Material/MaterialComparisonFunc.md | 31 +++ .../Material/MaterialConstantFieldDesc.md | 34 ++++ .../Material/Material/MaterialCullMode.md | 26 +++ .../Material/Material/MaterialProperty.md | 28 +++ .../Material/Material/MaterialPropertyType.md | 35 ++++ .../Material/Material/MaterialRenderQueue.md | 34 ++++ .../Material/Material/MaterialRenderState.md | 63 +++++++ .../Material/Material/MaterialTagEntry.md | 26 +++ .../Material/MaterialTextureBinding.md | 35 ++++ .../Material/PendingTextureLoadState.md | 27 +++ .../Material/RecalculateMemorySize.md | 24 +++ .../Resources/Material/Material/Release.md | 35 ++-- .../Material/Material/RemoveProperty.md | 44 +++-- .../Resources/Material/Material/RemoveTag.md | 27 +++ .../Resources/Material/Material/SetBool.md | 31 ++- .../Resources/Material/Material/SetFloat.md | 32 ++-- .../Resources/Material/Material/SetFloat2.md | 31 ++- .../Resources/Material/Material/SetFloat3.md | 31 ++- .../Resources/Material/Material/SetFloat4.md | 31 ++- .../Resources/Material/Material/SetInt.md | 31 ++- .../Material/Material/SetRenderQueue.md | 34 ++++ .../Material/Material/SetRenderState.md | 32 ++++ .../Material/Material/SetShaderPass.md | 29 +++ .../Resources/Material/Material/SetTag.md | 27 +++ .../Material/MaterialLoader/Constructor.md | 31 +-- .../Material/MaterialLoader/Destructor.md | 30 +-- .../MaterialLoader/GetDefaultSettings.md | 31 +-- .../MaterialLoader/GetResourceType.md | 30 +-- .../MaterialLoader/GetSupportedExtensions.md | 42 +++-- ...r与Material系统下一阶段计划_完成归档_2026-04-04.md} | 7 +- engine/src/Resources/Shader/ShaderLoader.cpp | 14 +- tests/Resources/Shader/test_shader_loader.cpp | 3 +- 67 files changed, 1429 insertions(+), 574 deletions(-) create mode 100644 docs/api/XCEngine/Resources/Material/Material/ClearTags.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/FindConstantField.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetChangeVersion.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetConstantLayout.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetProperties.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetRenderQueue.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetRenderState.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetShader.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetShaderPass.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetTag.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetTagCount.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetTagName.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetTagValue.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetTags.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/GetTextureBindings.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/HasTag.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialConstantFieldDesc.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialProperty.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialPropertyType.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialRenderQueue.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialTagEntry.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/MaterialTextureBinding.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/PendingTextureLoadState.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/RecalculateMemorySize.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/RemoveTag.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/SetRenderQueue.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/SetRenderState.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/SetShaderPass.md create mode 100644 docs/api/XCEngine/Resources/Material/Material/SetTag.md rename docs/plan/{Shader与Material系统下一阶段计划.md => used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md} (95%) diff --git a/docs/api/XCEngine/Resources/Material/Material/ClearTags.md b/docs/api/XCEngine/Resources/Material/Material/ClearTags.md new file mode 100644 index 00000000..b7d60cb8 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/ClearTags.md @@ -0,0 +1,25 @@ +# Material::ClearTags + +```cpp +void ClearTags(); +``` + +## 作用 + +清空当前全部材质 tag。 + +## 当前行为 + +- 直接调用 `m_tags.Clear()`。 +- 随后调用 `MarkChanged(false)`，即使原本已经为空也会推进 `changeVersion`。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前覆盖了多 tag 清空后的计数与存在性结果。 + +## 相关文档 + +- [Material](Material.md) +- [SetTag](SetTag.md) +- [RemoveTag](RemoveTag.md) +- [GetTagCount](GetTagCount.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/Constructor.md b/docs/api/XCEngine/Resources/Material/Material/Constructor.md index eca5b6d2..8e7fdb5c 100644 --- a/docs/api/XCEngine/Resources/Material/Material/Constructor.md +++ b/docs/api/XCEngine/Resources/Material/Material/Constructor.md @@ -1,28 +1,32 @@ -# Material::Material() - -构造对象。 +# Material::Material ```cpp Material(); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造一个默认空材质对象。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** +- 当前实现是默认构造，没有额外初始化逻辑 +- 主要状态依赖头文件里的成员默认值: + - `renderQueue = Geometry` + - `m_changeVersion = 1` + - 其余资源身份、属性、binding 和常量缓冲均为空/默认值 -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; -} -``` +- 新构造的 `Material` 默认不是有效资源；`IsValid()` 初始为 `false` +- 只有后续经过资源加载器初始化或显式写入内容后，它才会逐步承载实际材质状态 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 的 `Material.DefaultConstructor` 当前验证了默认类型、`IsValid()` 初值和 `GetMemorySize()` 初值。 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [IsValid](IsValid.md) +- [GetMemorySize](GetMemorySize.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/Destructor.md b/docs/api/XCEngine/Resources/Material/Material/Destructor.md index 520b40d0..8b1a48eb 100644 --- a/docs/api/XCEngine/Resources/Material/Material/Destructor.md +++ b/docs/api/XCEngine/Resources/Material/Material/Destructor.md @@ -1,29 +1,23 @@ -# Material::~Material() - -销毁对象并释放相关资源。 +# Material::~Material ```cpp virtual ~Material() override; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `Material` 实例。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** +- 当前实现是默认析构函数，没有额外清理逻辑 -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 对象离开作用域时会自动触发析构。 -} -``` +- `Material` 持有的 `ResourceHandle`、容器和字符串会按各自成员语义自动析构 +- 显式状态重置逻辑在 [Release](Release.md) 中，而不在析构函数里 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/FindConstantField.md b/docs/api/XCEngine/Resources/Material/Material/FindConstantField.md new file mode 100644 index 00000000..bc3d2dc2 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/FindConstantField.md @@ -0,0 +1,25 @@ +# Material::FindConstantField + +```cpp +const MaterialConstantFieldDesc* FindConstantField(const Containers::String& name) const; +``` + +## 作用 + +按名称查找当前 constant layout 中的字段描述。 + +## 当前行为 + +- 对 `m_constantLayout` 做线性遍历。 +- 命中时返回字段指针。 +- 未命中时返回 `nullptr`。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前显式验证了 `beta` 字段的查找结果。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialConstantFieldDesc](MaterialConstantFieldDesc.md) +- [GetConstantLayout](GetConstantLayout.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetBool.md b/docs/api/XCEngine/Resources/Material/Material/GetBool.md index 086bb3af..f58eb275 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetBool.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetBool.md @@ -1,31 +1,19 @@ # Material::GetBool -获取相关状态或对象。 - ```cpp bool GetBool(const Containers::String& name) const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +读取一个 `Bool` 属性。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetBool(...)。 - (void)object; -} -``` +- 如果存在同名 `Bool` 属性，返回保存的布尔值 +- 否则返回 `false` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetBool](SetBool.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetChangeVersion.md b/docs/api/XCEngine/Resources/Material/Material/GetChangeVersion.md new file mode 100644 index 00000000..e4a32733 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetChangeVersion.md @@ -0,0 +1,26 @@ +# Material::GetChangeVersion + +```cpp +Core::uint64 GetChangeVersion() const; +``` + +## 作用 + +读取当前材质的 mutation 版本号。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_changeVersion`。 +- 默认构造后初始值是 `1`。 +- 大多数公开 setter 最终都会经过内部 `MarkChanged(...)`，从而推进版本号。 +- [Release](Release.md) 当前会把它重置回 `1`。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前验证了数值属性和纹理绑定写入都会推进版本号。 + +## 相关文档 + +- [Material](Material.md) +- [Release](Release.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetConstantBufferData.md b/docs/api/XCEngine/Resources/Material/Material/GetConstantBufferData.md index b48673d7..656eb038 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetConstantBufferData.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetConstantBufferData.md @@ -1,30 +1,26 @@ # Material::GetConstantBufferData -获取相关状态或对象。 - ```cpp const Containers::Array& GetConstantBufferData() const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前材质已经打包好的常量缓冲字节数组视图。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前语义 -**示例：** +- 返回的是内部 `m_constantBufferData` 的只读引用，不做拷贝 +- 这个访问器本身不会触发重新打包 +- 常量缓冲内容的更新由 `SetShader()`、数值属性写入、`RemoveProperty()`、`ClearAllProperties()` 或显式 [UpdateConstantBuffer](UpdateConstantBuffer.md) 触发 -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetConstantBufferData(...)。 - (void)object; -} -``` +- 返回数据只包含当前可打包的数值属性 +- texture / cubemap binding 不会写进这里 +- 调用方如果长期持有这个引用，需要自己保证 `Material` 生命周期与后续修改时机 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetConstantLayout.md b/docs/api/XCEngine/Resources/Material/Material/GetConstantLayout.md new file mode 100644 index 00000000..d5be0210 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetConstantLayout.md @@ -0,0 +1,26 @@ +# Material::GetConstantLayout + +```cpp +const Containers::Array& GetConstantLayout() const; +``` + +## 作用 + +读取当前 packed constant buffer 的布局描述。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_constantLayout` 的常量引用。 +- 这份布局由 [UpdateConstantBuffer](UpdateConstantBuffer.md) 生成和刷新。 +- 有 shader schema 时，顺序跟随 shader property 声明顺序；无 shader schema 时，顺序退回属性名字典序。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前覆盖了无 shader schema 的稳定槽位结果，以及有 shader schema 时的顺序跟随行为。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialConstantFieldDesc](MaterialConstantFieldDesc.md) +- [FindConstantField](FindConstantField.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetFloat.md b/docs/api/XCEngine/Resources/Material/Material/GetFloat.md index f3128907..9d94255c 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetFloat.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetFloat.md @@ -1,31 +1,24 @@ # Material::GetFloat -获取相关状态或对象。 - ```cpp float GetFloat(const Containers::String& name) const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +读取一个 `Float` 属性。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 如果 `m_properties` 中存在同名属性且类型正好是 `Float`，返回其第一个分量 +- 否则返回 `0.0f` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetFloat(...)。 - (void)object; -} -``` +- 它不会尝试做类型转换 +- 对缺失属性、类型不匹配属性和 texture 属性，返回值都一样是 `0.0f` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetFloat](SetFloat.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetFloat2.md b/docs/api/XCEngine/Resources/Material/Material/GetFloat2.md index fb6cda87..2aafa58e 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetFloat2.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetFloat2.md @@ -1,31 +1,19 @@ # Material::GetFloat2 -获取相关状态或对象。 - ```cpp Math::Vector2 GetFloat2(const Containers::String& name) const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +读取一个 `Float2` 属性。 -**返回：** `Math::Vector2` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetFloat2(...)。 - (void)object; -} -``` +- 如果存在同名 `Float2` 属性，返回其前两个分量 +- 否则返回 `Math::Vector2::Zero()` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetFloat2](SetFloat2.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetFloat3.md b/docs/api/XCEngine/Resources/Material/Material/GetFloat3.md index 54b3a5f1..d526d797 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetFloat3.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetFloat3.md @@ -1,31 +1,19 @@ # Material::GetFloat3 -获取相关状态或对象。 - ```cpp Math::Vector3 GetFloat3(const Containers::String& name) const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +读取一个 `Float3` 属性。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetFloat3(...)。 - (void)object; -} -``` +- 如果存在同名 `Float3` 属性，返回其前三个分量 +- 否则返回 `Math::Vector3::Zero()` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetFloat3](SetFloat3.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetFloat4.md b/docs/api/XCEngine/Resources/Material/Material/GetFloat4.md index 8fc1f25a..4278827d 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetFloat4.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetFloat4.md @@ -1,31 +1,19 @@ # Material::GetFloat4 -获取相关状态或对象。 - ```cpp Math::Vector4 GetFloat4(const Containers::String& name) const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +读取一个 `Float4` 属性。 -**返回：** `Math::Vector4` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetFloat4(...)。 - (void)object; -} -``` +- 如果存在同名 `Float4` 属性，返回四个分量 +- 否则返回 `Math::Vector4::Zero()` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetFloat4](SetFloat4.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetGUID.md b/docs/api/XCEngine/Resources/Material/Material/GetGUID.md index bdd45f01..afffa53f 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetGUID.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetGUID.md @@ -1,30 +1,24 @@ # Material::GetGUID -获取相关状态或对象。 - ```cpp ResourceGUID GetGUID() const override; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前材质资源的运行时 `ResourceGUID`。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 头文件内联返回成员 `m_guid` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetGUID(...)。 - (void)object; -} -``` +- 这里返回的是运行时资源 GUID，不是项目资产 `AssetGUID` +- 对由 `ResourceManager` 管理的对象，这个 GUID 通常由加载请求路径生成 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [GetPath](GetPath.md) +- [AssetRef](../../../Core/Asset/AssetRef/AssetRef.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetInt.md b/docs/api/XCEngine/Resources/Material/Material/GetInt.md index 9204d71e..ab897ec9 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetInt.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetInt.md @@ -1,31 +1,19 @@ # Material::GetInt -获取相关状态或对象。 - ```cpp Core::int32 GetInt(const Containers::String& name) const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +读取一个 `Int` 属性。 -**返回：** `Core::int32` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetInt(...)。 - (void)object; -} -``` +- 如果存在同名 `Int` 属性，返回第一个整型分量 +- 否则返回 `0` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetInt](SetInt.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetMemorySize.md b/docs/api/XCEngine/Resources/Material/Material/GetMemorySize.md index 0fe56d61..dc6f1119 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetMemorySize.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetMemorySize.md @@ -1,30 +1,34 @@ # Material::GetMemorySize -获取相关状态或对象。 - ```cpp size_t GetMemorySize() const override; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前 `Material` 记录的估算内存占用。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 头文件内联返回成员 `m_memorySize` -```cpp -#include +## 当前语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetMemorySize(...)。 - (void)object; -} -``` +- 这个值由 `UpdateMemorySize()` 维护 +- 统计范围当前包括: + - 常量缓冲字节数 + - `MaterialRenderState` + - `shaderPass` + - tag、texture binding、property 的结构体和字符串开销 + - `name` / `path` 字符串长度 + +## 关键语义 + +- 它是当前类内部维护的估算值，不是系统级精确分配统计 +- 新构造对象默认返回 `0` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetName.md b/docs/api/XCEngine/Resources/Material/Material/GetName.md index 21cbe634..95fd0dc3 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetName.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetName.md @@ -1,30 +1,24 @@ # Material::GetName -获取相关状态或对象。 - ```cpp const Containers::String& GetName() const override; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前材质资源名。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 头文件内联返回内部成员 `m_name` 的常量引用 -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetName(...)。 - (void)object; -} -``` +- 这里不做拷贝 +- 新构造或已 [Release](Release.md) 的对象通常会返回空字符串 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [GetPath](GetPath.md) +- [GetGUID](GetGUID.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetPath.md b/docs/api/XCEngine/Resources/Material/Material/GetPath.md index 26641622..7c823295 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetPath.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetPath.md @@ -1,30 +1,24 @@ # Material::GetPath -获取相关状态或对象。 - ```cpp const Containers::String& GetPath() const override; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前材质对外暴露的资源路径。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 头文件内联返回内部成员 `m_path` 的常量引用 -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetPath(...)。 - (void)object; -} -``` +- 对由 `ResourceManager` 加载出来的项目材质，这里通常保留的是原始请求路径，而不是 artifact 路径 +- 新构造或已 [Release](Release.md) 的对象通常会返回空字符串 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [GetName](GetName.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetProperties.md b/docs/api/XCEngine/Resources/Material/Material/GetProperties.md new file mode 100644 index 00000000..0e7d7aef --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetProperties.md @@ -0,0 +1,27 @@ +# Material::GetProperties + +```cpp +std::vector GetProperties() const; +``` + +## 作用 + +导出当前材质属性表的值拷贝集合。 + +## 当前行为 + +- 当前实现会从 `m_properties.GetPairs()` 取出所有键值对。 +- 只把 `pair.second` 拷贝进返回的 `std::vector`，不会把 key 额外单独返回。 +- 返回值每次调用都会重新构造。 + +## 关键语义 + +- 这是拷贝导出，不是内部容器引用。 +- 当前不承诺稳定顺序；顺序取决于 `HashMap` 当前 pairs 视图。 +- `AssetDatabase` 当前会用它写出 `.xcmat` 的非纹理属性段。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialProperty](MaterialProperty.md) +- [HasProperty](HasProperty.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetRenderQueue.md b/docs/api/XCEngine/Resources/Material/Material/GetRenderQueue.md new file mode 100644 index 00000000..c3a8551d --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetRenderQueue.md @@ -0,0 +1,21 @@ +# Material::GetRenderQueue + +```cpp +Core::int32 GetRenderQueue() const; +``` + +## 作用 + +读取当前材质的 render queue 整数值。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_renderQueue`。 +- 默认值当前是 `MaterialRenderQueue::Geometry` 对应的整数值。 +- 若调用方使用了整数重载写入自定义队列，这里会原样返回该整数。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialRenderQueue](MaterialRenderQueue.md) +- [SetRenderQueue](SetRenderQueue.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetRenderState.md b/docs/api/XCEngine/Resources/Material/Material/GetRenderState.md new file mode 100644 index 00000000..3f05b844 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetRenderState.md @@ -0,0 +1,21 @@ +# Material::GetRenderState + +```cpp +const MaterialRenderState& GetRenderState() const; +``` + +## 作用 + +读取当前材质的 render state 常量引用。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_renderState` 的常量引用。 +- 默认值当前对应 [MaterialRenderState](MaterialRenderState.md) 的默认成员初始化状态。 +- 调用方不应在后续材质写操作后继续持久保存这份引用。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialRenderState](MaterialRenderState.md) +- [SetRenderState](SetRenderState.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetShader.md b/docs/api/XCEngine/Resources/Material/Material/GetShader.md new file mode 100644 index 00000000..acc7ff4d --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetShader.md @@ -0,0 +1,20 @@ +# Material::GetShader + +```cpp +class Shader* GetShader() const; +``` + +## 作用 + +读取当前绑定的 shader 裸指针视图。 + +## 当前语义 + +- 它只是 `m_shader.Get()` 的直通只读入口。 +- 未绑定 shader 时返回 `nullptr`。 +- 不转移所有权，也不增加引用计数。 + +## 相关文档 + +- [Material](Material.md) +- [SetShader](SetShader.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetShaderPass.md b/docs/api/XCEngine/Resources/Material/Material/GetShaderPass.md new file mode 100644 index 00000000..55c5b492 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetShaderPass.md @@ -0,0 +1,20 @@ +# Material::GetShaderPass + +```cpp +const Containers::String& GetShaderPass() const; +``` + +## 作用 + +读取当前显式指定的 shader pass 名。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_shaderPass` 的常量引用。 +- 默认值是空字符串。 +- 空字符串不代表失败，只表示“未显式绑定 pass 名”。 + +## 相关文档 + +- [Material](Material.md) +- [SetShaderPass](SetShaderPass.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetTag.md b/docs/api/XCEngine/Resources/Material/Material/GetTag.md new file mode 100644 index 00000000..44686387 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetTag.md @@ -0,0 +1,21 @@ +# Material::GetTag + +```cpp +Containers::String GetTag(const Containers::String& name) const; +``` + +## 作用 + +按名称读取一个 tag 的值。 + +## 当前行为 + +- 对 `m_tags` 做线性遍历。 +- 命中时返回对应 `value` 的拷贝。 +- 未命中时返回空 `Containers::String()`。 + +## 相关文档 + +- [Material](Material.md) +- [SetTag](SetTag.md) +- [HasTag](HasTag.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetTagCount.md b/docs/api/XCEngine/Resources/Material/Material/GetTagCount.md new file mode 100644 index 00000000..5415e27b --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetTagCount.md @@ -0,0 +1,21 @@ +# Material::GetTagCount + +```cpp +Core::uint32 GetTagCount() const; +``` + +## 作用 + +返回当前 tag 数量。 + +## 当前语义 + +- 头文件内联实现为 `static_cast(m_tags.Size())`。 +- 计数对象是内部 tag 数组，而不是某个哈希表视图。 + +## 相关文档 + +- [Material](Material.md) +- [GetTags](GetTags.md) +- [GetTagName](GetTagName.md) +- [GetTagValue](GetTagValue.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetTagName.md b/docs/api/XCEngine/Resources/Material/Material/GetTagName.md new file mode 100644 index 00000000..2c8293a1 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetTagName.md @@ -0,0 +1,20 @@ +# Material::GetTagName + +```cpp +Containers::String GetTagName(Core::uint32 index) const; +``` + +## 作用 + +按索引读取 tag 名。 + +## 当前行为 + +- `index < m_tags.Size()` 时返回对应 tag 名的拷贝。 +- 越界时返回空 `Containers::String()`。 + +## 相关文档 + +- [Material](Material.md) +- [GetTagCount](GetTagCount.md) +- [GetTagValue](GetTagValue.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetTagValue.md b/docs/api/XCEngine/Resources/Material/Material/GetTagValue.md new file mode 100644 index 00000000..95d63aa0 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetTagValue.md @@ -0,0 +1,20 @@ +# Material::GetTagValue + +```cpp +Containers::String GetTagValue(Core::uint32 index) const; +``` + +## 作用 + +按索引读取 tag 值。 + +## 当前行为 + +- `index < m_tags.Size()` 时返回对应 tag 值的拷贝。 +- 越界时返回空 `Containers::String()`。 + +## 相关文档 + +- [Material](Material.md) +- [GetTagCount](GetTagCount.md) +- [GetTagName](GetTagName.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetTags.md b/docs/api/XCEngine/Resources/Material/Material/GetTags.md new file mode 100644 index 00000000..9e6410f6 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetTags.md @@ -0,0 +1,21 @@ +# Material::GetTags + +```cpp +const Containers::Array& GetTags() const; +``` + +## 作用 + +读取内部 tag 数组的常量引用。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_tags` 的常量引用。 +- 保留的是当前数组顺序；但由于 [RemoveTag](RemoveTag.md) 采用 swap-remove，删除操作后顺序不保证稳定。 +- 调用方不应在后续材质写操作后继续持久保存这份引用。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialTagEntry](MaterialTagEntry.md) +- [GetTagCount](GetTagCount.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetTextureBindings.md b/docs/api/XCEngine/Resources/Material/Material/GetTextureBindings.md new file mode 100644 index 00000000..c414c519 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/GetTextureBindings.md @@ -0,0 +1,22 @@ +# Material::GetTextureBindings + +```cpp +const Containers::Array& GetTextureBindings() const; +``` + +## 作用 + +读取内部 texture binding 数组的常量引用。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_textureBindings` 的常量引用。 +- 这只是元数据视图，不会触发懒加载，也不会主动 resolve pending load。 +- 调用方不应在后续材质写操作后继续持久保存这份引用。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialTextureBinding](MaterialTextureBinding.md) +- [GetTextureBindingCount](GetTextureBindingCount.md) +- [GetTextureBindingTexture](GetTextureBindingTexture.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/GetType.md b/docs/api/XCEngine/Resources/Material/Material/GetType.md index 42a9748d..da60cf9e 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetType.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetType.md @@ -1,30 +1,23 @@ # Material::GetType -获取相关状态或对象。 - ```cpp ResourceType GetType() const override; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前资源对象的资源类型标识。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 头文件内联返回固定值 `ResourceType::Material` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::GetType(...)。 - (void)object; -} -``` +- 这不是从运行时状态推导出来的动态结果 +- 即使对象当前还未初始化或已被 [Release](Release.md) 重置，这个访问器仍返回 `ResourceType::Material` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/HasProperty.md b/docs/api/XCEngine/Resources/Material/Material/HasProperty.md index b6a84c4e..db714220 100644 --- a/docs/api/XCEngine/Resources/Material/Material/HasProperty.md +++ b/docs/api/XCEngine/Resources/Material/Material/HasProperty.md @@ -1,31 +1,24 @@ # Material::HasProperty -判断是否具备指定状态或能力。 - ```cpp bool HasProperty(const Containers::String& name) const; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +判断当前材质的属性表里是否存在指定名字的属性。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 直接转发到 `m_properties.Contains(name)` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::HasProperty(...)。 - (void)object; -} -``` +- 这里检查的是当前 `Material` 持有的属性表，而不是 shader schema 声明本身 +- 但如果当前材质已经绑定 shader，且对应属性被默认值回填进 `m_properties`，它同样会返回 `true` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetShader](SetShader.md) +- [RemoveProperty](RemoveProperty.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/HasTag.md b/docs/api/XCEngine/Resources/Material/Material/HasTag.md new file mode 100644 index 00000000..c0f0484b --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/HasTag.md @@ -0,0 +1,21 @@ +# Material::HasTag + +```cpp +bool HasTag(const Containers::String& name) const; +``` + +## 作用 + +判断指定 tag 是否存在。 + +## 当前行为 + +- 对 `m_tags` 做线性遍历。 +- 只检查 tag 名是否命中，不比较 value。 + +## 相关文档 + +- [Material](Material.md) +- [SetTag](SetTag.md) +- [GetTag](GetTag.md) +- [RemoveTag](RemoveTag.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/IsValid.md b/docs/api/XCEngine/Resources/Material/Material/IsValid.md index bb631aa9..922351b2 100644 --- a/docs/api/XCEngine/Resources/Material/Material/IsValid.md +++ b/docs/api/XCEngine/Resources/Material/Material/IsValid.md @@ -1,30 +1,25 @@ # Material::IsValid -查询当前状态。 - ```cpp bool IsValid() const override; ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +判断当前材质资源对象是否处于有效状态。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前行为 -**示例：** +- 头文件内联返回成员 `m_isValid` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::IsValid(...)。 - (void)object; -} -``` +- 新构造对象默认返回 `false` +- [Release](Release.md) 会再次把它置回 `false` +- 这个访问器本身不检查 shader、属性或 texture binding 是否齐全 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [Constructor](Constructor.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/Material.md b/docs/api/XCEngine/Resources/Material/Material/Material.md index 4f32f176..bbfa8bef 100644 --- a/docs/api/XCEngine/Resources/Material/Material/Material.md +++ b/docs/api/XCEngine/Resources/Material/Material/Material.md @@ -6,11 +6,11 @@ **头文件**: `XCEngine/Resources/Material/Material.h` -**描述**: 运行时材质资源，统一承载 shader schema、render metadata、数值属性、texture binding 元数据以及延迟纹理兑现逻辑。 +**描述**: 运行时材质资源，统一承载 shader schema、render metadata、数值属性、texture binding 元数据、constant layout 与懒加载纹理兑现状态。 ## 概览 -`Material` 当前同时维护五类状态: +`Material` 当前同时维护六类状态： 1. 资源身份 `name`、`path`、`guid`、`isValid`、`memorySize` @@ -22,106 +22,116 @@ `name`、`slot`、已加载 `Texture` 句柄、稳定 `AssetRef`、path、pending async load 状态 5. packed constant buffer `m_constantBufferData` +6. constant layout 与变更版本 + `m_constantLayout`、`m_changeVersion` -## shader schema 与默认值 +## render metadata 与 tag -当 `SetShader(...)` 绑定 shader 后，`Material` 会按 shader property schema 做一次同步: +`Material` 当前不只是“属性容器”。`renderQueue`、`renderState`、`shaderPass` 与 `tags` 已经是渲染执行链路的正式输入： + +- `renderQueue` 直接参与可见项排序。 +- `renderState` 由 `RenderMaterialUtility` 映射到 RHI blend/depth/cull 描述。 +- `shaderPass` 允许材质显式指向目标 shader pass。 +- `tags` 则继续承载 `LightMode`、`RenderType` 一类 pass 选择语义。 + +`tests/Resources/Material/test_material.cpp` 当前已覆盖默认 render metadata、queue/state 读写、shader pass 读写，以及 tag 的写入/替换/删除/清空语义。 +`tests/Rendering/unit/test_render_scene_extractor.cpp` 当前还依赖 `renderQueue`、`shaderPass` 和 `LightMode` tag 做 pass 选择与排序。 + +## shader schema、默认值与 texture binding + +当 [SetShader](SetShader.md) 绑定 shader 后，`Material` 会按 shader property schema 做一次同步： - 为 schema 中缺失的属性补默认值 - 清理不再存在的旧属性 - 如果现有属性类型和新 schema 不兼容，则重置回 shader 默认值 - texture / cubemap 属性保留在 texture binding 通道，不写进 numeric property packing -`tests/Resources/Material/test_material.cpp` 当前明确覆盖了: - -- `SetShader()` 会 seed shader 默认值 -- `RemoveProperty()` 会把 schema 内属性恢复到 shader 默认值 -- `ClearAllProperties()` 在有 shader schema 时会恢复整套默认值 -- 切换 shader 时会清理旧 schema 属性并补齐新 schema 默认值 - -## texture binding 的当前模型 - -### 两层状态 - -每个 texture binding 现在同时有两层语义: +texture binding 当前使用“两层状态”： - 稳定元数据 `AssetRef` + path - 已加载句柄 `ResourceHandle` -### 三种写入入口 +首次调用 [GetTexture](GetTexture.md) 或 [GetTextureBindingTexture](GetTextureBindingTexture.md) 时，若当前只有 path / `AssetRef`，`Material` 才会通过 `ResourceManager` 启动异步兑现。 -- [SetTexture](SetTexture.md) - 直接写入已加载纹理，并尽量补齐 `AssetRef` -- [SetTextureAssetRef](SetTextureAssetRef.md) - 直接写入稳定 `AssetRef` 与可选 path，同时清空 loaded handle -- [SetTexturePath](SetTexturePath.md) - 只保留 path 元数据，同时清空 `AssetRef` 和 loaded handle +## constant layout 与 change version -### 两种读取入口 +[UpdateConstantBuffer](UpdateConstantBuffer.md) 当前不只生成裸字节 payload，也会同步生成 [MaterialConstantFieldDesc](MaterialConstantFieldDesc.md) 列表： -- [GetTexture](GetTexture.md) - 按名称读纹理，并在需要时启动异步加载 -- [GetTextureBindingTexture](GetTextureBindingTexture.md) - 按 binding index 做同样的懒加载入口 +- `offset` +- `size` +- `alignedSize` -如果只想看“当前是否已经加载完成”，而不想触发新的加载，应改用: +有 shader schema 时，布局顺序跟随 shader property 声明顺序。 +没有 shader schema 时，布局顺序退回属性名字典序。 -- [GetTextureBindingLoadedTexture](GetTextureBindingLoadedTexture.md) - -### `AssetRef` 与 path 的边界 - -- `AssetRef` 是更稳定的项目资产身份 -- path 是可选的辅助定位信息 -- `.xcmat` v2 当前会尽量把两者都保存进 artifact -- 如果只有 `AssetRef` 没有 path，首次访问纹理时会先通过 `ResourceManager::TryResolveAssetPath(...)` 反查 path，再启动异步加载 -- source 材质解析出来的 binding path 可能是项目内绝对路径；而只带 `AssetRef` 的 `.xcmat` 绑定在首次兑现后，通常会补回 `Assets/...` 形式的主 source 路径 - -## 常量缓冲打包语义 - -[UpdateConstantBuffer](UpdateConstantBuffer.md) 当前只打包数值属性: - -- `Float*` -- `Int*` -- `Bool` - -texture / cubemap 属性不会写进 `m_constantBufferData`。 - -当前打包顺序分两种路径: - -- 如果当前绑定了 shader 且 shader property 列表非空: - - 只按 shader schema 中声明顺序收集兼容的数值属性 -- 如果当前没有 shader schema: - - 按属性名字典序排序 - -两种路径下都遵守: - -- 每个属性固定占 `16` 字节槽位 -- `Bool` 写成 `uint32 0/1` +[GetChangeVersion](GetChangeVersion.md) 当前则提供一个轻量 mutation 计数器。大多数公开 setter 最终都会经过内部 `MarkChanged(...)`，从而推进版本号。 ## 当前实现边界 -- `GetTexture(...)` / `GetTextureBindingTexture(...)` 只会启动异步加载，不会自己 pump `ResourceManager` 完成队列 -- `SetTexture(...)` 只有在纹理路径非空且不是虚拟路径时，才会尝试反查 `AssetRef` -- `GetTextureBindingLoadedTexture(...)` 只返回当前已兑现的句柄，不会触发新的加载 -- constant buffer 在“有 shader schema”和“无 shader schema”两种情况下采用不同排序规则；不要把无 shader 时的字典序行为误解成通用规则 +- `GetTexture(...)` / `GetTextureBindingTexture(...)` 只会启动异步加载，不会自己 pump `ResourceManager` 完成队列。 +- `GetProperties()` 返回的是从 `HashMap` 导出的值拷贝，当前不承诺稳定顺序。 +- `GetTags()` / `GetTextureBindings()` / `GetConstantLayout()` 返回的是内部数组常量引用；调用方不能假设跨后续写操作仍保持有效。 +- `RecalculateMemorySize()` 只重算 `memorySize`，不会刷新 constant buffer，也不会推进 `changeVersion`。 +- constant buffer 只打包数值属性；texture / cubemap 仍走独立 binding 通道。 ## 关键声明 | 声明 | 角色 | |------|------| -| `MaterialRenderQueue` | 内建 render queue 常量 | -| `MaterialRenderState` | blend / depth / cull 等 runtime render state | -| `MaterialPropertyType` | 数值属性与 texture/cubemap 属性的区分枚举 | -| `MaterialProperty` | 单个属性的名称、类型和值 | -| `MaterialTextureBinding` | 单个 texture binding 的 loaded handle、`AssetRef`、path 与 pending load 状态 | +| [MaterialRenderQueue](MaterialRenderQueue.md) | 内建 render queue 常量。 | +| [MaterialCullMode](MaterialCullMode.md) | 光栅剔除模式。 | +| [MaterialComparisonFunc](MaterialComparisonFunc.md) | 深度比较函数。 | +| [MaterialBlendOp](MaterialBlendOp.md) | 混合操作。 | +| [MaterialBlendFactor](MaterialBlendFactor.md) | 混合因子。 | +| [MaterialRenderState](MaterialRenderState.md) | blend / depth / cull 等 runtime render state。 | +| [MaterialPropertyType](MaterialPropertyType.md) | 数值属性与 texture/cubemap 属性的区分枚举。 | +| [MaterialProperty](MaterialProperty.md) | 单个属性的名称、类型和值。 | +| [MaterialConstantFieldDesc](MaterialConstantFieldDesc.md) | constant layout 字段描述。 | +| [MaterialTagEntry](MaterialTagEntry.md) | 材质 tag 键值对。 | +| [PendingTextureLoadState](PendingTextureLoadState.md) | 懒加载纹理兑现的异步完成状态。 | +| [MaterialTextureBinding](MaterialTextureBinding.md) | texture binding 的 loaded handle、`AssetRef`、path 与 pending load 状态。 | -## 重点方法 +## 公开方法 + +### 资源与 render metadata | 方法 | 说明 | |------|------| | [SetShader](SetShader.md) | 绑定 shader，并按 shader schema 同步属性集。 | +| [GetShader](GetShader.md) | 读取当前绑定的 shader 裸指针视图。 | +| [SetRenderQueue](SetRenderQueue.md) | 写入 render queue。 | +| [GetRenderQueue](GetRenderQueue.md) | 读取当前 render queue 整数值。 | +| [SetRenderState](SetRenderState.md) | 整体替换 render state。 | +| [GetRenderState](GetRenderState.md) | 读取当前 render state 常量引用。 | +| [SetShaderPass](SetShaderPass.md) | 写入显式 shader pass 名。 | +| [GetShaderPass](GetShaderPass.md) | 读取当前 shader pass 名。 | + +### tag API + +| 方法 | 说明 | +|------|------| +| [SetTag](SetTag.md) | 写入或覆盖一个材质 tag。 | +| [GetTag](GetTag.md) | 按名称读取 tag 值。 | +| [HasTag](HasTag.md) | 判断指定 tag 是否存在。 | +| [RemoveTag](RemoveTag.md) | 删除指定 tag。 | +| [ClearTags](ClearTags.md) | 清空全部 tag。 | +| [GetTagCount](GetTagCount.md) | 返回当前 tag 数量。 | +| [GetTagName](GetTagName.md) | 按索引读取 tag 名。 | +| [GetTagValue](GetTagValue.md) | 按索引读取 tag 值。 | +| [GetTags](GetTags.md) | 读取内部 tag 数组常量引用。 | + +### 属性与 texture binding + +| 方法 | 说明 | +|------|------| +| [SetFloat](SetFloat.md) | 写入标量浮点属性。 | +| [SetFloat2](SetFloat2.md) | 写入二维浮点属性。 | +| [SetFloat3](SetFloat3.md) | 写入三维浮点属性。 | +| [SetFloat4](SetFloat4.md) | 写入四维浮点属性。 | +| [SetInt](SetInt.md) | 写入整型属性。 | +| [SetBool](SetBool.md) | 写入布尔属性。 | | [SetTexture](SetTexture.md) | 直接写入已加载纹理，并尽量补 `AssetRef` 元数据。 | | [SetTextureAssetRef](SetTextureAssetRef.md) | 只写 texture 资产身份与可选 path。 | | [SetTexturePath](SetTexturePath.md) | 只写 path 元数据。 | @@ -132,8 +142,34 @@ texture / cubemap 属性不会写进 `m_constantBufferData`。 | [GetTextureBindingPath](GetTextureBindingPath.md) | 读取某个 binding 当前保存的 path。 | | [GetTextureBindingLoadedTexture](GetTextureBindingLoadedTexture.md) | 只看已加载句柄，不触发新的加载。 | | [GetTextureBindingTexture](GetTextureBindingTexture.md) | 按 index 读取纹理，并在需要时启动懒加载。 | +| [GetTextureBindings](GetTextureBindings.md) | 读取内部 texture binding 数组常量引用。 | +| [GetProperties](GetProperties.md) | 导出当前属性值的拷贝集合。 | +| [HasProperty](HasProperty.md) | 判断属性是否存在。 | +| [RemoveProperty](RemoveProperty.md) | 删除属性，或回退到 shader 默认值。 | | [ClearAllProperties](ClearAllProperties.md) | 清空当前属性集，再按 shader schema 回填默认值。 | + +### constant layout 与变更追踪 + +| 方法 | 说明 | +|------|------| +| [GetConstantBufferData](GetConstantBufferData.md) | 读取 packed constant buffer 字节视图。 | +| [GetConstantLayout](GetConstantLayout.md) | 读取当前 constant layout 常量引用。 | +| [FindConstantField](FindConstantField.md) | 按名称查找 layout 字段。 | | [UpdateConstantBuffer](UpdateConstantBuffer.md) | 重新打包数值属性常量缓冲。 | +| [GetChangeVersion](GetChangeVersion.md) | 读取当前 mutation 版本号。 | +| [RecalculateMemorySize](RecalculateMemorySize.md) | 仅重新计算 `memorySize`。 | + +### 资源基础接口 + +| 方法 | 说明 | +|------|------| +| [Release](Release.md) | 清空运行时材质数据并把资源置为 invalid。 | +| [GetType](GetType.md) | 返回固定资源类型 `ResourceType::Material`。 | +| [GetName](GetName.md) | 返回 `IResource` 身份字段中的 `name`。 | +| [GetPath](GetPath.md) | 返回 `IResource` 身份字段中的 `path`。 | +| [GetGUID](GetGUID.md) | 返回 `IResource` 身份字段中的 `guid`。 | +| [IsValid](IsValid.md) | 返回当前资源是否处于有效状态。 | +| [GetMemorySize](GetMemorySize.md) | 返回当前缓存的内存估算值。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md new file mode 100644 index 00000000..203bb72f --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md @@ -0,0 +1,39 @@ +# MaterialBlendFactor + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 枚举值 + +| 值 | 数值 | 含义 | +|------|------|------| +| `Zero` | `0` | 常量 `0`。 | +| `One` | `1` | 常量 `1`。 | +| `SrcColor` | `2` | 源颜色。 | +| `InvSrcColor` | `3` | `1 - 源颜色`。 | +| `SrcAlpha` | `4` | 源 alpha。 | +| `InvSrcAlpha` | `5` | `1 - 源 alpha`。 | +| `DstAlpha` | `6` | 目标 alpha。 | +| `InvDstAlpha` | `7` | `1 - 目标 alpha`。 | +| `DstColor` | `8` | 目标颜色。 | +| `InvDstColor` | `9` | `1 - 目标颜色`。 | +| `SrcAlphaSat` | `10` | 饱和后的源 alpha。 | +| `BlendFactor` | `11` | 外部 blend 常量。 | +| `InvBlendFactor` | `12` | `1 - blend 常量`。 | +| `Src1Color` | `13` | 第二源颜色。 | +| `InvSrc1Color` | `14` | `1 - 第二源颜色`。 | +| `Src1Alpha` | `15` | 第二源 alpha。 | +| `InvSrc1Alpha` | `16` | `1 - 第二源 alpha`。 | + +## 当前语义 + +- 它当前用于 `srcBlend`、`dstBlend`、`srcBlendAlpha`、`dstBlendAlpha` 四个 render-state 字段。 +- `Material` 默认 render state 对颜色和 alpha 都使用 `One/Zero` 组合，即关闭混合时的常见默认值。 + +## 相关文档 + +- [MaterialRenderState](MaterialRenderState.md) +- [SetRenderState](SetRenderState.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md new file mode 100644 index 00000000..1d4d63da --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md @@ -0,0 +1,27 @@ +# MaterialBlendOp + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 枚举值 + +| 值 | 数值 | 含义 | +|------|------|------| +| `Add` | `0` | 加法混合。 | +| `Subtract` | `1` | 源减目标。 | +| `ReverseSubtract` | `2` | 目标减源。 | +| `Min` | `3` | 取最小值。 | +| `Max` | `4` | 取最大值。 | + +## 当前语义 + +- 它同时用于 `blendOp` 和 `blendOpAlpha` 两个字段。 +- `Material` 默认 render state 对颜色和 alpha 都使用 `Add`。 + +## 相关文档 + +- [MaterialRenderState](MaterialRenderState.md) +- [SetRenderState](SetRenderState.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md b/docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md new file mode 100644 index 00000000..9e3fa9a6 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md @@ -0,0 +1,31 @@ +# MaterialComparisonFunc + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 枚举值 + +| 值 | 数值 | 含义 | +|------|------|------| +| `Never` | `0` | 永不通过。 | +| `Less` | `1` | 小于时通过。 | +| `Equal` | `2` | 等于时通过。 | +| `LessEqual` | `3` | 小于等于时通过。 | +| `Greater` | `4` | 大于时通过。 | +| `NotEqual` | `5` | 不等于时通过。 | +| `GreaterEqual` | `6` | 大于等于时通过。 | +| `Always` | `7` | 总是通过。 | + +## 当前语义 + +- 它当前只作为 [MaterialRenderState](MaterialRenderState.md) 的 `depthFunc` 字段出现。 +- `Material` 默认 render state 使用 `Less`。 + +## 相关文档 + +- [MaterialRenderState](MaterialRenderState.md) +- [SetRenderState](SetRenderState.md) +- [GetRenderState](GetRenderState.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialConstantFieldDesc.md b/docs/api/XCEngine/Resources/Material/Material/MaterialConstantFieldDesc.md new file mode 100644 index 00000000..90f84f7e --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialConstantFieldDesc.md @@ -0,0 +1,34 @@ +# MaterialConstantFieldDesc + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | 字段名。 | +| `type` | `MaterialPropertyType` | 原始材质属性类型。 | +| `offset` | `Core::uint32` | 字段在 packed payload 中的偏移。 | +| `size` | `Core::uint32` | 实际有效字节数。 | +| `alignedSize` | `Core::uint32` | 为对齐预留的槽位大小。 | + +## 当前语义 + +- 这是 [GetConstantLayout](GetConstantLayout.md) 返回的布局项类型。 +- `alignedSize` 当前固定按 `16` 字节槽位生成。 +- `offset` 当前按布局顺序逐槽累加，而不是直接等于 `size` 累加。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前验证了 `alpha / beta / gamma` 三个字段的 `offset/size/alignedSize` 结果，并覆盖 [FindConstantField](FindConstantField.md) 的查找行为。 + +## 相关文档 + +- [Material](Material.md) +- [GetConstantLayout](GetConstantLayout.md) +- [FindConstantField](FindConstantField.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md b/docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md new file mode 100644 index 00000000..e787e49a --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md @@ -0,0 +1,26 @@ +# MaterialCullMode + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 枚举值 + +| 值 | 数值 | 含义 | +|------|------|------| +| `None` | `0` | 不做面剔除。 | +| `Front` | `1` | 剔除正面。 | +| `Back` | `2` | 剔除背面。 | + +## 当前语义 + +- 它是 [MaterialRenderState](MaterialRenderState.md) 的一个字段，由 `RenderMaterialUtility` 映射到具体 RHI cull mode。 +- `Material` 默认 render state 当前使用 `None`。 + +## 相关文档 + +- [MaterialRenderState](MaterialRenderState.md) +- [SetRenderState](SetRenderState.md) +- [GetRenderState](GetRenderState.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialProperty.md b/docs/api/XCEngine/Resources/Material/Material/MaterialProperty.md new file mode 100644 index 00000000..d7e13f90 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialProperty.md @@ -0,0 +1,28 @@ +# MaterialProperty + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | 属性名。 | +| `type` | `MaterialPropertyType` | 属性类型。 | +| `value` | `MaterialProperty::Value` | 数值属性联合体。 | +| `refCount` | `Core::uint32` | 当前保留的计数字段。 | + +## 当前语义 + +- 这是 `Material` 内部属性表 `m_properties` 的值类型。 +- `value` 当前只真正承载数值属性；texture / cubemap 属性主要通过 [MaterialTextureBinding](MaterialTextureBinding.md) 持有稳定元数据和已加载句柄。 +- `refCount` 当前在公开 setter 和 shader 默认值构造路径里都会被写成 `1`，但 `Material.cpp` 当前并不把它当成运行时引用计数系统来维护。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialPropertyType](MaterialPropertyType.md) +- [GetProperties](GetProperties.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialPropertyType.md b/docs/api/XCEngine/Resources/Material/Material/MaterialPropertyType.md new file mode 100644 index 00000000..e343569b --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialPropertyType.md @@ -0,0 +1,35 @@ +# MaterialPropertyType + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 枚举值 + +| 值 | 含义 | +|------|------| +| `Float` | 标量浮点属性。 | +| `Float2` | 二维浮点属性。 | +| `Float3` | 三维浮点属性。 | +| `Float4` | 四维浮点属性。 | +| `Int` | 标量整型属性。 | +| `Int2` | 二维整型属性。 | +| `Int3` | 三维整型属性。 | +| `Int4` | 四维整型属性。 | +| `Bool` | 布尔属性。 | +| `Texture` | 2D 纹理属性。 | +| `Cubemap` | Cubemap 属性。 | + +## 当前语义 + +- `Material` 当前用它区分“可打包进 constant buffer 的数值属性”和“走 texture binding 通道的纹理属性”。 +- shader schema 同步时，`ShaderPropertyType::Float/Range` 当前映射到 `Float`，`Vector/Color` 映射到 `Float4`，`Texture2D` 映射到 `Texture`，`TextureCube` 映射到 `Cubemap`。 +- 只有 `Float*`、`Int*` 和 `Bool` 会进入 [UpdateConstantBuffer](UpdateConstantBuffer.md)。 + +## 相关文档 + +- [MaterialProperty](MaterialProperty.md) +- [MaterialConstantFieldDesc](MaterialConstantFieldDesc.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialRenderQueue.md b/docs/api/XCEngine/Resources/Material/Material/MaterialRenderQueue.md new file mode 100644 index 00000000..23f59e4b --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialRenderQueue.md @@ -0,0 +1,34 @@ +# MaterialRenderQueue + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 枚举值 + +| 值 | 数值 | 含义 | +|------|------|------| +| `Background` | `1000` | 背景队列。 | +| `Geometry` | `2000` | 默认不透明几何队列。 | +| `AlphaTest` | `2450` | Alpha-test 几何队列。 | +| `Transparent` | `3000` | 透明队列。 | +| `Overlay` | `4000` | 覆盖层 / HUD 类队列。 | + +## 当前语义 + +- `Material` 内部把 render queue 存成 `Core::int32`，而不是单独保存一个枚举值。 +- [SetRenderQueue](SetRenderQueue.md) 的枚举重载当前只是把这里的数值 cast 成整数再写入。 +- `RenderSceneExtractor` 与若干渲染 integration scene 当前都直接依赖这些队列值做排序与 pass 分桶。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前验证了默认队列是 `Geometry`，并覆盖了枚举与整数两种写入路径。 +`tests/Rendering/unit/test_render_scene_extractor.cpp` 与多组材质状态 integration scene 当前还依赖这些队列值验证排序与透明/不透明分流。 + +## 相关文档 + +- [Material](Material.md) +- [SetRenderQueue](SetRenderQueue.md) +- [GetRenderQueue](GetRenderQueue.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md b/docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md new file mode 100644 index 00000000..1b226323 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md @@ -0,0 +1,63 @@ +# MaterialRenderState + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `blendEnable` | `bool` | 是否启用混合。 | +| `srcBlend` | `MaterialBlendFactor` | 颜色混合源因子。 | +| `dstBlend` | `MaterialBlendFactor` | 颜色混合目标因子。 | +| `srcBlendAlpha` | `MaterialBlendFactor` | alpha 混合源因子。 | +| `dstBlendAlpha` | `MaterialBlendFactor` | alpha 混合目标因子。 | +| `blendOp` | `MaterialBlendOp` | 颜色混合操作。 | +| `blendOpAlpha` | `MaterialBlendOp` | alpha 混合操作。 | +| `colorWriteMask` | `Core::uint8` | 颜色写掩码。 | +| `depthTestEnable` | `bool` | 是否启用深度测试。 | +| `depthWriteEnable` | `bool` | 是否启用深度写入。 | +| `depthFunc` | `MaterialComparisonFunc` | 深度比较函数。 | +| `cullMode` | `MaterialCullMode` | 光栅剔除模式。 | + +## 当前语义 + +- 这是 `Material` 当前 render metadata 的核心结构。 +- `operator==` / `operator!=` 当前逐字段比较全部 render-state 成员。 +- 默认值当前是： + - `blendEnable = false` + - `srcBlend = One` + - `dstBlend = Zero` + - `srcBlendAlpha = One` + - `dstBlendAlpha = Zero` + - `blendOp = Add` + - `blendOpAlpha = Add` + - `colorWriteMask = 0xF` + - `depthTestEnable = true` + - `depthWriteEnable = true` + - `depthFunc = Less` + - `cullMode = None` + +## 当前使用位置 + +- [SetRenderState](SetRenderState.md) 当前整体替换这份状态。 +- `RenderMaterialUtility` 当前会把它映射到 RHI blend/depth/rasterizer 描述。 +- 多组 rendering integration scene 当前都直接依赖这份结构验证透明、剔除和深度写入行为。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前覆盖了默认值与整结构写入/读回。 +`tests/Rendering/unit/test_render_scene_extractor.cpp` 和多组材质状态 integration scene 当前还依赖它驱动实际渲染状态。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialCullMode](MaterialCullMode.md) +- [MaterialComparisonFunc](MaterialComparisonFunc.md) +- [MaterialBlendOp](MaterialBlendOp.md) +- [MaterialBlendFactor](MaterialBlendFactor.md) +- [SetRenderState](SetRenderState.md) +- [GetRenderState](GetRenderState.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialTagEntry.md b/docs/api/XCEngine/Resources/Material/Material/MaterialTagEntry.md new file mode 100644 index 00000000..ec24d71a --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialTagEntry.md @@ -0,0 +1,26 @@ +# MaterialTagEntry + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | tag 名。 | +| `value` | `Containers::String` | tag 值。 | + +## 当前语义 + +- `Material` 当前用内部 `m_tags` 数组保存这组键值对。 +- [SetTag](SetTag.md) 会按 `name` 覆盖现有项，未命中时才追加新条目。 +- [RemoveTag](RemoveTag.md) 当前采用 swap-remove，而不是稳定保序删除。 + +## 相关文档 + +- [Material](Material.md) +- [SetTag](SetTag.md) +- [GetTags](GetTags.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialTextureBinding.md b/docs/api/XCEngine/Resources/Material/Material/MaterialTextureBinding.md new file mode 100644 index 00000000..6f12a677 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialTextureBinding.md @@ -0,0 +1,35 @@ +# MaterialTextureBinding + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | binding 名。 | +| `slot` | `Core::uint32` | 当前数组内槽位索引。 | +| `texture` | `ResourceHandle` | 已兑现的纹理句柄。 | +| `textureRef` | `AssetRef` | 稳定纹理身份。 | +| `texturePath` | `Containers::String` | 可选路径元数据。 | +| `pendingLoad` | `std::shared_ptr` | 当前挂起的异步加载状态。 | + +## 当前语义 + +- 它是 `Material` texture binding 通道的核心记录类型。 +- 当前模型明确区分： + - 稳定元数据：`textureRef + texturePath` + - 运行时兑现句柄：`texture` +- `slot` 当前会在 texture binding 被删改后重新按数组索引回写。 +- `pendingLoad` 非空时表示异步纹理兑现仍在飞行中。 + +## 相关文档 + +- [Material](Material.md) +- [PendingTextureLoadState](PendingTextureLoadState.md) +- [GetTextureBindings](GetTextureBindings.md) +- [SetTextureAssetRef](SetTextureAssetRef.md) +- [SetTexturePath](SetTexturePath.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/PendingTextureLoadState.md b/docs/api/XCEngine/Resources/Material/Material/PendingTextureLoadState.md new file mode 100644 index 00000000..cc1f4202 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/PendingTextureLoadState.md @@ -0,0 +1,27 @@ +# PendingTextureLoadState + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Material/Material.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `resource` | `IResource*` | 异步加载完成后返回的资源指针。 | +| `errorMessage` | `Containers::String` | 加载失败时的错误信息。 | +| `completed` | `bool` | 异步请求是否已经结束。 | + +## 当前语义 + +- 这是 `Material` 懒加载纹理兑现链路里的临时异步状态对象。 +- [MaterialTextureBinding](MaterialTextureBinding.md) 当前通过 `std::shared_ptr` 持有它。 +- `ResourceManager::LoadAsync(...)` 的回调会写入 `resource/errorMessage/completed`，随后 `Material::ResolvePendingTextureBinding(...)` 再把它兑现成真正的 `ResourceHandle`。 + +## 相关文档 + +- [MaterialTextureBinding](MaterialTextureBinding.md) +- [GetTexture](GetTexture.md) +- [GetTextureBindingTexture](GetTextureBindingTexture.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/RecalculateMemorySize.md b/docs/api/XCEngine/Resources/Material/Material/RecalculateMemorySize.md new file mode 100644 index 00000000..e1cfa678 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/RecalculateMemorySize.md @@ -0,0 +1,24 @@ +# Material::RecalculateMemorySize + +```cpp +void RecalculateMemorySize(); +``` + +## 作用 + +仅重新计算当前材质的 `memorySize`。 + +## 当前行为 + +- 当前实现只是转调内部 `UpdateMemorySize()`。 +- 不会刷新 constant buffer。 +- 不会推进 `changeVersion`。 + +## 当前使用位置 + +- `MaterialLoader`、`BuiltinResources` 和 `MeshLoader` 当前会在直接改写底层字段后调用这里，收口最终的 `memorySize`。 + +## 相关文档 + +- [Material](Material.md) +- [GetMemorySize](GetMemorySize.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/Release.md b/docs/api/XCEngine/Resources/Material/Material/Release.md index 564ceb37..02ecb415 100644 --- a/docs/api/XCEngine/Resources/Material/Material/Release.md +++ b/docs/api/XCEngine/Resources/Material/Material/Release.md @@ -1,30 +1,31 @@ # Material::Release -释放引用或底层资源。 - ```cpp -void Release() override; +void Release(); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +重置当前 `Material` 的运行时状态，把对象恢复到未初始化、无效的空材质状态。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** +- `m_shader.Reset()` +- 把 `renderQueue` 恢复到 `MaterialRenderQueue::Geometry` +- 重置 `renderState` +- 清空 `shaderPass`、`tags`、`m_properties`、`m_textureBindings`、`m_constantBufferData` +- 把 `m_changeVersion` 重置为 `1` +- 把 `m_isValid` 设为 `false` +- 调用 `UpdateMemorySize()` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::Release(...)。 - (void)object; -} -``` +- 这不是 `delete this` +- 它会清掉当前 shader schema 同步出来的属性和所有 texture binding +- 调用后对象仍然存在，但已经不再表示一个有效材质资源 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetShader](SetShader.md) +- [ClearAllProperties](ClearAllProperties.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/RemoveProperty.md b/docs/api/XCEngine/Resources/Material/Material/RemoveProperty.md index 47eb9c4b..f29896b4 100644 --- a/docs/api/XCEngine/Resources/Material/Material/RemoveProperty.md +++ b/docs/api/XCEngine/Resources/Material/Material/RemoveProperty.md @@ -1,31 +1,41 @@ # Material::RemoveProperty -移除元素或解除关联。 - ```cpp void RemoveProperty(const Containers::String& name); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +移除指定属性；如果它属于当前 shader schema，则恢复成 shader 默认值而不是彻底消失。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** +1. 先尝试 `ResetPropertyToShaderDefault(name)` +2. 如果成功: + - 用 shader 默认值重写该属性 + - 调用 `MarkChanged(true)` + - 直接返回 +3. 如果失败: + - 从 `m_properties` 里擦除该属性 + - 如果它原来是 `Texture` / `Cubemap` 属性，同时移除同名 texture binding + - 调用 `MarkChanged(true)` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::RemoveProperty(...)。 - (void)object; -} -``` +- 对带 shader schema 的材质来说，它更像“恢复默认值”而不是“盲删” +- 对非 schema 属性或当前没有 shader 的材质，它才是真正的删除 +- 删除 texture 属性时，binding 元数据和已加载句柄也会一起清掉 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前验证了: + +- 删除普通数值属性后，`HasProperty()` 会变成 `false` +- 删除 schema 属性时，会恢复到 shader 默认值 +- 删除 texture 属性时，会把 texture binding 一起移除 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetShader](SetShader.md) +- [ClearAllProperties](ClearAllProperties.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/RemoveTag.md b/docs/api/XCEngine/Resources/Material/Material/RemoveTag.md new file mode 100644 index 00000000..c769418e --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/RemoveTag.md @@ -0,0 +1,27 @@ +# Material::RemoveTag + +```cpp +void RemoveTag(const Containers::String& name); +``` + +## 作用 + +删除指定名称的材质 tag。 + +## 当前行为 + +- 线性扫描 `m_tags`。 +- 命中后采用 swap-remove： + - 若不是最后一项，则用尾元素覆盖当前位置 + - 再 `PopBack()` +- 只有真正删掉 tag 时才会调用 `MarkChanged(false)`；未命中时不推进 `changeVersion`。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前覆盖了 tag 删除后的空返回与存在性变化。 + +## 相关文档 + +- [Material](Material.md) +- [SetTag](SetTag.md) +- [ClearTags](ClearTags.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetBool.md b/docs/api/XCEngine/Resources/Material/Material/SetBool.md index 6a6ba3c4..957bcff0 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetBool.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetBool.md @@ -1,32 +1,27 @@ # Material::SetBool -设置相关状态或配置。 - ```cpp void SetBool(const Containers::String& name, bool value); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +写入一个布尔属性。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** +- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Bool)` +- 不兼容时直接 no-op +- 兼容时移除同名 texture binding +- 用 `Bool` 类型重建属性，并写入布尔值 +- 调用 `MarkChanged(true)` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::SetBool(...)。 - (void)object; -} -``` +- 常量缓冲打包时，布尔值最终会写成 `uint32 0/1` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetInt](SetInt.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetFloat.md b/docs/api/XCEngine/Resources/Material/Material/SetFloat.md index 251e85b9..b9376e11 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetFloat.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetFloat.md @@ -1,32 +1,28 @@ # Material::SetFloat -设置相关状态或配置。 - ```cpp void SetFloat(const Containers::String& name, float value); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +写入一个标量浮点属性。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** +- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Float)` +- 如果当前 shader schema 不允许这个名字或类型，直接 no-op +- 否则移除同名 texture binding +- 用 `Float` 类型重建该属性并写入 `value` +- 调用 `MarkChanged(true)` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::SetFloat(...)。 - (void)object; -} -``` +- 绑定 shader 后，这个入口只接受 schema 中兼容 `Float` 的属性名 +- 如果同名属性之前是 texture binding，这次写入会把 binding 一起替换掉 ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetShader](SetShader.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetFloat2.md b/docs/api/XCEngine/Resources/Material/Material/SetFloat2.md index db748474..179f75dc 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetFloat2.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetFloat2.md @@ -1,32 +1,23 @@ # Material::SetFloat2 -设置相关状态或配置。 - ```cpp void SetFloat2(const Containers::String& name, const Math::Vector2& value); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +写入一个 `Float2` 数值属性。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::SetFloat2(...)。 - (void)object; -} -``` +- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Float2)` +- 不兼容时直接 no-op +- 兼容时移除同名 texture binding +- 用 `Float2` 类型重建属性，并把 `x/y` 写进内部值槽 +- 调用 `MarkChanged(true)` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetFloat](SetFloat.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetFloat3.md b/docs/api/XCEngine/Resources/Material/Material/SetFloat3.md index 9c420b5d..2ec2fa83 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetFloat3.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetFloat3.md @@ -1,32 +1,23 @@ # Material::SetFloat3 -设置相关状态或配置。 - ```cpp void SetFloat3(const Containers::String& name, const Math::Vector3& value); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +写入一个 `Float3` 数值属性。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::SetFloat3(...)。 - (void)object; -} -``` +- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Float3)` +- 不兼容时直接 no-op +- 兼容时移除同名 texture binding +- 用 `Float3` 类型重建属性，并把 `x/y/z` 写进内部值槽 +- 调用 `MarkChanged(true)` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetFloat](SetFloat.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetFloat4.md b/docs/api/XCEngine/Resources/Material/Material/SetFloat4.md index d5e20e0a..3d5361c4 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetFloat4.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetFloat4.md @@ -1,32 +1,23 @@ # Material::SetFloat4 -设置相关状态或配置。 - ```cpp void SetFloat4(const Containers::String& name, const Math::Vector4& value); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +写入一个 `Float4` 数值属性。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::SetFloat4(...)。 - (void)object; -} -``` +- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Float4)` +- 不兼容时直接 no-op +- 兼容时移除同名 texture binding +- 用 `Float4` 类型重建属性，并把四个分量写进内部值槽 +- 调用 `MarkChanged(true)` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetFloat](SetFloat.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetInt.md b/docs/api/XCEngine/Resources/Material/Material/SetInt.md index 8065341f..9607bb2c 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetInt.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetInt.md @@ -1,32 +1,23 @@ # Material::SetInt -设置相关状态或配置。 - ```cpp void SetInt(const Containers::String& name, Core::int32 value); ``` -该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +写入一个整型属性。 -**返回：** `void` - 无返回值。 +## 当前行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Material object; - // 根据上下文补齐参数后调用 Material::SetInt(...)。 - (void)object; -} -``` +- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Int)` +- 不兼容时直接 no-op +- 兼容时移除同名 texture binding +- 用 `Int` 类型重建属性，并写入整数值 +- 调用 `MarkChanged(true)` ## 相关文档 -- [返回类总览](Material.md) -- [返回模块目录](../Material.md) +- [Material](Material.md) +- [SetBool](SetBool.md) +- [UpdateConstantBuffer](UpdateConstantBuffer.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetRenderQueue.md b/docs/api/XCEngine/Resources/Material/Material/SetRenderQueue.md new file mode 100644 index 00000000..fcd2fa24 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/SetRenderQueue.md @@ -0,0 +1,34 @@ +# Material::SetRenderQueue + +```cpp +void SetRenderQueue(Core::int32 renderQueue); +void SetRenderQueue(MaterialRenderQueue renderQueue); +``` + +## 作用 + +写入当前材质的 render queue。 + +## 当前行为 + +- 整数重载会把传入值原样写入 `m_renderQueue`。 +- 枚举重载当前只是做一次 `static_cast(renderQueue)`，再转调整数重载。 +- 两个重载最终都会调用内部 `MarkChanged(false)`： + - 重算 `memorySize` + - 推进 `changeVersion` + - 不重新打包 constant buffer + +## 关键语义 + +- 当前不会对队列值做范围校验或夹紧。 +- renderer 侧实际消费的是整数队列值，而不是枚举标签本身。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前覆盖了枚举与整数两种写入路径。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialRenderQueue](MaterialRenderQueue.md) +- [GetRenderQueue](GetRenderQueue.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetRenderState.md b/docs/api/XCEngine/Resources/Material/Material/SetRenderState.md new file mode 100644 index 00000000..06d6d33a --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/SetRenderState.md @@ -0,0 +1,32 @@ +# Material::SetRenderState + +```cpp +void SetRenderState(const MaterialRenderState& renderState); +``` + +## 作用 + +整体替换当前材质的 render state。 + +## 当前行为 + +- 把传入结构整体复制到 `m_renderState`。 +- 随后调用 `MarkChanged(false)`： + - 重算 `memorySize` + - 推进 `changeVersion` + - 不重新打包 constant buffer + +## 当前语义 + +- 这是整结构写入，不是字段级 merge。 +- 渲染路径当前会把这份状态交给 `RenderMaterialUtility` 做 RHI 状态映射。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前验证了 blend/depth/cull 字段的整结构写入与读回。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialRenderState](MaterialRenderState.md) +- [GetRenderState](GetRenderState.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetShaderPass.md b/docs/api/XCEngine/Resources/Material/Material/SetShaderPass.md new file mode 100644 index 00000000..a20895e8 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/SetShaderPass.md @@ -0,0 +1,29 @@ +# Material::SetShaderPass + +```cpp +void SetShaderPass(const Containers::String& shaderPass); +``` + +## 作用 + +写入当前材质显式指定的 shader pass 名。 + +## 当前行为 + +- 直接把 `shaderPass` 写入 `m_shaderPass`。 +- 随后调用 `MarkChanged(false)`，推进 `changeVersion`。 + +## 当前语义 + +- 空字符串表示当前材质没有显式指定 pass。 +- 渲染路径当前会优先尝试消费这里写入的 pass 名，再退回 tag 或 shader metadata 做 pass 选择。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前覆盖了 `ForwardLit` 写入与读回。 +`tests/Rendering/unit/test_render_scene_extractor.cpp` 与多组 integration scene 当前还依赖这个入口驱动 `ForwardLit / Unlit / ObjectId` 等 pass 选择。 + +## 相关文档 + +- [Material](Material.md) +- [GetShaderPass](GetShaderPass.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetTag.md b/docs/api/XCEngine/Resources/Material/Material/SetTag.md new file mode 100644 index 00000000..14a89891 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/SetTag.md @@ -0,0 +1,27 @@ +# Material::SetTag + +```cpp +void SetTag(const Containers::String& name, const Containers::String& value); +``` + +## 作用 + +写入或覆盖一个材质 tag。 + +## 当前行为 + +- 先线性扫描 `m_tags`。 +- 若命中同名 tag，则只覆盖 `value`。 +- 若未命中，则在数组末尾追加新的 [MaterialTagEntry](MaterialTagEntry.md)。 +- 两种路径最终都会调用 `MarkChanged(false)`。 + +## 测试覆盖 + +`tests/Resources/Material/test_material.cpp` 当前覆盖了 tag 新增与“同名写入替换旧值”的行为。 + +## 相关文档 + +- [Material](Material.md) +- [MaterialTagEntry](MaterialTagEntry.md) +- [GetTag](GetTag.md) +- [HasTag](HasTag.md) diff --git a/docs/api/XCEngine/Resources/Material/MaterialLoader/Constructor.md b/docs/api/XCEngine/Resources/Material/MaterialLoader/Constructor.md index eae6a694..c9fe377f 100644 --- a/docs/api/XCEngine/Resources/Material/MaterialLoader/Constructor.md +++ b/docs/api/XCEngine/Resources/Material/MaterialLoader/Constructor.md @@ -1,28 +1,31 @@ -# MaterialLoader::MaterialLoader() +# MaterialLoader::MaterialLoader -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Material/MaterialLoader.h` + +## 签名 ```cpp MaterialLoader(); ``` -该方法声明于 `XCEngine/Resources/Material/MaterialLoader.h`，当前页面用于固定 `MaterialLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造一个材质加载器实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 当前实现是默认构造函数，没有额外初始化逻辑 -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::MaterialLoader object; -} -``` +- `MaterialLoader` 当前是无状态 loader +- 实际格式分派和解析逻辑都发生在 [Load](Load.md) 里，而不是构造阶段 ## 相关文档 -- [返回类总览](MaterialLoader.md) -- [返回模块目录](../Material.md) +- [MaterialLoader](MaterialLoader.md) +- [Load](Load.md) diff --git a/docs/api/XCEngine/Resources/Material/MaterialLoader/Destructor.md b/docs/api/XCEngine/Resources/Material/MaterialLoader/Destructor.md index 7d4f35f3..d7b82cea 100644 --- a/docs/api/XCEngine/Resources/Material/MaterialLoader/Destructor.md +++ b/docs/api/XCEngine/Resources/Material/MaterialLoader/Destructor.md @@ -1,29 +1,29 @@ -# MaterialLoader::~MaterialLoader() +# MaterialLoader::~MaterialLoader -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Material/MaterialLoader.h` + +## 签名 ```cpp virtual ~MaterialLoader() override; ``` -该方法声明于 `XCEngine/Resources/Material/MaterialLoader.h`，当前页面用于固定 `MaterialLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁材质加载器实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 当前实现是默认析构函数，没有额外清理逻辑 -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::MaterialLoader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 因为 `MaterialLoader` 当前不持有长期状态，所以析构阶段没有额外释放步骤 ## 相关文档 -- [返回类总览](MaterialLoader.md) -- [返回模块目录](../Material.md) +- [MaterialLoader](MaterialLoader.md) diff --git a/docs/api/XCEngine/Resources/Material/MaterialLoader/GetDefaultSettings.md b/docs/api/XCEngine/Resources/Material/MaterialLoader/GetDefaultSettings.md index 0a50dcf9..a3441959 100644 --- a/docs/api/XCEngine/Resources/Material/MaterialLoader/GetDefaultSettings.md +++ b/docs/api/XCEngine/Resources/Material/MaterialLoader/GetDefaultSettings.md @@ -1,30 +1,31 @@ # MaterialLoader::GetDefaultSettings -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Material/MaterialLoader.h` + +## 签名 ```cpp ImportSettings* GetDefaultSettings() const override; ``` -该方法声明于 `XCEngine/Resources/Material/MaterialLoader.h`，当前页面用于固定 `MaterialLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回这个 loader 的默认导入设置对象。 -**返回：** `ImportSettings*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 当前固定返回 `nullptr` -```cpp -#include +## 关键语义 -void Example() { - XCEngine::Resources::MaterialLoader object; - // 根据上下文补齐参数后调用 MaterialLoader::GetDefaultSettings(...)。 - (void)object; -} -``` +- 这说明 `MaterialLoader` 目前没有独立的默认 `ImportSettings` 对象 +- `Load()` 也没有消费材质专属导入设置；传入的 `settings` 当前被显式忽略 ## 相关文档 -- [返回类总览](MaterialLoader.md) -- [返回模块目录](../Material.md) +- [MaterialLoader](MaterialLoader.md) +- [Load](Load.md) diff --git a/docs/api/XCEngine/Resources/Material/MaterialLoader/GetResourceType.md b/docs/api/XCEngine/Resources/Material/MaterialLoader/GetResourceType.md index e9e6dd77..52705d0b 100644 --- a/docs/api/XCEngine/Resources/Material/MaterialLoader/GetResourceType.md +++ b/docs/api/XCEngine/Resources/Material/MaterialLoader/GetResourceType.md @@ -1,30 +1,30 @@ # MaterialLoader::GetResourceType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Material/MaterialLoader.h` + +## 签名 ```cpp ResourceType GetResourceType() const override; ``` -该方法声明于 `XCEngine/Resources/Material/MaterialLoader.h`，当前页面用于固定 `MaterialLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回这个 loader 负责的资源类型。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联返回固定值 `ResourceType::Material` -```cpp -#include +## 测试覆盖 -void Example() { - XCEngine::Resources::MaterialLoader object; - // 根据上下文补齐参数后调用 MaterialLoader::GetResourceType(...)。 - (void)object; -} -``` +`tests/Resources/Material/test_material_loader.cpp` 的 `MaterialLoader.GetResourceType` 当前直接验证了这一点。 ## 相关文档 -- [返回类总览](MaterialLoader.md) -- [返回模块目录](../Material.md) +- [MaterialLoader](MaterialLoader.md) +- [Load](Load.md) diff --git a/docs/api/XCEngine/Resources/Material/MaterialLoader/GetSupportedExtensions.md b/docs/api/XCEngine/Resources/Material/MaterialLoader/GetSupportedExtensions.md index 8acbb1af..47d77dd2 100644 --- a/docs/api/XCEngine/Resources/Material/MaterialLoader/GetSupportedExtensions.md +++ b/docs/api/XCEngine/Resources/Material/MaterialLoader/GetSupportedExtensions.md @@ -1,30 +1,42 @@ # MaterialLoader::GetSupportedExtensions -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Material/MaterialLoader.h` + +## 签名 ```cpp Containers::Array GetSupportedExtensions() const override; ``` -该方法声明于 `XCEngine/Resources/Material/MaterialLoader.h`，当前页面用于固定 `MaterialLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前 loader 接受的文件扩展名列表。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +当前返回的扩展名依次是: -```cpp -#include +- `mat` +- `material` +- `json` +- `xcmat` -void Example() { - XCEngine::Resources::MaterialLoader object; - // 根据上下文补齐参数后调用 MaterialLoader::GetSupportedExtensions(...)。 - (void)object; -} -``` +返回值不包含前导点。 + +## 关键语义 + +- 这份列表同时覆盖 source 材质和 `.xcmat` artifact +- `builtin://...` 路径不通过这里表达；那条分支由 [CanLoad](CanLoad.md) / [Load](Load.md) 里的专门协议判断处理 + +## 测试覆盖 + +`tests/Resources/Material/test_material_loader.cpp` 的 `MaterialLoader.GetSupportedExtensions` 当前验证了返回数量和内容。 ## 相关文档 -- [返回类总览](MaterialLoader.md) -- [返回模块目录](../Material.md) +- [MaterialLoader](MaterialLoader.md) +- [CanLoad](CanLoad.md) diff --git a/docs/plan/Shader与Material系统下一阶段计划.md b/docs/plan/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md similarity index 95% rename from docs/plan/Shader与Material系统下一阶段计划.md rename to docs/plan/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md index 481d23ae..1ec4dfe2 100644 --- a/docs/plan/Shader与Material系统下一阶段计划.md +++ b/docs/plan/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md @@ -490,7 +490,12 @@ Unity-like Shader Authoring (.shader) - `rendering_unit_tests` 73/73 通过，builtin pass contract 与 renderer 侧消费路径在当前重构后保持稳定 - 本轮最小回归集结果：`shader_tests` 31/31，`material_tests` 53/53，`rendering_unit_tests` 73/73 - 以当前目标范围看，`shader / material` 核心主线已经可以阶段性收口 -- 下一步：如果继续补强，只需要按需补一层 rendering integration smoke；如果继续推进新需求，可以从这个收口点切出去 +- 补充验收（`2026-04-04`）： + - 补跑 integration smoke 时发现并修复了一处真实回归：Unity-like `.shader` authoring 将 HLSL 的 `MainVS / MainPS` 入口错误套到了 GLSL/Vulkan variant，上层表现为 Vulkan `BuiltinForwardPipeline` 建 pipeline 失败 + - 修复后补跑 `rendering_integration_textured_quad_scene` 与 `rendering_integration_unlit_scene`、`rendering_integration_object_id_scene`，三者在 `D3D12 / OpenGL / Vulkan` 下均通过 + - 额外补跑 `rendering_integration_backpack_lit_scene` 时，暴露出一条相邻但不同范围的问题：direct `MeshLoader` 导入的 mesh/material/texture 生命周期路径存在异常退出/不干净收尾，已超出本次 `shader / material contract` 收口范围 + - 因此本计划按“核心主线已收口，附带一条相邻 residual risk”归档；若后续继续补强，优先单独开一轮处理 `MeshLoader + imported subresource lifetime` +- 下一步：从当前目标范围出发，本计划可归档；后续如继续推进，请以新计划承接 `backpack_lit_scene` 这条相邻问题 当前阶段明确不做： diff --git a/engine/src/Resources/Shader/ShaderLoader.cpp b/engine/src/Resources/Shader/ShaderLoader.cpp index d99bfe22..d93864eb 100644 --- a/engine/src/Resources/Shader/ShaderLoader.cpp +++ b/engine/src/Resources/Shader/ShaderLoader.cpp @@ -1396,9 +1396,10 @@ LoadResult BuildShaderFromAuthoringDesc( vertexVariant.stage = ShaderType::Vertex; vertexVariant.backend = backendVariant.backend; vertexVariant.language = backendVariant.language; - vertexVariant.entryPoint = !pass.vertexEntryPoint.Empty() - ? pass.vertexEntryPoint - : GetDefaultEntryPoint(backendVariant.language, ShaderType::Vertex); + vertexVariant.entryPoint = + backendVariant.language == ShaderLanguage::HLSL && !pass.vertexEntryPoint.Empty() + ? pass.vertexEntryPoint + : GetDefaultEntryPoint(backendVariant.language, ShaderType::Vertex); vertexVariant.profile = !backendVariant.vertexProfile.Empty() ? backendVariant.vertexProfile : GetDefaultProfile(backendVariant.language, backendVariant.backend, ShaderType::Vertex); @@ -1414,9 +1415,10 @@ LoadResult BuildShaderFromAuthoringDesc( fragmentVariant.stage = ShaderType::Fragment; fragmentVariant.backend = backendVariant.backend; fragmentVariant.language = backendVariant.language; - fragmentVariant.entryPoint = !pass.fragmentEntryPoint.Empty() - ? pass.fragmentEntryPoint - : GetDefaultEntryPoint(backendVariant.language, ShaderType::Fragment); + fragmentVariant.entryPoint = + backendVariant.language == ShaderLanguage::HLSL && !pass.fragmentEntryPoint.Empty() + ? pass.fragmentEntryPoint + : GetDefaultEntryPoint(backendVariant.language, ShaderType::Fragment); fragmentVariant.profile = !backendVariant.fragmentProfile.Empty() ? backendVariant.fragmentProfile : GetDefaultProfile(backendVariant.language, backendVariant.backend, ShaderType::Fragment); diff --git a/tests/Resources/Shader/test_shader_loader.cpp b/tests/Resources/Shader/test_shader_loader.cpp index de083f37..b478e555 100644 --- a/tests/Resources/Shader/test_shader_loader.cpp +++ b/tests/Resources/Shader/test_shader_loader.cpp @@ -349,13 +349,14 @@ TEST(ShaderLoader, LoadUnityLikeShaderAuthoringBuildsRuntimeContract) { const ShaderStageVariant* openglFragment = shader->FindVariant("ForwardLit", ShaderType::Fragment, ShaderBackend::OpenGL); ASSERT_NE(openglFragment, nullptr); - EXPECT_EQ(openglFragment->entryPoint, "MainPS"); + EXPECT_EQ(openglFragment->entryPoint, "main"); EXPECT_EQ(openglFragment->profile, "fs_4_30"); EXPECT_NE(std::string(openglFragment->sourceCode.CStr()).find("AUTHORING_FORWARD_LIT_GL_PS"), std::string::npos); const ShaderStageVariant* vulkanFragment = shader->FindVariant("ForwardLit", ShaderType::Fragment, ShaderBackend::Vulkan); ASSERT_NE(vulkanFragment, nullptr); + EXPECT_EQ(vulkanFragment->entryPoint, "main"); EXPECT_EQ(vulkanFragment->profile, "fs_4_50"); EXPECT_NE(std::string(vulkanFragment->sourceCode.CStr()).find("AUTHORING_FORWARD_LIT_VK_PS"), std::string::npos);