Class: BatchRenderer

.brend~BatchRenderer

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 PIXI.brend.BatchFactory.

  • Geometry Composition: The geometries of all display-objects are merged together in a composite geometry. This is done using an instance of PIXI.brend.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 PIXI.brend.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 PIXI.brend.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:

  1. PIXI.ObjectRenderer

  2. PIXI.AbstractBatchRenderer

new BatchRenderer (renderer, options)

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 PIXI.brend.BatchRendererPluginFactory.

Name Type Description
renderer PIXI.Renderer

renderer to attach to

options object
Name Type Default Description
attribSet Array.<PIXI.brend.AttributeRedirect>
indexProperty string | null
vertexCountProperty string | number optional
textureProperty string | null
texturesPerObject number 1 optional
texIDAttrib string

name of texture-id attribute variable

stateFunction function

returns a PIXI.State for an object

shaderFunction function

generates a shader given this instance

BatchGeometryFactory Class PIXI.brend.BatchGeometry optional
BatchFactoryClass Class PIXI.brend.StdBatchFactory optional
BatchDrawer Class PIXI.brend.BatchDrawer optional
See:
Example
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);
    }
}

Extends

  • PIXI.ObjectRenderer

Members

_attribRedirects Array.<PIXI.brend.AttributeRedirect> protectedreadonly

Attribute redirects

_BatchDrawerClass Class protectedreadonly

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

Default Value:
  • PIXI.brend.BatchDrawer

_batchFactory _BatchFactoryClass protectedreadonly

_BatchFactoryClass Class protectedreadonly

Batch-factory class.

Default Value:
  • PIXI.brend.StdBatchFactory

_BatchGeometryFactoryClass Class protectedreadonly

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

Default Value:
  • PIXI.brend.BatchGeometryFactory

_drawer _BatchDrawerClass protectedreadonly

_geometryFactory _BatchGeometryFactoryClass protectedreadonly

_inBatchIDAttrib string protectedreadonly

Indexes the display-object in the batch.

_indexProperty string protectedreadonly

Indices property

_shaderFunction function protectedreadonly

Shader generating function (takes the batch renderer)

See:

_stateFunction function protectedreadonly

State generating function (takes a display-object)

Default Value:
  • () => PIXI.State.for2d()

_texIDAttrib string protectedreadonly

Texture ID attribute

_textureProperty string protectedreadonly

Texture(s) property

_texturesPerObject number protectedreadonly

Textures per display-object

Default Value:
  • 1

_uniformIDAttrib string protectedreadonly

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 Array.<PIXI.brend.UniformRedirect> protectedreadonly

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

Default Value:
  • null

_vertexCountProperty string protectedreadonly

Vertex count property (optional)

options protectedreadonly

The options used to create this batch renderer.

Methods

contextChange ()

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

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.

render (displayObject)

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);
Name Type Description
displayObject PIXI.DisplayObject

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.

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