Class ScriptableRenderer

Class ScriptableRenderer implements a rendering strategy. It describes how culling and lighting work and the effects supported. A custom scriptable renderer is the lowest level of extensibility of URP. It allows you to implement a fully new rendering strategy at the expense of a lot more complexity and work. However, It's still a lot less work and more maintainable than writing a full-fledged custom render pipeline. If you want to simply extend the existing URP renderers (2D and 3D), using ScriptableRendererFeature should always be considered first.

Inheritance

object

ScriptableRenderer

UniversalRenderer

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: UnityEngine.Rendering.Universal

Assembly: Unity.RenderPipelines.Universal.Runtime.dll

Syntax

public abstract class ScriptableRenderer : IDisposable

Remarks

A renderer can be used for all cameras or be overridden on a per-camera basis. It will implement light culling and setup and describe a list of ScriptableRenderPass to execute in a frame. It will also define the RenderGraph to execute. External users can then again extend your scriptable renderer to support more effects with additional ScriptableRendererFeatures.

The ScriptableRenderer is a run-time object. The resources and asset data for the renderer are serialized in ScriptableRendererData (more specifically a class derived from ScriptableRendererData which contains additional data for your renderer).

The high-level steps needed to create and use your own scriptable renderer are:

1. Create subclasses of ScriptableRenderer and ScriptableRendererData and implement the rendering logic. Key functions to implement here are: ScriptableRenderer.OnRecordRenderGraph which will define the rendergraph to execute when rendering a camera. And ScriptableRendererData.Create to create an instance of your new ScriptableRenderer subclass.
2. Create an asset of your new ScriptableRendererData subclass and assign it to the renderer asset field in the URP asset so it gets picked up at run time.

Examples

You can find a code sample in the URP tests package in the "Graphics/Tests/SRPTests/Packages/com.unity.testing.urp/Scripts/Runtime/CustomRenderPipeline/" folder of the SRP repository.

Constructors

ScriptableRenderer(ScriptableRendererData)

Creates a new ScriptableRenderer instance.

Declaration

public ScriptableRenderer(ScriptableRendererData data)

Parameters

Type	Name	Description
ScriptableRendererData	data	The ScriptableRendererData data to initialize the renderer.

See Also

ScriptableRendererData

Fields

k_CameraTarget

An RTHandle wrapping the BuiltinRenderTextureType.CameraTarget render target. This is a helper that avoids having to (re)allocate a new RTHandle every time the camera target is needed.

Declaration

protected static readonly RTHandle k_CameraTarget

Field Value

Type	Description
RTHandle

Properties

activeRenderPassQueue

Returns a list of render passes scheduled to be executed by this renderer.

Declaration

protected List<ScriptableRenderPass> activeRenderPassQueue { get; }

Property Value

Type	Description
List<ScriptableRenderPass>

See Also

ScriptableRenderPass

profilingExecute

Override to provide a custom profiling name

Declaration

protected ProfilingSampler profilingExecute { get; set; }

Property Value

Type	Description
ProfilingSampler

rendererFeatures

Returns a list of renderer features added to this renderer.

Declaration

protected List<ScriptableRendererFeature> rendererFeatures { get; }

Property Value

Type	Description
List<ScriptableRendererFeature>

See Also

ScriptableRendererFeature

supportedRenderingFeatures

Supported rendering features by this renderer. The scriptable renderer framework will use the returned information to adjust things like inspectors, etc.

Declaration

public ScriptableRenderer.RenderingFeatures supportedRenderingFeatures { get; set; }

Property Value

Type	Description
ScriptableRenderer.RenderingFeatures

See Also

SupportedRenderingFeatures

supportsGPUOcclusion

Used to determine if this renderer supports the use of GPU occlusion culling.

Declaration

public virtual bool supportsGPUOcclusion { get; }

Property Value

Type	Description
bool

unsupportedGraphicsDeviceTypes

List of unsupported Graphics APIs for this renderer.The scriptable renderer framework will use the returned information to adjust things like inspectors, etc.

Declaration

public GraphicsDeviceType[] unsupportedGraphicsDeviceTypes { get; set; }

Property Value

Type	Description
GraphicsDeviceType[]

See Also

GraphicsDeviceType

Methods

Dispose()

Disposable pattern implementation. Cleans up resources used by the renderer.

Declaration

public void Dispose()

Dispose(bool)

Called by Dispose(). Override this function to clean up resources in your renderer. Be sure to call this base dispose in your overridden function to free resources allocated by the base.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	See the definition of IDisposable.

EnqueuePass(ScriptableRenderPass)

Enqueues a render pass for execution.

Declaration

public void EnqueuePass(ScriptableRenderPass pass)

Parameters

Type	Name	Description
ScriptableRenderPass	pass	Render pass to be enqueued.

FinishRendering(CommandBuffer)

Called upon finishing rendering the camera stack. You can release any resources created by the renderer here.

Declaration

public virtual void FinishRendering(CommandBuffer cmd)

Parameters

Type	Name	Description
CommandBuffer	cmd	The command buffer where any work should be recorded on..

GetCameraClearFlag(ref CameraData)

Returns a clear flag based on CameraClearFlags.

Declaration

protected static ClearFlag GetCameraClearFlag(ref CameraData cameraData)

Parameters

Type	Name	Description
CameraData	cameraData	The Camera data.

Returns

Type	Description
ClearFlag	A clear flag that tells if color and/or depth should be cleared.

See Also

CameraData

