Class RenderGraph

This class is the main entry point of the Render Graph system.

Inheritance

Object

RenderGraph

Inherited Members

Object.ToString()

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: UnityEngine.Experimental.Rendering.RenderGraphModule

Syntax

public class RenderGraph

Constructors

RenderGraph(String)

Render Graph constructor.

Declaration

public RenderGraph(string name = "RenderGraph")

Parameters

Type	Name	Description
String	name	Optional name used to identify the render graph instnace.

Fields

kMaxMRTCount

Maximum number of MRTs supported by Render Graph.

Declaration

public static readonly int kMaxMRTCount

Field Value

Type	Description
Int32

Properties

defaultResources

Set of default resources usable in a pass rendering code.

Declaration

public RenderGraphDefaultResources defaultResources { get; }

Property Value

Type	Description
RenderGraphDefaultResources

isRenderGraphViewerActive

If true, the Render Graph Viewer is active.

Declaration

public static bool isRenderGraphViewerActive { get; }

Property Value

Type	Description
Boolean

name

Name of the Render Graph.

Declaration

public string name { get; }

Property Value

Type	Description
String

NativeRenderPassesEnabled

Enable the use of the render pass API by the graph instead of traditional SetRenderTarget. This is an advanced feature and users have to be aware of the specific impact it has on rendergraph/graphics APIs below.

When enabled, the render graph try to use render passes and supasses instead of relying on SetRendertarget. It will try to aggressively optimize the number of BeginRenderPass+EndRenderPass calls as well as calls to NextSubPass. This with the aim to maximize the time spent "on chip" on tile based renderers.

The Graph will automatically determine when to break render passes as well as the load and store actions to apply to these render passes. To do this, the graph will analyze the use of textures. E.g. when a texture is used twice in a row as a active render target, the two render graph passes will be merged in a single render pass with two surpasses. On the other hand if a render target is sampled as a texture in a later pass this render target will be stored (and possibly resolved) and the render pass will be broken up.

When setting this setting to true some existing render graph API is no longer valid as it can't express detailed frame information needed to emit native render pases. In particular:

• The ImportBackbuffer overload without a RenderTargetInfo argument.
• Any AddRenderPass overloads. The more specific AddRasterPass/AddComputePass/AddLowLevelPass functions should be used to register passes.

In addition to this, additional validation will be done on the correctness of arguments of existing API that was not previously done. This could lead to new errors when using existing render graph code with NativeRenderPassesEnabled.

Note: that CommandBuffer.BeginRenderPass/EndRenderPass calls are different by design from SetRenderTarget so this could also have effects outside of render graph (e.g. for code relying on the currently active render target as this will not be updated when using render passes).

Declaration

public bool NativeRenderPassesEnabled { get; set; }

Property Value

Type	Description
Boolean

Methods

AddComputePass<PassData>(String, out PassData)

Add a new Compute Render Pass to the Render Graph. Raster passes can execute rasterization workloads but cannot do other GPU work like copies or compute.

Declaration

public IComputeRenderGraphBuilder AddComputePass<PassData>(string passName, out PassData passData)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.

Returns

Type	Description
IComputeRenderGraphBuilder	A new instance of a IRasterRenderGraphBuilder used to setup the new Rasterization Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddComputePass<PassData>(String, out PassData, ProfilingSampler)

Add a new Compute Render Pass to the Render Graph. Compute passes can execute compute workloads but cannot do rasterization.

Declaration

public IComputeRenderGraphBuilder AddComputePass<PassData>(string passName, out PassData passData, ProfilingSampler sampler)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.
ProfilingSampler	sampler	Profiling sampler used around the pass.

Returns

Type	Description
IComputeRenderGraphBuilder	A new instance of a IComputeRenderGraphBuilder used to setup the new Compute Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddLowLevelPass<PassData>(String, out PassData)

