调用

DreamShader » Graph » 调用

从 Graph 块中调用 Function、GraphFunction、ShaderFunction、VirtualFunction 或带输入的参数，既可以作为值表达式，也可以作为独立语句。

.dsm / .dsf 由 legacy 前端读取，由 2.0 绑定器绑定 (自 2.0.0 起)。本页的调用写法构建的节点和以前一样；1.x 调用与 .dss 调用读法不同的地方，由编号的 legacy 规则处理，并用自己的码说明。每种调用的 .dss 写法见 dsc migrate。

语法概要

// value form — the call produces a value
<target> = <callee> ( [ <argument> [ , <argument> ] … ] ) ;

// statement form — the call writes into named out variables
<callee> ( [ <input-argument> , ] … <out-target> [ , <out-target> ] … ) ;

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

( ) , = :: 和 default 是字面 DreamShaderLang 文本。[ … ]、{ a | b } 和 … 是元记号。在任何调用里，命名参数之后再出现位置参数都是 DSH2158 (自 2.0.0 起)。

可调用的种类

别的文件里的 ShaderFunction 要经由指向其资产的 VirtualFunction 调用：import 只引入 .dsh 头文件，而头文件里不放资产块。

UE.*、Substrate.*、数学内置、构造器和 SampleTexture2D 也使用调用语法，但它们会在上述任何种类之前被解析，并有单独的文档——见内置、数学内置和构造器。与数学内置同名的函数是 DSH6206 (自 2.0.0 起)。完整的分发顺序见名称解析。

被调方的写法

没有重载。一个名字只声明一样东西：再声明一个同名的函数、属性或结构体是 DSH4210。例外是叶子名被它之前声明的函数（通常来自导入的头文件）占用的 ShaderFunction 块：块的函数改以 <Name>_Asset 声明，资产保留原名（提示 DSH5290）。只差大小写的两个名字是两个声明；拼法与两者都不同的调用就没有唯一的不区分大小写匹配，报 DSH4208。

值形式

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

(单输出 Function / GraphFunction 值调用自 1.3.1 起)

GraphFunction 调用和 Function 调用一样是一个 Custom 节点；从函数体里提出来的 UE. 调用成为该节点的更多输入，用这次调用的参数降级。

被调方相同、参数相同的调用是一个节点；见节点复用。

语句形式

F_PulseTint(BaseColor, Tint, TintedColor, PulseAmount);

(多输出 ShaderFunction / VirtualFunction 语句调用自 1.3.5 起)

调用语句可以调用任何东西。没人接收其值的调用——内置、构造器、参数——会被接受，它产生的节点因为没人读而被丢掉 (自 2.0.0 起；1.x 拒绝这样的语句)。既不是调用也不是赋值的表达式语句是 DSH2211（F(a).Out;、x;）；x++; 是 DSH2207，break; 是 DSH2208。

函数语句调用的参数这样读：

在第一种读法中，未被覆盖的输入必须声明为 opt 或传入 default，否则 DSH4217。每个声明的输出都必须收到一个目标——无法丢弃其中一个。

out 目标规则

[!NOTE] out 目标的拼写与某个声明只差大小写时，它就是那个声明，并带有 DSH5275 —— 而不是第二个变量 （自 2.0.0 起）。只有当任何大小写下都没有声明某个名字时，它才会 成为新的局部变量。

参数

位置参数与命名参数

位置参数在前、命名参数在后；反过来是 DSH2158。同一个参数被给了两次——按位置和按名字，或按名字两次——是 DSH4215。 在语句调用中，命名参数会关闭末尾接收输出的读法（见 语句形式）。

参数名精确比较，带上面的 DSH5275 回退；节点引脚在另一种大小写下匹配时警告 DSH5276。1.x 前端 自己读取的名字——Output、OutputName、OutputIndex、True、False、A、B——匹配时 忽略大小写。

default

（自 1.2.3 起）

default 是一个裸标识符，用于占住一个有意留空的输入（legacy 规则 L25）。 它区分大小写地匹配 （自 2.0.0 起），且仅在没有声明同名变量时生效。

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

输出选择

Output、OutputName 和 OutputIndex 是 1.x 前端自己读取的命名参数：它会将它们从调用中移除，改为选择输出， 如同在调用之后写 .Name 或 [k]。它们 适用于任何函数种类的调用 （Function 和 GraphFunction 自 2.0.0 起），也适用于 UE.* 调用。

[!WARNING] 选择器使调用成为一个值。它不能用在语句调用中：被选中的调用是一个无人接收的表达式， 即 DSH2211。

UE.Expression(…) 接受同样的三个选择器；节点没有的名字是 DSH5201，超出其输出的下标是 DSH5282。见 UE.Expression。

BreakOutFloatNComponents

