Mirror Engine
V5
How To
Mirror Engine Logo

Mirror Engine API


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

Entity

The entity under which batched models are added.

scene

Scene

The scene that the batch manager affects.

Returns

BatchManager

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

BatchGroup

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

Batch

A batch object.

clonedMeshInstances

MeshInstance[]

New mesh instances.

Returns

Batch

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

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

Batch

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

MeshInstance[]

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

Mirror Engine Logo