Blogs

Unity’s Scriptable Render Pipeline represents a great advance on the way that unity deals with graphics, giving more power to the users to customize the pipeline the way they want. I have started to use the Universal Render Pipeline (URP) recently and, despite all its advantages over the built-in pipeline, it still suffers of lack of documentation. I mean, you can find information of every function available in the package documentation, but it’s still hard to find examples and translations from built-in to URP. Unity’s docs are (were?) good because when you look for something, you usually find the explanation of that and sometimes it’s followed by an example of how to use that.

I am pretty sure that Unity is working on improving the current situation of the docs (specially regarding packages), but while that’s not available I decided to write this article with a kind of translation from built-in to URP. I’m doing this not only to help others, but to help myself as well, so I can find all things in one place.

Before starting, here are some useful links to help you dive into URP stuff:

• URP package docs
• URP github
• Official examples
• Unlit template
• Boat attack demo project
• Phil Lira’s shader examples
• Outline post-effect using ScriptableRendererFeature
• Phil Lira’s twitter

Summary

Okay! So let’s go! All things here are mostly based on version 7.3 (version I’m using currently) sooo… you know… things might change. Some of the sections follow the built-in documentation order. The article is organized as follows:

1. General Structure
2. Shader Include Files
3. Light Modes
4. Variants
5. Predefined Shader Preprocessor Macros
   1. Helpers
   2. Shadow Mapping
   3. Texture/Sampler Declaration Macros
6. Built-in Shader Helper Functions
   1. Vertex Transformation Functions
   2. Generic Helper Functions
   3. Forward Rendering Helper Functions
   4. Screen-space Helper Functions
   5. Vertex-lit Helper Functions
7. Built-in Shader Variables
   1. Lighting
8. Random Stuff
   1. Shadows
   2. Fog
   3. Depth
   4. Etc.
9. Post-processing/VFX
10. Conclusion

General Structure ↑

First of all, add "RenderPipeline" = "UniversalPipeline" to your tags. Next, all URP shaders are written using HLSL embraced by HLSLPROGRAM/ENDHLSL/etc. macros. To avoid headaches, use them as well.

Shader Include Files ↑

Other useful includes:

• Packages/com.unity.render-pipelines.core/ShaderLibrary/SpaceTransforms.hlsl
• Packages/com.unity.render-pipelines.universal/ShaderLibrary/ShaderVariablesFunctions.hlsl
• Packages/com.unity.render-pipelines.core/ShaderLibrary/Common.hlsl
• Packages/com.unity.render-pipelines.universal/ShaderLibrary/Input.hlsl
• Packages/com.unity.render-pipelines.core/ShaderLibrary/Color.hlsl
• Packages/com.unity.render-pipelines.universal/ShaderLibrary/DeclareDepthTexture.hlsl
• Packages/com.unity.render-pipelines.universal/ShaderLibrary/DeclareOpaqueTextue.hlsl

Light Modes ↑

The other light modes supported are:

• DepthOnly
• Meta (for lightmap baking)
• Universal2D

Variants ↑

URP support some variants, so depending on the things you are using, you might need to add some #pragma multi_compile for some of the following keywords:

• _MAIN_LIGHT_SHADOWS
• _MAIN_LIGHT_SHADOWS_CASCADE
• _ADDITIONAL_LIGHTS_VERTEX
• _ADDITIONAL_LIGHTS
• _ADDITIONAL_LIGHT_SHADOWS
• _SHADOWS_SOFT
• _MIXED_LIGHTING_SUBTRACTIVE

Predefined Shader Preprocessor Macros ↑

Helpers ↑

Shadow Mapping ↑

You must include “Packages/com.unity.render-pipelines.universal/ShaderLibrary/Shadows.hlsl”.

Texture/Sampler Declaration Macros ↑

Unity has a bunch of texture/sampler macros to improve cross compatibility between APIs, but people are not used to use them. Those still exist in URP, but now with different names and new additions. I will not put all of them here because it’s a lot, but you can check their definitions per platform in the API includes.

Important to note that SCREENSPACE_TEXTURE has become TEXTURE2D_X. If you are working on some screen space effect for VR in Single Pass Instanced or Multi-view modes, you must declare the textures used with TEXTURE2D_X. This macro will handle for you the correct texture (array or not) declaration. You also have to sample the textures using SAMPLE_TEXTURE2D_X and use UnityStereoTransformScreenSpaceTex for the uv.

Built-in Shader Helper Functions ↑

You can find them all in “Packages/com.unity.render-pipelines.core/ShaderLibrary/SpaceTransforms.hlsl”.

Vertex Transformation Functions ↑

Generic Helper Functions ↑

Forward Rendering Helper Functions ↑

Screen-space Helper Functions ↑

Vertex-lit Helper Functions ↑

A bunch of utilities can be found in “Packages/com.unity.render-pipelines.core/ShaderLibrary/Common.hlsl”.

Built-in Shader Variables ↑

Most of the shader variables remains the same, except by lighting.

Lighting ↑

If you want to loop over all additional lights using GetAdditionalLight(...), you can query the additional lights count by using GetAdditionalLightsCount().

Random Stuff ↑

Shadows ↑

For more info about shadows, check “Packages/com.unity.render-pipelines.universal/ShaderLibrary/Shadows.hlsl”.

Fog ↑

For more info about fog, check “Packages/com.unity.render-pipelines.universal/ShaderLibrary/ShaderVariablesFunctions.hlsl”.

Depth ↑

To use the camera depth texture, include “Packages/com.unity.render-pipelines.universal/ShaderLibrary/DeclareDepthTexture.hlsl” and the _CameraDepthTexture will be declared for you as well as helper the functions SampleSceneDepth(...) and LoadSceneDepth(...).

