BatchManager
Glues many mesh instances into a single one for better performance.
Summary
Methods
| addGroup | Adds new global batch group. |
| clone | Clones a batch. |
| create | Takes a mesh instance list that has been prepared by BatchManager#prepare, and returns a Batch object. |
| generate | Destroys all batches and creates new based on scene models. |
| getGroupByName | Retrieves a BatchGroup object with a corresponding name, if it exists, or null otherwise. |
| markGroupDirty | Mark a specific batch group as dirty. |
| prepare | Takes a list of mesh instances to be batched and sorts them into lists one for each draw call. |
| removeGroup | Remove global batch group by id. |
Details
Constructor
BatchManager(device, root, scene)
Create a new BatchManager instance.
Parameters
| device | GraphicsDevice | The graphics device used by the batch manager. |
| root | Entity | The entity under which batched models are added. |
| scene | Scene | The scene that the batch manager affects. |
Methods
addGroup(name, dynamic, maxAabbSize, [id], [layers])
Adds new global batch group.
Parameters
| name | string | Custom name. |
| dynamic | boolean | Is this batch group dynamic? Will these objects move/rotate/scale after being batched? |
| maxAabbSize | number | Maximum size of any dimension of a bounding box around batched objects. BatchManager#prepare will split objects into local groups based on this size. |
| id | number | Optional custom unique id for the group (will be generated automatically otherwise). |
| layers | number[] | Optional layer ID array. Default is [LAYERID_WORLD]. The whole batch group will belong to these layers. Layers of source models will be ignored. |
Returns
BatchGroupGroup object.
clone(batch, clonedMeshInstances)
Clones a batch. This method doesn't rebuild batch geometry, but only creates a new model and batch objects, linked to different source mesh instances.
Parameters
| batch | Batch | A batch object. |
| clonedMeshInstances | MeshInstance[] | New mesh instances. |
Returns
BatchNew batch object.
create(meshInstances, dynamic, [batchGroupId])
Takes a mesh instance list that has been prepared by BatchManager#prepare, and returns a Batch object. This method assumes that all mesh instances provided can be rendered in a single draw call.
Parameters
| meshInstances | MeshInstance[] | Input list of mesh instances. |
| dynamic | boolean | Is it a static or dynamic batch? Will objects be transformed after batching? |
| batchGroupId | number | Link this batch to a specific batch group. This is done automatically with default batches. |
Returns
BatchThe resulting batch object.
generate([groupIds])
Destroys all batches and creates new based on scene models. Hides original models. Called by engine automatically on app start, and if batchGroupIds on models are changed.
Parameters
| groupIds | number[] | Optional array of batch group IDs to update. Otherwise all groups are updated. |
getGroupByName(name)
Retrieves a BatchGroup object with a corresponding name, if it exists, or null otherwise.
Parameters
| name | string | Name. |
Returns
BatchGroup, nullThe batch group matching the name or null if not found.
markGroupDirty(id)
Mark a specific batch group as dirty. Dirty groups are re-batched before the next frame is rendered. Note, re-batching a group is a potentially expensive operation.
Parameters
| id | number | Batch Group ID to mark as dirty. |
prepare(meshInstances, dynamic, maxAabbSize, translucent)
Takes a list of mesh instances to be batched and sorts them into lists one for each draw call. The input list will be split, if:
- Mesh instances use different materials.
- Mesh instances have different parameters (e.g. lightmaps or static lights).
- Mesh instances have different shader defines (shadow receiving, being aligned to screen space, etc).
- Too many vertices for a single batch (65535 is maximum).
- Too many instances for a single batch (hardware-dependent, expect 128 on low-end and 1024 on high-end).
- Bounding box of a batch is larger than maxAabbSize in any dimension.
Parameters
| meshInstances | MeshInstance[] | Input list of mesh instances |
| dynamic | boolean | Are we preparing for a dynamic batch? Instance count will matter then (otherwise not). |
| maxAabbSize | number | Maximum size of any dimension of a bounding box around batched objects. |
| translucent | boolean | Are we batching UI elements or sprites This is useful to keep a balance between the number of draw calls and the number of drawn triangles, because smaller batches can be hidden when not visible in camera. |
Returns
MeshInstance[][]An array of arrays of mesh instances, each valid to pass to BatchManager#create.