Archive shader material closure plan

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)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 新构造的 `Material` 默认不是有效资源；`IsValid()` 初始为 `false`
-    XCEngine::Resources::Material object;
+- 只有后续经过资源加载器初始化或显式写入内容后，它才会逐步承载实际材质状态
-}
+
-```
+## 测试覆盖
+
+`tests/Resources/Material/test_material.cpp` 的 `Material.DefaultConstructor` 当前验证了默认类型、`IsValid()` 初值和 `GetMemorySize()` 初值。
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [IsValid](IsValid.md)
+- [GetMemorySize](GetMemorySize.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- `Material` 持有的 `ResourceHandle`、容器和字符串会按各自成员语义自动析构
-    XCEngine::Resources::Material object;
+- 显式状态重置逻辑在 [Release](Release.md) 中，而不在析构函数里
-    // 对象离开作用域时会自动触发析构。
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [Release](Release.md)

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)

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 路径。
+## 作用
 
-**参数：**
+读取一个 `Bool` 属性。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前行为
 
-**示例：**
+- 如果存在同名 `Bool` 属性，返回保存的布尔值
-
+- 否则返回 `false`
-```cpp
-#include <XCEngine/Resources/Material/Material.h>
-
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::GetBool(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetBool](SetBool.md)

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)

docs/api/XCEngine/Resources/Material/Material/GetConstantBufferData.md

@@ -1,30 +1,26 @@
 # Material::GetConstantBufferData
 
-获取相关状态或对象。
-
 ```cpp
 const Containers::Array<Core::uint8>& GetConstantBufferData() const;
 ```
 
-该方法声明于 `XCEngine/Resources/Material/Material.h`，当前页面用于固定 `Material` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前材质已经打包好的常量缓冲字节数组视图。
 
-**返回：** `const Containers::Array<Core::uint8>&` - 返回值语义详见头文件声明。
+## 当前语义
 
-**示例：**
+- 返回的是内部 `m_constantBufferData` 的只读引用，不做拷贝
+- 这个访问器本身不会触发重新打包
+- 常量缓冲内容的更新由 `SetShader()`、数值属性写入、`RemoveProperty()`、`ClearAllProperties()` 或显式 [UpdateConstantBuffer](UpdateConstantBuffer.md) 触发
 
-```cpp
+## 关键语义
-#include <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 返回数据只包含当前可打包的数值属性
-    XCEngine::Resources::Material object;
+- texture / cubemap binding 不会写进这里
-    // 根据上下文补齐参数后调用 Material::GetConstantBufferData(...)。
+- 调用方如果长期持有这个引用，需要自己保证 `Material` 生命周期与后续修改时机
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)

docs/api/XCEngine/Resources/Material/Material/GetConstantLayout.md

@@ -0,0 +1,26 @@
+# Material::GetConstantLayout
+
+```cpp
+const Containers::Array<MaterialConstantFieldDesc>& 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)

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 路径。
+## 作用
 
-**参数：**
+读取一个 `Float` 属性。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `float` - 返回值语义详见头文件声明。
+## 当前行为
 
-**示例：**
+- 如果 `m_properties` 中存在同名属性且类型正好是 `Float`，返回其第一个分量
+- 否则返回 `0.0f`
 
-```cpp
+## 关键语义
-#include <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 它不会尝试做类型转换
-    XCEngine::Resources::Material object;
+- 对缺失属性、类型不匹配属性和 texture 属性，返回值都一样是 `0.0f`
-    // 根据上下文补齐参数后调用 Material::GetFloat(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetFloat](SetFloat.md)

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 路径。
+## 作用
 
-**参数：**
+读取一个 `Float2` 属性。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `Math::Vector2` - 返回值语义详见头文件声明。
+## 当前行为
 
-**示例：**
+- 如果存在同名 `Float2` 属性，返回其前两个分量
-
+- 否则返回 `Math::Vector2::Zero()`
-```cpp
-#include <XCEngine/Resources/Material/Material.h>
-
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::GetFloat2(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetFloat2](SetFloat2.md)

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 路径。
+## 作用
 
-**参数：**
+读取一个 `Float3` 属性。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `Math::Vector3` - 返回值语义详见头文件声明。
+## 当前行为
 