Etc. ↑

Post-processing/VFX ↑

URP does not support OnPreCull, OnPreRender, OnPostRender and OnRenderImage. It does support OnRenderObject and OnWillRenderObject, but you might find issues depending on what you want to do. So, If you used to use those when creating your visual effects, I recommend learning how to use the new approaches available. The RenderPipelineManager provides the following injection points in the pipeline:

• beginCameraRendering(ScriptableRenderContext context, Camera camera)
• endCameraRendering(ScriptableRenderContext context, Camera camera)
• beginFrameRendering(ScriptableRenderContext context,Camera[] cameras)
• endFrameRendering(ScriptableRenderContext context,Camera[] cameras)

Example of usage:

void OnEnable()
{
	RenderPipelineManager.beginCameraRendering += MyCameraRendering;
}

void OnDisable()
{
	RenderPipelineManager.beginCameraRendering -= MyCameraRendering;
}

void MyCameraRendering(ScriptableRenderContext context, Camera camera)
{
	...
	if(camera == myEffectCamera)
	{
	...
	}
	...
}

Like I said, OnWillRenderObject is supported, however if you need to perform a render call inside of it (e.g. water reflection/refraction), it will not work. As soon as you call Camera.Render(), you will see the following message:

Recursive rendering is not supported in SRP (are you calling Camera.Render from within a render pipeline?)

In this case, replace the OnWillRenderObject by begin/endCameraRendering (like the example above) and call RenderSingleCamera() from URP instead of Camera.Render(). Changing the example above, you would have something like

void MyCameraRendering(ScriptableRenderContext context, Camera camera)
{
	...
	if(camera == myEffectCamera)
	{
	...
		UniversalRenderPipeline.RenderSingleCamera(context, camera);
	}
	...
}

The other approach to work with Post-processing is to use a ScriptableRendererFeature. This post has a great explanation of an outline effect using this feature. A ScriptableRendererFeature allows you to inject ScriptableRenderPass(es) at different stages of the pipeline, thus being a powerful tool for creating post-processing effects. The injection places are the following:

• BeforeRendering
• BeforeRenderingShadows
• AfterRenderingShadows
• BeforeRenderingPrepasses
• AfterRenderingPrePasses
• BeforeRenderingOpaques
• AfterRenderingOpaques
• BeforeRenderingSkybox
• AfterRenderingSkybox
• BeforeRenderingTransparents
• AfterRenderingTransparents
• BeforeRenderingPostProcessing
• AfterRenderingPostProcessing
• AfterRendering

This is a simple example of a ScriptableRendererFeature performing a blit with a custom material:

public class CustomRenderPassFeature : ScriptableRendererFeature
{
    class CustomRenderPass : ScriptableRenderPass
    {
        CustomRPSettings _CustomRPSettings;
        RenderTargetHandle _TemporaryColorTexture;

        private RenderTargetIdentifier _Source;
        private RenderTargetHandle _Destination;

        public CustomRenderPass(CustomRPSettings settings)
        {
            _CustomRPSettings = settings;
        }

        public void Setup(RenderTargetIdentifier source, RenderTargetHandle destination)
        {
            _Source = source;
            _Destination = destination;
        }

        public override void Configure(CommandBuffer cmd, RenderTextureDescriptor cameraTextureDescriptor)
        {
            _TemporaryColorTexture.Init("_TemporaryColorTexture");
        }

        public override void Execute(ScriptableRenderContext context, ref RenderingData renderingData)
        {
            CommandBuffer cmd = CommandBufferPool.Get("My Pass");

            if (_Destination == RenderTargetHandle.CameraTarget)
            {
                cmd.GetTemporaryRT(_TemporaryColorTexture.id, renderingData.cameraData.cameraTargetDescriptor, FilterMode.Point);
                cmd.Blit(_Source, _TemporaryColorTexture.Identifier());
                cmd.Blit(_TemporaryColorTexture.Identifier(), _Source, _CustomRPSettings.m_Material);
            }
            else
            {
                cmd.Blit(_Source, _Destination.Identifier(), _CustomRPSettings.m_Material, 0);
            }

            context.ExecuteCommandBuffer(cmd);
            CommandBufferPool.Release(cmd);
        }

        public override void FrameCleanup(CommandBuffer cmd)
        {
            if (_Destination == RenderTargetHandle.CameraTarget)
            {
                cmd.ReleaseTemporaryRT(_TemporaryColorTexture.id);
            }
        }
    }

    [System.Serializable]
    public class CustomRPSettings
    {
        public Material m_Material;
    }

    public CustomRPSettings m_CustomRPSettings = new CustomRPSettings();
    CustomRenderPass _ScriptablePass;

    public override void Create()
    {
        _ScriptablePass = new CustomRenderPass(m_CustomRPSettings);

        _ScriptablePass.renderPassEvent = RenderPassEvent.AfterRenderingOpaques;
    }

    public override void AddRenderPasses(ScriptableRenderer renderer, ref RenderingData renderingData)
    {
        _ScriptablePass.Setup(renderer.cameraColorTarget, RenderTargetHandle.CameraTarget);
        renderer.EnqueuePass(_ScriptablePass);
    }
}

You can create a ScriptableRendererFeature by clicking on “Create > Rendering > Universal Render Pipeline > Renderer Feature”. The feature that you have created has to be added to your ForwardRenderer. To do so, select the ForwardRenderer, click on “Add Renderer Feature” and select the feature to be added. You can expose properties in the feature inspector, for example, if you add the example above, you will see a material slot available.

Conclusion ↑

That’s it for now. I will try to keep this updated (narrator: he won’t) according to the new things I’m learning or new features that I see added. If you have comments or suggestions, you can find me on twitter.