模型材质（程序）

概述

本文档主要讲解程序代码（C++和Lua）如何设置模型材质和需要注意的一些事项。

模型材质（Model Materials）指模型（Model），蒙皮（Skin），贴花（Decal）等对象使用的材质，继承自IVisbase。

对于包含以上对象的组合类型，比如组合体对象（Actor Object）、特效模型对象（Effect Model Object），需要获取具体的模型对象才能编辑其材质。

如果需要对一个组件对象设置模型材质，需要先获取到上述对象的直接组件对象LModelComponent、LSkinComponent、LDecalComponent等，然后再获取到它的代理对象，用代理对象设置材质。当通过Lua脚本设置时，也可以直接编辑组件对象LModelComponent、LSkinComponent、LDecalComponent等的材质， C++代码是不可以的。

设置材质文件接口

• SetExternalMaterialFile设置和它引用同一个模型文件的对象的材质文件，支持设置一个材质或者多个材质引用的材质文件。

      bool SetExternalMaterialFile(const char* material_name, 
          const char* file,  const char* section);

• SetPrivateMaterialFile设置当前对象的材质文件，支持设置一个材质或者多个材质引用的材质文件。

      bool SetPrivateMaterialFile(const char* material_name, 
          const char* file,  const char* section);

• LoadMaterial加载材质文件，由SetExternalMaterialFile, SetPrivateMaterialFile修改对象关联材质文件后，需要调用LoadMaterial使修改立即生效。

    bool LoadMaterial(bool asynchronization = true);

参数说明

SetExternalMaterialFile，SetPrivateMaterialFile参数个数和含义相同，如下：

• material_name：材质名，可以通过GetMaterialNameList接口查询所有的材质名。也可以在材质编辑器（Material Editor）里面浏览模型的所有材质名。

  void GetMaterialNameList(const IVarList& args,   IVarList& result)

  材质名可以设置成""，表示对象中的所有材质都引用下面的file参数指定的材质文件。

• file: 材质文件，引擎使用的材质文件，扩展名为.mtl，格式为Ini格式。

• section: 已经废弃的属性，设置成""即可。原来指材质Ini文件中的段落名字。

LoadMaterial 有一个可选参数asynchronization，表示是否使用异步加载模式，默认是true，可以省略。

Lua代码示例

模型资源：%EditorResource%mdl\base_shape\mat.xmod 材质资源：%EditorResource%mdl\base_shape\pbr_metalic.mtl

--设置模型资源的Mat_1材质引用的材质文件
Model:SetExternalMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--设置模型资源的所有材质引用的材质文件
Model:SetExternalMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--设置当前对象的Mat_1材质引用的材质文件
Model:SetPrivateMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--设置当前对象的所有材质引用的材质文件
Model:SetPrivateMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--重载材质,使其立即生效
Model:LoadMaterial()

C++代码示例

模型资源：%EditorResource%mdl\base_shape\mat.xmod 材质资源：%EditorResource%mdl\base_shape\pbr_metalic.mtl

IVisBase* pVisual;
//设置模型资源的Mat_1材质引用的材质文件
pVisual->SetExternalMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

//设置模型资源的所有材质引用的材质文件
pVisual->SetExternalMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

//设置当前对象的Mat_1材质引用的材质文件
pVisual->SetPrivateMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

//设置当前对象的所有材质引用的材质文件
pVisual->SetPrivateMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")
    
//重载材质,使其立即生效
pVisual->LoadMaterial()

设置材质属性接口

• SetCustomMaterialValue修改一个对象的材质实例的属性。只影响这个对象的材质，不影响其他和它引用同一个材质文件的对象。

      bool SetCustomMaterialValue(const char* material_name, 
          const char* key,  const char* val);

• SetModelMaterialValue修改一个材质的所有材质实例的属性。

      bool SetModelMaterialValue(const char* material_name, 
          const char* key,  const char* val);

参数说明

SetCustomMaterialValue，SetModelMaterialValue参数个数和含义相同。

• material_name: 材质名, 可以通过GetMaterialNameList接口查询所有的材质名，也可以在材质编辑器里面浏览模型的所有材质名。

  void GetMaterialNameList(const IVarList& args,   IVarList& result) 

• key：材质属性名，常用的有Ambient, Diffuse, Metallic, Roughness, SpecularLevel, DiffuseMap, NormalMap, MetallicMap等。 可以通过下面的配置查询到：

  * **/00_flexi_engine/client/unique_editor/pro/skin/pl_material/material_config/model_material.xml**
  * 任意一个**.mtl**文件

• val：属性值，各种属性类型（bool, float, int, color, vector, map）值的字符串格式，其中颜色属性需用浮点数表示，以下表格式列举：

类型	值	属性值
bool	false	"false"
bool	true	"true"
float	0.0	"0.0"
int	0	"0"
color	1.0, 1.1, 0.5	"1.0, 1.1, 0.5"
color	255, 255, 0	"1.0, 1.0, 0.0"
vector	1.0, 2.0, 3.0	"1.0, 2.0, 3.0"
path	"c：\abc.dds"	"c：\abc.dds"

Lua代码示例

模型资源：%EditorResource%mdl\base_shape\mat.xmod

Model:SetCustomMaterialValue("Mat_1", "Diffuse", "1.0, 0, 0")

C++代码示例

模型资源：%EditorResource%mdl\base_shape\mat.xmod

IVisBase* pVisual;
...
((IMeshVisual*)pVisual)->SetCustomMaterialValue("Mat_1", "Diffuse", "1.0, 0, 0")

or

CVarList result;
g_pCore->InvokeMethod(pVisual, "SetCustomMaterialValue", CVarList()<< "Mat_1" << "Diffuse" << "1.0, 0, 0", result)

设置材质文件和材质属性的注意事项

区别

• 设置材质文件，会将材质文件里面的所有属性设置给材质。
• 设置材质属性，仅修改指定的材质属性。

同时使用两种设置

设置材质文件和设置材质属性，都可以更新材质属性，一般情况下不需要同时设置。特殊情况下同时使用，也是有效的。

• 需先设置材质文件，确保材质加载完成后，才可以通过材质接口进行材质属性设置，否则会出现属性设置被覆盖的问题。

• 确保材质加载完成，可以用LoadMaterial(false)进行同步加载，或者用LoadMaterial(true)进行异步加载，然后进行加载等待。

贴图属性设置

• 通过材质文件设置的材质，调用LoadMaterial()后，内部会自动执行贴图的重载，无需额外的调用贴图重载操作。
• 如果通过接口设置的是贴图属性，还需要调用ReloadMaterialTexture或ReloadAllMaterialTextures方可生效。