Version:

Lua 材质函数 API

Lua 材质函数允许自定义处理材质属性的逻辑。它们可以读取属性值、设置着色器输入和着色器选项、配置渲染状态、调整编辑器中材质属性的可见性等。

有关 Lua 编程语言的一般信息，请参阅学习 Lua。

Note:
Lua 材质函数有别于** Lua 游戏脚本**。虽然它们都使用 Lua 语言，但应用程序接口和编程环境大多是分开的。EBuses、属性表和实体集成等功能是游戏脚本独有的，Lua 材质函数无法使用。 Lua 数学库是 API 中唯一两个系统通用的部分。

名称上下文

材质函数可以在隐式名称上下文中运行，在这种上下文中，脚本中出现的名称会附加某些前缀。这样，同一个 Lua 脚本就可以在不同的上下文中使用。

例如，一种材质类型可能有一个名为 “metallic的组，而另一种材质类型则有一个名为 “metalness ”的组。在这两种情况下，组都具有texture 和 factor属性。Lua 函数将以简单的texture 和 factor来引用这些属性，系统会在内部自动预置相应的名称上下文。材质属性、着色器输入（常量或图像）和着色器选项可能各有一个单独的名称上下文。

有关如何指定名称上下文的详细信息，请在材质类型文件规范中搜索 “前缀”。

主函数

材质系统希望在 Lua 脚本的全局范围内定义以下函数。

Process(`context`)

这是材质用于渲染时运行的主要函数。它在材质首次初始化或相关材质属性值发生变化时运行。 context 对象提供了访问 API 的途径，以便访问材质属性和着色器。

ProcessEditor(`context`)

这是材质在工具中编辑时运行的主要函数。它在材质首次初始化或相关材质属性值发生变化时运行。context对象提供了访问 API 的途径，以便访问材质属性及其元数据。

GetMaterialPropertyDependencies()

返回函数可以读取的所有材质属性的列表。对于未报告依赖关系而访问的属性，将报告错误。

GetShaderOptionDependencies()

