cullingResults | The set of visible objects to draw. You typically obtain this from ScriptableRenderContext.Cull. |
drawingSettings | A struct that describes how to draw the objects. |
filteringSettings | A struct that describes how to filter the set of visible objects, so that Unity only draws a subset. |
stateBlock | A set of values that Unity uses to override the GPU's render state. |
tagName | The name of a SubShader Tag or Pass Tag. |
isPassTagName | If set to true, tagName specifies a Pass Tag. Otherwise, tagName specifies a SubShader Tag. |
tagValues | An array of ShaderTagId structs, where the name is the value of a given SubShader Tag or Pass Tag. |
renderTypes | An array of ShaderTagId structs, where the name is the value of a SubShader Tag that has the name "RenderType". |
stateBlocks | An array of structs that describe which parts of the GPU's render state to override. |
Schedules the drawing of a set of visible objects, and optionally overrides the GPU's render state.
This function creates commands to draw the specified geometry, and adds the commands to the internal command list of the ScriptableRenderContext
. The ScriptableRenderContext
executes all the commands in its internal list when ScriptableRenderContext.Submit is called.
For a full example that demonstrates how to use this function in context, see Creating a simple render loop in a custom render pipeline. This short example demonstrates using a CommandBuffer to set the view matrix, and then calling this function to draw geometry using that matrix:
using UnityEngine; using UnityEngine.Rendering;
public class ExecuteCommandBufferExample { ScriptableRenderContext scriptableRenderContext;
// Placeholder data DrawingSettings exampleDrawingSettings; CullingResults exampleCullingResults = new CullingResults(); FilteringSettings exampleFilteringSettings = new FilteringSettings();
public void Draw() { // Create a CommandBuffer to set the view matrix Matrix4x4 exampleViewMatrix = Matrix4x4.Scale(new Vector3(2f, 2f, 2f)); CommandBuffer myCommandBuffer = new CommandBuffer(); myCommandBuffer.SetViewMatrix(exampleViewMatrix);
// Schedule the execution of the CommandBuffer scriptableRenderContext.ExecuteCommandBuffer(myCommandBuffer); myCommandBuffer.Clear();
// Schedule the drawing operation scriptableRenderContext.DrawRenderers(exampleCullingResults, ref exampleDrawingSettings, ref exampleFilteringSettings);
// Perform all scheduled tasks, in the order that they were scheduled // This means that the CommandBuffer is executed before the drawing operation occurs scriptableRenderContext.Submit(); } }
Overriding the render state
When you draw geometry using this function, you can use one or more RenderStateBlock structs to override the GPU's render state in the following ways:
You can use the stateBlock
parameter to provide a single RenderStateBlock struct. Unity uses the render state defined in stateBlock
for all the geometry that this function draws.
You can use the stateBlocks
parameter to provide an array of RenderStateBlock structs, and the renderTypes
parameter to provide an array of values for the SubShader Tag with a name of RenderType
. For each element in the renderTypes
array, if Unity finds geometry with a SubShader Tag name of RenderType
and a matching value, it uses the render state defined in the corresponding element of the stateBlocks
array. If there are multiple matches, Unity uses the first one. If an element in the renderTypes
array has the default value for ShaderTagId, Unity treats this as a catch-all and uses the corresponding render state for all geometry.
You can use the stateBlocks
parameter to provide an array of RenderStateBlock structs, and use the tagName
, tagValues
, and isPassTagName
parameters to specify the name and values of any SubShader Tag or Pass Tag. For each element in the tagNames
and tagValues
arrays, Unity identifies geometry with a matching SubShader Tag or Pass Tag name and value, and applies the render state defined in the corresponding element of the stateBlocks
array. If there are multiple matches, Unity uses the first one. If an element in the tagValues
has the default value for ShaderTagId, Unity treats this as a catch-all and uses the corresponding render state for all geometry.
This example demonstrates how to override the render state:
using UnityEngine; using UnityEngine.Rendering; using Unity.Collections;
public class OverrideRenderStateExample { ScriptableRenderContext scriptableRenderContext;
// Placeholder data DrawingSettings exampleDrawingSettings; CullingResults exampleCullingResults = new CullingResults(); FilteringSettings exampleFilteringSettings = new FilteringSettings();
// Override the render state for all geometry that this function draws public void OverrideRenderStateForAll() { // Tell Unity how to override the render state var stateBlock = new RenderStateBlock(RenderStateMask.Depth); stateBlock.depthState = new DepthState(true, CompareFunction.LessEqual);
// Schedule a command to draw the geometry using the desired render state // Unity will execute all scheduled commands during the next call to ScriptableRenderContext.Submit scriptableRenderContext.DrawRenderers(exampleCullingResults, ref exampleDrawingSettings, ref exampleFilteringSettings, ref stateBlock); }
// Override the render state for all geometry that has a SubShader Tag // with a name of "RenderType" and a value of "ExampleRenderTypeTagValue" public void OverrideRenderStateUsingRenderTypeTag() { // Create the parameters that tell Unity how to override the render state var stateBlock = new RenderStateBlock(RenderStateMask.Depth); stateBlock.depthState = new DepthState(true, CompareFunction.Greater); var stateBlocks = new NativeArray<RenderStateBlock>(1, Allocator.Temp); stateBlocks[0] = stateBlock;
// Create the parameters that tell Unity when to override the render state ShaderTagId renderType = new ShaderTagId("ExampleRenderTypeTagValue"); var renderTypes = new NativeArray<ShaderTagId>(1, Allocator.Temp); renderTypes[0] = renderType;
// Schedule a command to draw the geometry using the desired render state // Unity will execute all scheduled commands during the next call to ScriptableRenderContext.Submit scriptableRenderContext.DrawRenderers(exampleCullingResults, ref exampleDrawingSettings, ref exampleFilteringSettings, renderTypes, stateBlocks);
// DrawRenderers copies the array contents, so it is safe to dispose of the native arrays stateBlocks.Dispose(); renderTypes.Dispose(); }
// Override the render state in two different ways. // Use one state for all geometry that has a Pass Tag // with a name of "ExamplePassTagName" and a value of "ExamplePassTagValue". // For all other geometry, use a second state. public void OverrideRenderStateUsingPassTag() { // Create the parameters that tell Unity how to override the render state var stateBlock0 = new RenderStateBlock(RenderStateMask.Depth); stateBlock0.depthState = new DepthState(true, CompareFunction.Greater); var stateBlock1 = new RenderStateBlock(RenderStateMask.Depth); stateBlock1.depthState = new DepthState(true, CompareFunction.Less); var stateBlocks = new NativeArray<RenderStateBlock>(2, Allocator.Temp); stateBlocks[0] = stateBlock0; stateBlocks[1] = stateBlock1; // default override
// Create the parameters that tell Unity when to override the render state ShaderTagId tagName = new ShaderTagId("ExamplePassTagName"); bool isPassTagName = true; var tagValues = new NativeArray<ShaderTagId>(2, Allocator.Temp); tagValues[0] = new ShaderTagId("ExamplePassTagValue"); tagValues[1] = new ShaderTagId(); // catch all
// Schedule a command to draw the geometry using the desired render state // Unity will execute all scheduled commands during the next call to ScriptableRenderContext.Submit scriptableRenderContext.DrawRenderers(exampleCullingResults, ref exampleDrawingSettings, ref exampleFilteringSettings, tagName, isPassTagName, tagValues, stateBlocks);
// DrawRenderers copies the array contents, so it is safe to dispose of the native arrays stateBlocks.Dispose(); tagValues.Dispose(); } }
See Also: CullingResults, DrawingSettings, FilteringSettings, RenderStateBlock.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.