材质

NMaterial

• 接口

接口	说明
GetMainTexture	获取主纹理
SetMainTexture	设置主纹理
SetRenderTexture	将渲染纹理设置到主纹理
GetMainColor	获取主颜色
SetMainColor	设置主颜色
SetMainTextureScale	设置主纹理缩放
SetMainTextureOffset	设置主纹理偏移
GetMainTextureScale	获取主纹理缩放
GetMainTextureOffset	获取主纹理偏移
SetShaderProperty	设置着色器属性
GetShaderProperty	获取着色器属性
SetMaterialShaderType	设置材质使用的材质着色器类型
GetMaterialShaderType	获取材质使用的材质着色器类型
GetRenderQueueLayer	获取材质的渲染顺序层
SetRenderQueueLayer	设置材质的渲染顺序层
GetPipelineState	获取材质的渲染状态
SetPipelineState	设置材质的渲染状态
IsEnableGPUInstance	获取是否开启GPU实例化
SetEnableGPUInstance	设置是否开启GPU实例化

属性设置接口

• 接口

void SetShaderProperty(const EngineString& name, NTexturePtr value);
void SetShaderProperty(const EngineString& name, ITexture* value);
void SetShaderProperty(const EngineString& name, NRenderTexturePtr value, ESurfaceInRenderTexture type = ESurfaceInRenderTexture::ColorSurface);
void SetShaderProperty(const EngineString& name, const Color& value);
void SetShaderProperty(const EngineString& name, const HDRColor& value);
void SetShaderProperty(const EngineString& name, int value);
void SetShaderProperty(const EngineString& name, float value);
void SetShaderProperty(const EngineString& name, bool value);
void SetShaderProperty(const EngineString& name, const Vector2& value);
void SetShaderProperty(const EngineString& name, const Vector3& value);
void SetShaderProperty(const EngineString& name, const Vector4& value);
void SetShaderProperty(const EngineString& name, const Matrix4& value);
void SetShaderProperty(const EngineString& name, const std::vector<Vector4f>& value);
void SetShaderProperty(const EngineStrin &; name, const std::vector<int>& value);
void SetShaderProperty(const EngineString& name, const std::vector<float>& value);
void SetShaderProperty(const EngineString& name, const std::vector<Vector2f>& value);
void SetShaderProperty(const EngineString& name, const std::vector<Vector3f>& value);

• 参数

参数	说明
name	属性名
value	参数值
type	渲染纹理的颜色附件或者深度附件

• 描述

您可以通过NMaterial的SetShaderProperty参数设置材质属性值。 其中，当value的类型为渲染纹理时，您需要指定绑定的是颜色纹理附件还是深度纹理附件。

其中，当value的类型是Color、Color32、HDRColor时，您只需要传入sRGB空间的颜色即可，参数设置接口会自动做线性颜色转换。

其中，当value的类型是Matrix4时，针对GL，引擎会自动做转置计算，您无需担心转置问题。

void ExampleClass::Update()
{
	NMaterialPtr mat = GetNActor()->GetComponent<NMeshComponent>()->GetMaterial();
	mat->SetShaderProperty(“metallValue”, 0.0f);
	mat->SetShaderProperty(“usedCutOut”, false);
	mat->SetShaderProperty(“Offset”, Vector2f(0.0f, 0.0f));
	mat->SetShaderProperty(“Tiling”, Vector2f(1.0f, 1.0f));
}

属性获取接口

• 接口

NTexturePtr GetShaderTextureProperty(const EngineString& name);
const Color& GetShaderColorProperty(const EngineString& name);
int GetShaderIntProperty(const EngineString& name);
float GetShaderFloatProperty(const EngineString& name);
bool GetShaderBoolProperty(const EngineString& name);
const Vector2& GetShaderVector2Property(const EngineString& name);
const Vector3& GetShaderVector3Property(const EngineString& name);
const Vector4& GetShaderVector4Property(const EngineString& name);
const Matrix4& GetShaderMatrix4Property(const EngineString& name);
const std::vector<Vector4f> GetShaderVector4ArrayProperty(const EngineString& name);
const std::vector<int> GetShaderIntArrayProperty(const EngineString& name);
const std::vector<float> GetShaderFloatArrayProperty(const EngineString& name);
const std::vector<Vector2f> GetShaderVector2ArrayProperty(const EngineString& name);
const std::vector<Vector3f> GetShaderVector3ArrayProperty(const EngineString& name);

