DreamShaderLang
插件参考DreamShaderLang

关键字索引

关键字索引

DreamShader » DreamShaderLang » 关键字索引

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

声明于.dsm, .dsf, .dsh
类型索引
大小写规则顶层块关键字和保留字区分大小写;本页其他内容均不区分大小写,除非其所在行另有说明

概要

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

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

顶层块关键字

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

关键字头文件必需特性生成参考
ShaderShader(Name = "…"[, Root = "…"])NameUMaterialShader
ShaderFunctionShaderFunction(Name = "…"[, Root = "…"])NameUMaterialFunctionShaderFunction
ShaderLayer (自 1.3.0 起)ShaderLayer(Name = "…"[, Root = "…"])NameUMaterialFunctionMaterialLayerShaderLayer
ShaderLayerBlend (自 1.3.0 起)ShaderLayerBlend(Name = "…"[, Root = "…"])NameUMaterialFunctionMaterialLayerBlendShaderLayer
MaterialLayer (1.3.0 中已弃用)MaterialLayer(Name = "…"[, Root = "…"])Name同 ShaderLayerShaderLayer
MaterialLayerBlend (1.3.0 中已弃用)MaterialLayerBlend(Name = "…"[, Root = "…"])Name同 ShaderLayerBlendShaderLayer
VirtualFunction (自 1.2.0 起)VirtualFunction(Name = "…"[, Asset = "…"])Name,以及来自 Asset = 或 Options.Asset 的资产无 — 声明现有资产VirtualFunction
NamespaceNamespace(Name = "…")Name无 — 辅助函数的范围Namespace
FunctionFunction [SelfContained | Inline] [<ret>] <Name>( … ) { <HLSL> }名称、至少一个输出HLSL 辅助函数Function
GraphFunction (自 1.3.1 起)GraphFunction [<ret>] <Name>( … ) { <HLSL> }名称、至少一个输出带节点输入的 HLSL 辅助函数GraphFunction

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。

名称接受于含义参考
PropertiesShader, ShaderFunction, ShaderLayer, ShaderLayerBlend参数、const 和 UE.* 节点声明Properties
PropertiesVirtualFunctionInputs 的别名 — 类型化参数,而非参数节点VirtualFunction
InputsShaderFunction, ShaderLayer, ShaderLayerBlend, VirtualFunction类型化输入参数Inputs / Outputs
OutputsShaderFunction, ShaderLayer, ShaderLayerBlend, VirtualFunction类型化输出参数Inputs / Outputs
OutputsShader输出声明和绑定 — 不同的语法Output bindings
ResultsShaderFunction, ShaderLayer, ShaderLayerBlend, VirtualFunctionOutputs 的别名Inputs / Outputs
SettingsShader材质设置 — 特殊键加上反射的 UMaterial 属性Material settings
SettingsShaderFunction, ShaderLayer, ShaderLayerBlend材质函数键Function settings
SettingsVirtualFunctionOptions 的别名Options
OptionsVirtualFunction声明的资产和其他存储的键Options
GraphShader, ShaderFunction, ShaderLayer, ShaderLayerBlend节点图主体Graph
Code—在任何位置均被拒绝;请使用 GraphGraph
LayoutShader, ShaderFunction, ShaderLayer, ShaderLayerBlendNode / Comment 放置Layout

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

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

声明限定符

限定符位置作用参考
const (自 1.2.6 起)位于 Properties 声明中的类型之前发出常量节点而不是参数;在大多数参数节点标记上被拒绝(DSH3253)属性
opt (自 1.2.3 起)位于 Inputs 声明中的类型之前在 Unreal 中将该函数输入标记为可选;当其后跟随类型和名称时被识别输入 / 输出
in位于 Function / GraphFunction 参数类型之前输入参数;当参数只有两个词时的默认值函数
out位于 Function / GraphFunction 参数类型之前输出参数;除非声明了返回类型,否则至少需要一个,并且不能与返回类型并列(DSH6305、DSH6304)函数
SelfContained位于 Function 之后读取并被忽略:每个 Function 节点已经嵌入了其主体所调用的内容,这正是它向 1.x 所要求的内容;在 GraphFunction 上不被接受(DSH6307)函数
Inline位于 Function 之后SelfContained 的精确别名,带有警告 DSH6306 (自 2.0.0 起)函数

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

上下文关键字

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

