Swizzle

DreamShader » Graph » Swizzle

Postfix member access on a numeric value that selects, reorders or repeats its channels.

Synopsis

<swizzle> := <expression> . <channels>
<channels> := <channel> [ <channel> ] [ <channel> ] [ <channel> ]
<channel>  := { x | y | z | w | r | g | b | a }

Between one and four channel characters. . and the channel letters are literal; [ … ] and { a | b } are meta-notation.

Channel sets

• Exactly two sets exist: xyzw and rgba. There is no stpq set and no uv set — neither u nor v resolves, so .uv fails with DSH4230.
• Channel characters are matched case-insensitively: .RGB, .Rgb, .XyZ are all valid.
• Mixing the two sets in one swizzle is DSH4230 (since 2.0.0; 1.x accepted .xg as .xy).

Length and bounds

A swizzle can only ever narrow or rearrange; it can never read past the base width.

[!WARNING] A scalar does not splat through an out-of-range channel. Roughness.yz on a scalar parameter is a hard error, not a two-component broadcast: DSH4230. To broadcast a scalar, repeat channel 0 (Roughness.xx), use a constructor (float2(Roughness)), or rely on scalar widening at an assignment.

Lowering

(since 2.0.0) A swizzle is a node: the generator never puts a channel mask on a connection. Four cases, tried in this order.

An identity mask — every channel of the value, in order: .x on a float, .rgb on a float3 — is no node in a .dss. In a 1.x source it is kept as a ComponentMask, because 1.x masked the connection whatever width the value was declared with.

Sequential versus non-sequential masks

Case 1 replaces a ComponentMask in this table by a pin wherever the source node has one. Every node is counted once however often the swizzle is written: equal nodes are merged (see Node reuse).

Composed swizzles

A swizzle of an already-swizzled value re-maps through the existing mask, so the channel numbering is always relative to the value being swizzled, not to the original node.

A mask of a mask is folded into one mask while the result stays ascending, so v.rgb.rg is one ComponentMask (or one pin) on v. Selecting an entry that does not exist in the outer list is an ordinary bounds failure against the swizzled width — v.ga.b is DSH4230 because .ga has 2 components, whatever the width of v.

Swizzling a call result

. is an ordinary postfix operator, so any call result can be swizzled directly — no temporary variable is required.

float u  = UE.TexCoord().x;
vec3  c  = SampleTexture2D(Albedo, uv).rgb;
vec2  yx = vec4(1.0, 2.0, 3.0, 4.0).yx;
float m  = MyFunction(A, B).r;

The swizzle applies to the call's value. On a call of a Function, GraphFunction, ShaderFunction or VirtualFunction, a member that names one of the function's outputs selects that output instead, and so does any member when the function returns nothing (legacy rule L3b): .r on a function that has only out parameters is read as an output name, and is DSH5280 unless an output is called r. See Calls. On a UE.* node with several outputs, a member names an output; a swizzle is allowed where the outputs are channel views of one value, as on a texture sample.

Non-swizzlable bases

Member access on a non-numeric value is not a swizzle.

Notes

• A swizzle costs one node however often it is written: Src.rgb used ten times is one ComponentMask — or no node, when Src has an RGB pin.
• Narrowing in a 1.x source takes the leading channels (r, rg, rgb) with the same swizzle, so an implicit cut costs what the swizzle costs. See Conversions.
• A swizzle of constants is folded: vec4(1.0, 2.0, 3.0, 4.0).yx is one Constant2Vector(2, 1).
• Repeated and reordered swizzles are merged like any other expression, so Src.bgr written twice yields one AppendVector chain. See Node reuse.
• . followed by anything that is not an identifier is a parse error before any swizzle logic runs: DSH2161.

Diagnostics

Example

Shader(Name="Docs/M_Swizzle")
{
    Properties { vec4 Src = vec4(0.1, 0.2, 0.3, 0.4); }
    Settings   { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs    { vec3 Color; Base.EmissiveColor = Color; }

    Graph {
        vec3  Forward   = Src.rgb;   // leading channels -> the parameter's RGB pin
        vec3  Reordered = Src.bgr;   // reordered        -> a mask per channel, 2 AppendVector
        float One       = Src.a;     // ascending        -> 1 ComponentMask
        vec2  Repeated  = One.rr;    // scalar base      -> 1 AppendVector
        Color = Forward + Reordered * One + vec3(Repeated, 0.0);
    }
}

Generated nodes:

VectorParameter                       -> Src (property node)
(no node)                             -> Src.rgb        [the RGB pin of Src]
ComponentMask B, ComponentMask G,
  AppendVector, AppendVector          -> Src.bgr        [r is the R pin of Src]
ComponentMask A                       -> Src.a
AppendVector                          -> One.rr
Multiply, Add, Constant(0.0),
  AppendVector, Add                   -> Base.EmissiveColor

See also

• Expressions — postfix precedence and where . binds
• Conversions — implicit narrowing and widening
• Constructors — the explicit way to widen or repack
• MaterialAttributes — what . means on an attributes value
• Calls — swizzling the result of a function or builtin call
• Node reuse — why a swizzle written ten times is one node
• Unsupported constructs — why v[0] is refused
• Graph layout — where the generated nodes are placed