转换

DreamShader » Graph » 转换

将 Graph 值适配到其所处位置的类型的规则，以及它们消耗多少节点。

(自 2.0.0 起) 1.x 的 Graph 函数体由 2.0 绑定器绑定，且每个值都有一个类型：1 到 4 个分量的数字，属于同一种类（float、half、double、int、uint、bool），一种纹理类型的纹理，SamplerState、MaterialAttributes 或 Substrate。转换就是绑定器将一个值的类型与它所处位置的类型进行比较。1.x 源可以做而 .dss 不可以做的事——将较宽的值截断为较窄值——是遗留规则 L22，并且它对此加以说明。

概要

转换不是由作者编写的；它在值遇到有类型位置时自动应用。

convert( <value>, <place type> ) -> <value> | <error>

<type> := MaterialAttributes
        | Substrate
        | SamplerState
        | Texture( { Texture2D | TextureCube | Texture2DArray | Texture3D | VolumeTexture } )
        | Number( { float | half | double | int | uint | bool }, { 1 | 2 | 3 | 4 } )

转换适用的位置

在任何情况下，对未声明任何内容的名称的赋值都会以值自身的类型来声明它（遗留规则 L26，信息 DSH5292）；没有什么需要转换。

一个在两个分支中都对变量赋值的 if 会合并两个变量声明类型的值，因此合并本身不转换任何内容 (自 2.0.0 起)；见 if / else。

规则顺序

规则按此确切顺序进行测试；第一个匹配的规则决定结果。

规则 7 涵盖了拓宽非标量的值——输入 2 进入 3 或 4，输入 3 进入 4，在节点引脚以外的任何地方——以及每种类型族的更改。

数字转换矩阵

在 1.x 源中，输入宽度在侧面，预期宽度在顶部。在节点引脚处，矩阵中的两个错误被接受（规则 4），并且截断不生成节点。

种类转换矩阵

“错误”是该位置的代码（见第一个表格）。

纹理只转换为其自身的纹理类型：Texture2D、TextureCube、Texture2DArray、Texture3D 和 VolumeTexture 是五种类型，而 SamplerState 是其自身的类型，不是纹理 (自 2.0.0 起)。TextureCube 永远不会转换为 Texture2D。

窄化

在 1.x 源中，比其位置更宽的值会保留其前导分量（遗留规则 L22）。这种截断不再静默 (自 2.0.0 起)：每一次都是信息 DSH5289，因此源上的 dsc check 会列出它们，而 dsc migrate 会写出 swizzle。它消耗 swizzle 所消耗的内容：一个 ComponentMask，除非源节点恰好为这些前导通道拥有一个输出引脚——见 Swizzle。

vec4  Src   = vec4(0.1, 0.2, 0.3, 0.4);
float3 Rgb  = Src;      // Src.rgb — DSH5289; channel A is dropped
float  R    = Src;      // Src.r   — DSH5289

显式写出 swizzle（float3 Rgb = Src.rgb;）会记录意图，构建相同的节点，并使该信息消失。

窄化仅适用于上述位置 1–7。它被有意地不应用于：

拓宽

唯一的拓宽规则是标量广播。一个单分量值无需节点即可满足更宽的位置： 该标量本身会在读取该值的任何位置被连接，它所到达的材质节点会 对其进行复制 （自 2.0.0 起；1.x 会构建一条 AppendVector 链）。常量标量会被折叠进 ConstantNVector。

float  K   = 0.5;
vec3   All = K;         // no node: K is connected wherever All is read

没有零填充，也没有部分拓宽。float3 v = SomeFloat2; 就是 DSH4228。使用 构造函数来说明额外通道包含什么：float3 v = float3(SomeFloat2, 0.0);。唯一 接受更窄向量的地方是节点的引脚（规则 4）。

Float、int 和 bool

编译器知道每个数字的种类 （自 2.0.0 起）；生成的图却不知道，因为 材质图中的每个值都是 float。因此种类的变化不会对图产生任何改变。

后果：

• int x = 7.9; 存储 7.9。如果想要截断，请使用 floor(…)。
• bool b = 0.5; 存储 0.5。不存在到 0 或 1 的转换。
• 显式图转换遵循同样的规则：(int)0.5 和 (bool)0.5 都保留 0.5， 包括当常量表达式由绑定器求值时。使用 trunc(...) 丢弃 小数部分，或使用 value != 0 生成 0/1。@custom 主体内部的转换是 HLSL 转换。
• 将 float4 赋值给 int3 会像 float4 → float3（DSH5289）一样收窄。
• 种类在一个地方有影响：两个整数 构造函数调用之间的 / 是 DSH4243。如果任一侧是整数字面量（7）或 int 变量， 则与 1.x 一样是浮点除法。参见 整数除法。

权威分量数

（自 2.0.0 起） 不存在。1.x 允许某些值——常量折叠的构造函数、dot、 已知宽度表的 UE.* 内置项——携带一个“权威”宽度，该宽度会覆盖声明 并引导运算符。现在每个值都具有其类型的宽度：

因此 float2 dir = UE.CameraVectorWS(); 是一个 float2——前两个分量 DSH5289——而 1.x 存储三个。两个不同宽度的操作数只能通过标量广播相遇；其他任何情况都是 DSH4226（位置 9），并且运算符从不自行拓宽或收窄操作数。

说明

• 转换绝不会把数字变成 MaterialAttributes、纹理或 Substrate 值，也不会把一种 纹理类型变成另一种。
• 声明纹理、SamplerState 或 Substrate 变量而不提供初始值设定项是 DSH2215，因为没有可用的默认值来起始。 标量和向量从零开始。参见声明。
• Outputs 声明是其声明类型的普通变量：对它的每次赋值都在 写入处检查，而不是在图构建完成后检查一次。
• 一个 MaterialAttributes 值到达不承载它的引脚或函数输入时，会在图构建时 成为 DSH4371。

诊断

示例

Shader(Name="Docs/M_Conversions", Root="Game")
{
    Properties {
        VectorParameter Tint = float4(1.0, 2.0, 3.0, 999.0);
        ScalarParameter K    = 0.5;
    }

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

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

    Graph {
        float3 dir    = UE.CameraVectorWS();  // a float3 output
        float3 tinted = Tint;                 // narrowing: Tint.rgb, info DSH5289
        float3 lit    = K;                    // scalar broadcast: no node
        Color = dir * tinted + lit;
    }
}

将最后一条语句替换为 Color = dir * Tint; 会失败并报 DSH4226：float4 参数 使乘积为四个分量宽，而运算符不会拓宽 float3 操作数来 匹配。

另请参阅

• 表达式 — 运算符操作数规则和整数除法检查
• 构造函数 — 改变值宽度的显式方式
• Swizzle — 收窄的显式方式，以及收窄所付出的节点代价
• 声明 — 声明类型标记、默认值、重复声明
• if / else — 分支合并及其要求的类型
• MaterialAttributes — 逐属性类型
• 调用 — 针对已声明输入类型的参数转换
• 类型 — 完整的类型标记目录
• UE.* 内置项 — 内置项的输出类型
• dsc migrate — 规则 L22 及其写入的 swizzle
• 诊断索引 — 按流水线阶段列出的每个代码