Add a new Low Level Render Pass to the Render Graph. Low level passes can do certain operations compute/raster render passes cannot do and have access to the full command buffer API. The low level API should be used sparingly as it has the following downsides

• All native render passes will be serialized out.
• In the future the render graph compiler may generate a sub-optimal command stream for low level passes. When using a low level pass the graph will also not automatically set-up graphics state like rendertargets. The pass should do this itself using cmd.SetRenderTarget and related commands.

Declaration

public ILowLevelRenderGraphBuilder AddLowLevelPass<PassData>(string passName, out PassData passData)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.

Returns

Type	Description
ILowLevelRenderGraphBuilder	A new instance of a ILowLevelRenderGraphBuilder used to setup the new Low Level Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddLowLevelPass<PassData>(String, out PassData, ProfilingSampler)

Add a new Low Level Render Pass to the Render Graph. Low level passes can do certain operations compute/raster render passes cannot do and have access to the full command buffer API. The low level API should be used sparingly as it has the following downsides

• All native render passes will be serialized out.
• In the future the render graph compiler may generate a sub-optimal command stream for low level passes. When using a low level pass the graph will also not automatically set-up graphics state like rendertargets. The pass should do this itself using cmd.SetRenderTarget and related commands.

Declaration

public ILowLevelRenderGraphBuilder AddLowLevelPass<PassData>(string passName, out PassData passData, ProfilingSampler sampler)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.
ProfilingSampler	sampler	Profiling sampler used around the pass.

Returns

Type	Description
ILowLevelRenderGraphBuilder	A new instance of a ILowLevelRenderGraphBuilder used to setup the new Low Level Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddMovePass(TextureHandle, TextureHandle)

Add a new move pass to the Render Graph. This pass moves data from one texture to another. Note that this pass is more limited in functionality than for example doing a blit from one texture to another. It cannot do any type conversions, the textures have to be the same size,... This pass may be optimized away by the RenderGraph depending on the dependencies within the graph. E.g. if the destination resource is the only resource ever using the data in source the graph may decide to directly render to the destination instead of rendering to source and then doing an copy to destination.

Declaration

public void AddMovePass(TextureHandle source, TextureHandle destination)

Parameters

Type	Name	Description
TextureHandle	source	Texture to read data from.
TextureHandle	destination	Texture to copy data into.

AddRasterRenderPass<PassData>(String, out PassData)

Add a new Raster Render Pass to the Render Graph. Raster passes can execute rasterization workloads but cannot do other GPU work like copies or compute.

Declaration

public IRasterRenderGraphBuilder AddRasterRenderPass<PassData>(string passName, out PassData passData)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.

Returns

Type	Description
IRasterRenderGraphBuilder	A new instance of a IRasterRenderGraphBuilder used to setup the new Rasterization Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddRasterRenderPass<PassData>(String, out PassData, ProfilingSampler)

Add a new Raster Render Pass to the Render Graph. Raster passes can execute rasterization workloads but cannot do other GPU work like copies or compute.

Declaration

public IRasterRenderGraphBuilder AddRasterRenderPass<PassData>(string passName, out PassData passData, ProfilingSampler sampler)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.
ProfilingSampler	sampler	Profiling sampler used around the pass.

Returns

Type	Description
IRasterRenderGraphBuilder	A new instance of a IRasterRenderGraphBuilder used to setup the new Rasterization Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddRenderPass<PassData>(String, out PassData)

Add a new Render Pass to the Render Graph.

Declaration

public RenderGraphBuilder AddRenderPass<PassData>(string passName, out PassData passData)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.

Returns

Type	Description
RenderGraphBuilder	A new instance of a RenderGraphBuilder used to setup the new Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddRenderPass<PassData>(String, out PassData, ProfilingSampler)

Add a new Render Pass to the Render Graph.

Declaration

public RenderGraphBuilder AddRenderPass<PassData>(string passName, out PassData passData, ProfilingSampler sampler)

Parameters

