字面量

DreamShader » 图表 » 字面量

一个 Graph 表达式可以包含三种字面量形式：数值字面量、字符串字面量，以及布尔字面量 true / false。

一个 1.x 的 Graph 主体由 DreamShaderLang 2.0 词法分析器读取*（自 2.0.0 起）*：下面的词法规则 是 2.0 的规则，而少数读取结果不同的 1.x 写法会被拒绝，并给出说明 1.x 行为的错误码。

概要

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

数值字面量以数字开头，或以紧跟数字的 . 开头。[ … ]、 { a | b } 和 … 是元记号；.、e、+、- 和 " 是字面字符。

数值字面量

没有小数部分、指数或浮点后缀的字面量对编译器来说是整数—— int，或带有 u 的 uint （自 2.0.0 起）；其他所有情况都是 float（带 h 的 half）。在 生成的图表中，每个字面量都是同一回事：一个单分量浮点 Constant。

词法细节：

• 一个数字是一个记号：数字、至多一个 .、至多一个指数，然后是后缀字母。任何 仍粘连在其后的内容——另一个 .、字母、后缀之后的数字——都属于同一个记号，并使其 成为 DSH2105 （自 2.0.0 起；1.x 保留最长有效前缀并 丢弃其余部分）。因此 0.5.5、0..5、1abc 和 1.0fx 是错误，而不是数字。
• 指数需要数字：1e 和 1e+ 是 DSH2105。指数的符号可以是 + 或 -， 且仅在紧跟 e/E 之后时才会被读取。
• 十六进制字面量（0x1F）对词法分析器来说是整数，且在 1.x 的 Graph 中会被拒绝 （DSH2222）。没有二进制或八进制表示法，也没有数字 分隔符。
• 开头的 - 不属于字面量；它是一元负号运算符。 取负的字面量会折叠成一个 Constant。

数值后缀

后缀字母保留在字面量的文本中，并决定其种类；值则是它们前面的数字。

规则：

• 一个数字后面可以跟多个后缀字母。浮点字母与整数类型字母组合 （1fu）会 DSH2105，在带有小数部分或指数的字面量上使用整数类型字母 （1.0u、1e3l）或在十六进制字面量上使用浮点字母也是如此。
• 字面量的种类只对编译器有意义——参见整数与浮点。 图表中两者都得到一个浮点 Constant。

整数与浮点

字符串字面量

字符串字面量在进行词法分析时转义会被解码，并且永远不会求值为一个值。它仅 在参数处理器读取字面量文本而不求值时才是合法的——例如设置节点属性的命名 UE.* / Substrate.* 参数、Output= / OutputName= 输出选择器， 或 Path(…) 资产引用。任何需要值的地方都会是 DSH4202。

[!NOTE] 字符串永远不会跨行。在其行结束前没有闭合 " 的字符串会被 DSH2103 （自 2.0.0 起；1.x 会一直读取到输入末尾）， 而文件的其余部分仍会被读取并报告各自的错误。

合法位置：

vec4 Scene = UE.SceneTexture(Id = "PostProcessInput0");

无效位置（任何需要值的位置）：

float x = "0.5";   // DSH4202

布尔字面量

true 和 false （自 1.6.0 起） 在解析该行时即被读取为字面量，且不区分大小写，早于 任何名称查找 （自 2.0.0 起；1.x 在变量和属性之后解析它们）。

StaticBool Enabled = true;     // a bool variable
float      On      = TRUE;     // any case; a bool used as a number is 1

[!WARNING] 由于 true / false 在任何名称之前被读取，因此名为 True 或 False 的 Graph 变量或已声明属性（不区分大小写）无法被读取：该名称的每次使用都是该字面量。请避免使用这些 名称。参见名称解析。

备注

• 相等的数字字面量在整个图中是同一个 Constant 节点：去重遍 会以 9 位有效数字比较值，因此写五次 0.5，或 1 和 1.0，都是同一个节点。
• 当构造函数的每个参数都是常量时，构造函数会折叠为一个 Constant2Vector / Constant3Vector / Constant4Vector 节点，而不是 Constant 个节点加上 AppendVector 个节点——包括整数构造函数 （自 2.0.0 起）。参见 构造函数。
• 一个字面量宽度为一个分量；任何值的宽度都不会与其类型不同 （自 2.0.0 起）。参见 转换。
• 此处的字面量规则是 Graph 表达式的规则。Properties、Settings 和元数据块的声明级规则见词法元素。

诊断

示例

Shader(Name="Docs/M_Literals", Root="Game")
{
    Properties { ScalarParameter K = 0.5; }

    Settings {
        Domain = "Surface";
        ShadingModel = "DefaultLit";
        BlendMode = "Opaque";
    }

    Outputs {
        float Rough;
        vec3 Color;
        Base.Roughness = Rough;
        Base.EmissiveColor = Color;
    }

    Graph {
        Rough = 0.55f * K;              // a float literal with its suffix
        float H     = .5;               // leading dot
        float Small = 1e-3;             // exponent
        float One   = 1;                // an int literal: the same Constant node as the 1.0 below
        Color = vec3(H * K, Small, 1.0) * One;
    }
}

生成的节点：

ScalarParameter K
Constant(0.55), Multiply             -> Base.Roughness
Constant(0.5), Multiply              -> H * K
Constant(0.001)                      -> Small
Constant(1.0)                        -> One, and the third vec3 component: one node
AppendVector, AppendVector           -> vec3(H * K, Small, 1.0)
Multiply                             -> Base.EmissiveColor

另见

• 表达式 — 运算符、优先级以及字面量可以出现的位置
• 构造函数 — 全常量构造函数调用的常量折叠
• 转换 — 1 分量字面量如何加宽到向量目标
• 词法元素 — 注释、标识符以及声明级字面量规则
• 类型 — 完整的类型标记目录
• 名称解析 — 查找顺序，以及为什么 true 无法被遮蔽
• 节点复用 — 常量去重
• 泛型 UE.Expression — 字面量可以填充的命名字符串参数