Custom Material Expressions

The Custom Material Expression enables you to write custom HLSL shader code operating on an arbitrary amount of inputs and outputting the result of the operation.

You can insert the Custom expression from the Custom category in the Material palette or from the right-click search menu in the Material Graph.

When the Custom node is selected, the following properties display in the Details Panel.

Using the Custom Material Expression

Add as many inputs as you need to the Inputs array, and name them. Then type or paste your HLSL code in the Code property field. You can type either a full function body with return statements as shown in the example, or a simple expression such as Input.bgr. You must also specify the output data type in OutputType.

The example shown below is a Custom expression that can blur a Texture Object based on the value in a Scalar Parameter.

Here is the code that was used above so that you can try the Custom node for yourself. Copy and paste the following text into the Code field in the Details Panel properties.

    float3 blur = Texture2DSample(Tex, TexSampler, UV);

    for (int i = 0; i < r; i++)
    {

      blur += Texture2DSample(Tex, TexSampler, UV + float2(i * dist, 0));
      blur += Texture2DSample(Tex, TexSampler, UV - float2(i * dist, 0));

    }

    for (int j = 0; j < r; j++)
    { 

      blur += Texture2DSample(Tex, TexSampler, UV + float2(0, j * dist));
      blur += Texture2DSample(Tex, TexSampler, UV - float2(0, j * dist));

    }

    blur /= 2*(2*r)+1;
    return blur;

The following video shows the creation and result of a Custom expression using the above HLSL code.

Known Issues

The following sections detail some common pitfalls to be aware of when writing custom Material expressions.

Input Arguments Are Function-Local

Note that Custom expressions always have a return value because they are wrapped inside another function. All input arguments (like Tex, UV, r, and dist in the above example) are declared as parameters of that outer function, so their scope of visibility is function-local.

Sometimes developers write structures with member functions and expect these parameters to be accessible inside that structure, but they cannot access function-local parameters. Therefore, you must copy those parameters by hand when member functions are used inside the Custom expression.

The example below would fail to compile (assuming the same example as above).

    struct InnerStruct
    {
      float4 Run()
      {
        // ERROR: Tex, TexSampler, and UV is not accessible within InnerStruct
        return Texture2DSample(Tex, TexSampler, UV);
      }
    };
    InnerStruct S;
    return S.Run();

Syntax Errors When Using HLSLcc Compiler

Some shader backends that use the older HLSLcc compiler report syntax errors on HLSL types such as vector and matrix. Try to be explicit with your data types and use float4 or float4x4 respectively. We keep fixing those bugs but at the same time we are moving our efforts to the new DirectXShaderCompiler (DXC).

Warnings