调用

Graph 块体里凡是写成 Name(...) 的都是调用。可调用的有六种声明种类和两类参数，此外还有会被优先解析的 内置和构造器。一个调用能用什么形式、能不能当作值使用、接不接受命名参数，全都取决于被调用的是什么。

语法概要

// 值形式 —— 调用产生一个值
<target> = <callee> ( [ <argument> [ , <argument> ] … ] ) ;

// 语句形式 —— 调用写入具名的 out 变量
<callee> ( [ <input-argument> , ] … <out-target> [ , <out-target> ] … ) ;

<callee>     := <identifier> | <namespace> :: <identifier>
<argument>   := <expression> | <identifier> = <expression> | default
<out-target> := <identifier>

可调用的种类

UE.*、Substrate.*、数学内置、构造器和 SampleTexture2D 也使用调用语法，但它们会在上述任何种类之前 被解析。见 UE.* 节点和数学内置。

分发顺序

调用名严格按此顺序探测。第一个认领该名字的表面胜出，后面的表面根本不会被查询。

步骤 5 有一个细节：数学内置处理器会区分"这不是数学内置"和"这是数学内置但调用写错了"。只有后者会中止， 所以 clamp(x) 报的是 Math function 'clamp' expects exactly 3 arguments.，而不会落到用户函数上。

在步骤 9，如果有多于一种声明种类匹配，调用失败并报 Graph call '{Name}' is ambiguous because multiple definitions use that name: {Kinds}. 恰好匹配一个时，分发优先级是 材质函数 → VirtualFunction → GraphFunction，而 Function 由步骤 10 到达。

被调方的写法

没有重载解析。名字不按参数个数或类型区分；第一个名字匹配的声明胜出。

值形式

float L = Luma(BaseColor);
vec3  C = Common::ApplyTint(BaseColor, Tint);
vec3  N = F_Normal(uv, Output="Normal");

调用结果是普通的后缀表达式，所以可以直接 swizzle：SampleTexture2D(Albedo, uv).rgb。

语句形式

F_PulseTint(BaseColor, Tint, TintedColor, PulseAmount);

多输出 ShaderFunction / VirtualFunction 的语句调用自 since 1.3.5 起可用。

参数是先输入，再每个输出对应一个 out 目标，按声明顺序排列。每个声明的输出都必须有目标——没有办法丢弃 其中一个。

out 目标规则

out 目标不需要事先存在，也不需要声明。每个目标会在当前作用域里被绑定到该调用的对应输出，并带上该输出的 声明形状，替换掉这个名字原有的值，且不做类型检查。如果宽度有讲究，请先声明变量。

参数

位置参数与命名参数

参数名在比较前会被规范化：先去首尾空白，再转小写。Coordinates=、coordinates= 和 COORDINATES = 是同一个参数。位置参数只在无名参数之中计数，所以位置下标会跳过它前面的所有命名参数。

"不许混用"是按调用而不是按参数判定的：只要有任何一个参数是命名的，就不允许出现位置参数。匹配不到任何 声明输入的命名参数报 {Kind} '{Name}' does not have an input named '{Argument}'.；位置参数过多报 {Kind} '{Name}' received {Got} positional input argument(s), but only {Declared} input(s) are declared.

每个输入参数都会被转换到该输入的声明类型，并伴随一贯的静默收窄——见 转换。

default

since 1.2.3 default 是一个裸标识符，匹配不区分大小写，用来显式请求某个可选输入的声明默认值， 而不是给它传一个值。

完全省略末尾的可选输入，效果与传 default 相同。

float3 tinted = F_Tint(BaseColor, default, Output="OutColor");

输出选择

Output、OutputName 和 OutputIndex 是 ShaderFunction、ShaderLayer、ShaderLayerBlend 和 VirtualFunction 值形式上的保留命名参数。它们会在绑定输入之前从输入参数表里移除。

float value = F_MultiOutput(Input=Mask, Output="Height");
float other = F_MultiOutput(Input=Mask, OutputIndex=1);

UE.Expression(…) 接受同样的三个选择器，规则相同；见 UE.Expression。

BreakOutFloatNComponents

声明名为 BreakOutFloat2Components、BreakOutFloat3Components 或 BreakOutFloat4Components （不区分大小写）的 VirtualFunction 调用会被内联成 swizzle，而不是生成 MaterialFunctionCall 节点， 前提是它有一个可用的首个输入参数和一个输出选择器：

