运算符与转换

Graph 语言产生值的那一半：字面量、标识符、调用、成员访问和四个算术运算符，最终求值成 UMaterialExpression 节点。本页内容同样适用于 Outputs 绑定表达式和 Outputs 声明默认值——它们就是 同一套文法下的单条表达式。

语法概要

<expression>     := <additive>
<additive>       := <multiplicative> [ { + | - } <multiplicative> ] …
<multiplicative> := <unary> [ { * | / } <unary> ] …
<unary>          := { + | - } <unary> | <postfix>
<postfix>        := <primary> [ <postfix-op> ] …
<postfix-op>     := . <identifier> | :: <identifier> | ( [ <argument> [ , <argument> ] … ] )
<primary>        := <identifier> | <number-literal> | <string-literal> | ( <additive> )
<argument>       := [ <identifier> = ] <additive>

这就是全部文法。( ) , . :: = + - * / 是它认识的全部标点。

优先级与结合性

绑定最紧的排在最前。解析器实现的就是这四层，没有第五层。

不存在的运算符

操作数规则

+ - * / 的两个操作数按此顺序检查。

规则 5 的完整含义：被加宽的必须是不带权威分量数的那一个，权威分量数必须大于零，另一个操作数的分量数 必须小于或等于它。运算符处从不尝试收窄——在这里丢通道是被刻意拒绝的，宁可让尺寸错误暴露出来。

这里没有单独的标量提升步骤。标量操作数原样传给材质节点，由 Unreal 自行复制，所以 A 是 vec3、K 是 float 时 A * K 只产生一个 Multiply 节点，而不是先 AppendVector splat。

二元运算符的结果

一元运算符

表达式求值器不会把 -2.0 折叠成负字面量：它变成 Constant(2.0) * Constant(-1)。但在构造器参数 内部会被折叠，因为常量折叠接受字面量前的一元 + 或 -——vec3(-1.0, 0.0, 1.0) 只产生一个 Constant3Vector。

整数除法

/ 是唯一带额外类型规则的运算符：

Integer division is not supported by the material graph; use float() or floor(a/b).

它在两个操作数都带整数标记时触发。这个标记只由一件事设置：直接调用整数构造器（int、int2..4、 ivec2..4、uint、uint2..4、uvec2..4）。字面量不会设置它，变量不会，3u 这类带后缀的字面量不会， 任何运算符的结果也不会。

字面量

数值字面量

<number-literal> := { <digit> | . } … [ { e | E } [ { + | - } ] <digit> … ] [ <suffix> ]
<suffix>         := { f | F | h | H | u | U | l | L }

每个数值字面量都是1 分量浮点值。不存在整数字面量类型。

词法细节：

• 数字和 . 会被贪婪地吞进同一个记号。多个 . 是被接受的，而数值转换很宽容：它取最长的合法前缀， 把余下部分丢掉且不报诊断，所以 0.5.5 是 0.5，0..5 是 0。
• 最多消耗一个指数。第二个 e / E 会终止该记号并开始一个标识符。
• 没有十六进制、二进制或八进制写法，也没有数字分隔符。
• 前导 - 不属于字面量，它是一元负号运算符。

f F h H u U l L 这八个后缀会被消耗并排除在记号文本之外。它们没有任何语义效果——不改类型、不改宽度、 不改整数标记。只允许一个后缀字符，而且只有当它后面的字符既非字母数字也非 _ 时才被消耗。这就是 0.55f; 与 1.0fx 的区别。

字符串字面量

字符串字面量在分词时解码转义，且永远不会求值成一个值。它只在参数处理器读取字面文本而非对其求值的 地方合法：UE.* 或 Substrate.* 的命名参数、Output= / OutputName= 选择器，或 Path(…) 资产引用。

vec4 Scene = UE.SceneTexture(Id = "PostProcessInput0");   // 可以
float x    = "0.5";   // String literals can only be used in named UE builtin arguments.

布尔字面量

true 和 false （未发布） 按普通标识符词法处理，并且很晚才解析——排在 Graph 变量和已声明属性 之后。它们产生一个 1 分量的 UMaterialExpressionStaticBool 节点，匹配不区分大小写，也是从 Graph 块里 给 StaticSwitch 输入或 StaticBool 函数输入供值的唯一方式。