GetCameraClearFlag(UniversalCameraData)

Returns a clear flag based on CameraClearFlags.

Declaration

protected static ClearFlag GetCameraClearFlag(UniversalCameraData cameraData)

Parameters

Type	Name	Description
UniversalCameraData	cameraData	The Camera data.

Returns

Type	Description
ClearFlag	A clear flag that tells if color and/or depth should be cleared.

See Also

CameraData

OnBeginRenderGraphFrame()

Override this method to initialize anything before starting the recording of the render graph, such as resources. This is the last point where it is ok to call ScriptableRenderer.EnqueuePass as after this function the queue will be sorted for the frame.

Declaration

public virtual void OnBeginRenderGraphFrame()

OnEndRenderGraphFrame()

Override this method to cleanup things after recording the render graph, such as resources. This executes after the render graph is recorded but before it is compiled and executed.

Declaration

public virtual void OnEndRenderGraphFrame()

SetCameraMatrices(CommandBuffer, ref CameraData, bool)

Set camera matrices. This method will set UNITY_MATRIX_V, UNITY_MATRIX_P, UNITY_MATRIX_VP to the camera matrices. Additionally this will also set unity_CameraProjection and unity_CameraProjection. If setInverseMatrices is set to true this function will also set UNITY_MATRIX_I_V and UNITY_MATRIX_I_VP. This function has no effect when rendering in stereo. When in stereo rendering you cannot override camera matrices. If you need to set general purpose view and projection matrices call SetViewAndProjectionMatrices(CommandBuffer, Matrix4x4, Matrix4x4, bool) instead.

Declaration

public static void SetCameraMatrices(CommandBuffer cmd, ref CameraData cameraData, bool setInverseMatrices)

Parameters

Type	Name	Description
CommandBuffer	cmd	CommandBuffer to submit data to GPU.
CameraData	cameraData	CameraData containing camera matrices information.
bool	setInverseMatrices	Set this to true if you also need to set inverse camera matrices.

SetCameraMatrices(CommandBuffer, UniversalCameraData, bool)

Set camera matrices. This method will set UNITY_MATRIX_V, UNITY_MATRIX_P, UNITY_MATRIX_VP to camera matrices. Additionally this will also set unity_CameraProjection and unity_CameraProjection. If setInverseMatrices is set to true this function will also set UNITY_MATRIX_I_V and UNITY_MATRIX_I_VP. This function has no effect when rendering in stereo. When in stereo rendering you cannot override camera matrices. If you need to set general purpose view and projection matrices call SetViewAndProjectionMatrices(CommandBuffer, Matrix4x4, Matrix4x4, bool) instead.

Declaration

public static void SetCameraMatrices(CommandBuffer cmd, UniversalCameraData cameraData, bool setInverseMatrices)

Parameters

Type	Name	Description
CommandBuffer	cmd	CommandBuffer to submit data to GPU.
UniversalCameraData	cameraData	CameraData containing camera matrices information.
bool	setInverseMatrices	Set this to true if you also need to set inverse camera matrices.

SetupCullingParameters(ref ScriptableCullingParameters, ref CameraData)

Override this method to configure the culling parameters for the renderer. You can use this to configure if lights should be culled per-object or the maximum shadow distance for example.

Declaration

public virtual void SetupCullingParameters(ref ScriptableCullingParameters cullingParameters, ref CameraData cameraData)

Parameters

Type	Name	Description
ScriptableCullingParameters	cullingParameters	Use this to change culling parameters used by the render pipeline.
CameraData	cameraData	Current render state information.

SupportedCameraStackingTypes()

This setting controls if the camera editor should display the camera stack category. If your scriptable renderer is not supporting stacking this one should return 0. For the UI to show the Camera Stack widget this must at least support CameraRenderType.Base.

Declaration

public virtual int SupportedCameraStackingTypes()

Returns

Type	Description
int	The bitmask of the supported camera render types in the renderer's current state.

See Also

CameraRenderType

SupportsCameraNormals()

Check if the ScriptableRenderer implements a camera normal pass.

Declaration

protected virtual bool SupportsCameraNormals()

Returns

Type	Description
bool	Returns true if the ScriptableRenderer implements a camera normal pass. False otherwise.

SupportsCameraOpaque()

Check if the ScriptableRenderer implements a camera opaque pass.

Declaration

protected virtual bool SupportsCameraOpaque()

Returns

Type	Description
bool	Returns true if the ScriptableRenderer implements a camera opaque pass. False otherwise.

SupportsCameraStackingType(CameraRenderType)

Check if the given camera render type is supported in the renderer's current state. The default implementation simply checks if the camera type is part of the SupportedCameraStackingTypes() bitmask.

Declaration

public bool SupportsCameraStackingType(CameraRenderType cameraRenderType)

Parameters

Type	Name	Description
CameraRenderType	cameraRenderType	The camera render type that is checked if supported.

Returns

Type	Description
bool	True if the given camera render type is supported in the renderer's current state.

See Also

CameraRenderType

SupportsMotionVectors()

Check if the ScriptableRenderer implements a motion vector pass for temporal techniques. The Camera will check this to enable/disable features and/or apply jitter when required.

For example, Temporal Anti-aliasing in the Camera settings is enabled only if the ScriptableRenderer can support motion vectors.

Declaration

protected virtual bool SupportsMotionVectors()

Returns

Type	Description
bool	Returns true if the ScriptableRenderer implements a motion vector pass. False otherwise.

Implements

IDisposable