Type	Name	Description
String	passName	Name of the new Render Pass (this is also be used to generate a GPU profiling marker).
PassData	passData	Instance of PassData that is passed to the render function and you must fill.
ProfilingSampler	sampler	Profiling sampler used around the pass.

Returns

Type	Description
RenderGraphBuilder	A new instance of a RenderGraphBuilder used to setup the new Render Pass.

Type Parameters

Name	Description
PassData	Type of the class to use to provide data to the Render Pass.

AddResolvePass(TextureHandle, TextureHandle)

Add a new Render Pass to the Render Graph that resolves the source texture into the destination texture. Note this is a special pass that depending on the GPU configuration might be "semi-free" and not execute any additional GPU commands. It is highly recommended to use resolve passes instead of making small passes that for example do commandBuffer.ResolveAntiAliasedSurface If the source and destination texture are both non MSAA this is equivalent to a move (see AddMovePass).

Declaration

public void AddResolvePass(TextureHandle source, TextureHandle destination)

Parameters

Type	Name	Description
TextureHandle	source	Texture to read data from.
TextureHandle	destination	Texture to copy data into.

BeginProfilingSampler(ProfilingSampler, String, Int32)

Begin a profiling scope.

Declaration

public void BeginProfilingSampler(ProfilingSampler sampler, string file = "", int line = 0)

Parameters

Type	Name	Description
ProfilingSampler	sampler	Sampler used for profiling.
String	file	File name of the source file this function is called from. Used for debugging. This parameter is automatically generated by the compiler. Users do not need to pass it.
Int32	line	File line of the source file this function is called from. Used for debugging. This parameter is automatically generated by the compiler. Users do not need to pass it.

Cleanup()

Cleanup the Render Graph.

Declaration

public void Cleanup()

CreateBuffer(in BufferDesc)

Create a new Render Graph Graphics Buffer resource.

Declaration

public BufferHandle CreateBuffer(in BufferDesc desc)

Parameters

Type	Name	Description
BufferDesc	desc	Graphics Buffer descriptor.

Returns

Type	Description
BufferHandle	A new GraphicsBufferHandle.

CreateBuffer(in BufferHandle)

Create a new Render Graph Graphics Buffer resource using the descriptor from another graphics buffer.

Declaration

public BufferHandle CreateBuffer(in BufferHandle graphicsBuffer)

Parameters

Type	Name	Description
BufferHandle	graphicsBuffer	Graphics Buffer from which the descriptor should be used.

Returns

Type	Description
BufferHandle	A new GraphicsBufferHandle.

CreateGizmoRendererList(in Camera, in GizmoSubset)

Creates a new Gizmo Renderer List Render Graph resource.

Declaration

public RendererListHandle CreateGizmoRendererList(in Camera camera, in GizmoSubset gizmoSubset)

Parameters

Type	Name	Description
Camera	camera	The camera that is used for rendering the Gizmo.
GizmoSubset	gizmoSubset	GizmoSubset that specifies whether gizmos render before or after postprocessing for a camera render.

Returns

Type	Description
RendererListHandle	A new RendererListHandle.

CreateRendererList(in RendererListParams)

Creates a new Renderer List Render Graph resource.

Declaration

public RendererListHandle CreateRendererList(in RendererListParams desc)

Parameters

Type	Name	Description
RendererListParams	desc	Renderer List descriptor.

Returns

Type	Description
RendererListHandle	A new RendererListHandle.

CreateRendererList(in RendererListDesc)

Creates a new Renderer List Render Graph resource.

Declaration

public RendererListHandle CreateRendererList(in RendererListDesc desc)

Parameters

Type	Name	Description
RendererListDesc	desc	Renderer List descriptor.

Returns

Type	Description
RendererListHandle	A new RendererListHandle.

CreateShadowRendererList(ref ShadowDrawingSettings)

Creates a new Shadow Renderer List Render Graph resource.

Declaration

