BatchRendererGroup sample: Achieve high frame rate even on budget devices

In this post, we describe a small shooter game sample that animates and renders several interactive objects. Many demos are made for high-end PCs only, but the goal here is to achieve a high frame rate on a budget phone using GLES 3.0. This sample uses BatchRendererGroup, Burst compiler, and the C# Job System. It runs in Unity 2022.3 and doesn't require entities or entities.graphics DOTS packages.

Let’s get started.

Let’s jump right into what the sample is. This sample is running at a steady 60 fps on a budget 2019 Samsung Galaxy A51 (using a Mali G72-MP3 GPU). The graphics API is set to GLES 3.0.

You can study the code and try it on your favorite platform by downloading the project from GitHub. You’ll only need stock Unity 2022.3.

In this post we mainly focus on BatchRendererGroup and the sample class BRG_Container.cs. You can also study the animation and physics code in the BRG_Background.cs and BRG_Debris.cs classes.

Let’s explore what we see before going deeper into how to make it.

• The background floor is constructed from many cubes. All boxes are animated to move up and down.
• The main ship moves horizontally on the screen and shoots missiles at colored spheres. (You can shoot missiles faster by tapping the screen.)
• When a missile flies over the floor, a magnetic field slightly lifts and highlights the floor cells. It also throws ground debris into the air.
• When a missile hits a sphere, it explodes into colored debris.
• When debris hits the floor, the colliding cell on the floor flashes white. The more debris that hits a cell, the more the cell’s color darkens. In addition, the weight of the debris causes indents in the ground.

Both the floor cells and debris are made of cubes. Each cube has a different position and color. We want to animate and manage everything using the CPU to make the interactions between floor and debris easier. (Debris isn’t just a cosmetic visual, so it can’t be done with the GPU only.)

For rendering, we aren’t creating a GameObject per item to avoid an unnecessary performance hit on a low-end mobile device. Instead, we’re using the newly introduced BatchRendererGroup API.

Graphics.DrawMeshInstanced is a convenient and fast way to render many similar meshes at different positions. However, it has the following limitations compared to the BatchRendererGroup API:

• It requires providing a managed memory array with matrices, so you may get garbage collection. Also, inverted matrices are CPU-computed, even if the shader doesn’t need it (for instance, with URP/unlit).
• If you want to customize any property other than the obj2world matrix (like having one color per instance), you need to provide your own custom shader either by writing it from scratch or using Shader Graph
• Matrix or custom data must be uploaded to GPU memory at each draw. You can’t have persistent GPU memory data with Graphics.DrawMeshInstanced. Depending on context, this could be a huge performance hit.

BatchRendererGroup (or BRG) is an API that efficiently generates draw commands from C# and produces GPU-instancing draw calls. Since it doesn’t use managed memory, you can also generate commands using the Burst compiler.

Tip: The entities.graphics package is made to render entities (ECS package) and is built on top of BRG. entities.package does all GPU memory management and optimal draw commands creation for you. We’re not using ECS in this sample, so we’ll directly drive BRG.

BRG uses a specific GPU data layout and dedicated shader variant. The shader variant can fetch data from the standard constant buffer (UnityPerMaterial) or from a custom, large GPU buffer (BRG raw buffer). It’s up to you to manage how you store your data in the raw buffer, which is a Shader Storage Buffer Object (SSBO, or byte address buffer). The default BRG data layout is the structure of arrays (SoA) type.

You can instantiate any properties of a material without having to create a custom shader. In the sample, we want to instantiate obj2world matrix (to position cubes), world2obj matrix (for lighting), and BaseColor per box instance (because each floor cell or debris has its own color).

All other properties are the same for all cubes (e.g., smoothness value), and you can describe which properties will have custom values per instance using metadata.

The BRG metadata is an optional 32-bit value you can set per shader property. It tells the shader code how to load the property value from GPU memory and from where. Bits 0–30 define the offset of the property within the BRG raw buffer, and bit 31 tells whether the property value is the same for all instances or the offset is the beginning of an array, with one value per instance.

The exact meaning of BRG metadata also depends on the shader property type. Let’s sum up all possibilities:

Unlike Graphics.DrawMeshInstanced, BRG uses a persistent GPU memory buffer. Let’s say you have 10 cube positions and colors in the raw buffer, but only cubes 0, 3, and 7 are visible. You only want to draw three cubes, but you need the shader to properly read the position and color of those cubes. To do that, BRG shader uses a small additional indirection. This visibility buffer is just an array of “int” you fill when generating draw commands. 

