变换内置函数

DreamShader » 内置函数 » 变换内置函数

两个改变值坐标基准的 UE.* 内置函数：UE.TransformVector 用于方向， UE.TransformPosition 用于点。

基准是引擎枚举的一个值，书写时不带其前缀："World"，或裸词 World。在 .dss 中会精确匹配。在 1.x 源中，空格、_ 和 - 会被忽略， 可以写出枚举的前缀或作用域，并给出警告 DSH5278："world"、" WORLD " 和 TRANSFORMSOURCE_World 是 World。1.x 自身拥有的名称 —— AbsoluteWorld、Particle，以及表示位置时的 CameraRelativeWorld 和 FirstPerson —— 按引擎的名称书写，并给出相同警告（见下文）。 枚举不具有的任何其他值都会导致 DSH5215。

UE.TransformVector

在基准之间变换方向向量。仅做旋转 —— 不应用平移，这正是它 不适合用于点的原因。

概要

UE.TransformVector ( { <expression> | Input = <expression> }
                     [ , Source      = "<vector-basis>" ]
                     [ , Destination = "<vector-basis>" ] )

参数

Source 和 Destination 接受带引号的字符串或裸词 —— Source = World 和 Source = "World" 等价。它们是这两个属性在目录中的别名，这两个属性也可以 直接按名称使用。

源基准名称

目标基准名称

相同的六种拼写，即目标枚举的值。

[!NOTE] 1.x 源在任一列表中还可以为 World 写出 AbsoluteWorld，为 Instance 写出 Particle 或 InstanceParticle，大小写不限：前端会写出引擎的名称，并给出警告 DSH5278 （2.0.0 – 2.1.0 曾以 DSH5215 拒绝每一个）。引擎自身的 ParticleWorld 值会 被隐藏，目录中不会列出它。

UE.TransformPosition

在基准之间变换点，应用平移。

概要

UE.TransformPosition ( { <expression> | Input = <expression> }
                       [ , Source                        = "<position-basis>" ]
                       [ , Destination                   = "<position-basis>" ]
                       [ , PeriodicWorldTileSize         = <expression> ]
                       [ , FirstPersonInterpolationAlpha = <expression> ] )

参数

[!IMPORTANT] 节点自身的 Destination 是 Local。1.x 写出的是 World，前端也是如此：不带 Destination 的调用会转到世界空间，而 dsc migrate 会写出 Destination = World，因为对 .dss 的调用会得到节点的 Local。（2.0.0 – 2.1.0 未写出 默认值，此类调用是一次不改变任何东西的变换。）

基准名称

一个枚举同时服务于 Source 和 Destination。

1.x 源还可以写出 AbsoluteWorld（World）、CameraRelativeWorld（TranslatedWorld）、 FirstPerson（FirstPersonTranslatedWorld）、Particle 和 InstanceParticle（Instance）， 大小写不限：前端会写出引擎的名称，并给出警告 DSH5278 （2.0.0 – 2.1.0 曾以 DSH5215 拒绝每一个）。引擎自身的 Particle 值会被隐藏且不会在目录中列出。引擎 将 FirstPersonTranslatedWorld 标记为不是有效的 Source；DreamShader 不检查这一点。

[!WARNING] 运行中的引擎缺少的基准会被报告为未知值，而不是版本错误。 在枚举不具有 PeriodicWorld 的引擎上，UE.TransformPosition(P, Source = "Local", Destination = "PeriodicWorld") 是 DSH5215， 即拼写错误会得到的代码。消息会指出失败的属性 —— Source 对应 TransformSourceType，Destination 对应 TransformType （自 2.0.0 起）。

[!WARNING] 两个可选引脚都跟随引擎，且方式相同。 在类缺少 PeriodicWorldTileSize 或 FirstPersonInterpolationAlpha 的引擎上，该参数不是节点的引脚： 1.x 源会保留它并给出信息 DSH5291，而构建该 节点会失败并给出 DSH8212 （自 2.0.0 起；1.x 会静默丢弃 PeriodicWorldTileSize，并以自己的错误拒绝 FirstPersonInterpolationAlpha）。要使一份源在 各引擎版本间都能构建，请用 #if DS_ENGINE_MINOR >= … 保护该参数 —— 参见 预处理器。

共同行为

[!WARNING] 这些名称在 1.x 中未读取的参数会被丢弃，并伴有警告。 只保留上文记录的这些名称； 其他任何内容都会随 DSH5254 一起被丢弃 (自 2.0.0 起；1.x 会毫无提示地丢弃它)。 UE.TransformVector(V, Src = "World") 使用默认的 Source、Tangent，因为参数 拼写为 Src 而不是 Source；第二个位置参数——UE.TransformVector(V, "World")—— 也会被丢弃，因为只读取位置 0。始终完整命名 Source 和 Destination。

诊断

求值 Input、PeriodicWorldTileSize 或 FirstPersonInterpolationAlpha 表达式会报告 内部表达式自身的诊断。每个代码都在 诊断 中的对应页面上进行了描述。

示例

Shader(Name="Docs/M_Transforms")
{
    Properties = {
        vec3 TangentNormal = vec3(0.0, 0.0, 1.0);
    }
    Outputs  = {
        vec3 N;
        vec3 Emissive;
        Base.Normal        = N;
        Base.EmissiveColor = Emissive;
    }
    Graph = {
        // Direction: tangent space -> world space (both node defaults, written out for clarity).
        N = UE.TransformVector(TangentNormal, Source = "Tangent", Destination = "World");

        // Point: absolute world space -> camera-relative world space.
        vec3 WorldP = UE.WorldPosition();
        vec3 ViewP  = UE.TransformPosition(WorldP, Source = "World", Destination = "TranslatedWorld");

        Emissive = normalize(ViewP) * 0.5 + vec3(0.5, 0.5, 0.5);
    }
}

生成的节点：

Transform          Input=TangentNormal  TransformSourceType=TRANSFORMSOURCE_Tangent
                                        TransformType=TRANSFORM_World          -> N        (3 components)
WorldPosition                                                                  -> WorldP   (output XYZ)
TransformPosition  Input=WorldP         TransformSourceType=TRANSFORMPOSSOURCE_World
                                        TransformType=TRANSFORMPOSSOURCE_TranslatedWorld
                                                                               -> ViewP    (3 components)
Normalize / Multiply / Add chain                                               -> Emissive

另请参阅

• 内置函数 — Graph 内可用的调用接口
• UE.* 目录 — 其他 25 个 1.x 名称及其参数
• UE.Expression — 按类获取任何 UMaterialExpression，以及枚举值
• 数学内置函数 — normalize、dot 以及其余无前缀调用接口
• Substrate.* — Substrate 节点
• 调用 — 调用语法、命名参数、位置参数
• 表达式与运算符 — 参数表达式可以包含的内容
• 转换 — 宽度以及值如何适配
• 节点重用 — 相同节点
• 输出绑定 — Base.Normal 以及其他绑定目标
• 诊断索引 — 每个代码