标识符解析

裸标识符按顺序在三个表面上查找：

步骤 1 先比对精确拼写，再退化为不区分大小写扫描。步骤 2 是参数变成节点的地方：它在首次读取时惰性创建 并插入值表，之后每次读取都由步骤 1 服务。

Graph 变量查找不区分大小写，但值表是按赋值时使用的拼写建键的。float3 Color = …; 后面跟 color = …; 会写入第二个条目；之后的读取取精确匹配找到的那个，否则退回第一个不区分大小写命中项。 每个变量请只用一种拼写。

构造器

<constructor-call> := <constructor-name> ( <expression> [ , <expression> ] … )

共 34 个名字，全部不区分大小写。分量数完全由名字的最后一个字符决定：2 → 2，3 → 3， 4 → 4，其余 → 1。

看起来该有、实际没有的名字：vec1、ivec1、uvec1、bvec1（GLSL 家族从 2 开始）；int1、uint1、 bool1（只有 float1 和 half1 有 1 的拼法）；hvec2..4（没有 GLSL half 家族）；double、 dvec2..4；float2x2、float3x3、float4x4、mat2、mat3、mat4（本语言任何地方都没有矩阵 类型）；以及已移除的别名 Scalar、Vector、Color。它们都按普通标识符词法处理，落到用户函数查找， 最后报 Unknown Graph function '{Name}'.

参数规则

参数从左到右求值，并在任何元数检查之前先过筛。

然后，记构造器分量数为 N：

规则 9 就是从左到右的通道拼接；只要总数精确，混合宽度完全没问题。

常量折叠

当 N >= 2、名字不是整数构造器、且每个参数都是无名的数值字面量（可以带一个前导一元 + 或 -）时， 整个调用会塌缩成一个常量向量节点。

折叠出来的节点是构造器结果中唯一带权威分量数的一种。折叠向量按值去重，所以 vec3(0.5) 写五次也只有 一个 Constant3Vector。

Swizzle

<swizzle>  := <expression> . <channels>
<channels> := <channel> [ <channel> ] [ <channel> ] [ <channel> ]
<channel>  := { x | y | z | w | r | g | b | a }

只存在两套字符集：xyzw 和 rgba。没有 stpq，也没有 uv——u 和 v 都无法解析，所以 .uv 会失败。 通道字符不区分大小写，而且在一个 swizzle 里混用两套字符集是被接受的：.xg 就是通道 0 和 1， 和 .xy 完全一样。

长度与边界

swizzle 只能收窄或重排，绝不能读到基值宽度之外。

降级策略

三种策略，按此顺序尝试。

"严格递增"判断的是底层节点的源通道，而不是写出来的字母。

复合 swizzle

对已经带掩码的值再做 swizzle，会经由已有掩码重新映射，所以编号永远相对于被 swizzle 的那个值，而不是原始 节点。

只要结果仍然递增，复合就会折叠成单个掩码，所以 v.rgb.rg 完全不产生节点。选取外层列表里不存在的项， 是相对掩码后宽度的普通越界失败：v.ga.b 报 Swizzle 'b' is invalid for a value with 2 components.

因为 . 是普通后缀运算符，任何调用结果都可以直接 swizzle，不需要临时变量：

float u  = UE.TexCoord().x;
vec3  c  = SampleTexture2D(Albedo, uv).rgb;
vec2  yx = vec4(1.0, 2.0, 3.0, 4.0).yx;
float m  = MyFunction(A, B).r;

不能 swizzle 的基值

转换

转换不是作者写出来的。它在任何"值遇到期望形状"的地方自动应用，也是生成材质里大多数静默宽度变化的成因。

应用位置

赋给一个既不是已有变量也不是 Outputs 声明的名字时，不做任何转换：新变量直接带上该值自身的形状。

规则顺序

纵向是输入宽度，横向是期望宽度：

跨种类的情况：

四种纹理维度是四种不同的期望形状。Texture2D 和 SamplerState 都表示 Texture2D；Texture3D 和 VolumeTexture 都表示 VolumeTexture；TextureCube 和 Texture2DArray 各自独立。TextureCube 永远 不会转换成 Texture2D。