-**示例：**
+- 如果存在同名 `Float3` 属性，返回其前三个分量
-
+- 否则返回 `Math::Vector3::Zero()`
-```cpp
-#include <XCEngine/Resources/Material/Material.h>
-
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::GetFloat3(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetFloat3](SetFloat3.md)

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 路径。
+## 作用
 
-**参数：**
+读取一个 `Float4` 属性。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `Math::Vector4` - 返回值语义详见头文件声明。
+## 当前行为
 
-**示例：**
+- 如果存在同名 `Float4` 属性，返回四个分量
-
+- 否则返回 `Math::Vector4::Zero()`
-```cpp
-#include <XCEngine/Resources/Material/Material.h>
-
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::GetFloat4(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetFloat4](SetFloat4.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 这里返回的是运行时资源 GUID，不是项目资产 `AssetGUID`
-    XCEngine::Resources::Material object;
+- 对由 `ResourceManager` 管理的对象，这个 GUID 通常由加载请求路径生成
-    // 根据上下文补齐参数后调用 Material::GetGUID(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [GetPath](GetPath.md)
+- [AssetRef](../../../Core/Asset/AssetRef/AssetRef.md)

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 路径。
+## 作用
 
-**参数：**
+读取一个 `Int` 属性。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `Core::int32` - 返回值语义详见头文件声明。
+## 当前行为
 
-**示例：**
+- 如果存在同名 `Int` 属性，返回第一个整型分量
-
+- 否则返回 `0`
-```cpp
-#include <XCEngine/Resources/Material/Material.h>
-
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::GetInt(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetInt](SetInt.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 这个值由 `UpdateMemorySize()` 维护
-    XCEngine::Resources::Material object;
+- 统计范围当前包括:
-    // 根据上下文补齐参数后调用 Material::GetMemorySize(...)。
+  - 常量缓冲字节数
-    (void)object;
+  - `MaterialRenderState`
-}
+  - `shaderPass`
-```
+  - tag、texture binding、property 的结构体和字符串开销
+  - `name` / `path` 字符串长度
+
+## 关键语义
+
+- 它是当前类内部维护的估算值，不是系统级精确分配统计
+- 新构造对象默认返回 `0`
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)
+- [Release](Release.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 这里不做拷贝
-    XCEngine::Resources::Material object;
+- 新构造或已 [Release](Release.md) 的对象通常会返回空字符串
-    // 根据上下文补齐参数后调用 Material::GetName(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [GetPath](GetPath.md)
+- [GetGUID](GetGUID.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 对由 `ResourceManager` 加载出来的项目材质，这里通常保留的是原始请求路径，而不是 artifact 路径
-    XCEngine::Resources::Material object;
+- 新构造或已 [Release](Release.md) 的对象通常会返回空字符串
-    // 根据上下文补齐参数后调用 Material::GetPath(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [GetName](GetName.md)
+- [Release](Release.md)

docs/api/XCEngine/Resources/Material/Material/GetProperties.md

@@ -0,0 +1,27 @@
+# Material::GetProperties
+
+```cpp
+std::vector<MaterialProperty> GetProperties() const;
+```
+
+## 作用
+
+导出当前材质属性表的值拷贝集合。
+
+## 当前行为
+
+- 当前实现会从 `m_properties.GetPairs()` 取出所有键值对。
+- 只把 `pair.second` 拷贝进返回的 `std::vector<MaterialProperty>`，不会把 key 额外单独返回。
+- 返回值每次调用都会重新构造。
+
+## 关键语义
+
+- 这是拷贝导出，不是内部容器引用。
+- 当前不承诺稳定顺序；顺序取决于 `HashMap` 当前 pairs 视图。
+- `AssetDatabase` 当前会用它写出 `.xcmat` 的非纹理属性段。
+
+## 相关文档
+
+- [Material](Material.md)
+- [MaterialProperty](MaterialProperty.md)
+- [HasProperty](HasProperty.md)

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)

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)

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)

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)

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)

docs/api/XCEngine/Resources/Material/Material/GetTagCount.md

@@ -0,0 +1,21 @@
+# Material::GetTagCount
+
+```cpp
+Core::uint32 GetTagCount() const;
+```
+
+## 作用
+
+返回当前 tag 数量。
+
+## 当前语义
+
+- 头文件内联实现为 `static_cast<Core::uint32>(m_tags.Size())`。
+- 计数对象是内部 tag 数组，而不是某个哈希表视图。
+
+## 相关文档
+
+- [Material](Material.md)
+- [GetTags](GetTags.md)
+- [GetTagName](GetTagName.md)
+- [GetTagValue](GetTagValue.md)

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)

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)

docs/api/XCEngine/Resources/Material/Material/GetTags.md