public RendererListHandle CreateShadowRendererList(ref ShadowDrawingSettings shadowDrawingSettings)

Parameters

Type	Name	Description
ShadowDrawingSettings	shadowDrawingSettings	DrawSettings that describe the shadow drawcall.

Returns

Type	Description
RendererListHandle	A new RendererListHandle.

CreateSharedTexture(in TextureDesc, Boolean)

Create a new Render Graph Shared Texture resource. This texture will be persistent across render graph executions.

Declaration

public TextureHandle CreateSharedTexture(in TextureDesc desc, bool explicitRelease = false)

Parameters

Type	Name	Description
TextureDesc	desc	Creation descriptor of the texture.
Boolean	explicitRelease	Set to true if you want to manage the lifetime of the resource yourself. Otherwise the resource will be released automatically if unused for a time.

Returns

Type	Description
TextureHandle	A new TextureHandle.

CreateTexture(in TextureDesc)

Create a new Render Graph Texture resource.

Declaration

public TextureHandle CreateTexture(in TextureDesc desc)

Parameters

Type	Name	Description
TextureDesc	desc	Texture descriptor.

Returns

Type	Description
TextureHandle	A new TextureHandle.

CreateTexture(TextureHandle)

Create a new Render Graph Texture resource using the descriptor from another texture.

Declaration

public TextureHandle CreateTexture(TextureHandle texture)

Parameters

Type	Name	Description
TextureHandle	texture	Texture from which the descriptor should be used.

Returns

Type	Description
TextureHandle	A new TextureHandle.

CreateTextureIfInvalid(in TextureDesc, ref TextureHandle)

Create a new Render Graph Texture if the passed handle is invalid and use said handle as output. If the passed handle is valid, no texture is created.

Declaration

public void CreateTextureIfInvalid(in TextureDesc desc, ref TextureHandle texture)

Parameters

Type	Name	Description
TextureDesc	desc	Desc used to create the texture.
TextureHandle	texture	Texture from which the descriptor should be used.

CreateUIOverlayRendererList(in Camera)

Creates a new UIOverlay Renderer List Render Graph resource.

Declaration

public RendererListHandle CreateUIOverlayRendererList(in Camera camera)

Parameters

Type	Name	Description
Camera	camera	The camera that is used for rendering the UIOverlay.

Returns

Type	Description
RendererListHandle	A new RendererListHandle.

CreateWireOverlayRendererList(in Camera)

Creates a new WireOverlay Renderer List Render Graph resource.

Declaration

public RendererListHandle CreateWireOverlayRendererList(in Camera camera)

Parameters

Type	Name	Description
Camera	camera	The camera that is used for rendering the WireOverlay.

Returns

Type	Description
RendererListHandle	A new RendererListHandle.

EndFrame()

End frame processing. Purge resources that have been used since last frame and resets internal states. This need to be called once per frame.

Declaration

public void EndFrame()

EndProfilingSampler(ProfilingSampler, String, Int32)

End a profiling scope.

Declaration

public void EndProfilingSampler(ProfilingSampler sampler, string file = "", int line = 0)

Parameters

Type	Name	Description
ProfilingSampler	sampler	Sampler used for profiling.
String	file	File name of the source file this function is called from. Used for debugging. This parameter is automatically generated by the compiler. Users do not need to pass it.
Int32	line	File line of the source file this function is called from. Used for debugging. This parameter is automatically generated by the compiler. Users do not need to pass it.

GetBufferDesc(in BufferHandle)

Gets the descriptor of the specified Graphics Buffer resource.

Declaration

public BufferDesc GetBufferDesc(in BufferHandle graphicsBuffer)

Parameters

Type	Name	Description
BufferHandle	graphicsBuffer	Graphics Buffer resource from which the descriptor is requested.

Returns

Type	Description
BufferDesc	The input graphics buffer descriptor.

GetRegisteredRenderGraphs()

