BatchRenderer

class BatchRenderer extends PIXI.ObjectRenderer

This object renderer renders multiple display-objects in batches. It can greatly reduce the number of draw calls issued per frame.

Batch Rendering Pipeline

The batch rendering pipeline consists of the following stages:

Display-Object Buffering: Each display-object is kept in a buffer until it fills up or a flush is required.
Batch Generation: In a sliding window, display-object batches are generated based off of certain constraints like GPU texture units and the uniforms used in each display-object. This is done using an instance of BatchFactory.
Geometry Composition: The geometries of all display-objects are merged together in a composite geometry. This is done using an instance of BatchGeometryFactory.
Drawing: Each batch is rendered in-order using gl.draw*. The textures and uniforms of each display-object are uploaded as arrays. This is done using an instance of BatchDrawer.

Each stage in this pipeline can be configured by overriding the appropriate component and passing that class to BatchRendererPluginFactory.from*.

Shaders

Shader templates

Since the max. display-object count per batch is not known until the WebGL context is created, shaders are generated at runtime by processing shader templates. A shader templates has "%macros%" that are replaced by constants at runtime.

To use shader templates, simply use BatchShaderFactory#derive. This will generate a function that derives a shader from your template at runtime.

Textures

The batch renderer uploads textures in the uniform sampler2D uSamplers[%texturesPerBatch%];. The varying float vTextureId defines the index into this array that holds the current display-object's texture.

Uniforms

This renderer currently does not support customized uniforms for display-objects. This is a work-in-progress feature.

Learn more

This batch renderer uses the PixiJS object-renderer API to hook itself:


 import * as PIXI from 'pixi.js';
 import { BatchRendererPluginFactory } from 'pixi-batch-renderer';

 // Define the geometry of your display-object and create a BatchRenderer using
 // BatchRendererPluginFactory. Register it as a plugin with PIXI.Renderer.
 PIXI.Renderer.registerPlugin('ExampleBatchRenderer', BatchRendererPluginFactory.from(...));

 class ExampleObject extends PIXI.Container
 {
     _render(renderer: PIXI.Renderer): void
     {
          // BatchRenderer will handle the whole rendering process for you!
          renderer.batch.setObjectRenderer(renderer.plugins['ExampleBatchRenderer']);
          renderer.plugins['ExampleBatchRenderer'].render(this);
     }
 }

Constructor

new BatchRenderer(renderer: PIXI.Renderer, options: object) → {}

Creates a batch renderer the renders display-objects with the described geometry.

To register a batch-renderer plugin, you must use the API provided by BatchRendererPluginFactory.

Parameters:
Name	Type	Attributes	Default	Description
renderer	PIXI.Renderer			renderer to attach to
options	object
options.attribSet	Array<AttributeRedirect>
options.indexProperty	string \| unknown
options.vertexCountProperty	string \| number	<optional>
options.textureProperty	string \| unknown
options.texturesPerObject	number	<optional>	1
options.texIDAttrib	string			name of texture-id attribute variable
options.stateFunction	Function	<optional>	PIXI.State.for2d()	returns a `PIXI.State` for an object
options.shaderFunction	Function			generates a shader given this instance
options.BatchGeometryFactory	Class	<optional>	BatchGeometry
options.BatchFactoryClass	Class	<optional>	StdBatchFactory
options.BatchDrawer	Class	<optional>	BatchDrawer

See:

Summary

Properties from BatchRenderer

	_masterIDAttrib
AttributeRedirect[]	protected _attribRedirects Attribute redirects
Class	protected _BatchDrawerClass = BatchDrawer
_BatchFactoryClass	protected _batchFactory
Class	protected _BatchFactoryClass = StdBatchFactory
Class	protected _BatchGeometryFactoryClass = BatchGeometryFactory
_BatchDrawerClass	protected _drawer
_BatchGeometryFactoryClass	protected _geometryFactory
string	protected _inBatchIDAttrib
string \| number \| ((object: PIXI.DisplayObject) => number)	protected _indexCountProperty
string	protected _indexProperty Indices property
Function	protected _shaderFunction
Function	protected _stateFunction = () => PIXI.State.for2d()
string	protected _texIDAttrib
string	protected _textureProperty
number	protected _texturesPerObject = 1
string	protected _uniformIDAttrib
Array<UniformRedirect>	protected _uniformRedirects = null
string \| number \| ((object: PIXI.DisplayObject) => number)	protected _vertexCountProperty
	protected options
PIXI.Renderer	protected renderer

Methods from BatchRenderer

void	contextChange() Internal method that is called whenever the renderer's WebGL context changes.
void	flush()
void	render(displayObject: PIXI.DisplayObject)
void	start()
void	stop() Internal method that stops buffering of display-objects and flushes any existing buffers.
number	protected calculateIndexCount(object: PIXI.DisplayObject) Calculates the number of indices in the display object's geometry.
number	protected calculateVertexCount(object: PIXI.DisplayObject) Calculates the number of vertices in the display object's geometry.

Methods inherited from ObjectRenderer

void	destroy() Generic destruction method that frees all resources. This should be called by subclasses.

Public Properties

_masterIDAttrib BatchRenderer.ts:321

_masterIDAttrib

