165 lines
5.2 KiB
Markdown
165 lines
5.2 KiB
Markdown
# Material
|
|
|
|
**命名空间**: `XCEngine::Resources`
|
|
|
|
**类型**: `class`
|
|
|
|
**头文件**: `XCEngine/Resources/Material.h`
|
|
|
|
**描述**: 材质资源类，管理渲染所需的着色器和属性参数。
|
|
|
|
## 概述
|
|
|
|
`Material` 是 XCEngine 中的材质资源类，继承自 `IResource`。它管理材质关联的着色器和各种属性参数（浮点数、向量、整数、布尔值、纹理等），并支持将属性数据打包到常量缓冲区供 GPU 着色器使用。
|
|
|
|
## 头文件
|
|
|
|
```cpp
|
|
#include <XCEngine/Resources/Material.h>
|
|
```
|
|
|
|
## 枚举类型
|
|
|
|
### MaterialPropertyType
|
|
|
|
材质属性类型枚举，定义材质支持的属性数据类型。
|
|
|
|
| 值 | 描述 |
|
|
|----|------|
|
|
| `Float` | 单精度浮点数 |
|
|
| `Float2` | 二维浮点向量 |
|
|
| `Float3` | 三维浮点向量 |
|
|
| `Float4` | 四维浮点向量 |
|
|
| `Int` | 32位整数 |
|
|
| `Int2` | 二维整数向量 |
|
|
| `Int3` | 三维整数向量 |
|
|
| `Int4` | 四维整数向量 |
|
|
| `Bool` | 布尔值 |
|
|
| `Texture` | 二维纹理资源 |
|
|
| `Cubemap` | 立方体贴图资源 |
|
|
|
|
## 结构体
|
|
|
|
### MaterialProperty
|
|
|
|
材质属性结构体，存储单个属性的名称、类型和值。
|
|
|
|
| 成员 | 类型 | 描述 |
|
|
|------|------|------|
|
|
| `name` | `Containers::String` | 属性名称标识符 |
|
|
| `type` | `MaterialPropertyType` | 属性数据类型 |
|
|
| `value` | `union Value` | 属性值联合体，支持 float[4]、int[4]、bool |
|
|
| `refCount` | `Core::uint32` | 引用计数 |
|
|
|
|
## 公共方法表格
|
|
|
|
### 资源基类方法
|
|
|
|
| 方法 | 描述 |
|
|
|------|------|
|
|
| `GetType()` | 返回 `ResourceType::Material` |
|
|
| `GetName()` | 获取材质名称 |
|
|
| `GetPath()` | 获取材质资源路径 |
|
|
| `GetGUID()` | 获取全局唯一标识符 |
|
|
| `IsValid()` | 检查材质是否有效且已加载 |
|
|
| `GetMemorySize()` | 获取材质占用的内存大小 |
|
|
| `Release()` | 释放材质所有引用和资源 |
|
|
|
|
### 着色器管理
|
|
|
|
| 方法 | 描述 |
|
|
|------|------|
|
|
| [`SetShader`](set-shader.md) | 设置材质使用的着色器 |
|
|
| [`GetShader`](get-shader.md) | 获取材质关联的着色器指针 |
|
|
|
|
### 属性设置方法
|
|
|
|
| 方法 | 描述 |
|
|
|------|------|
|
|
| [`SetFloat`](set-float.md) | 设置浮点属性 |
|
|
| [`SetFloat2`](set-float2.md) | 设置二维向量属性 |
|
|
| [`SetFloat3`](set-float3.md) | 设置三维向量属性 |
|
|
| [`SetFloat4`](set-float4.md) | 设置四维向量属性 |
|
|
| [`SetInt`](set-int.md) | 设置整数属性 |
|
|
| [`SetBool`](set-bool.md) | 设置布尔属性 |
|
|
| [`SetTexture`](set-texture.md) | 设置纹理属性 |
|
|
|
|
### 属性获取方法
|
|
|
|
| 方法 | 描述 |
|
|
|------|------|
|
|
| [`GetFloat`](get-float.md) | 获取浮点属性值，不存在返回 0.0f |
|
|
| [`GetFloat2`](get-float2.md) | 获取二维向量属性值 |
|
|
| [`GetFloat3`](get-float3.md) | 获取三维向量属性值 |
|
|
| [`GetFloat4`](get-float4.md) | 获取四维向量属性值 |
|
|
| [`GetInt`](get-int.md) | 获取整数属性值，不存在返回 0 |
|
|
| [`GetBool`](get-bool.md) | 获取布尔属性值，不存在返回 false |
|
|
| [`GetTexture`](get-texture.md) | 获取纹理属性句柄 |
|
|
|
|
### 常量缓冲区
|
|
|
|
| 方法 | 描述 |
|
|
|------|------|
|
|
| [`GetConstantBufferData`](get-constant-buffer-data.md) | 获取常量缓冲区原始数据 |
|
|
| [`UpdateConstantBuffer`](update-constant-buffer.md) | 更新常量缓冲区数据 |
|
|
|
|
### 属性查询与管理
|
|
|
|
| 方法 | 描述 |
|
|
|------|------|
|
|
| [`HasProperty`](has-property.md) | 检查指定属性是否存在 |
|
|
| [`RemoveProperty`](remove-property.md) | 移除指定属性 |
|
|
| [`ClearAllProperties`](clear-all-properties.md) | 清空所有属性和纹理绑定 |
|
|
|
|
## 使用示例
|
|
|
|
```cpp
|
|
// 通过资源管理器加载材质
|
|
ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
|
|
|
|
// 设置着色器
|
|
ResourceHandle<Shader> shader = ResourceManager::Get().Load<Shader>("shaders/pbr.shader");
|
|
mat->SetShader(shader);
|
|
|
|
// 设置材质属性
|
|
mat->SetFloat("roughness", 0.5f);
|
|
mat->SetFloat("metallic", 0.0f);
|
|
mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f));
|
|
mat->SetFloat4("emission", Math::Vector4(1.0f, 0.5f, 0.2f, 2.0f));
|
|
mat->SetInt("normalScale", 1);
|
|
mat->SetBool("receiveShadow", true);
|
|
|
|
// 设置纹理
|
|
ResourceHandle<Texture> albedoTex = ResourceManager::Get().Load<Texture>("textures/albedo.png");
|
|
ResourceHandle<Texture> normalTex = ResourceManager::Get().Load<Texture>("textures/normal.png");
|
|
ResourceHandle<Texture> roughnessTex = ResourceManager::Get().Load<Texture>("textures/roughness.png");
|
|
mat->SetTexture("albedoMap", albedoTex);
|
|
mat->SetTexture("normalMap", normalTex);
|
|
mat->SetTexture("roughnessMap", roughnessTex);
|
|
|
|
// 获取属性
|
|
float roughness = mat->GetFloat("roughness");
|
|
Math::Vector3 albedo = mat->GetFloat3("albedo");
|
|
Shader* shader = mat->GetShader();
|
|
|
|
// 属性查询
|
|
if (mat->HasProperty("metallic")) {
|
|
float metallic = mat->GetFloat("metallic");
|
|
}
|
|
|
|
// 更新常量缓冲区供 GPU 使用
|
|
mat->UpdateConstantBuffer();
|
|
const auto& cbData = mat->GetConstantBufferData();
|
|
|
|
// 释放材质
|
|
mat->Release();
|
|
```
|
|
|
|
## 相关文档
|
|
|
|
- [IResource](../iresource/iresource.md) - 资源基类接口
|
|
- [Shader](../shader/shader.md) - 着色器资源
|
|
- [Texture](../texture/texture.md) - 纹理资源
|
|
- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
|
|
- [Resources 模块总览](../resources.md) - 返回模块总览
|