Get the list of all registered render graphs.

Declaration

public static List<RenderGraph> GetRegisteredRenderGraphs()

Returns

Type	Description
List<RenderGraph>	The list of all registered render graphs.

GetTextureDesc(TextureHandle)

Gets the descriptor of the specified Texture resource.

Declaration

public TextureDesc GetTextureDesc(TextureHandle texture)

Parameters

Type	Name	Description
TextureHandle	texture	Texture resource from which the descriptor is requested.

Returns

Type	Description
TextureDesc	The input texture descriptor.

ImportBackbuffer(RenderTargetIdentifier)

Import the final backbuffer to render graph. This function can only be used when NativeRenderPassesEnabled is false.

Declaration

public TextureHandle ImportBackbuffer(RenderTargetIdentifier rt)

Parameters

Type	Name	Description
RenderTargetIdentifier	rt	Backbuffer render target identifier.

Returns

Type	Description
TextureHandle	A new TextureHandle that represents the imported texture in the context of this rendergraph.

ImportBackbuffer(RenderTargetIdentifier, RenderTargetInfo, ImportResourceParams)

Import the final backbuffer to render graph. The rendergraph can't derive the properties of a RenderTargetIdentifier as it is an opaque handle so the user has to pass them in through the info argument.

Declaration

public TextureHandle ImportBackbuffer(RenderTargetIdentifier rt, RenderTargetInfo info, ImportResourceParams importParams = default(ImportResourceParams))

Parameters

Type	Name	Description
RenderTargetIdentifier	rt	Backbuffer render target identifier.
RenderTargetInfo	info	The properties of the passed in RTHandle.
ImportResourceParams	importParams	Info describing the clear behavior of imported textures. Clearing textures using importParams may be more efficient than manually clearing the texture using cmd.Clear on some hardware.

Returns

Type	Description
TextureHandle	A new TextureHandle that represents the imported texture in the context of this rendergraph.

ImportBuffer(GraphicsBuffer, Boolean)

Import an external Graphics Buffer to the Render Graph. Any pass writing to an imported graphics buffer will be considered having side effects and can't be automatically culled.

Declaration

public BufferHandle ImportBuffer(GraphicsBuffer graphicsBuffer, bool forceRelease = false)

Parameters

Type	Name	Description
GraphicsBuffer	graphicsBuffer	External Graphics Buffer that needs to be imported.
Boolean	forceRelease	The imported graphics buffer will be released after usage.

Returns

Type	Description
BufferHandle	A new GraphicsBufferHandle.

ImportRayTracingAccelerationStructure(in RayTracingAccelerationStructure, String)

Import an external RayTracingAccelerationStructure to the Render Graph. Any pass writing to (building) an imported RayTracingAccelerationStructure will be considered having side effects and can't be automatically culled.

Declaration

public RayTracingAccelerationStructureHandle ImportRayTracingAccelerationStructure(in RayTracingAccelerationStructure accelStruct, string name = null)

Parameters

Type	Name	Description
RayTracingAccelerationStructure	accelStruct	External RayTracingAccelerationStructure that needs to be imported.
String	name	Optional name for identifying the RayTracingAccelerationStructure in the Render Graph.

Returns

Type	Description
RayTracingAccelerationStructureHandle	A new RayTracingAccelerationStructureHandle.

ImportTexture(RTHandle)

Import an external texture to the Render Graph. Any pass writing to an imported texture will be considered having side effects and can't be automatically culled.

Declaration

public TextureHandle ImportTexture(RTHandle rt)

Parameters

Type	Name	Description
RTHandle	rt	External RTHandle that needs to be imported.

Returns

Type	Description
TextureHandle	A new TextureHandle that represents the imported texture in the context of this rendergraph.

ImportTexture(RTHandle, ImportResourceParams)

Import an external texture to the Render Graph. Any pass writing to an imported texture will be considered having side effects and can't be automatically culled.