vec4   Src = vec4(0.1, 0.2, 0.3, 0.4);
float3 Rgb = Src;      // 静默变成 Src.rgb —— A 通道被丢弃
float  R   = Src;      // 静默变成 Src.r

收窄被刻意排除在以下位置之外：二元运算符的操作数（那里改为抛尺寸不匹配错误）、构造器参数、 swizzle 边界。

唯一的加宽规则是标量 splat。没有补零，也没有部分加宽：float3 v = SomeFloat2; 会报 Expected 3 component(s) but got 2. 请用构造器说明多出来的通道装什么。

float、int 与 bool

Graph 语言里根本没有数值表示层面的转换。

所以 int x = 7.9; 存的就是 7.9——想截断请用 floor(…)；bool b = 0.5; 存的就是 0.5。整数值与浮点值 之间唯一可观察的差别就是整数标记，而它唯一的作用就是整数除法的拒绝。

权威分量数

当一个值的宽度来自引擎而不是来自声明推断时，它就带有权威分量数。

已知宽度的内置节点类：

其他任何节点的输出宽度对生成器都是未知的。

这个标志会改变两件事。

作用 1——运算符挽救。 + - * / 遇到两个不兼容宽度时，可以把其中一个加宽到权威那一个，但只能往上加。 这就是 Tint 是 4 分量 VectorParameter 时 UE.CameraVectorWS() * Tint 会失败的原因：内置是权威的 3， 参数是非权威的 4，而 4 大于 3，挽救被阻止，于是抛出尺寸错误。

作用 2——声明宽度可能被忽略。

float2 dir = UE.CameraVectorWS();   // 存成 3 分量；float2 被忽略，不报错
Color = dir * Tint;                 // 如果 Tint 是 4 分量，错误在这里才出现

作用 3——分支合并。 判断某个 if 分支是否改变了一个值时，权威标志和整数标志不参与比较，所以只在 这两个标志上不同的两个值被视为相同，该名字不会被合并。

节点复用

在相同操作数值上的、文本相同的子表达式会塌缩成一个节点。A + B 写两次只产生一个 Add；一个资产里所有 0.5 都映射到一个 Constant；一元负号背后的 Constant(-1) 被资产内所有一元负号共享。缓存按值身份令牌 建键——节点、输出索引、分量数、全部五个掩码字段，以及纹理、属性、Substrate、权威和整数标志——所以 int(2) 和 float(2) 永远不会撞车，而在两次文本相同的调用之间重新给变量赋值，会正确地产生两个节点。

F_Tint(a, b) 和 F_Tint(b, a) 是不同的键，因为位置参数按下标建键；F_Tint(Color = a) 和 F_Tint(color = a) 是同一个键，因为参数名会被规范化。哪些调用种类会去重，见 调用。

诊断

示例

Shader(Name="Docs/M_Expressions")
{
    Properties {
        vec3 A = vec3(1.0, 0.5, 0.2);
        vec3 B = vec3(0.1, 0.2, 0.3);
        float K = 2.0;
    }
    Settings { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs { vec3 Color; Base.EmissiveColor = Color; }
    Graph {
        vec3 Sum    = A + B;
        vec3 Diff   = A - B;
        vec3 Scaled = A * K;
        vec3 Ratio  = A / K;
        vec3 Neg    = -Scaled;
        Color = (Sum + Diff - Scaled + Ratio) * 0.25 + Neg;
    }
}

VectorParameter A, VectorParameter B, ScalarParameter K   (property nodes)
Add(A, B)                                        -> Sum
Subtract(A, B)                                   -> Diff
Multiply(A, K)                                   -> Scaled
Divide(A, K)                                     -> Ratio
Multiply(Scaled, Constant(-1))                   -> Neg
Add / Subtract / Add chain, Multiply(..., 0.25), Add(..., Neg)

参见

• 语句与声明 —— 表达式出现在哪些语句形式里
• 调用 —— 调用语法、命名参数、输出选择
• 数学内置 —— fmod、pow、min、max、lerp、saturate
• UE.* 节点 —— 哪些内置有已知输出宽度
• 不支持的写法 —— 所有被拒绝和被静默截断的写法