返回函数可能设置的所有着色器选项的列表。对于未报告依赖关系而访问的选项，将报告错误。(请注意，C++ API 中的Material::SetSystemShaderOption函数只能在未声明为依赖关系或未被材质类型使用的着色器选项上调用）。

示例:

function GetMaterialPropertyDependencies()
    return {"textureMap", "useTexture"}
end
 
function GetShaderOptionDependencies()
    return {"o_metallic_useTexture"}
end

function Process(context)
    local textureMap = context:GetMaterialPropertyValue_Image("textureMap")
    local useTexture = context:GetMaterialPropertyValue_bool("useTexture")
    context:SetShaderOptionValue_bool("o_metallic_useTexture", useTexture and textureMap ~= nil)
end

function ProcessEditor(context)
    local textureMap = context:GetMaterialPropertyValue_Image("textureMap")
    local useTexture = context:GetMaterialPropertyValue_bool("useTexture")

    if(nil == textureMap) then
        context:SetMaterialPropertyVisibility("useTexture", MaterialPropertyVisibility_Hidden)
        context:SetMaterialPropertyVisibility("textureMapUv", MaterialPropertyVisibility_Hidden)
        context:SetMaterialPropertyVisibility("factor", MaterialPropertyVisibility_Enabled)
    elseif(not useTexture) then
        context:SetMaterialPropertyVisibility("useTexture", MaterialPropertyVisibility_Enabled)
        context:SetMaterialPropertyVisibility("textureMapUv", MaterialPropertyVisibility_Disabled)
        context:SetMaterialPropertyVisibility("factor", MaterialPropertyVisibility_Enabled)
    else
        context:SetMaterialPropertyVisibility("useTexture", MaterialPropertyVisibility_Enabled)
        context:SetMaterialPropertyVisibility("textureMapUv", MaterialPropertyVisibility_Enabled)
        context:SetMaterialPropertyVisibility("factor", MaterialPropertyVisibility_Hidden)
    end
end

全局实用函数

这些函数可在全局范围内使用。

Error(string): 向 AZ_Error报告错误信息。
Warning(string): 向 AZ_Warning报告警告信息。
Print(string): 向AZ_TracePrintf报告信息。

Process(context) 函数

这些函数在传递给 Process 函数的 context 对象中可用。

GetMaterialPropertyValue_

每个 GetMaterialPropertyValue_ 函数都会获取一个string属性名称，并返回相应类型的值。必须使用与材质属性的数据类型相匹配的版本。材质属性必须在 GetMaterialPropertyDependencies 中列出。

GetMaterialPropertyValue_bool(string): 返回boolean
GetMaterialPropertyValue_int(string): 返回number
GetMaterialPropertyValue_uint(string): 返回number
GetMaterialPropertyValue_enum(string): 返回number
GetMaterialPropertyValue_float(string): 返回number
GetMaterialPropertyValue_Vector2(string): 返回Vector2类型。查看 Lua Math Library.
GetMaterialPropertyValue_Vector3(string): 返回Vector3类型。查看 Lua Math Library.
GetMaterialPropertyValue_Vector4(string): 返回Vector4类型。查看 Lua Math Library.
GetMaterialPropertyValue_Color(string): 返回Color类型。查看 Lua Math Library.
GetMaterialPropertyValue_Image(string): 返回userdata类型的泛型指南，如果图像可用；否则返回nil。

HasMaterialProperty(`string`)

返回给定名称的属性是否存在的布尔值。请注意，材质属性不必在 GetMaterialPropertyDependencies 中列出，因为此函数仅检查可用性，而不是读取值。

SetShaderConstant_

函数 SetShaderConstant_ 已重命名为 SetShaderParameterValue_，以更准确地反映底层实现。为了向后兼容，SetShaderConstant_ 函数仍然可用，但被视为已弃用。

每个 SetShaderParameterValue_ 函数都采用要设置的string着色器输入名称和值。必须使用与着色器输入的数据类型匹配的版本。

SetShaderParameterValue_bool(string, boolean)
SetShaderParameterValue_int(string, number)
SetShaderParameterValue_uint(string, number)
SetShaderParameterValue_float(string, number)
SetShaderParameterValue_Vector2(string, Vector2)
SetShaderParameterValue_Vector3(string, Vector3)
SetShaderParameterValue_Vector4(string, Vector4)
SetShaderParameterValue_Color(string, Color)
SetShaderParameterValue_Matrix3x3(string, Matrix3x3)
SetShaderParameterValue_Matrix4x4(string, Matrix4x4)

SetShaderOptionValue_

每个SetShaderOptionValue_ 函数都会接收一个 string 着色器选项名称和要设置的值。该值将应用于材质类型中所有具有给定名称选项的着色器。必须使用与着色器选项的数据类型相匹配的版本。着色器选项必须列在 GetShaderOptionDependencies中。

SetShaderOptionValue_bool(string, boolean)
SetShaderOptionValue_uint(string, number)
SetShaderOptionValue_enum(string, number)

Note:
在 ShaderItem 对象中也有类似的 SetShaderOptionValue_ 函数，可对单个着色器进行操作。

GetShaderCount()

返回材质类型中着色器的数量。

GetShader(`number`)

返回给定索引处的 ShaderItem 或一个虚拟的 ShaderItem （如果索引超出范围）。参见 ShaderItem 函数。

GetShaderByTag(`string`)

返回具有给定标签名称的ShaderItem ，如果未找到该名称，则返回一个虚拟的ShaderItem 。请参阅 ShaderItem 函数和材质类型文件规范中的着色器标记。

HasShaderWithTag(`string`)

返回一个 boolean 值，表示是否存在具有给定标签名称的着色器。请参阅材质类型文件规范中的着色器标签。

ProcessEditor(context) 函数

这些函数在传递给 ProcessEditor 函数的 context 对象中可用。

GetMaterialPropertyValue_

每个 GetMaterialPropertyValue_ 函数都会获取一个string属性名称，并返回相应类型的值。您必须使用与材质属性的数据类型相匹配的版本。材质属性必须在 GetMaterialPropertyDependencies中列出。

GetMaterialPropertyValue_bool(string): 返回boolean
GetMaterialPropertyValue_int(string): 返回number
GetMaterialPropertyValue_uint(string): 返回number
GetMaterialPropertyValue_enum(string): 返回number
GetMaterialPropertyValue_float(string): 返回number
GetMaterialPropertyValue_Vector2(string): 返回Vector2类型。查看 Lua Math Library.
GetMaterialPropertyValue_Vector3(string): 返回Vector3类型。查看 Lua Math Library.
GetMaterialPropertyValue_Vector4(string): 返回Vector4类型。查看 Lua Math Library.
GetMaterialPropertyValue_Color(string): 返回Color类型。查看 Lua Math Library.
GetMaterialPropertyValue_Image(string): 返回userdata类型的泛型指南，如果图像可用；否则返回nil。

SetMaterialProperty

每个 SetMaterialProperty 函数都接收一个string属性名，并设置该属性的编辑器元数据的某些方面。请参阅材质类型文件规范中的属性布局中的相应项。请注意，材质属性不必在 GetMaterialPropertyDependencies中列出，因为这些函数只是设置元数据，而不是读取数值。

SetMaterialPropertyDescription(string, string)
SetMaterialPropertyMinValue_int(string, number)
SetMaterialPropertyMinValue_uint(string, number)
SetMaterialPropertyMinValue_float(string, number)
SetMaterialPropertyMaxValue_int(string, number)
SetMaterialPropertyMaxValue_uint(string, number)
SetMaterialPropertyMaxValue_float(string, number)
SetMaterialPropertySoftMinValue_int(string, number)
SetMaterialPropertySoftMinValue_uint(string, number)
SetMaterialPropertySoftMinValue_float(string, number)
SetMaterialPropertySoftMaxValue_int(string, number)
SetMaterialPropertySoftMaxValue_uint(string, number)
SetMaterialPropertySoftMaxValue_float(string, number)
SetMaterialPropertyGroupVisibility(string, MaterialPropertyVisibility): 类似于SetMaterialPropertyVisibility，设置整个组而不是单个属性的可见性。

ShaderItem functions

ShaderItem 是一个 lua userdata项，具有以下功能：

GetRenderStatesOverride()

返回一个 RenderStates 对象，该对象可用于为任何可用的呈现状态设置重载。

SetEnabled(boolean)

设置是否启用着色器。

SetDrawListTagOverride(`string`)

覆盖着色器将使用的绘制列表标签名称。设置为空字符串可清除覆盖并恢复 .shader 文件中的值。参见着色器文件规范中的DrawList。

SetShaderOptionValue_

每个 SetShaderOptionValue_ 函数都使用一个string着色器选项名称和值来更新此着色器的一个选项。你必须使用与着色器选项的数据类型相匹配的版本。着色器选项必须在 GetShaderOptionDependencies中列出。

SetShaderOptionValue_bool(string, boolean)
SetShaderOptionValue_uint(string, number)
SetShaderOptionValue_enum(string, number)

Note:
在 Process(context) 中也有类似的 SetShaderOptionValue_ 函数，可对单个着色器进行操作。

RenderStates 函数

RenderStates 是一个具有以下功能的 lua userdata项。每个渲染状态都有一个 Set 函数用于设置覆盖值，还有一个 Clear 函数用于清除覆盖值并恢复默认值。这些函数中的大部分都是对低级渲染 API 的轻量封装。

Multisample State 函数

SetMultisampleCustomPosition(number multisampleCustomLocationIndex, number x, number y)
ClearMultisampleCustomPosition
SetMultisampleCustomPositionCount(number)
ClearMultisampleCustomPositionCount
SetMultisampleCount(number)
ClearMultisampleCount
SetMultisampleQuality(number)
ClearMultisampleQuality

Raster State 函数

SetFillMode( FillMode)
ClearFillMode
SetCullMode( CullMode)
ClearCullMode
SetDepthBias(number)
ClearDepthBias
SetDepthBiasClamp(number)
ClearDepthBiasClamp
SetDepthBiasSlopeScale(number)
ClearDepthBiasSlopeScale
SetMultisampleEnabled(boolean)
ClearMultisampleEnabled
SetDepthClipEnabled(boolean)
ClearDepthClipEnabled
SetConservativeRasterEnabled(boolean)
ClearConservativeRasterEnabled
SetForcedSampleCount(number)
ClearForcedSampleCount

Blend State 函数

SetAlphaToCoverageEnabled(boolean)
ClearAlphaToCoverageEnabled
SetIndependentBlendEnabled(boolean)
ClearIndependentBlendEnabled
SetBlendEnabled(boolean)
ClearBlendEnabled
SetBlendWriteMask(number)
ClearBlendWriteMask
SetBlendSource( BlendFactor)
ClearBlendSource
SetBlendDest( BlendFactor)
ClearBlendDest
SetBlendOp( BlendOp)
ClearBlendOp
SetBlendAlphaSource( BlendFactor)
ClearBlendAlphaSource
SetBlendAlphaDest( BlendFactor)
ClearBlendAlphaDest
SetBlendAlphaOp( BlendOp)
ClearBlendAlphaOp

Depth/Stencil State 函数

SetDepthEnabled(boolean)
ClearDepthEnabled
SetDepthWriteMask( DepthWriteMask)
ClearDepthWriteMask
SetDepthComparisonFunc( ComparisonFunc)
ClearDepthComparisonFunc
SetStencilEnabled(boolean)
ClearStencilEnabled
SetStencilReadMask(number)
ClearStencilReadMask
SetStencilWriteMask(number)
ClearStencilWriteMask
SetStencilFrontFaceFailOp( StencilOp)
ClearStencilFrontFaceFailOp
SetStencilFrontFaceDepthFailOp( StencilOp)
ClearStencilFrontFaceDepthFailOp
SetStencilFrontFacePassOp( StencilOp)
ClearStencilFrontFacePassOp
SetStencilFrontFaceFunc( ComparisonFunc)
ClearStencilFrontFaceFunc
SetStencilBackFaceFailOp( StencilOp)
ClearStencilBackFaceFailOp
SetStencilBackFaceDepthFailOp( StencilOp)
ClearStencilBackFaceDepthFailOp
SetStencilBackFacePassOp( StencilOp)
ClearStencilBackFacePassOp
SetStencilBackFaceFunc( ComparisonFunc)
ClearStencilBackFaceFunc

枚举类型

这些枚举类型通过以下全局值反射到 lua 中：

MaterialPropertyVisibility

MaterialPropertyVisibility_Enabled
MaterialPropertyVisibility_Disabled
MaterialPropertyVisibility_Hidden

FillMode

FillMode_Solid
FillMode_Wireframe
FillMode_Invalid

CullMode

CullMode_None
CullMode_Front
CullMode_Back
CullMode_Invalid

ComparisonFunc

ComparisonFunc_Never
ComparisonFunc_Less
ComparisonFunc_Equal
ComparisonFunc_LessEqual
ComparisonFunc_Greater
ComparisonFunc_NotEqual
ComparisonFunc_GreaterEqual
ComparisonFunc_Always
ComparisonFunc_Invalid

BlendFactor

BlendFactor_Zero
BlendFactor_One
BlendFactor_ColorSource
BlendFactor_ColorSourceInverse
BlendFactor_AlphaSource
BlendFactor_AlphaSourceInverse
BlendFactor_AlphaDest
BlendFactor_AlphaDestInverse
BlendFactor_ColorDest
BlendFactor_ColorDestInverse
BlendFactor_AlphaSourceSaturate
BlendFactor_Factor
BlendFactor_FactorInverse
BlendFactor_ColorSource1
BlendFactor_ColorSource1Inverse
BlendFactor_AlphaSource1
BlendFactor_AlphaSource1Inverse
BlendFactor_Invalid

BlendOp

BlendOp_Add
BlendOp_Subtract
BlendOp_SubtractReverse
BlendOp_Minimum
BlendOp_Maximum
BlendOp_Invalid

DepthWriteMask

DepthWriteMask_Zero
DepthWriteMask_All
DepthWriteMask_Invalid

StencilOp

StencilOp_Keep
StencilOp_Zero
StencilOp_Replace
StencilOp_IncrementSaturate
StencilOp_DecrementSaturate
StencilOp_Invert
StencilOp_Increment
StencilOp_Decrement
StencilOp_Invalid

Lua 材质函数 API

名称上下文

主函数

Process(context)

ProcessEditor(context)

GetMaterialPropertyDependencies()

GetShaderOptionDependencies()

全局实用函数

Process(context) 函数

GetMaterialPropertyValue_

HasMaterialProperty(string)

SetShaderConstant_

SetShaderOptionValue_

GetShaderCount()

GetShader(number)

GetShaderByTag(string)

HasShaderWithTag(string)

ProcessEditor(context) 函数

GetMaterialPropertyValue_

SetMaterialProperty

ShaderItem functions

GetRenderStatesOverride()

SetEnabled(boolean)

SetDrawListTagOverride(string)

SetShaderOptionValue_

RenderStates 函数

Multisample State 函数

Raster State 函数

Blend State 函数

Depth/Stencil State 函数

枚举类型

MaterialPropertyVisibility

FillMode

CullMode

ComparisonFunc

BlendFactor

BlendOp

DepthWriteMask

StencilOp

Process(`context`)

ProcessEditor(`context`)

HasMaterialProperty(`string`)

GetShader(`number`)

GetShaderByTag(`string`)

HasShaderWithTag(`string`)

SetDrawListTagOverride(`string`)