Layout 与

Layout 固定生成节点的位置并声明注释框，它会取代自动布局。#Region 给图语句分组，好让自动布局有东西 可以圈。两者都不会改变着色器数学。

它们写在不同的地方：Layout 是和 Graph 并列的 section；#Region 指令写在 Graph 函数体内部。

语法概览

Layout [=]
{
    Node( Var = "<variable>", X = <int>, Y = <int> ) ;
    Comment( Name = "<title>", X = <int>, Y = <int>, W = <int>, H = <int>
             [, Color = float4( <r>, <g>, <b>, <a> )] ) ;
    …
}

语句是以 ; 分隔的调用。语句名和参数键都按大小写不敏感匹配，块前的 = 是可选的 since 1.5.0。Layout 在 Shader、ShaderFunction、ShaderLayer 和 ShaderLayerBlend 中被 接受，在 VirtualFunction 中不被接受 —— 那个块不生成图。

Node

把一个已经生成出来的表达式钉到确切位置上。

Var 指的是图构建过程中被记录下来的一个值。会被记录的名字有三类：

MaterialExpressionEditorX/Y 和编辑器图节点的 NodePosX/Y 都会被写入，所以位置在重新打开材质后依然 保留。

Comment

在确切矩形上创建一个注释框。

Color 字面量遵循通用的向量字面量语法：( 之前的 token 被忽略，所以 float4(…)、vec4(…) 和 (…) 都能解析。一个分量铺成 (x, x, x, 1)，两个给 (x, y, 0, 0)，三个给 (x, y, z, 1)，第四个之后的分量 会被解析然后丢弃。

生成的注释框始终使用 FontSize = 24 和分组模式，所以拖动框会带动它圈住的节点。

参数解析

坐标系

位置是 Unreal 材质图编辑器坐标：X 向右增大，Y 向下增大。负 X 是"上游"；材质根节点位于所有节点的 右侧。

自动布局使用的这些常量，在手工摆放节点时是有用的参照：

纵向步距：属性节点和自动布局行是 220，函数输入输出是 180。

显式布局与自动布局

Layout 块不是在自动布局之上叠加 —— 它替换掉那套排序算法。

在显式路径上，块里没点名的表达式仍然会被摆放：位置从已经定位的邻居迭代传播 —— 位于已知消费者和已知 依赖的中点、已知消费者左边 360、或已知依赖右边 360 —— 重合槽位有扇出避让。仍然没被摆放的，会进入 所有已定位节点左侧的兜底列。

#Region / #EndRegion

Region 指令住在 Graph 函数体文本里，不在 Layout 里。它们给一段图语句命名；布局阶段会把每个不同 的 region 名变成一个注释框块。

Graph = {
    #Region "Surface"
    Color = BaseColor.rgb;
    Rough = Roughness;
    #EndRegion

    #Region "Emissive"
    Glow = Tint * Intensity;
    #EndRegion
}

region 内部的语句会给它产出的变量打上 region 名标签。在自动布局路径上，每个 region 变成一个注释框；在 显式路径上，region 名参与决定跨块 reroute 插在哪里的块边界。

除此之外没有别的 # 指令。#Region 只在 Graph 体内被识别；其他任何地方的 # 都不是指令。

说明

• 注释文本总是带 DreamShader: 前缀。 Comment(Name="Sampling", …) 产出的框显示为 DreamShader: Sampling。这个前缀同时也是拆除标记：重新生成时，文本以 DreamShader: 开头的注释框 会被删除重建，不带这个前缀的框则得以保留。手工创建的注释框是唯一能在重新生成中幸存的手工修改。 见 重新生成。
• Name 去引号后为空或只有空白的 Comment 会在解析阶段被拒绝，所以永远不会为它创建框。
• 反编译器 输出的 Layout 块就是这个格式，所以材质可以导出、编辑、再生成而 保住位置。是否输出由 Export Decompiled Layout 项目设置控制，默认开启。
• 自动布局会在超大图上放弃。表达式数量达到或超过 1200 时它会记录 Skipping automatic layout for large DreamShader graph ({Count} nodes). Existing generated positions will be used. 并保留构建阶段的位置。Layout 块正是控制这类图的手段。

示例

Shader(Name="Materials/M_Layout", Root="Game")
{
    Properties {
        VectorParameter Tint      = float4(0.4, 0.8, 1.0, 1.0);
        ScalarParameter Intensity = 2.0 [Slider(0, 10)];
    }

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

    Graph {
        #Region "Emissive"
        float3 Boosted = Tint.rgb * Intensity;
        Color = Boosted + vec3(0.05, 0.05, 0.05);
        #EndRegion
    }

    Layout {
        Comment(Name="Emissive", X=-1300, Y=-260, W=1100, H=520,
                Color=float4(0.10, 0.22, 0.16, 0.35));
        Node(Var="Tint",      X=-1200, Y=-160);
        Node(Var="Intensity", X=-1200, Y=  60);
        Node(Var="Boosted",   X= -800, Y=-160);
        Node(Var="Color",     X= -400, Y= -60);
    }
}

生成的图：

Comment      "DreamShader: Emissive"   at (-1300, -260)  size 1100 x 520
Tint         VectorParameter           at (-1200, -160)
Intensity    ScalarParameter           at (-1200,   60)
Boosted      Multiply                  at ( -800, -160)
Color        Add                       at ( -400,  -60)
DS_Color_<n> NamedReroute              positioned by propagation

除非材质被持久化，否则什么都不会落盘 —— 见上面的瞬时模式警告。

诊断

继续阅读