关键字索引

DreamShader » DreamShaderLang » 关键字索引

声明语法特殊处理的每个单词：顶层块关键字、节名称及其别名、声明限定符、上下文关键字、保留名称，以及在输出 HLSL 之前被重写的标识符。

概要

<top-level-keyword> ( <attribute-key> = <value> [, …] )
{
    <section-name> [=] { <qualifier>… <type> <name> [= <default>] [[ <metadata> ]] ; … } [;]
}

[!NOTE] 块关键字、节名称和类型名称对标识符而言并非保留字。 属性、 输出变量、参数或函数可以命名为 Shader、Graph 或 Layout；它们 仅在语法期望出现的位置被识别。保留字是 例外 (自 2.0.0 起)。

顶层块关键字

以整个单词为单位，区分大小写进行匹配：ShaderFunction 是一个独立的单词，绝不会是 Shader 后跟其他内容。大小写错误的版本（shader(…)）不是块： DSH2240。

Shader 限制为每个文件一个（DSH2250），并且 .dsh 头文件根本不包含资产块（DSH2249），因此 import 不能添加第二个。其他每个块都可以重复。Function 和 GraphFunction 也可以嵌套在 Namespace 内，此时它们的名称变为 <Namespace>::<Name>。

[!WARNING] 自 1.3.0 起，MaterialLayer 和 MaterialLayerBlend 已弃用，建议改用 ShaderLayer 和 ShaderLayerBlend。它们的读取方式相同，但会给出警告 DSH2251。后续诊断和生成的元数据始终 报告现代拼写。

节名称

不区分大小写进行匹配。块之前的 = 是可选的 (自 1.5.0 起)，其后的 ; 也是 可选的。节可以按任意顺序出现，也可以重复：Properties、Inputs 和 Outputs 会追加， Settings 按键逐个合并，第二个 Graph 或 Layout 会替换第一个，并给出警告 DSH2258 (自 2.0.0 起)。块不接受的名称会报 DSH2245。

Function 和 GraphFunction 完全没有节 — 它们的 { … } 是原始 HLSL。

[!WARNING] Code = { … } 在所有接受节的块中都是错误： DSH2246，并且在 VirtualFunction 中，连同 Graph， DSH2247。请使用 Graph。

声明限定符

in 和 out 是函数参数上唯一被接受的限定符，不区分大小写；其他任何内容都是 DSH6302。

上下文关键字

仅在所列位置被识别，且不区分大小写，除非该行另有说明。

保留字

(自 2.0.0 起) 单个词法分析器读取每个文件，其关键字在 1.x 文件中同样被保留，且为小写： uniform static const extern export in out inout struct if else for while do return break continue discard true false import。它们都不能命名属性、 输出、输入或 Graph 变量。其他大小写是普通词语：Const 和 IN 在 1.x 语法期望它们的位置被读取为 const 和 in，而 True 被读取为 true。

保留名称

return 在 Function 主体内是 HLSL。在声明了返回类型的函数中出现裸 return; 是 DSH6308。

标识符重写

在发出 HLSL 之前，会在 Function 和 GraphFunction 声明内重写标识符。 匹配不区分大小写且仅限完整标识符；字符串和注释内的文本保持不变， 而 :: 限定的名称会绕过该表 — 它会被展平为 <Namespace>_<Name>。

与此表中任何条目都不匹配的标记会原样输出。每个节中的类型标记都通过 类型上的同一个类型表读取，该表保存着相同的 GLSL 拼写。

诊断

完整列表见诊断索引。

示例

所有关键字类都放在一个文件中。

Namespace(Name="Common")
{
    Function float Luma(in vec3 color) {
        return dot(color, vec3(0.2126, 0.7152, 0.0722));   // vec3 -> float3 on emission
    }
}

Shader(Name="Materials/M_Keywords")
{
    Properties {
        Group("Look") {
            const vec3      Ambient = vec3(0.02, 0.02, 0.03);
            ScalarParameter Rough   = 0.5 [Group="Surface"; Slider(0, 1)];
        }
        TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_Noise");
    }

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

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

    Graph {
        #Region "Sampling"
        vec2 UV  = UE.TexCoord(Index = 0);
        vec4 Tex = BaseTex(Coordinates = UV);
        #EndRegion

        Color = Tex.rgb * Common::Luma(Tex.rgb) + Ambient * Rough;
    }

    Layout {
        Comment(Name="Sampling", X=-1200, Y=-200, W=900, H=400);
        Node(Var="UV", X=-1100, Y=-120);
    }
}

另请参阅

• 词法元素 —— 本索引背后的区分大小写矩阵和标记规则
• 源文件 —— 每种文件类型可以声明哪些块
• 类型 —— 每个类型标记及其在各上下文中的有效性
• Shader · ShaderFunction · ShaderLayer · VirtualFunction · Function · GraphFunction · Namespace —— 各块页面
• 属性 · 输入 / 输出 · 输出绑定 · 选项 · 布局 —— 各节页面
• import · 预处理器 —— 不属于语法的指令
• 诊断索引 —— 所有代码