关键字位置含义参考
import顶层,位于块之间将 .dsh 头文件的名称声明到本文件中 (自 2.0.0 起;1.x 会粘贴该文件);小写 — 其他大小写读取结果相同,并带有警告 DSH2253import
Group("…") { … } (自 1.5.0 起)Properties 内的语句位置将参数组作用域限定到其包含的每个声明;可嵌套,与 | 组合属性
Slider(min, max) (自 1.5.0 起)[ … ] 元数据块中的条目设置标量参数的 UI 范围元数据块
Path( … )纹理或资产值声明的默认值带有根拼写的资产引用Path(...)
Base.Outputs 绑定目标的开头绑定到材质属性输出绑定
Expression( … )Outputs 绑定目标的开头绑定到反射节点上的引脚;Class="…" 是必需的输出绑定
.Pin[<index>]位于 Expression( … ) 目标之后选择要绑定的引脚输出绑定
Node( … )Layout 内的语句固定变量的节点位置布局
Comment( … )Layout 内的语句放置注释框布局
#Region / #EndRegionGraph 主体内的独立行命名图的一个区域;可嵌套布局
#if / #elif / #else / #endif (自 1.9.0 起)独立行,除 Function / GraphFunction HLSL 主体外的任何位置在解析前从文本中剪除未采用的分支;仅限小写预处理器
#ifdef / #ifndef (自 1.9.0 起)独立行,相同位置#if defined(NAME) 和 #if !defined(NAME) 的语法糖预处理器
#define / #undef (自 1.9.0 起)独立行,相同位置定义或移除一个名称,仅对该文件有效;#define 值延伸到行尾且为纯文本预处理器
defined (自 1.9.0 起)位于 #if / #elif 表达式内名称已定义时为 1,否则为 0;defined(X) 和 defined X 均可用预处理器
UE.Properties 中的类型位置,Graph 中的调用位置内置材质节点命名空间;在 Graph 调用中精确写为 UE (自 2.0.0 起)UE.* 目录
true / false默认值,Graph 表达式布尔字面量;在需要标量的位置转换为 1.0 / 0.0类型
default (自 1.2.3 起)Graph 中的调用实参使该输入保持未连接,因此应用函数自身的默认值;仅限小写 (自 2.0.0 起)调用

保留字

(自 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。

保留名称

名称位置规则
__returnFunction / GraphFunction 参数名任何情况下均保留;使用该名称的参数为 DSH6303
return所有位置一个保留字:它不能命名输出变量,也不是绑定源 (自 2.0.0 起)
DS_… (自 1.9.0 起)预处理器定义名称整个 DS_ 前缀属于 DreamShader。此类名称的 #define 或 #undef 会以 DSH1039 失败;其他定义层级会发出警告并丢弃它。参见预处理器

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

标识符重写

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

书写形式重写为适用于
vec2float2参数与返回类型、正文文本
vec3float3参数与返回类型、正文文本
vec4float4参数与返回类型、正文文本
ivec2int2参数与返回类型、正文文本
ivec3int3参数与返回类型、正文文本
ivec4int4参数与返回类型、正文文本
uvec2uint2参数与返回类型、正文文本
uvec3uint3参数与返回类型、正文文本
uvec4uint4参数与返回类型、正文文本
bvec2bool2参数与返回类型、正文文本
bvec3bool3参数与返回类型、正文文本
bvec4bool4参数与返回类型、正文文本
mat2float2x2参数与返回类型、正文文本
mat3float3x3参数与返回类型、正文文本
mat4float4x4参数与返回类型、正文文本
mixlerp仅正文文本
fractfrac仅正文文本
modfmod仅正文文本

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

诊断

代码触发条件
DSH2240顶层文本不是块关键字或 import —— 包括拼写正确但大小写错误的关键字
DSH2248在 .dsm / .dsf 的顶层使用了 2.0 语法
DSH2242资源块头没有 Name 属性
DSH6309、DSH6311Namespace / VirtualFunction 没有名称,或名称不是标识符
DSH2250文件中有第二个 Shader
DSH2245该块不接受的节名称
DSH2246、DSH2247Code 节;VirtualFunction 中的 Graph 或 Code 节
DSH6310Namespace 中除 Function 或 GraphFunction 之外的任何内容,包括嵌套的 Namespace
DSH2251警告:MaterialLayer / MaterialLayerBlend
DSH2253警告:import 使用了另一种大小写
DSH2258警告:第二个 Graph 或 Layout 节
DSH6302、DSH6303、DSH6304、DSH6305、DSH6306、DSH6307、DSH6308上文的 Function / GraphFunction 签名规则

完整列表见诊断索引。

示例

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

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

另请参阅

本页目录