Graphics.RenderSpriteInstanced

Parameters

Description

Renders multiple instances of a sprite using GPU instancing.

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: 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);
    }
}