• 参数

参数	说明
name	需要查询的属性名

• 描述

您可以通过NMaterial的GetShaderXXXProperty接口获取材质已经设置的属性值。

如果材质中实际存储的值类型和您调用的Get函数不一致，可能无法得出正确的结果，请务必保持一致。

void ExampleClass::Update()
{
	NMaterialPtr mat = GetNActor()->GetComponent<NMeshComponent>()->GetMaterial();
	mat->GetShaderFloatProperty (“metallValue”, 0.0f);
	mat->GetShaderBoolProperty (“usedCutOut”, false);
	mat->GetShaderVector2Property (“Offset”, Vector2f(0.0f, 0.0f));
	mat->GetShaderVector2Property (“Tiling”, Vector2f(1.0f, 1.0f));
}

便利性属性设置和获取接口

• 接口

NTexturePtr GetMainTexture();
void SetMainTexture(NTexturePtr texture);
void SetRenderTexture(const NRenderTexturePtr texure);
Color GetMainColor();
void SetMainColor(const Color& color);
void SetMainTextureScale(const Vector2& scale);
void SetMainTextureOffset(const Vector2& offset);
Vector2 GetMainTextureScale();
Vector2 GetMainTextureOffset();

• 参数

参数	说明
texure	纹理对象/渲染纹理对象
color	主颜色
scale	纹理缩放
offset	纹理偏移

• 描述

您可以通过NMaterial提供的便利性属性设置和获取接口，设置或获取常用的属性信息。

如果材质中不包含这些属性，可能会获取到未知结果。

void ExampleClass::Update()
{
	NMaterialPtr mat = GetNActor()->GetComponent<NMeshComponent>()->GetMaterial();
	mat->SetMainTexture(nullptr);
	mat->SetMainColor(Color::White);
	mat-> SetMainTextureScale (Vector2f(0.0f, 0.0f));
	mat-> SetMainTextureScale (Vector2f(1.0f, 1.0f));
}

材质渲染状态接口

• 接口

PipelineState GetPipelineState(int passIndex=0);
void SetPipelineState(const PipelineState& pipelineState,int passIndex=0);
DepthState GetDepthState(int passIndex=0);
StencilState GetStencilState(int passIndex = 0);
BlendingState GetBlendingState(int passIndex = 0);
RasterState GetRasterState(int passIndex = 0);
void SetDepthState(const DepthState& depthState, int passIndex = 0);
void SetStencilState(const StencilState& stencilState, int passIndex = 0);
void SetBlendingState(const BlendingState& blendState, int passIndex = 0);
void SetRasterState(const RasterState& rasterState, int passIndex = 0);

• 参数

参数	说明
passIndex	Pass的序号
pipelineState	渲染状态
depthState	深度渲染状态
stencilState	模板渲染状态
blendState	混合渲染状态
rasterState	光栅渲染状态

• 深度渲染状态

参数	说明
depthTest	是否开启深度测试
depthWrite	是否开启深度写入
compareFunc	深度比较函数

• 模板渲染状态

参数	说明
stencilTest	是否开启模板检测
readMask	模板读取遮罩
writeMask	模板写入遮罩
refValue	模板测试值
compareFuncFront	正面模板比较函数
passOpFront	正面模板比较通过操作符
failOpFront	正面模板比较失败操作符
depthFailOpFront	正面深度比较失败操作符
compareFuncBack	背面模板比较函数
passOpBack	背面模板比较通过操作符
failOpBack	背面模板比较失败操作符
depthFailOpBack	背面深度比较失败操作符

• 混合渲染状态

参数	说明
enableAlphaTest	是否开启透明度检测
enableBlending	是否开启颜色混合
srcFactor	源颜色混合系数
dstFactor	目标颜色混合系数
srcAlphaFactor	源透明度混合系数
dstAlphaFactor	目标透明度混合系数
colorBlendOp	颜色混合操作符
alphaBlendOp	透明度混合操作符
compareFunc	比较函数
alphaCutoff	透明度截断
colorWriteMask	颜色写入遮罩