@@ -0,0 +1,21 @@
+# Material::GetTags
+
+```cpp
+const Containers::Array<MaterialTagEntry>& GetTags() const;
+```
+
+## 作用
+
+读取内部 tag 数组的常量引用。
+
+## 当前语义
+
+- 头文件内联实现为直接返回 `m_tags` 的常量引用。
+- 保留的是当前数组顺序；但由于 [RemoveTag](RemoveTag.md) 采用 swap-remove，删除操作后顺序不保证稳定。
+- 调用方不应在后续材质写操作后继续持久保存这份引用。
+
+## 相关文档
+
+- [Material](Material.md)
+- [MaterialTagEntry](MaterialTagEntry.md)
+- [GetTagCount](GetTagCount.md)

docs/api/XCEngine/Resources/Material/Material/GetTextureBindings.md

@@ -0,0 +1,22 @@
+# Material::GetTextureBindings
+
+```cpp
+const Containers::Array<MaterialTextureBinding>& GetTextureBindings() const;
+```
+
+## 作用
+
+读取内部 texture binding 数组的常量引用。
+
+## 当前语义
+
+- 头文件内联实现为直接返回 `m_textureBindings` 的常量引用。
+- 这只是元数据视图，不会触发懒加载，也不会主动 resolve pending load。
+- 调用方不应在后续材质写操作后继续持久保存这份引用。
+
+## 相关文档
+
+- [Material](Material.md)
+- [MaterialTextureBinding](MaterialTextureBinding.md)
+- [GetTextureBindingCount](GetTextureBindingCount.md)
+- [GetTextureBindingTexture](GetTextureBindingTexture.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 这不是从运行时状态推导出来的动态结果
-    XCEngine::Resources::Material object;
+- 即使对象当前还未初始化或已被 [Release](Release.md) 重置，这个访问器仍返回 `ResourceType::Material`
-    // 根据上下文补齐参数后调用 Material::GetType(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [Release](Release.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 这里检查的是当前 `Material` 持有的属性表，而不是 shader schema 声明本身
-    XCEngine::Resources::Material object;
+- 但如果当前材质已经绑定 shader，且对应属性被默认值回填进 `m_properties`，它同样会返回 `true`
-    // 根据上下文补齐参数后调用 Material::HasProperty(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetShader](SetShader.md)
+- [RemoveProperty](RemoveProperty.md)

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)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 新构造对象默认返回 `false`
-    XCEngine::Resources::Material object;
+- [Release](Release.md) 会再次把它置回 `false`
-    // 根据上下文补齐参数后调用 Material::IsValid(...)。
+- 这个访问器本身不检查 shader、属性或 texture binding 是否齐全
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [Constructor](Constructor.md)
+- [Release](Release.md)

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` 当前明确覆盖了:
+texture binding 当前使用“两层状态”：
-
-- `SetShader()` 会 seed shader 默认值
-- `RemoveProperty()` 会把 schema 内属性恢复到 shader 默认值
-- `ClearAllProperties()` 在有 shader schema 时会恢复整套默认值
-- 切换 shader 时会清理旧 schema 属性并补齐新 schema 默认值
-
-## texture binding 的当前模型
-
-### 两层状态
-
-每个 texture binding 现在同时有两层语义:
 
 - 稳定元数据
   `AssetRef` + path
 - 已加载句柄
   `ResourceHandle<Texture>`
 
-### 三种写入入口
+首次调用 [GetTexture](GetTexture.md) 或 [GetTextureBindingTexture](GetTextureBindingTexture.md) 时，若当前只有 path / `AssetRef`，`Material` 才会通过 `ResourceManager` 启动异步兑现。
 
-- [SetTexture](SetTexture.md)
+## constant layout 与 change version
-  直接写入已加载纹理，并尽量补齐 `AssetRef`
-- [SetTextureAssetRef](SetTextureAssetRef.md)
-  直接写入稳定 `AssetRef` 与可选 path，同时清空 loaded handle
-- [SetTexturePath](SetTexturePath.md)
-  只保留 path 元数据，同时清空 `AssetRef` 和 loaded handle
 
-### 两种读取入口
+[UpdateConstantBuffer](UpdateConstantBuffer.md) 当前不只生成裸字节 payload，也会同步生成 [MaterialConstantFieldDesc](MaterialConstantFieldDesc.md) 列表：
 
-- [GetTexture](GetTexture.md)
+- `offset`
-  按名称读纹理，并在需要时启动异步加载
+- `size`
-- [GetTextureBindingTexture](GetTextureBindingTexture.md)
+- `alignedSize`
-  按 binding index 做同样的懒加载入口
 
-如果只想看“当前是否已经加载完成”，而不想触发新的加载，应改用:
+有 shader schema 时，布局顺序跟随 shader property 声明顺序。
+没有 shader schema 时，布局顺序退回属性名字典序。
 
-- [GetTextureBindingLoadedTexture](GetTextureBindingLoadedTexture.md)
+[GetChangeVersion](GetChangeVersion.md) 当前则提供一个轻量 mutation 计数器。大多数公开 setter 最终都会经过内部 `MarkChanged(...)`，从而推进版本号。
-
-### `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`
 
 ## 当前实现边界
 
-- `GetTexture(...)` / `GetTextureBindingTexture(...)` 只会启动异步加载，不会自己 pump `ResourceManager` 完成队列
+- `GetTexture(...)` / `GetTextureBindingTexture(...)` 只会启动异步加载，不会自己 pump `ResourceManager` 完成队列。
-- `SetTexture(...)` 只有在纹理路径非空且不是虚拟路径时，才会尝试反查 `AssetRef`
+- `GetProperties()` 返回的是从 `HashMap` 导出的值拷贝，当前不承诺稳定顺序。
-- `GetTextureBindingLoadedTexture(...)` 只返回当前已兑现的句柄，不会触发新的加载
+- `GetTags()` / `GetTextureBindings()` / `GetConstantLayout()` 返回的是内部数组常量引用；调用方不能假设跨后续写操作仍保持有效。
-- constant buffer 在“有 shader schema”和“无 shader schema”两种情况下采用不同排序规则；不要把无 shader 时的字典序行为误解成通用规则
+- `RecalculateMemorySize()` 只重算 `memorySize`，不会刷新 constant buffer，也不会推进 `changeVersion`。
+- constant buffer 只打包数值属性；texture / cubemap 仍走独立 binding 通道。
 
 ## 关键声明
 
 | 声明 | 角色 |
 |------|------|
-| `MaterialRenderQueue` | 内建 render queue 常量 |
+| [MaterialRenderQueue](MaterialRenderQueue.md) | 内建 render queue 常量。 |
-| `MaterialRenderState` | blend / depth / cull 等 runtime render state |
+| [MaterialCullMode](MaterialCullMode.md) | 光栅剔除模式。 |
-| `MaterialPropertyType` | 数值属性与 texture/cubemap 属性的区分枚举 |
+| [MaterialComparisonFunc](MaterialComparisonFunc.md) | 深度比较函数。 |
-| `MaterialProperty` | 单个属性的名称、类型和值 |
+| [MaterialBlendOp](MaterialBlendOp.md) | 混合操作。 |
-| `MaterialTextureBinding` | 单个 texture binding 的 loaded handle、`AssetRef`、path 与 pending load 状态 |
+| [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) | 返回当前缓存的内存估算值。 |
 
 ## 相关文档
 

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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<Texture>` | 已兑现的纹理句柄。 |
+| `textureRef` | `AssetRef` | 稳定纹理身份。 |
+| `texturePath` | `Containers::String` | 可选路径元数据。 |
+| `pendingLoad` | `std::shared_ptr<PendingTextureLoadState>` | 当前挂起的异步加载状态。 |
+
+## 当前语义
+
+- 它是 `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)

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<PendingTextureLoadState>` 持有它。
+- `ResourceManager::LoadAsync(...)` 的回调会写入 `resource/errorMessage/completed`，随后 `Material::ResolvePendingTextureBinding(...)` 再把它兑现成真正的 `ResourceHandle<Texture>`。
+
+## 相关文档
+
+- [MaterialTextureBinding](MaterialTextureBinding.md)
+- [GetTexture](GetTexture.md)
+- [GetTextureBindingTexture](GetTextureBindingTexture.md)

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)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 这不是 `delete this`
-    XCEngine::Resources::Material object;
+- 它会清掉当前 shader schema 同步出来的属性和所有 texture binding
-    // 根据上下文补齐参数后调用 Material::Release(...)。
+- 调用后对象仍然存在，但已经不再表示一个有效材质资源
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetShader](SetShader.md)
+- [ClearAllProperties](ClearAllProperties.md)

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 路径。
+## 作用
 
