XCEngine/docs/api/resources/resources-material.md

Material

命名空间: XCEngine::Resources

类型: class

描述: 材质资源类，管理渲染所需的着色器和属性参数。

概述

Material 是 XCEngine 中的材质资源类，继承自 IResource。它管理材质关联的着色器和各种属性参数（浮点数、向量、纹理等），并支持将属性数据打包到常量缓冲区。

头文件

#include <XCEngine/Resources/Material.h>

枚举类型

MaterialPropertyType

材质属性类型枚举。

值	描述
Float	单精度浮点数
Float2	二维浮点向量
Float3	三维浮点向量
Float4	四维浮点向量
Int	整数
Int2	二维整数向量
Int3	三维整数向量
Int4	四维整数向量
Bool	布尔值
Texture	纹理资源
Cubemap	立方体贴图资源

结构体

MaterialProperty

材质属性结构体。

成员	类型	描述
name	Containers::String	属性名称
type	MaterialPropertyType	属性类型
value	union	属性值（float/int/bool）
refCount	Core::uint32	引用计数

公共方法

基础属性

方法	描述
ResourceType GetType() const	返回 ResourceType::Material
const Containers::String& GetName() const	获取材质名称
const Containers::String& GetPath() const	获取材质路径
ResourceGUID GetGUID() const	获取全局唯一标识符
bool IsValid() const	检查材质是否有效
size_t GetMemorySize() const	获取内存大小
void Release()	释放材质引用

着色器管理

方法	描述
void SetShader(const ResourceHandle<Shader>& shader)	设置材质着色器
Shader* GetShader() const	获取材质着色器

属性设置

方法	描述
void SetFloat(const Containers::String& name, float value)	设置浮点属性
void SetFloat2(const Containers::String& name, const Math::Vector2& value)	设置 Vector2 属性
void SetFloat3(const Containers::String& name, const Math::Vector3& value)	设置 Vector3 属性
void SetFloat4(const Containers::String& name, const Math::Vector4& value)	设置 Vector4 属性
void SetInt(const Containers::String& name, Core::int32 value)	设置整数属性
void SetBool(const Containers::String& name, bool value)	设置布尔属性
void SetTexture(const Containers::String& name, const ResourceHandle<Texture>& texture)	设置纹理属性

属性获取

方法	描述
float GetFloat(const Containers::String& name) const	获取浮点属性
Math::Vector2 GetFloat2(const Containers::String& name) const	获取 Vector2 属性
Math::Vector3 GetFloat3(const Containers::String& name) const	获取 Vector3 属性
Math::Vector4 GetFloat4(const Containers::String& name) const	获取 Vector4 属性
Core::int32 GetInt(const Containers::String& name) const	获取整数属性
bool GetBool(const Containers::String& name) const	获取布尔属性
ResourceHandle<Texture> GetTexture(const Containers::String& name) const	获取纹理属性

常量缓冲区

方法	描述
const Containers::Array<Core::uint8>& GetConstantBufferData() const	获取常量缓冲区数据
void UpdateConstantBuffer()	更新常量缓冲区数据

属性管理

方法	描述
bool HasProperty(const Containers::String& name) const	检查属性是否存在
void RemoveProperty(const Containers::String& name)	移除属性
void ClearAllProperties()	清空所有属性

使用示例

// 加载材质
ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");

// 设置着色器
mat->SetShader(shaderHandle);

// 设置各种属性
mat->SetFloat("roughness", 0.5f);
mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f));
mat->SetTexture("albedoMap", albedoTex);
mat->SetTexture("normalMap", normalTex);
mat->SetInt("normalScale", 1);

// 获取属性
float roughness = mat->GetFloat("roughness");
Math::Vector3 albedo = mat->GetFloat3("albedo");

// 检查属性
if (mat->HasProperty("metallic")) {
    float metallic = mat->GetFloat("metallic");
}

// 更新常量缓冲区
mat->UpdateConstantBuffer();
auto cbData = mat->GetConstantBufferData();

相关文档

• IResource - 资源基类
• Shader - 着色器资源
• Texture - 纹理资源