Note: RTHandles that wrap RenderTargetIdentifier will fail to import using this overload as render graph can't derive the render texture's properties. In that case the overload taking a RenderTargetInfo argument should be used instead.

Declaration

public TextureHandle ImportTexture(RTHandle rt, ImportResourceParams importParams)

Parameters

Type	Name	Description
RTHandle	rt	External RTHandle that needs to be imported.
ImportResourceParams	importParams	Info describing the clear behavior of imported textures. Clearing textures using importParams may be more efficient than manually clearing the texture using cmd.Clear on some hardware.

Returns

Type	Description
TextureHandle	A new TextureHandle that represents the imported texture in the context of this rendergraph.

ImportTexture(RTHandle, RenderTargetInfo, ImportResourceParams)

Import an external texture to the Render Graph. This overload should be used for RTHandles wrapping a RenderTargetIdentifier. If the RTHandle is wrapping a RenderTargetIdentifer, Rendergrpah can't derive the render texture's properties so the user has to provide this info to the graph through RenderTargetInfo.

Any pass writing to an imported texture will be considered having side effects and can't be automatically culled.

Note: To avoid inconsistencies between the passed in RenderTargetInfo and render texture this overload can only be used when the RTHandle is wrapping a RenderTargetIdentifier. If this is not the case, the overload of ImportTexture without a RenderTargetInfo argument should be used instead.

Declaration

public TextureHandle ImportTexture(RTHandle rt, RenderTargetInfo info, ImportResourceParams importParams = default(ImportResourceParams))

Parameters

Type	Name	Description
RTHandle	rt	External RTHandle that needs to be imported.
RenderTargetInfo	info	The properties of the passed in RTHandle.
ImportResourceParams	importParams	Info describing the clear behavior of imported textures. Clearing textures using importParams may be more efficient than manually clearing the texture using cmd.Clear on some hardware.

Returns

Type	Description
TextureHandle	A new TextureHandle that represents the imported texture in the context of this rendergraph.

RecordAndExecute(in RenderGraphParameters)

Starts the recording of the the render graph and then automatically execute when the return value goes out of scope. This must be called before adding any pass to the render graph.

Declaration

public RenderGraphExecution RecordAndExecute(in RenderGraphParameters parameters)

Parameters

Type	Name	Description
RenderGraphParameters	parameters	Parameters necessary for the render graph execution.

Returns

Type	Description
RenderGraphExecution	RenderGraphExecution

Examples

This shows how to increment an integer.

using (renderGraph.RecordAndExecute(parameters))
{
    // Add your render graph passes here.
}

See Also

RenderGraphExecution

RefreshSharedTextureDesc(TextureHandle, in TextureDesc)

Refresh a shared texture with a new descriptor.

Declaration

public void RefreshSharedTextureDesc(TextureHandle handle, in TextureDesc desc)

Parameters

Type	Name	Description
TextureHandle	handle	Shared texture that needs to be updated.
TextureDesc	desc	New Descriptor for the texture.

RegisterDebug(DebugUI.Panel)

Register the render graph to the debug window.

Declaration

public void RegisterDebug(DebugUI.Panel panel = null)

Parameters

Type	Name	Description
DebugUI.Panel	panel

ReleaseSharedTexture(TextureHandle)

Release a Render Graph shared texture resource.

Declaration

public void ReleaseSharedTexture(TextureHandle texture)

Parameters

Type	Name	Description
TextureHandle	texture	The handle to the texture that needs to be release.

UnRegisterDebug()

Unregister render graph from the debug window.

Declaration

public void UnRegisterDebug()

Extension Methods

AnalyticsUtils.ToNestedColumnWithDefault<T>(T, T, Boolean)

ReflectionUtils.Invoke(Object, String, Object[])

ReflectionUtils.SetField(Object, String, Object)

ReflectionUtils.GetField(Object, String)

ReflectionUtils.GetFields(Object)