-**参数：**
+移除指定属性；如果它属于当前 shader schema，则恢复成 shader 默认值而不是彻底消失。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+## 当前行为
 
-**示例：**
+1. 先尝试 `ResetPropertyToShaderDefault(name)`
+2. 如果成功:
+   - 用 shader 默认值重写该属性
+   - 调用 `MarkChanged(true)`
+   - 直接返回
+3. 如果失败:
+   - 从 `m_properties` 里擦除该属性
+   - 如果它原来是 `Texture` / `Cubemap` 属性，同时移除同名 texture binding
+   - 调用 `MarkChanged(true)`
 
-```cpp
+## 关键语义
-#include <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 对带 shader schema 的材质来说，它更像“恢复默认值”而不是“盲删”
-    XCEngine::Resources::Material object;
+- 对非 schema 属性或当前没有 shader 的材质，它才是真正的删除
-    // 根据上下文补齐参数后调用 Material::RemoveProperty(...)。
+- 删除 texture 属性时，binding 元数据和已加载句柄也会一起清掉
-    (void)object;
+
-}
+## 测试覆盖
-```
+
+`tests/Resources/Material/test_material.cpp` 当前验证了:
+
+- 删除普通数值属性后，`HasProperty()` 会变成 `false`
+- 删除 schema 属性时，会恢复到 shader 默认值
+- 删除 texture 属性时，会把 texture binding 一起移除
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetShader](SetShader.md)
+- [ClearAllProperties](ClearAllProperties.md)

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)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 常量缓冲打包时，布尔值最终会写成 `uint32 0/1`
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::SetBool(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetInt](SetInt.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)

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 <XCEngine/Resources/Material/Material.h>
 