In this example, you need to fill an array of three ints with {0,3,7} and can then generate a BRG draw command of three instances.

The shader code to fetch for “baseColor” property looks like this:

In our game sample, the floor is made of 32x100 cells, or 3,200. Each has a position, height, and color, and the cells scroll while the camera remains static. When a row scrolls out of the view, we inject a new row of 32 cells.

With 3,200 cells at any point in time, culling is not really necessary (all cells are always within the camera’s view). To position each cell, you need an obj2world matrix per cell, the invert matrix for lighting, and a color. To render the complete floor, we’ll use a single BRG draw command.

The sample’s debris is made up of small cubes, each one having a position, color, and rotation on its vertical axis. This is very similar to the floor cells. To do this, we created BRG_Container.cs. The class manages a BRG object to render floor cells or explosion debris. All physics animation and interaction is done with C# code using BRG_Debris.cs.

Unlike floor cells, the amount of debris varies across the frame. At initialization, you specify the maximum number of items to BRG_Container. In our sample, it’s 16,384 for debris (each explosion consists of 1,024 debris cubes) and we use async jobs to animate debris in a gravity field. When debris hits a floor cell, it interacts by digging into the ground.

To optimize GPU memory storage and bandwidth, BRG uses a float3x4 to store a matrix instead of float4x4. Keep in mind that a BRG matrix in the raw buffer is 48 bytes, not 64.

The raw buffer will look like this:

Tip: Debris raw buffer data looks similar to floor data as it also uses three custom properties (obj2world, world2obj, and color). The maximum number of items is 16,384 for debris, meaning a raw buffer of 112x16,384 bytes, or 1.75 MiB. Not all debris is rendered most of the time, depending on the number of debris cubes in existence at a given time.

We have a GPU GraphicsBuffer of 358,400 bytes. Since animation is done with the CPU, we also allocate a similar buffer in system memory (CPU can process data at full speed in system memory). Let’s call this second buffer a “shadow copy” of the GPU memory. C# code will animate the floor cells, using sin, and debris from the shadow copy. When animation is done, we upload the shadow copy buffer to the GPU using the GraphicsBuffer.SetData API.

Any BRG draw command needs a MeshID, MaterialID, and BatchID. The first two are easy to understand, but BatchID is more subtle. Think of BatchID as “kind of a batch.” To render the floor, you need to register one kind of batch, defined as follows:

1. “unity_ObjectToWorld” property is an array starting at offset 0 of the BRG raw buffer
2. “unity_WorldToObject” property is an array starting at offset 153,600
3. “_BaseColor” property is an array, starting at offset 307,200

Code to register this kind of batch at creation time will look similar to this:

We get the m_batchId at creation time, and can then use it for each BRG draw command (so the shader knows exactly how to fetch data for that kind of batch).

Tip: BatchRendererGroup.AddBatch is not a rendering command. It’s used to register a kind of batch, for future rendering commands.

So far, we can animate floor cells, upload the shadow copy system memory buffer to the GPU, and render all cells using a single DrawCommand of 3,200 instances.

This will work on most platforms: DirectX, Vulkan, Metal, and various game consoles, but not on GLES. The problem is that most GLES 3.0 devices can’t access SSBO during the vertex stage (i.e., the GL_MAX_VERTEX_SHADER_STORAGE_BLOCKS value is 0). So, when the graphics API is set to GLES, BRG will use a constant buffer, or UBO, instead to store the raw data.

This adds constraints: A constant buffer can be any size, but only a small part of it (a window) is visible at any given time when the shader is running. The window size depends on the hardware and driver, but a widely accepted value is 16 KiB.

Tip: In UBO mode, you should always use the BatchRendererGroup.GetConstantBufferMaxWindowSize() API to get the correct BRG window size.

Let’s see how our code changes if we want to run on GLES. For floor cells, the total amount of data is 350 KiB. We can’t do a single DrawInstanced(3,200) because the shader won’t be able to see 350 KiB at once. So, we have to split data within the UBO to maximize the amount of instances per draw, fitting into a 16 KiB block. One floor cell is 112 bytes (two matrices and one color), so you can fit 16,384 divided by 112, or 146 instances in a 16 KiB block. To render 3,200 instances, we will need to issue 21 DrawInstanced(146) and a last DrawInstanced(134).

