Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

RenderSpriteInstanced

Renders multiple instances of a sprite using GPU instancing.
Read time 12 minutesLast updated 10 days ago

Definition

  • Type: Method
  • Namespace: UnityEngine
  • Assembly: UnityEngine.CoreModule

RenderSpriteInstanced<T>(RenderParams, SpriteParams, int, `<>[])

Renders multiple instances of a sprite using GPU instancing.
public static void RenderSpriteInstanced<T>(in RenderParams renderParams, in SpriteParams spriteParams, int submeshIndex, T[] instanceData) where T : unmanaged

Parameters

renderParams

RenderParams

spriteParams

SpriteParams

submeshIndex

int
The index of a submesh Unity renders when the sprite contains multiple materials (submeshes). For a sprite with a single material, use value 0.

instanceData

<T>[]
The array of instance data used to render the instances.

Remarks

This method renders sprites for the current frame. It's similar to Graphics.RenderSprite, but performance is better because it uses GPU instancing.
Use this function to render the same sprite multiple times using an instanced shader. Unity automatically calculates bounds for all the instances of this sprite unless you override the bounds using /RenderParams.worldBounds/. Unity uses the bounds to cull and sort all the instances of this sprite as a single entity, relative to other rendered sprites in the scene.
instanceData
can either be an array of 
Matrix4x4
, object-to-world transformation matrices per instance, or a custom data structure. When the 
instanceData
is a custom data structure, the structure can contain the following members:
Matrix4x4 objectToWorld; // mandatory: Specifies object-to-world transformation matrix.
Color spriteColor; // optional: Specifies the sprite color per instance. If not defined, defaults to Color.white.
uint renderingLayerMask; // optional: Specifies rendering layer mask per instance. If not defined, uses the renderLayerMask passed in RenderParams.
These members can appear in any order in the struct but they must have the above name and type. You can add other members but Unity ignores them when rendering.
You can only render a maximum of 1023 instances at once. The maximum depends on how much data you use for each instance.
By default, Unity uses an 
objectToWorld
matrix and a 
worldToObject
matrix for each instance, which means you can render a maximum of 511 instances at once. To remove the 
worldToObject
matrix from the instance data, add 
#pragma instancing_options assumeuniformscaling
to the shader.
Unity throws an 
InvalidOperationException
if the material doesn't have Material.enableInstancing set to true, if the current platform doesn't support this API, or if GPU instancing is not available. For more information, refer to SystemInfo.supportsInstancing.
Additional Resources: Graphics.RenderSprite.
The following example renders 10 sprites using 
RenderSpriteInstanced
. To use the script, enable GPU Instancing on the material:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 Matrix4x4[] instData = new Matrix4x4[numInstances];
 for(int i = 0; i < numInstances; ++i)
 instData[i] = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}
The following example uses a custom instance data struct that provides an object-to-world transformation and a rendering layer mask for rendering each instance. For demonstration purposes the struct defines also a custom data member 
myOtherData
that's unused for rendering but can be useful for other purposes:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 struct MyInstanceData
 {
 public Matrix4x4 objectToWorld;
 public Color spriteColor;
 public float myOtherData;
 };

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 MyInstanceData[] instData = new MyInstanceData[numInstances];
 for(int i = 0; i < numInstances; ++i)
 {
 instData[i].objectToWorld = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 instData[i].spriteColor = (i & 1) == 0 ? Color.red : Color.blue;
 }
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}

RenderSpriteInstanced<T>(RenderParams, SpriteParams, int, List<T>)

Renders multiple instances of a sprite using GPU instancing.
public static void RenderSpriteInstanced<T>(in RenderParams renderParams, in SpriteParams spriteParams, int submeshIndex, List<T> instanceData) where T : unmanaged

Parameters

renderParams

RenderParams

spriteParams

SpriteParams

submeshIndex

int
The index of a submesh Unity renders when the sprite contains multiple materials (submeshes). For a sprite with a single material, use value 0.

instanceData

List<T>
The array of instance data used to render the instances.

Remarks

This method renders sprites for the current frame. It's similar to Graphics.RenderSprite, but performance is better because it uses GPU instancing.
Use this function to render the same sprite multiple times using an instanced shader. Unity automatically calculates bounds for all the instances of this sprite unless you override the bounds using /RenderParams.worldBounds/. Unity uses the bounds to cull and sort all the instances of this sprite as a single entity, relative to other rendered sprites in the scene.
instanceData
can either be an array of 
Matrix4x4
, object-to-world transformation matrices per instance, or a custom data structure. When the 
instanceData
is a custom data structure, the structure can contain the following members:
Matrix4x4 objectToWorld; // mandatory: Specifies object-to-world transformation matrix.
Color spriteColor; // optional: Specifies the sprite color per instance. If not defined, defaults to Color.white.
uint renderingLayerMask; // optional: Specifies rendering layer mask per instance. If not defined, uses the renderLayerMask passed in RenderParams.
These members can appear in any order in the struct but they must have the above name and type. You can add other members but Unity ignores them when rendering.
You can only render a maximum of 1023 instances at once. The maximum depends on how much data you use for each instance.
By default, Unity uses an 
objectToWorld
matrix and a 
worldToObject
matrix for each instance, which means you can render a maximum of 511 instances at once. To remove the 
worldToObject
matrix from the instance data, add 
#pragma instancing_options assumeuniformscaling
to the shader.
Unity throws an 
InvalidOperationException
if the material doesn't have Material.enableInstancing set to true, if the current platform doesn't support this API, or if GPU instancing is not available. For more information, refer to SystemInfo.supportsInstancing.
Additional Resources: Graphics.RenderSprite.
The following example renders 10 sprites using 
RenderSpriteInstanced
. To use the script, enable GPU Instancing on the material:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 Matrix4x4[] instData = new Matrix4x4[numInstances];
 for(int i = 0; i < numInstances; ++i)
 instData[i] = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}
The following example uses a custom instance data struct that provides an object-to-world transformation and a rendering layer mask for rendering each instance. For demonstration purposes the struct defines also a custom data member 
myOtherData
that's unused for rendering but can be useful for other purposes:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 struct MyInstanceData
 {
 public Matrix4x4 objectToWorld;
 public Color spriteColor;
 public float myOtherData;
 };

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 MyInstanceData[] instData = new MyInstanceData[numInstances];
 for(int i = 0; i < numInstances; ++i)
 {
 instData[i].objectToWorld = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 instData[i].spriteColor = (i & 1) == 0 ? Color.red : Color.blue;
 }
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}

RenderSpriteInstanced<T>(RenderParams, SpriteParams, int, NativeArray<T>)

Renders multiple instances of a sprite using GPU instancing.
public static void RenderSpriteInstanced<T>(in RenderParams renderParams, in SpriteParams spriteParams, int submeshIndex, NativeArray<T> instanceData) where T : unmanaged

Parameters

renderParams

RenderParams

spriteParams

SpriteParams

submeshIndex

int
The index of a submesh Unity renders when the sprite contains multiple materials (submeshes). For a sprite with a single material, use value 0.

instanceData

NativeArray<T>
The array of instance data used to render the instances.

Remarks

This method renders sprites for the current frame. It's similar to Graphics.RenderSprite, but performance is better because it uses GPU instancing.
Use this function to render the same sprite multiple times using an instanced shader. Unity automatically calculates bounds for all the instances of this sprite unless you override the bounds using /RenderParams.worldBounds/. Unity uses the bounds to cull and sort all the instances of this sprite as a single entity, relative to other rendered sprites in the scene.
instanceData
can either be an array of 
Matrix4x4
, object-to-world transformation matrices per instance, or a custom data structure. When the 
instanceData
is a custom data structure, the structure can contain the following members:
Matrix4x4 objectToWorld; // mandatory: Specifies object-to-world transformation matrix.
Color spriteColor; // optional: Specifies the sprite color per instance. If not defined, defaults to Color.white.
uint renderingLayerMask; // optional: Specifies rendering layer mask per instance. If not defined, uses the renderLayerMask passed in RenderParams.
These members can appear in any order in the struct but they must have the above name and type. You can add other members but Unity ignores them when rendering.
You can only render a maximum of 1023 instances at once. The maximum depends on how much data you use for each instance.
By default, Unity uses an 
objectToWorld
matrix and a 
worldToObject
matrix for each instance, which means you can render a maximum of 511 instances at once. To remove the 
worldToObject
matrix from the instance data, add 
#pragma instancing_options assumeuniformscaling
to the shader.
Unity throws an 
InvalidOperationException
if the material doesn't have Material.enableInstancing set to true, if the current platform doesn't support this API, or if GPU instancing is not available. For more information, refer to SystemInfo.supportsInstancing.
Additional Resources: Graphics.RenderSprite.
The following example renders 10 sprites using 
RenderSpriteInstanced
. To use the script, enable GPU Instancing on the material:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 Matrix4x4[] instData = new Matrix4x4[numInstances];
 for(int i = 0; i < numInstances; ++i)
 instData[i] = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}
The following example uses a custom instance data struct that provides an object-to-world transformation and a rendering layer mask for rendering each instance. For demonstration purposes the struct defines also a custom data member 
myOtherData
that's unused for rendering but can be useful for other purposes:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 struct MyInstanceData
 {
 public Matrix4x4 objectToWorld;
 public Color spriteColor;
 public float myOtherData;
 };

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 MyInstanceData[] instData = new MyInstanceData[numInstances];
 for(int i = 0; i < numInstances; ++i)
 {
 instData[i].objectToWorld = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 instData[i].spriteColor = (i & 1) == 0 ? Color.red : Color.blue;
 }
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}

RenderSpriteInstanced<T>(RenderParams, SpriteParams, int, ReadOnlySpan<T>)

Renders multiple instances of a sprite using GPU instancing.
public static void RenderSpriteInstanced<T>(in RenderParams renderParams, in SpriteParams spriteParams, int submeshIndex, ReadOnlySpan<T> instanceData) where T : unmanaged

Parameters

renderParams

RenderParams

spriteParams

SpriteParams

submeshIndex

int
The index of a submesh Unity renders when the sprite contains multiple materials (submeshes). For a sprite with a single material, use value 0.

instanceData

ReadOnlySpan<T>
The array of instance data used to render the instances.

Remarks

This method renders sprites for the current frame. It's similar to Graphics.RenderSprite, but performance is better because it uses GPU instancing.
Use this function to render the same sprite multiple times using an instanced shader. Unity automatically calculates bounds for all the instances of this sprite unless you override the bounds using /RenderParams.worldBounds/. Unity uses the bounds to cull and sort all the instances of this sprite as a single entity, relative to other rendered sprites in the scene.
instanceData
can either be an array of 
Matrix4x4
, object-to-world transformation matrices per instance, or a custom data structure. When the 
instanceData
is a custom data structure, the structure can contain the following members:
Matrix4x4 objectToWorld; // mandatory: Specifies object-to-world transformation matrix.
Color spriteColor; // optional: Specifies the sprite color per instance. If not defined, defaults to Color.white.
uint renderingLayerMask; // optional: Specifies rendering layer mask per instance. If not defined, uses the renderLayerMask passed in RenderParams.
These members can appear in any order in the struct but they must have the above name and type. You can add other members but Unity ignores them when rendering.
You can only render a maximum of 1023 instances at once. The maximum depends on how much data you use for each instance.
By default, Unity uses an 
objectToWorld
matrix and a 
worldToObject
matrix for each instance, which means you can render a maximum of 511 instances at once. To remove the 
worldToObject
matrix from the instance data, add 
#pragma instancing_options assumeuniformscaling
to the shader.
Unity throws an 
InvalidOperationException
if the material doesn't have Material.enableInstancing set to true, if the current platform doesn't support this API, or if GPU instancing is not available. For more information, refer to SystemInfo.supportsInstancing.
Additional Resources: Graphics.RenderSprite.
The following example renders 10 sprites using 
RenderSpriteInstanced
. To use the script, enable GPU Instancing on the material:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 Matrix4x4[] instData = new Matrix4x4[numInstances];
 for(int i = 0; i < numInstances; ++i)
 instData[i] = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}
The following example uses a custom instance data struct that provides an object-to-world transformation and a rendering layer mask for rendering each instance. For demonstration purposes the struct defines also a custom data member 
myOtherData
that's unused for rendering but can be useful for other purposes:
using UnityEngine;

public class ExampleClass : MonoBehaviour
{
 public Material material;
 public Sprite sprite;
 const int numInstances = 10;

 struct MyInstanceData
 {
 public Matrix4x4 objectToWorld;
 public Color spriteColor;
 public float myOtherData;
 };

 void Update()
 {
 RenderParams rp = new RenderParams(material);
 SpriteParams sp = new SpriteParams(sprite);
 MyInstanceData[] instData = new MyInstanceData[numInstances];
 for(int i = 0; i < numInstances; ++i)
 {
 instData[i].objectToWorld = Matrix4x4.Translate(new Vector3(-4.5f+i, 0.0f, 5.0f));
 instData[i].spriteColor = (i & 1) == 0 ? Color.red : Color.blue;
 }
 Graphics.RenderSpriteInstanced(rp, sp, 0, instData);
 }
}