Archive shader material closure plan
This commit is contained in:
25
docs/api/XCEngine/Resources/Material/Material/ClearTags.md
Normal file
25
docs/api/XCEngine/Resources/Material/Material/ClearTags.md
Normal file
@@ -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)
|
||||
@@ -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() {
|
||||
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)
|
||||
|
||||
@@ -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() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- `Material` 持有的 `ResourceHandle`、容器和字符串会按各自成员语义自动析构
|
||||
- 显式状态重置逻辑在 [Release](Release.md) 中，而不在析构函数里
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [Release](Release.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)
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 根据上下文补齐参数后调用 Material::GetBool(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果存在同名 `Bool` 属性，返回保存的布尔值
|
||||
- 否则返回 `false`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [SetBool](SetBool.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)
|
||||
@@ -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;
|
||||
// 根据上下文补齐参数后调用 Material::GetConstantBufferData(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 返回数据只包含当前可打包的数值属性
|
||||
- texture / cubemap binding 不会写进这里
|
||||
- 调用方如果长期持有这个引用，需要自己保证 `Material` 生命周期与后续修改时机
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [UpdateConstantBuffer](UpdateConstantBuffer.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)
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
## 关键语义
|
||||
|
||||
void Example() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 根据上下文补齐参数后调用 Material::GetFloat(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 它不会尝试做类型转换
|
||||
- 对缺失属性、类型不匹配属性和 texture 属性，返回值都一样是 `0.0f`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [SetFloat](SetFloat.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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 根据上下文补齐参数后调用 Material::GetFloat2(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果存在同名 `Float2` 属性，返回其前两个分量
|
||||
- 否则返回 `Math::Vector2::Zero()`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [SetFloat2](SetFloat2.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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 根据上下文补齐参数后调用 Material::GetFloat3(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果存在同名 `Float3` 属性，返回其前三个分量
|
||||
- 否则返回 `Math::Vector3::Zero()`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [SetFloat3](SetFloat3.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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 根据上下文补齐参数后调用 Material::GetFloat4(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果存在同名 `Float4` 属性，返回四个分量
|
||||
- 否则返回 `Math::Vector4::Zero()`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [SetFloat4](SetFloat4.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() {
|
||||
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)
|
||||
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 根据上下文补齐参数后调用 Material::GetInt(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果存在同名 `Int` 属性，返回第一个整型分量
|
||||
- 否则返回 `0`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [SetInt](SetInt.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() {
|
||||
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)
|
||||
|
||||
@@ -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;
|
||||
// 根据上下文补齐参数后调用 Material::GetName(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这里不做拷贝
|
||||
- 新构造或已 [Release](Release.md) 的对象通常会返回空字符串
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [GetPath](GetPath.md)
|
||||
- [GetGUID](GetGUID.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() {
|
||||
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)
|
||||
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
20
docs/api/XCEngine/Resources/Material/Material/GetShader.md
Normal file
20
docs/api/XCEngine/Resources/Material/Material/GetShader.md
Normal file
@@ -0,0 +1,20 @@
|
||||
# Material::GetShader
|
||||
|
||||
```cpp
|
||||
class Shader* GetShader() const;
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
读取当前绑定的 shader 裸指针视图。
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 它只是 `m_shader.Get()` 的直通只读入口。
|
||||
- 未绑定 shader 时返回 `nullptr`。
|
||||
- 不转移所有权，也不增加引用计数。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Material](Material.md)
|
||||
- [SetShader](SetShader.md)
|
||||
@@ -0,0 +1,20 @@
|
||||
# Material::GetShaderPass
|
||||
|
||||
```cpp
|
||||
const Containers::String& GetShaderPass() const;
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
读取当前显式指定的 shader pass 名。
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 头文件内联实现为直接返回 `m_shaderPass` 的常量引用。
|
||||
- 默认值是空字符串。
|
||||
- 空字符串不代表失败，只表示“未显式绑定 pass 名”。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Material](Material.md)
|
||||
- [SetShaderPass](SetShaderPass.md)
|
||||
21
docs/api/XCEngine/Resources/Material/Material/GetTag.md
Normal file
21
docs/api/XCEngine/Resources/Material/Material/GetTag.md
Normal file
@@ -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)
|
||||
21
docs/api/XCEngine/Resources/Material/Material/GetTagCount.md
Normal file
21
docs/api/XCEngine/Resources/Material/Material/GetTagCount.md
Normal file
@@ -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)
|
||||
20
docs/api/XCEngine/Resources/Material/Material/GetTagName.md
Normal file
20
docs/api/XCEngine/Resources/Material/Material/GetTagName.md
Normal file
@@ -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)
|
||||
20
docs/api/XCEngine/Resources/Material/Material/GetTagValue.md
Normal file
20
docs/api/XCEngine/Resources/Material/Material/GetTagValue.md
Normal file
@@ -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)
|
||||
21
docs/api/XCEngine/Resources/Material/Material/GetTags.md
Normal file
21
docs/api/XCEngine/Resources/Material/Material/GetTags.md
Normal file
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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;
|
||||
// 根据上下文补齐参数后调用 Material::GetType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这不是从运行时状态推导出来的动态结果
|
||||
- 即使对象当前还未初始化或已被 [Release](Release.md) 重置，这个访问器仍返回 `ResourceType::Material`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [Release](Release.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() {
|
||||
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)
|
||||
|
||||
21
docs/api/XCEngine/Resources/Material/Material/HasTag.md
Normal file
21
docs/api/XCEngine/Resources/Material/Material/HasTag.md
Normal file
@@ -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)
|
||||
@@ -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() {
|
||||
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)
|
||||
|
||||
@@ -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<Texture>`
|
||||
|
||||
### 三种写入入口
|
||||
首次调用 [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) | 返回当前缓存的内存估算值。 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -0,0 +1,24 @@
|
||||
# Material::RecalculateMemorySize
|
||||
|
||||
```cpp
|
||||
void RecalculateMemorySize();
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
仅重新计算当前材质的 `memorySize`。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 当前实现只是转调内部 `UpdateMemorySize()`。
|
||||
- 不会刷新 constant buffer。
|
||||
- 不会推进 `changeVersion`。
|
||||
|
||||
## 当前使用位置
|
||||
|
||||
- `MaterialLoader`、`BuiltinResources` 和 `MeshLoader` 当前会在直接改写底层字段后调用这里，收口最终的 `memorySize`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Material](Material.md)
|
||||
- [GetMemorySize](GetMemorySize.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() {
|
||||
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)
|
||||
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
## 关键语义
|
||||
|
||||
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)
|
||||
|
||||
27
docs/api/XCEngine/Resources/Material/Material/RemoveTag.md
Normal file
27
docs/api/XCEngine/Resources/Material/Material/RemoveTag.md
Normal file
@@ -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)
|
||||
@@ -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() {
|
||||
XCEngine::Resources::Material object;
|
||||
// 根据上下文补齐参数后调用 Material::SetBool(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 常量缓冲打包时，布尔值最终会写成 `uint32 0/1`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Material.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [Material](Material.md)
|
||||
- [SetInt](SetInt.md)
|
||||
- [UpdateConstantBuffer](UpdateConstantBuffer.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() {
|
||||
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)
|
||||
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
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)
|
||||
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
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)
|
||||
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
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)
|
||||
|
||||
@@ -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 <XCEngine/Resources/Material/Material.h>
|
||||
|
||||
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)
|
||||
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
27
docs/api/XCEngine/Resources/Material/Material/SetTag.md
Normal file
27
docs/api/XCEngine/Resources/Material/Material/SetTag.md
Normal file
@@ -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)
|
||||
@@ -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() {
|
||||
XCEngine::Resources::MaterialLoader object;
|
||||
}
|
||||
```
|
||||
- `MaterialLoader` 当前是无状态 loader
|
||||
- 实际格式分派和解析逻辑都发生在 [Load](Load.md) 里，而不是构造阶段
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](MaterialLoader.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [MaterialLoader](MaterialLoader.md)
|
||||
- [Load](Load.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() {
|
||||
XCEngine::Resources::MaterialLoader object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 因为 `MaterialLoader` 当前不持有长期状态，所以析构阶段没有额外释放步骤
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](MaterialLoader.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [MaterialLoader](MaterialLoader.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() {
|
||||
XCEngine::Resources::MaterialLoader object;
|
||||
// 根据上下文补齐参数后调用 MaterialLoader::GetDefaultSettings(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这说明 `MaterialLoader` 目前没有独立的默认 `ImportSettings` 对象
|
||||
- `Load()` 也没有消费材质专属导入设置；传入的 `settings` 当前被显式忽略
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](MaterialLoader.md)
|
||||
- [返回模块目录](../Material.md)
|
||||
- [MaterialLoader](MaterialLoader.md)
|
||||
- [Load](Load.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() {
|
||||
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)
|
||||
|
||||
@@ -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
|
||||
#include <XCEngine/Resources/Material/MaterialLoader.h>
|
||||
- `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)
|
||||
|
||||
@@ -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` 这条相邻问题
|
||||
|
||||
当前阶段明确不做：
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user