参数

DreamShader » 参数

参数是一种 Properties 声明，在生成的资源中会成为命名的 UMaterialExpression 节点——可以是实例能够覆盖的材质参数、常量，或内置输入节点。

概要

[const] <type-token> <name> [ = <default-value> ] [ [ <metadata-entry> { ; | , } … ] ] ;

元数据块外层的 [ … ] 是字面 DreamShaderLang 标点；= <default-value> 周围的 [ … ] 以及整个元数据块周围的是“可选”元方括号。换句话说，带元数据的声明写作 float A = 1.0 [Group="X"];。

外层节语法——Properties 可以出现的位置、{ 之前可选的 =、重复、Group("Name") { … } 作用域以及排序规则——在属性（节）中规定。本节仅记录可以出现在 <type-token>、<default-value> 和 <metadata-entry> 槽位中的内容。

自 2.0.0 起，1.x 源由旧版前端读取，它会将每个属性转换为 2.0 语言为其书写的形式：一个 uniform、一个 static const，或在其被读取处构建的参数节点。.dss 的写法见2.0 语言；dsc migrate 会为你书写（Migrate）。

四种类型标记

每个标记都不区分大小写匹配。不匹配以上任何一项的标记是DSH3252；七种没有 2.0 写法的参数节点类型之一则是DSH3253 (自 2.0.0 起)。

应使用哪种形式

[!NOTE] const 与 39 种紧凑标记一起使用是合法的，并且 (自 2.0.0 起) 与 ScalarParameter、 VectorParameter 和 TextureObjectParameter 一起使用也是合法的，此时它们会构建与 const float、 const float4 和 const Texture2D 相同的常量。在任何其他 *Parameter 标记上则是 DSH3253。在 UE.* 声明上，const 会被忽略 (自 2.0.0 起)。

页面

附注

• 每种类型的默认值都是可选的。 没有 = <default> 时，标量为 0，向量在每个通道中为 0（对于 2 分量或 3 分量 token，alpha 为 1），纹理为该维度下引擎的默认 纹理 (自 2.0.0 起；1.x 会将向量保留为节点自身的默认值)。 Texture2DArray 没有引擎默认值：其节点保留类的 2D 默认纹理，且没有 诊断 (自 2.0.0 起)。请指定一个数组资产。
• 属性名是标识符 (自 2.0.0 起)。float 1Bad = 0; 是 DSH2105（格式错误的数字）以及 DSH3250。
• 成为声明的属性在文件作用域内声明 (自 2.0.0 起)。同一名称的两个属性——无论是在同一个块中， 还是在同一文件的两个块中——都会产生 DSH4210。名称按精确方式比较。1.x 中关于 函数的属性不得与其某个输入同名这一规则，在 2.0 中没有对应检查。
• 声明顺序不约束读取。 Graph 可以读取声明在块中更靠后位置的 属性。例外是 UE.* 属性：它是在每个读取它的函数体头部声明的局部变量， 按 Properties 顺序排列，因此若某个参数命名了另一个 UE.* 属性，该属性需要在 列表中更早出现并由同一个函数体读取；否则该名称就是未声明的 (DSH4200)。
• Properties 在 VirtualFunction 内部含义不同：在那里它是 Inputs 的同义词， 采用类型化参数语法，而非本语法。请参见 VirtualFunction。
• 写入材质的参数名是所声明的名称，除非 [ParameterName="…"] 覆盖它。请参见 Metadata。

诊断

元数据、默认值和资产引用诊断位于 Metadata、 紧凑类型 token 和 Path(…)。完整 列表见诊断索引。

示例

Shader(Name="Docs/M_Parameters")
{
    Properties = {
        const float DebugScale = 1.0;                     // Constant, not overridable

        Group("Surface") {
            vec3  Tint      = vec3(1.0, 0.5, 0.2);        // VectorParameter, reads RGB
            float Roughness = 0.4 [Slider(0, 1)];         // ScalarParameter with a UI range
        }

        TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_White") [
            SamplerType  = "LinearColor";
            MipValueMode = "None";
        ];

        StaticSwitchParameter UseDetail = true;

        UE.TexCoord(Index = 0) UV;                        // MaterialExpressionTextureCoordinate
    }

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

    Outputs = {
        vec3  Color;
        float Rough;

        Base.BaseColor  = Color;
        Base.Roughness  = Rough;
    }

    Graph = {
        vec4 Sample = BaseTex(Coordinates = UV);
        vec3 Lit    = Sample.rgb * Tint * DebugScale;
        Color = UseDetail(True = Lit, False = Tint);
        Rough = Roughness;
    }
}

生成的节点：

Constant              DebugScale        (const -> not a parameter)
VectorParameter       Tint              Group="Surface" SortPriority=0
ScalarParameter       Roughness         Group="Surface" SortPriority=10 SliderMin=0 SliderMax=1
TextureSampleParameter2D BaseTex        SamplerType=LinearColor
StaticSwitchParameter UseDetail
TextureCoordinate     UV                CoordinateIndex=0

另请参见

• Properties（节） — 节的语法、const 和 Group(…) 作用域
• 类型 token — 每个类型 token 在各上下文中的有效性矩阵
• Inputs / Outputs / Results — 函数使用的另一种参数语法
• Shader — Properties 节所在的块
• ShaderFunction — 函数局部属性
• UE 内置项 — 完整的 UE.* 目录
• UE.Expression — 通用反射节点构建
• Graph — 消费这些参数的语言
• 2.0 语言 — uniform、static const 和 /// 指令
• 诊断索引 — 每个代码