GPU instancing

GPU instancing is a draw call optimization method that renders multiple copies of a meshThe main graphics primitive of Unity. Meshes make up a large part of your 3D worlds. Unity supports triangulated or Quadrangulated polygon meshes. Nurbs, Nurms, Subdiv surfaces must be converted to polygons. More info
See in Glossary with the same material in a single draw call. Each copy of the mesh is called an instance. This is useful for drawing things that appear multiple times in a sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary, for example, trees or bushes.

GPU instancing renders identical meshes in the same draw call. To add variation and reduce the appearance of repetition, each instance can have different properties, such as Color or Scale. Draw calls that render multiple instances appear in the Frame Debugger as Draw Mesh (instanced).

Requirements and compatibility

This section includes information about the platform, render pipelineA series of operations that take the contents of a Scene, and displays them on a screen. Unity lets you choose from pre-built render pipelines, or write your own. More info
See in Glossary, and SRP Batcher compatibility of GPU instancing.

Platform compatibility

GPU instancing is available on every platform except WebGLA JavaScript API that renders 2D and 3D graphics in a web browser. The Unity WebGL build option allows Unity to publish content as JavaScript programs which use HTML5 technologies and the WebGL rendering API to run Unity content in a web browser. More info
See in Glossary 1.0.

Render pipeline compatibility

Notes:

1. Only if the shader isn’t compatible with the SRP Batcher.

SRP Batcher

GPU instancing isn’t compatible with the SRP Batcher. The SRP Batcher takes priority over GPU instancing. If a GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary is compatible with the SRP Batcher, Unity uses the SRP Batcher to render it, not GPU instancing. For more information about optimization method priority, see Optimization priority.

If your project uses the SRP Batcher and you want to use GPU instancing for a GameObject, you can do one of the following:

• Use Graphics.DrawMeshInstanced. This API bypasses the use of GameObjects and uses the specified parameters to directly draw a mesh on screen.
• Manually remove SRP Batcher compatibility. For information on how to do this, see Intentionally removing compatibility.

Using GPU instancing

Unity uses GPU instancing for GameObjects that share the same mesh and material. To instance a mesh and material:

• The material’s shaderA program that runs on the GPU. More info
  See in Glossary must support GPU instancing. Unity’s Standard Shader supports GPU instancing, as do all surface shadersA streamlined way of writing shaders for the Built-in Render Pipeline. More info
  See in Glossary. To add GPU instancing support to any other shader, see Creating shaders that support GPU instancing.
• The mesh must come from one of the following sources, grouped by behavior:
  • A MeshRenderer component or a Graphics.RenderMesh call.
    Behavior: Unity adds these meshes to a list and then checks to see which meshes it can instance.
    Unity does not support GPU instancing for SkinnedMeshRenderers or MeshRenderer components attached to GameObjects that are SRP Batcher compatible. For more information, see SRP Batcher compatibility.
  • A Graphics.RenderMeshInstanced or Graphics.RenderMeshIndirect call. These methods render the same mesh multiple times using the same shader. Each call to these methods issues a separate draw call. Unity does not merge these draw calls.

To use GPU instancing for a material, select the Enable GPU Instancing option in the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary.

Lighting

GPU instancing supports Unity’s Baked Global Illumination system. Unity Standard Shaders and surface shaders support GPU instancing and Unity’s Baked Global IlluminationA group of techniques that model both direct and indirect lighting to provide realistic lighting results.
See in Glossary system by default.

Each GPU instance supports global illumination from one of the following sources:

• Any number of Light ProbesLight probes store information about how light passes through space in your scene. A collection of light probes arranged within a given space can improve lighting on moving objects and static LOD scenery within that space. More info
  See in Glossary.
• One lightmapA pre-rendered texture that contains the effects of light sources on static objects in the scene. Lightmaps are overlaid on top of scene geometry to create the effect of lighting. More info
  See in Glossary.
  Note: An instance can use multiple atlas regions in the lightmap.
• One Light Probe Proxy VolumeA component that allows you to use more lighting information for large dynamic GameObjects that cannot use baked lightmaps (for example, large Particle Systems or skinned Meshes). More info
  See in Glossary(LPPV) component.
  Note: You must bake the LPPV for the space volume that contains all the instances.

GPU instancing automatically works with:

• Dynamic Mesh RenderersA mesh component that takes the geometry from the Mesh Filter and renders it at the position defined by the object’s Transform component. More info
  See in Glossary affected by Light Probes.
• Static Mesh Renderers you bake to the same lightmap texture. A Mesh Renderer is static in this context if it includes Contribute GI in its Static Editor Flags.

To enable Light Probe rendering for Graphics.DrawMeshInstanced, set the LightProbeUsage parameter to CustomProvided and provide a MaterialPropertyBlock that includes the Probe data. For more information and code examples, see LightProbes.CalculateInterpolatedLightAndOcclusionProbes.

Alternatively, you can pass an LPPV component reference and LightProbeUsage.UseProxyVolume to Graphics.DrawMeshInstanced. When you do this, all instances sample the volume for the L0 and L1 bands of the Light Probe data. If you want to supplement L2 data and occlusion data, use a MaterialPropertyBlock. For more information, see Light Probes: Technical Information.

Performance implications

Meshes that have a low number of vertices can’t be processed efficiently using GPU instancing because the GPU can’t distribute the work in a way that fully uses the GPU’s resources. This processing inefficiency can have a detrimental effect on performance. The threshold at which inefficiencies begin depends on the GPU, but as a general rule, don’t use GPU instancing for meshes that have fewer than 256 vertices.

If you want to render a mesh with a low number of vertices many times, best practice is to create a single buffer that contains all the mesh information and use that to draw the meshes.

• 2017–10–24 Page amended

• Enable instancing checkbox guidance, DrawMeshInstancedIndirect, #pragma multi-compile added in 5.6

• Shader warm up for GPU instancing added in 2017.3 NewIn20173

• Global Illumination (GI) support in GPU instancing added in 2018.1 NewIn20181