• 光栅渲染状态

参数	说明
cullMode	剔除模式
depthBias	深度偏移
slopeScaledDepthBias	坡度缩放深度偏移
depthClamp	深度裁剪

• 多边形渲染状态

参数	说明
fillMode	填充模式（仅GL支持）
lineWidth	线宽度
pointSize	点大小（仅GL支持）

• 描述

您可以通过NMaterial的SetPipelineState接口来设置全部的渲染状态，也可以通过SetXXXState来设置单个类别的渲染状态。

void ExampleClass::Update()
{
	NMaterialPtr mat = GetNActor()->GetComponent<NMeshComponent>()->GetMaterial();
	DepthState state = mat->GetDepthState();
	state.depthTest = false;
	mat->SetDepthState(state);
}

材质状态接口

• 接口

void SetMaterialShaderType(EngineString materialShaderName);
const EngineString& GetMaterialShaderType();
uint32 GetRenderQueueLayer();
void SetRenderQueueLayer(uint32 layer);
void SetRenderQueueTag(ERenderQueueTag queueTag);
ERenderQueueTag GetRenderQueueTag();
void RefreshUniformsImmediately();
bool IsEnableGPUInstance();
void SetEnableGPUInstance(bool value);

• 参数

参数	说明
materialShaderName	材质着色器类型名
layer	材质渲染顺序
value	是否开启GPU实例化渲染

• 描述

您可以通过NMaterial的SetMaterialShaderType接口设置材质的材质着色器，例如切换到BlinnPhong或者PBR材质。 您可以通过SetRenderQueueTag设置材质的渲染队列的来源，如由材质着色器指定等。 如果RenderQueueTag是ERQT_FromMaterialShader，则修改RenderQueueLayer无效

• ERenderQueueTag

数值	材质渲染队列
ERQT_FromMaterialShader	从材质着色器读取
ERQT_Background	Background
ERQT_Opaque	Opaque
ERQT_Transparent	Transparent
ERQT_Overlay	Overlay

您可以通过SetRenderQueueLayer设置材质的渲染顺序，如不透明、半透明、Overlay等。

数值	材质渲染队列
0-500	Background
500-3500	Opaque
3500-6500	Transparent
6500-∞	Overlay

您可以通过SetEnableGPUInstance设置是否使用GPU实例化功能。

当您修改了材质属性后需要及时应用时，请调用RefreshUniformsImmediately函数进行刷新，否则引擎只会在渲染前统一刷新属性。

void ExampleClass::Update()
{
	NMaterialPtr mat = GetNActor()->GetComponent<NMeshComponent>()->GetMaterial();
	mat->SetMaterialShaderType(“Unlit”);
}

材质文件

您可以在编辑器的资源界面创建材质文件，并将其拖给有可以接收材质的物体。 当您点击了材质文件后，会展开其属性反射，您可以进行修改。

材质球预览

编辑器支持预览材质球效果，当您修改材质属性时，下方的材质球预览界面会应用改动后的属性。 材质球预览界面有两个按钮，分别时切换光源个数和切换材质球显示模型。

运行时材质创建

• 接口

static NMaterialPtr CreateMaterial(const std::string& name, EMaterialTemplate materialTemplate);
static NMaterialPtr CreateMaterial(const std::string& name, const std::string& materialShaderType);
static NMaterialPtr LoadMaterial(const std::string& path);

• 参数

参数	说明
name	材质名称
materialTemplate	内置材质着色器模板
materialShaderType	自定义的材质着色器
path	材质文件路径

• 描述

您可以通过NResources提供的相关接口创建或者加载材质。

void ExampleClass::Update()
{
	NMaterialPtr mat =NResources::CreateMaterial(“Test”, EMaterialTemplate::MT_Unlit);
	NMaterialPtr mat1 =NResources::CreateMaterial(“Test1”, ”TestMaterialShader”);
	NMaterialPtr mat2 =NResources::LoadMaterial(“Assets/Materials/Custom.nmat”);
}