-void Example() {
+- 绑定 shader 后，这个入口只接受 schema 中兼容 `Float` 的属性名
-    XCEngine::Resources::Material object;
+- 如果同名属性之前是 texture binding，这次写入会把 binding 一起替换掉
-    // 根据上下文补齐参数后调用 Material::SetFloat(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetShader](SetShader.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)

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 路径。
+## 作用
 
-**参数：**
+写入一个 `Float2` 数值属性。
-- `name` - 参数语义详见头文件声明。
-- `value` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+## 当前行为
 
-**示例：**
+- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Float2)`
-
+- 不兼容时直接 no-op
-```cpp
+- 兼容时移除同名 texture binding
-#include <XCEngine/Resources/Material/Material.h>
+- 用 `Float2` 类型重建属性，并把 `x/y` 写进内部值槽
-
+- 调用 `MarkChanged(true)`
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::SetFloat2(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetFloat](SetFloat.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)

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 路径。
+## 作用
 
-**参数：**
+写入一个 `Float3` 数值属性。
-- `name` - 参数语义详见头文件声明。
-- `value` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+## 当前行为
 
-**示例：**
+- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Float3)`
-
+- 不兼容时直接 no-op
-```cpp
+- 兼容时移除同名 texture binding
-#include <XCEngine/Resources/Material/Material.h>
+- 用 `Float3` 类型重建属性，并把 `x/y/z` 写进内部值槽
-
+- 调用 `MarkChanged(true)`
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::SetFloat3(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetFloat](SetFloat.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)

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 路径。
+## 作用
 
-**参数：**
+写入一个 `Float4` 数值属性。
-- `name` - 参数语义详见头文件声明。
-- `value` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+## 当前行为
 