This is an advanced feature that allows you to pack the _texIDAttrib, _uniformIDAttrib, _inBatchIDAttrib, and other information into one 32-bit float attribute. You can then unpack them in the vertex shader and pass varyings to the fragment shader (because int varyings are not supported).

To use it, you must provide your own BatchGeometryFactory that overrides BatchGeometryFactory#append and sets the _masterIDAttrib.

Protected Properties

_attribRedirects BatchRenderer.ts:121

protected _attribRedirects: AttributeRedirect[]

Attribute redirects

_BatchDrawerClass BatchRenderer.ts:293

protected _BatchDrawerClass: Class = BatchDrawer

Batch drawer class. Its constructor takes one argument - this batch renderer.

_batchFactory BatchRenderer.ts:380

protected _batchFactory: _BatchFactoryClass

_BatchFactoryClass BatchRenderer.ts:275

protected _BatchFactoryClass: Class = StdBatchFactory

Batch-factory class.

_BatchGeometryFactoryClass BatchRenderer.ts:284

protected _BatchGeometryFactoryClass: Class = BatchGeometryFactory

Batch-geometry factory class. Its constructor takes one argument - this batch renderer.

_drawer BatchRenderer.ts:394

protected _drawer: _BatchDrawerClass

_geometryFactory BatchRenderer.ts:387

protected _geometryFactory: _BatchGeometryFactoryClass

_inBatchIDAttrib BatchRenderer.ts:249

protected _inBatchIDAttrib: string

Indexes the display-object in the batch.

_indexCountProperty BatchRenderer.ts:135

protected _indexCountProperty: string | number | ((object: PIXI.DisplayObject) => number)

A manual resolution of the number of indicies in a display object's geometry. This is ignored if the index buffer is not used (see _indexProperty). If not provided, the index buffer's entire length is used.

_indexProperty BatchRenderer.ts:128

protected _indexProperty: string

Indices property

_shaderFunction BatchRenderer.ts:266

protected _shaderFunction: Function

Shader generating function (takes the batch renderer)

See: BatchShaderFactory

_stateFunction BatchRenderer.ts:257

protected _stateFunction: Function = () => PIXI.State.for2d()

State generating function (takes a display-object)

_texIDAttrib BatchRenderer.ts:241

protected _texIDAttrib: string

Texture ID attribute

_textureProperty BatchRenderer.ts:224

protected _textureProperty: string

Texture(s) property

_texturesPerObject BatchRenderer.ts:232

protected _texturesPerObject: number = 1

Textures per display-object

_uniformIDAttrib BatchRenderer.ts:312

protected _uniformIDAttrib: string

Indexes the uniforms of the display-object in the uniform arrays. This is not equal to the in-batch ID because equal uniforms are not uploaded twice.

_uniformRedirects BatchRenderer.ts:302

protected _uniformRedirects: Array<UniformRedirect> = null

Uniform redirects. If you use uniforms in your shader, be sure to use one the compatible batch factories (like AggregateUniformsBatchFactory).

_vertexCountProperty BatchRenderer.ts:144

protected _vertexCountProperty: string | number | ((object: PIXI.DisplayObject) => number)

A manual resolution of the number of vertices in a display object's geometry. If not provided, this is calculated as the number of element in the first attribute's buffer.

options BatchRenderer.ts:332

protected options

The options used to create this batch renderer.

renderer BatchRenderer.ts:117

protected renderer: PIXI.Renderer

Public Methods

contextChange BatchRenderer.ts:364

contextChange() → {void}

Internal method that is called whenever the renderer's WebGL context changes.

Returns:
Type	Description
void

flush BatchRenderer.ts:440

flush() → {void}

Forces buffered display-objects to be rendered immediately. This should not be called unless absolutely necessary like the following scenarios:

before directly rendering your display-object, to preserve render-order.
to do a nested render pass (calling Renderer#render inside a render method) because the PixiJS renderer is not re-entrant.

Returns:
Type	Description
void

render BatchRenderer.ts:417

render(displayObject: PIXI.DisplayObject) → {void}

Adds the display-object to be rendered in a batch. Your display-object's render/_render method should call this as follows:

renderer.setObjectRenderer(<BatchRenderer>);
<BatchRenderer>.render(this);

Parameters:
Name	Type	Description
displayObject	PIXI.DisplayObject

Returns:
Type	Description
void

start BatchRenderer.ts:402

start() → {void}

This is an internal method. It ensures that the batch renderer is ready to start buffering display-objects. This is automatically invoked by the renderer's batch system.

Returns:
Type	Description
void

stop BatchRenderer.ts:529

stop() → {void}

Internal method that stops buffering of display-objects and flushes any existing buffers.

Returns:
Type	Description
void

Protected Methods

calculateIndexCount BatchRenderer.ts:556

protected calculateIndexCount(object: PIXI.DisplayObject) → {number}

Calculates the number of indices in the display object's geometry.

Parameters:
Name	Type	Description
object	PIXI.DisplayObject

Returns:
Type	Description
number

calculateVertexCount BatchRenderer.ts:542

protected calculateVertexCount(object: PIXI.DisplayObject) → {number}

Calculates the number of vertices in the display object's geometry.

Parameters:
Name	Type	Description
object	PIXI.DisplayObject

Returns:
Type	Description
number