名为 BreakOutFloat2Components、BreakOutFloat3Components 或 BreakOutFloat4Components （任意大小写）、第一个参数是位置参数、且带有输出选择器的调用会被读作 第一个参数的 swizzle。不会产生 MaterialFunctionCall 节点，也不会查找该名字的 函数 （自 2.0.0 起）。所选输出指名一个通道，其字母不区分大小写：

OutputIndex= 按下标选择同一通道。该通道必须位于名字所说的宽度之内（BreakOutFloat2Components 为 0–1）。否则 ——没有选择器、第一个参数是命名参数、通道超出宽度——该调用就是对同名函数的一次普通调用。两个选择器同时给出 是 DSH5252。

调用参数

输入引脚接线

(自 1.4.1 起)

节点自带输入引脚的已声明参数可以被“调用”，以接好这些引脚。前端把这类属性的每一次使用——调用或裸读取——都写成一次独立的 UE.Expression(Class = "<type>", ParameterName = "<name>", …) 调用，声明的默认值和元数据作为参数，调用的参数接到引脚上 (自 2.0.0 起)。参数相同的使用经过去重 pass（dedupe pass）后是一个节点；裸读取和引脚调用的参数不同，所以是指向同一个材质参数的两个节点。纹理采样参数读的是它的 RGBA 输出。

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

引脚名是节点自己的、引擎目录里列出的名字；另一种大小写带 DSH5276 解析。每个参数都必须是命名的（DSH5259），每个值都像任何 UE. 参数一样按引脚检查（DSH5214）。

[!NOTE] 资产槽位——采样器参数指向的贴图、曲线或字体——是用 [TextureSlot=Path(…)] 这类声明元数据设置的，它会成为节点的一个属性参数。 调用参数再指名声明已经设置过的属性是 DSH4215。既不是引脚也不是节点属性的名字是 DSH5213；当 它的值是图值时改为提示 DSH5291，节点建出来后按这个名字接引脚 （节点上没有这个引脚时 DSH8212）。

StaticSwitchParameter

(自 1.2.3 起)

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

两个分支都必须存在（DSH5258）；其他参数被丢弃并警告 DSH5254。该调用成为一个 UE.Expression(Class = "StaticSwitchParameter", …)，两个分支接在它的 A 和 B 引脚上， 像任何 UE. 节点的引脚一样检查 (自 2.0.0 起)。

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

递归与嵌套

诊断

每个诊断都有稳定的代码；代码的页面里有消息和处理方法。消息以 <file>(<line>,<col>): DSHnnnn: <message> 报告，位置在它 所指的调用或参数上。

解析与分发

参数与 out 目标

输出选择

Function

GraphFunction

Function 之下的全部内容，以及：

被提升的调用像任何其他表达式一样绑定，所以其中的错误会以其所在表达式自身的代码报告。

ShaderFunction 家族与 VirtualFunction

参数调用形式

示例

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);

        // Parameter pin call: wires the sampler's Coordinates pin, read through RGBA.
        vec4 Tex = Albedo(Coordinates = UV);

        // Value form, Function with a return value, declared in Helpers.dsh.
        float L  = Luma(Tex.rgb);

        // Value form, namespaced Function: the value is its first out parameter.
        vec3 Lit = Common::ApplyTint(Tex.rgb, Tint);

        // Statement form: inputs first, then one out target per output. Neither target is
        // declared, so each becomes a local of its output's type (info DSH5283).
        PulseTint(Lit, Tint, Pulsed, Amount);

        // StaticSwitchParameter call selects between the two.
        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 result), Amount (output amount)
AppendVector, AppendVector             -> vec3(L, L, L)
StaticSwitchParameter  UseTint         -> Color

PulseTint Custom 节点的输出按函数的 out 参数命名——result 是输出 0，amount 是附加输出——（自 2.0.0 起；1.x 按调用方的变量命名附加输出）。

另请参阅

• 名字解析 —— 完整的派发顺序与遮蔽规则
• 语句 —— 语句形式，包括独立调用语句
• 表达式 —— 调用如何融入表达式文法
• Function —— 声明 Function、Inline / SelfContained、返回类型
• GraphFunction —— UE.* 提升规则及其限制
• ShaderFunction —— 可复用的材质函数块
• ShaderLayer / ShaderLayerBlend —— 层函数块与元数
• VirtualFunction —— 声明现有的 UMaterialFunction
• Namespace —— :: 限定名与禁止嵌套规则
• 输入 / 输出 / 结果 —— in / out / opt 与声明的默认值
• 图中的参数 —— 读取参数与引脚调用形式
• UE.Expression —— 通用节点内置及其输出选择器
• 节点复用 —— 哪些调用节点会被去重
• dsc migrate —— 本页每条 legacy 规则在 .dss 中的写法
• 诊断索引 —— 按阶段列出的所有代码