Scripting your own Custom Pass in C#

You can extend the CustomPass class in the Custom Pass API to create complex effects, such as a Custom Pass that has more than one buffer or uses Compute Shaders.

When you create your own C# Custom Pass using the instructions in The Custom Pass C# Template, it automatically appears in the list of available Custom Passes in the Custom Pass Volume component.

The Custom Pass C# template

To create a new Custom pass, go to Assets > Create > Rendering > C# Custom Pass. This creates a new script that contains the Custom Pass C# template:

class #SCRIPTNAME# : CustomPass
{
    protected override void Setup(ScriptableRenderContext renderContext, CommandBuffer cmd) {}

    protected override void Execute(CustomPassContext ctx) {}

    protected override void Cleanup() {}
}

The C# Custom Pass template includes the following entry points to code your custom pass:

Entry Point Description
Setup Use this to allocate all the resources you need to render your pass, such as render textures, materials, and compute buffers.
Execute Use this to describe what HDRP renders during the Custom Pass.
Cleanup Use this to clear the resources you allocated in the Setup method .Make sure to include every allocated resource to avoid memory leaks.

The Setup and Execute methods give you access to a ScriptableRenderContext and a CommandBuffer. For information on using CommandBuffers with a ScriptableRenderContext, see Scheduling and executing commands in the Scriptable Render Pipeline.

Creating a full-screen Custom Pass in C#

The following code demonstrates how to create a full-screen Custom Pass that applies an outline effect to an object in your scene.

A mesh in a scene rendered using this outline effect

This effect uses a transparent full screen pass with a blend mode that replaces the pixels around the GameObject you assign the script to.

This shader code performs the following steps:

  1. Renders the objects in the outline layer to a buffer called outlineBuffer.
  2. Samples the color in outlineBuffer. If the color is below the threshold, then it means that the pixel might be in an outline.
  3. Searches neighboring pixels to check if this is the case.
  4. If Unity finds a pixel above the threshold, it applies the outline effect.

Creating a CustomPass script

To create a CustomPass script:

  1. Create a new C# script using Assets > Create > C# Script.
  2. Name your script. In this example, the new script is called “Outline”
  3. Enter the following code:
using UnityEngine;
using UnityEngine.Rendering.HighDefinition;
using UnityEngine.Rendering;
using UnityEngine.Experimental.Rendering;

class Outline : CustomPass
{
    public LayerMask    outlineLayer = 0;
    [ColorUsage(false, true)]
    public Color        outlineColor = Color.black;
    public float        threshold = 1;

    // To make sure the shader ends up in the build, we keep a reference to it
    [SerializeField, HideInInspector]
    Shader                  outlineShader;

    Material                fullscreenOutline;
    RTHandle                outlineBuffer;

    protected override void Setup(ScriptableRenderContext renderContext, CommandBuffer cmd)
    {
        outlineShader = Shader.Find("Hidden/Outline");
        fullscreenOutline = CoreUtils.CreateEngineMaterial(outlineShader);

        // Define the outline buffer
        outlineBuffer = RTHandles.Alloc(
            Vector2.one, TextureXR.slices, dimension: TextureXR.dimension,
            colorFormat: GraphicsFormat.B10G11R11_UFloatPack32,
// We don't need alpha for this effect
            useDynamicScale: true, name: "Outline Buffer"
        );
    }

    protected override void Execute(CustomPassContext ctx)
    {
        // Render meshes we want to apply the outline effect to in the outline buffer
        CoreUtils.SetRenderTarget(ctx.cmd, outlineBuffer, ClearFlag.Color);
        CustomPassUtils.DrawRenderers(ctx, outlineLayer);

        // Set up outline effect properties
        ctx.propertyBlock.SetColor("_OutlineColor", outlineColor);
        ctx.propertyBlock.SetTexture("_OutlineBuffer", outlineBuffer);
        ctx.propertyBlock.SetFloat("_Threshold", threshold);

        // Render the outline buffer fullscreen
        CoreUtils.SetRenderTarget(ctx.cmd, ctx.cameraColorBuffer, ClearFlag.None);
        CoreUtils.DrawFullScreen(ctx.cmd, fullscreenOutline, ctx.propertyBlock, shaderPassId: 0);
    }

    protected override void Cleanup()
    {
        CoreUtils.Destroy(fullscreenOutline);
        outlineBuffer.Release();
    }
}

Creating a Unity shader

To create a new shader:

  1. Create a new Unity shader using Assets> Create> Shader
  2. Name the new shader source file “Outline”
  3. Enter the following code:
