Mirror Engine API / BatchManager
Class: BatchManager
Glues many mesh instances into a single one for better performance.
Constructors
new BatchManager()
new BatchManager(
device: GraphicsDevice,
root: Entity,
scene: Scene): BatchManager
Create a new BatchManager instance.
Parameters
device
GraphicsDevice
The graphics device used by the batch manager.
root
The entity under which batched models are added.
scene
The scene that the batch manager affects.
Returns
Methods
addGroup()
addGroup(
name: string,
dynamic: boolean,
maxAabbSize: number,
id?: number,
layers?: number[]): BatchGroup
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
Group object.
clone()
clone(batch: Batch, clonedMeshInstances: MeshInstance[]): Batch
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
A batch object.
clonedMeshInstances
New mesh instances.
Returns
New batch object.
create()
create(
meshInstances: MeshInstance[],
dynamic: boolean,
batchGroupId?: number): Batch
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
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
The resulting batch object.
generate()
generate(groupIds?: number[]): void
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.
Returns
void
getGroupByName()
getGroupByName(name: string): null | BatchGroup
Retrieves a BatchGroup object with a corresponding name, if it exists, or null otherwise.
Parameters
name
string
Name.
Returns
null | BatchGroup
The batch group matching the name or null if not found.
markGroupDirty()
markGroupDirty(id: number): void
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.
Returns
void
prepare()
prepare(
meshInstances: MeshInstance[],
dynamic: boolean,
maxAabbSize: number,
translucent: boolean): MeshInstance[][]
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
Input list of mesh instances
dynamic
boolean
Are we preparing for a dynamic batch? Instance count will matter then (otherwise not).
maxAabbSize
number = Number.POSITIVE_INFINITY
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.
removeGroup()
removeGroup(id: number): void
Remove global batch group by id. Note, this traverses the entire scene graph and clears the batch group id from all components.
Parameters
id
number
Batch Group ID.
Returns
void