-**示例：**
+- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Float4)`
-
+- 不兼容时直接 no-op
-```cpp
+- 兼容时移除同名 texture binding
-#include <XCEngine/Resources/Material/Material.h>
+- 用 `Float4` 类型重建属性，并把四个分量写进内部值槽
-
+- 调用 `MarkChanged(true)`
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::SetFloat4(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetFloat](SetFloat.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)

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` - 无返回值。
+## 当前行为
 
-**示例：**
+- 先检查 `CanAssignPropertyType(name, MaterialPropertyType::Int)`
-
+- 不兼容时直接 no-op
-```cpp
+- 兼容时移除同名 texture binding
-#include <XCEngine/Resources/Material/Material.h>
+- 用 `Int` 类型重建属性，并写入整数值
-
+- 调用 `MarkChanged(true)`
-void Example() {
-    XCEngine::Resources::Material object;
-    // 根据上下文补齐参数后调用 Material::SetInt(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Material.md)
+- [Material](Material.md)
-- [返回模块目录](../Material.md)
+- [SetBool](SetBool.md)
+- [UpdateConstantBuffer](UpdateConstantBuffer.md)

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<Core::int32>(renderQueue)`，再转调整数重载。
+- 两个重载最终都会调用内部 `MarkChanged(false)`：
+  - 重算 `memorySize`
+  - 推进 `changeVersion`
+  - 不重新打包 constant buffer
+
+## 关键语义
+
+- 当前不会对队列值做范围校验或夹紧。
+- renderer 侧实际消费的是整数队列值，而不是枚举标签本身。
+
+## 测试覆盖
+
+`tests/Resources/Material/test_material.cpp` 当前覆盖了枚举与整数两种写入路径。
+
+## 相关文档
+
+- [Material](Material.md)
+- [MaterialRenderQueue](MaterialRenderQueue.md)
+- [GetRenderQueue](GetRenderQueue.md)

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)

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)

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)

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 <XCEngine/Resources/Material/MaterialLoader.h>
 
-void Example() {
+- `MaterialLoader` 当前是无状态 loader
-    XCEngine::Resources::MaterialLoader object;
+- 实际格式分派和解析逻辑都发生在 [Load](Load.md) 里，而不是构造阶段
-}
-```
 
 ## 相关文档
 
-- [返回类总览](MaterialLoader.md)
+- [MaterialLoader](MaterialLoader.md)
-- [返回模块目录](../Material.md)
+- [Load](Load.md)

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 <XCEngine/Resources/Material/MaterialLoader.h>
 
-void Example() {
+- 因为 `MaterialLoader` 当前不持有长期状态，所以析构阶段没有额外释放步骤
-    XCEngine::Resources::MaterialLoader object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
 
 ## 相关文档
 
-- [返回类总览](MaterialLoader.md)
+- [MaterialLoader](MaterialLoader.md)
-- [返回模块目录](../Material.md)

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 <XCEngine/Resources/Material/MaterialLoader.h>
 
-void Example() {
+- 这说明 `MaterialLoader` 目前没有独立的默认 `ImportSettings` 对象
-    XCEngine::Resources::MaterialLoader object;
+- `Load()` 也没有消费材质专属导入设置；传入的 `settings` 当前被显式忽略
-    // 根据上下文补齐参数后调用 MaterialLoader::GetDefaultSettings(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](MaterialLoader.md)
+- [MaterialLoader](MaterialLoader.md)
-- [返回模块目录](../Material.md)
+- [Load](Load.md)

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 <XCEngine/Resources/Material/MaterialLoader.h>
 
-void Example() {
+`tests/Resources/Material/test_material_loader.cpp` 的 `MaterialLoader.GetResourceType` 当前直接验证了这一点。
-    XCEngine::Resources::MaterialLoader object;
-    // 根据上下文补齐参数后调用 MaterialLoader::GetResourceType(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](MaterialLoader.md)
+- [MaterialLoader](MaterialLoader.md)
-- [返回模块目录](../Material.md)
+- [Load](Load.md)

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<Containers::String> GetSupportedExtensions() const override;
 ```
 
-该方法声明于 `XCEngine/Resources/Material/MaterialLoader.h`，当前页面用于固定 `MaterialLoader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 loader 接受的文件扩展名列表。
 
-**返回：** `Containers::Array<Containers::String>` - 返回值语义详见头文件声明。
+## 当前实现
 
-**示例：**
+当前返回的扩展名依次是:
 
-```cpp
+- `mat`
-#include <XCEngine/Resources/Material/MaterialLoader.h>
+- `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)
+- [MaterialLoader](MaterialLoader.md)
-- [返回模块目录](../Material.md)
+- [CanLoad](CanLoad.md)

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` 这条相邻问题
 
 当前阶段明确不做：
 

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()
+                vertexVariant.entryPoint =
-                    ? pass.vertexEntryPoint
+                    backendVariant.language == ShaderLanguage::HLSL && !pass.vertexEntryPoint.Empty()
-                    : GetDefaultEntryPoint(backendVariant.language, ShaderType::Vertex);
+                        ? 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()
+                fragmentVariant.entryPoint =
-                    ? pass.fragmentEntryPoint
+                    backendVariant.language == ShaderLanguage::HLSL && !pass.fragmentEntryPoint.Empty()
-                    : GetDefaultEntryPoint(backendVariant.language, ShaderType::Fragment);
+                        ? pass.fragmentEntryPoint
+                        : GetDefaultEntryPoint(backendVariant.language, ShaderType::Fragment);
                 fragmentVariant.profile = !backendVariant.fragmentProfile.Empty()
                     ? backendVariant.fragmentProfile
                     : GetDefaultProfile(backendVariant.language, backendVariant.backend, ShaderType::Fragment);

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