Shader "Hidden/Outline"
{
    HLSLINCLUDE

    #pragma vertex Vert

    #pragma target 4.5
    #pragma only_renderers d3d11 playstation xboxone vulkan metal switch

    #include "Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/RenderPass/CustomPass/CustomPassCommon.hlsl"

    TEXTURE2D_X(_OutlineBuffer);
    float4 _OutlineColor;
    float _Threshold;

    #define v2 1.41421
    #define c45 0.707107
    #define c225 0.9238795
    #define s225 0.3826834

    #define MAXSAMPLES 8
    // Neighbour pixel positions
    static float2 samplingPositions[MAXSAMPLES] =
    {
        float2( 1,  1),
        float2( 0,  1),
        float2(-1,  1),
        float2(-1,  0),
        float2(-1, -1),
        float2( 0, -1),
        float2( 1, -1),
        float2( 1, 0),
    };

    float4 FullScreenPass(Varyings varyings) : SV_Target
    {
        UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX(varyings);

        float depth = LoadCameraDepth(varyings.positionCS.xy);
        PositionInputs posInput = GetPositionInput(varyings.positionCS.xy, _ScreenSize.zw, depth, UNITY_MATRIX_I_VP, UNITY_MATRIX_V);
        float4 color = float4(0.0, 0.0, 0.0, 0.0);
        float luminanceThreshold = max(0.000001, _Threshold * 0.01);

        // Load the camera color buffer at the mip 0 if we're not at the before rendering injection point
        if (_CustomPassInjectionPoint != CUSTOMPASSINJECTIONPOINT_BEFORE_RENDERING)
            color = float4(CustomPassSampleCameraColor(posInput.positionNDC.xy, 0), 1);

        // When sampling RTHandle texture, always use _RTHandleScale.xy to scale your UVs first.
        float2 uv = posInput.positionNDC.xy * _RTHandleScale.xy;
        float4 outline = SAMPLE_TEXTURE2D_X_LOD(_OutlineBuffer, s_linear_clamp_sampler, uv, 0);
        outline.a = 0;

      // If this sample is below the threshold
        if (Luminance(outline.rgb) < luminanceThreshold)
        {
            // Search neighbors
            for (int i = 0; i < MAXSAMPLES; i++)
            {
                float2 uvN = uv + _ScreenSize.zw * _RTHandleScale.xy * samplingPositions[i];
                float4 neighbour = SAMPLE_TEXTURE2D_X_LOD(_OutlineBuffer, s_linear_clamp_sampler, uvN, 0);

                if (Luminance(neighbour) > luminanceThreshold)
                {
                    outline.rgb = _OutlineColor.rgb;
                    outline.a = 1;
                    break;
                }
            }
        }

        return outline;
    }

    ENDHLSL

    SubShader
    {
        Pass
        {
            Name "Custom Pass 0"

            ZWrite Off
            ZTest Always
            Blend SrcAlpha OneMinusSrcAlpha
            Cull Off

            HLSLPROGRAM
                #pragma fragment FullScreenPass
            ENDHLSL
        }
    }
    Fallback Off
}

Using a C# Custom Pass effect

To enable an effect you created in a shader, assign it to the FullScreen Material property of a Full-screeen Custom Pass component.

Controlling a Custom Pass Volume component using code

You can retrieve the CustomPassVolume in a script using GetComponent and access most of the things available from the UI like isGlobal, fadeRadius and injectionPoint.

You can also dynamically change the list of Custom Passes executed by modifying the customPasses list.

Scripting the Custom Pass Volume component properties

To customize the properties of a Custom Pass in the Inspector window, you can use a similar pattern to the CustomPropertyDrawer MonoBehaviour Editor, but with different attributes.

The following example is a part of the full-screen Custom Pass drawer:

[CustomPassDrawerAttribute(typeof(FullScreenCustomPass))]
public class FullScreenCustomPassDrawer : CustomPassDrawer
{
    protected override void Initialize(SerializedProperty customPass)
    {
        // Initialize the local SerializedProperty you will use in your pass.
    }

    protected override void DoPassGUI(SerializedProperty customPass, Rect rect)
    {
        // Draw your custom GUI using `EditorGUI` calls. Note that the Layout methods don't work here
    }

    protected override float GetPassHeight(SerializedProperty customPass)
    {
        // Return the vertical height in pixels that you used in the DoPassGUI method above.
        // Can be dynamic.
        return (EditorGUIUtility.singleLineHeight + EditorGUIUtility.standardVerticalSpacing) * X;
    }
}

When you create a Custom Pass drawer, Unity provides a default list of Custom Pass properties. Unity still does this when DoPassGUI is empty. These properties are the same properties that Unity provides in the draw renderers CustomPass Volume component by default.

If you don't need all of these settings, you can override the commonPassUIFlags property to remove some of them. The following example only keeps the name and the target buffer enum:

protected override PassUIFlag commonPassUIFlags => PassUIFlag.Name | PassUIFlag.TargetColorBuffer;