Now, the 350KiB UBO will be split into 22 window blocks of 16KiB each, like this:

Tip: In UBO mode, each window offset should be aligned to BatchRendererGroup.GetConstantBufferOffsetAlignment(). Typical alignment values range from 4 to 256 bytes.

In GLES, because of the UBO and the 16 KiB windows, you need to register 22 BatchID in order to store the offsets of each window. The initialization code then needs a loop:

Tip: To support GLES (UBO) and other Graphics API (SSBO) in the game sample, BRG_Container.cs sets some vars at initialization time. In SSBO mode, m_windowCount is 1 and m_alignedGPUWindowSize is the total buffer size. In UBO mode, m_alignedGPUWindowSize is 16 KiB and m_windowCount contains the number of 16 KiB blocks. (The 16 KiB value is for readability. Use GetConstantBufferMaxWindowSize() API to get the correct value.)

Once the CPU updates all matrices and colors in the system memory, you can upload the data to the GPU. This is done with the BRG_Container.UploadGpuData function. Because of the SoA data model, you can’t upload a single block of memory. For debris, the buffer is 16,384 items. In GLES mode, that means 113 windows of 16 KiB each if 16,384 debris are on screen.

But what if only 5,300 debris cubes are in a given frame? Because you have 146 items per window, this means the first 36 consecutive 16 KiB windows should be uploaded so you can use a single SetData (36x16 KiB). In the last window, only 44 debris cubes should be displayed. To upload 44 matrices, invert matrices and colors and use three SetData commands. At the very end, four SetData commands should be issued.

Tip: Even in SSBO mode, if the number of items is less than the max (for example, 5,300 debris over a max of 16,384), three SetData commands are required. You can take a look at BRG_Container.UploadGpuData(int instanceCount) for implementation details.

The main entry point of BRG is the culling callback function you provide at creation time. The prototype looks like:

Your code in this callback is responsible for two things:

1. To generate all draw commands into the output BatchCullingOut struct
2. To use (or not) information provided in the BatchCullingContext read-only struct within your own culling code

Note: The callback returns a JobHandle in case you want to launch an async job to perform these operations. The engine will use this to sync at the point the result is needed, so your command generation code won’t block the main thread.

BatchCullingContext contains information like camera matrix, camera frustum plans, etc. Basically, all the data you need to cull and generate fewer draw commands. In the sample, all objects fit in the camera view (floor cells and debris), so there’s no need to use culling code.

BatchCullingOutputDrawCommands struct contains various data, including arrays. It’s the user’s responsibility to allocate native memory for those arrays. The engine is responsible for releasing that memory once the data has been consumed (you’re allocating, Unity is responsible for releasing). Memory allocation should be Allocator.TempJob type.

The first array you should allocate is the visibility int array. In the sample, as we assume everything is visible, we just fill the visibility int array with incremental values, like {0,1,2,3,4,...}.

A BRG draw command is almost a GPU DrawInstanced call. The most important array to allocate and fill is the BatchDrawCommand. Let’s say there are 4,737 debris cubes in the current frame.

m_maxInstancePerWindow is 146 in GLES mode. You can compute the amount of draw commands and allocate the buffer using ceiling value of m_instanceCount divided by m_maxInstancePerWindow:

To avoid duplicating similar parameters into several draw commands, BatchCullingOutputDrawCommands has an array of BatchDrawRange struct. You can set up various parameters within BatchDrawRange.filterSettings, like renderingLayerMask, receive shadow flags, etc. As all draw commands will share the same rendering settings, you could allocate a single DrawCommandRange struct that will apply from draw command 0 and contains all drawCommandCount commands.

Then, fill the draw commands. Each BatchDrawCommand contains a meshID, batchID (to know how to use metadata), and materialID. It also contains the starting offset in the visibility int array buffer. As we don't need any frustum culling in our context, we fill the visibility array with {0,1,2,3,...}. Then all draw commands will refer to the same {0,1,2,3,..} indirection so each BatchDrawCommand will use 0 as visibility array starting offset.The following code allocates and fills all needed draw commands:

Directly driving BatchRendererGroup requires some work. However, it works out-of-the-box without needing custom shaders or additional packages. In some situations, like having to render plenty of CPU simulated objects with custom instantiated properties, BatchRendererGroup is your best friend.

You can download the project from this repository.

You can also visit the forums to discuss about additional details on how we used C# job system and Burst compiler to handle all animations and interactions at full speed, even on a low-end CPU.