OutputIndex= 按下标选中同样的通道。任一前提不满足——首个参数是 default、两个选择器都给了、一个选择器 都没给——调用就退回普通的 MaterialFunctionCall 路径。

调用参数

输入引脚接线

since 1.4.1 节点自带输入引脚的已声明参数可以被"调用"，以接好这些引脚。该调用会像裸引用一样物化 参数节点，并把每个命名参数连到同名的输入引脚上。节点按参数名缓存，所以之后的裸引用会共享这个已配置好的 节点。

接受这种形式的参数节点类型完整清单：

引脚名使用与参数名相同的规范化规则。所有参数都必须是命名的，且值都必须是数值。

Properties = {
    TextureSampleParameter2D Albedo = Path(Game, "Textures/T_Albedo");
}

Graph = {
    vec2 UV  = UE.TexCoord(Index = 0);
    vec4 Tex = Albedo(Coordinates = UV);
}

StaticSwitchParameter

since 1.2.3 StaticSwitchParameter 属性不作为裸标识符解析——它需要两个分支，所以只能通过调用 形式读取。

两个分支都必须存在，都不能是纹理对象或 Substrate 值，MaterialAttributes 标志必须一致，分量数必须相同。

Properties = {
    StaticSwitchParameter UseDetail = true [
        Group="Switches";
        SortPriority=30;
    ];
}

Graph = {
    vec3 Albedo = UseDetail(True = DetailColor, False = BaseColor);
}

因为这个开关是在着色器变体阶段而不是每像素解析的，所以当"选哪个"是材质设置而不是计算结果时，它是 if 的廉价替代品。

递归与嵌套

哪些调用会被复用

因为位置参数按下标建键，F_Tint(a, b) 和 F_Tint(b, a) 是不同的键；因为参数名会被规范化， F_Tint(Color = a) 和 F_Tint(color = a) 是同一个键。只要有任何一个参数产生不出键令牌，整个调用就不进 缓存，节点每次都会新建。

诊断

跨阶段的完整清单见错误速查。

示例

import "Helpers.dsh";

Shader(Name="Docs/M_Calls")
{
    Properties {
        vec3                     Tint    = vec3(1.0, 0.4, 0.1);
        TextureSampleParameter2D Albedo  = Path(Game, "Textures/T_Albedo");
        StaticSwitchParameter    UseTint = true;
    }

    Settings {
        Domain       = "Surface";
        ShadingModel = "Unlit";
    }

    Outputs {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph {
        vec2 UV  = UE.TexCoord(Index = 0);

        // 参数引脚调用：接好采样器的 Coordinates 引脚。
        vec4 Tex = Albedo(Coordinates = UV);

        // 值形式，Helpers.dsh 里声明的单输出 Function。
        float L  = Luma(Tex.rgb);

        // 值形式，带命名空间的 Function。
        vec3 Lit = Common::ApplyTint(Tex.rgb, Tint);

        // 语句形式：两个 out 目标，输入在前。目标不需要声明。
        PulseTint(Lit, Tint, Pulsed, Amount);

        // StaticSwitchParameter 调用在两者之间选择。
        Color = UseTint(True = Pulsed, False = vec3(L, L, L));
    }
}

Helpers.dsh：

Function float Luma(in vec3 color) { return dot(color, float3(0.299, 0.587, 0.114)); }

Function PulseTint(in vec3 color, in vec3 tint, out vec3 result, out float amount) {
    amount = 0.5 + 0.5 * sin(color.r * 6.28318);
    result = color * tint * amount;
}

Namespace(Name="Common")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }
}

TextureCoordinate                      -> UV
TextureSampleParameter2D  Albedo       -> Tex          (Coordinates pin wired to UV)
Custom  "Luma"                         -> L
Custom  "Common::ApplyTint"            -> Lit
Custom  "PulseTint"                    -> Pulsed (output 0), Amount (output 1)
StaticSwitchParameter  UseTint         -> Color

PulseTint 这个 Custom 节点上多出来的两个输出引脚，是按调用方的 out 变量命名的，而不是按声明的结果名 命名的。

参见

• 函数 —— 声明 Function、GraphFunction 与 Namespace
• import 与命名空间 —— :: 名字从哪里来
• Properties 类型 —— 哪些参数自带输入引脚
• 语句与声明 —— 作为语句的调用形式
• 运算符与转换 —— 调用在表达式文法里的位置
• UE.Expression —— 通用节点内置及其输出选择器