API Reference

Class List

pc.BatchManager

Glues many mesh instances into a single one for better performance.

Summary

Methods

addGroupAdds new global batch group.
cloneClones a batch.
createTakes a mesh instance list that has been prepared by pc.BatchManager#prepare, and returns a pc.Batch object.
generateDestroys all batches and creates new based on scene models.
getGroupByNameRetrieves a pc.BatchGroup object with a corresponding name, if it exists, or null otherwise.
prepareTakes a list of mesh instances to be batched and sorts them into lists one for each draw call.
registerRegisters entities as used inside the batch, and sets batch's reference counter to entity count.
removeGroupRemove global batch group by id.

Details

Constructor

BatchManager(device, root, scene)

Parameters

devicepc.GraphicsDeviceThe graphics device used by the batch manager.
rootpc.EntityThe entity under which batched models are added.
scenepc.SceneThe scene that the batch manager affects.

Methods

addGroup(name, dynamic, maxAabbSize, [id], [layers])

Adds new global batch group.

Parameters

nameStringCustom name
dynamicBooleanIs this batch group dynamic? Will these objects move/rotate/scale after being batched?
maxAabbSizeNumberMaximum size of any dimension of a bounding box around batched objects. pc.BatchManager#prepare will split objects into local groups based on this size.
idNumberOptional custom unique id for the group (will be generated automatically otherwise).
layersNumber[]Optional layer ID array. Default is [pc.LAYERID_WORLD]. The whole batch group will belong to these layers. Layers of source models will be ignored.

Returns

pc.BatchGroup Group 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

batchpc.BatchA batch object
clonedMeshInstancesArrayNew mesh instances

Returns

pc.Batch New batch object

create(meshInstances, dynamic, [batchGroupId])

Takes a mesh instance list that has been prepared by pc.BatchManager#prepare, and returns a pc.Batch object. This method assumes that all mesh instances provided can be rendered in a single draw call.

Parameters

meshInstancesArrayInput list of mesh instances
dynamicBooleanIs it a static or dynamic batch? Will objects be transformed after batching?
batchGroupIdNumberLink this batch to a specific batch group. This is done automatically with default batches.

Returns

pc.Batch The 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

groupIdsArrayOptional array of batch group IDs to update. Otherwise all groups are updated.

getGroupByName(name)

Retrieves a pc.BatchGroup object with a corresponding name, if it exists, or null otherwise.

Parameters

nameStringName

Returns

pc.BatchGroup Group object.

prepare(meshInstances, dynamic, maxAabbSize)

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

meshInstancesArrayInput list of mesh instances
dynamicBooleanAre we preparing for a dynamic batch? Instance count will matter then (otherwise not).
maxAabbSizeNumberMaximum size of any dimension of a bounding box around batched objects. 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

Array An array of arrays of mesh instances, each valid to pass to pc.BatchManager#create.

register(batch, entities)

Registers entities as used inside the batch, and sets batch's reference counter to entity count. If these entities are destroyed, pc.BatchManager#destroy will be called on the batch.

Parameters

batchpc.BatchA batch object
entitiesArrayAn array of pc.Entity

removeGroup(id)

Remove global batch group by id. Note, this traverses the entire scene graph and clears the batch group id from all components

Parameters

idStringGroup id