BatchGL

A library for easy WebGL batching.

View the Project on GitHub reissbaker/batchgl

BatchGL

Makes high-performance batched WebGL calls easy.

BatchGL models series of WebGL calls as a tree with vertex data buffered into the leaves. It renders the tree depth-first, so buffered vertices in leaves will get batched over together. Leaves closer to each other will get rendered more closely to each other, allowing for fewer expensive context switches, texture buffering, etc.

BatchGL is hosted on Github and is distributed under the MIT license. It's currently <1kb minifed and compressed.

Installation

bower install batchgl or npm install batchgl

You can use the build/batchgl.js file as-is, or run npm install && make build to get the minified and gzipped versions.

Examples

Here's how you might set up a texture-rendering pipeline:

/*
 * One-time setup of the rendering pipeline starts here:
 */

var Program = BatchGL.Root.extend({
  init: function(context, vertexShader, fragmentShader) {
    // compile shaders, link program here
  },
  run: function() {
    // tell WebGL to use the program
  }
});

var Texture = BatchGL.Step.extend({
  init: function(program, image) {
    // setup
  },
  run: function() {
    // buffer, bind textures
  }
});

var Uniform = BatchGL.Leaf.extend({
  init: function() {
    // setup
  },

  run: function() {
    // bind uniforms here
  },

  buffer: function(vertexSet) {
    // buffer vertices to WebGL
  },

  flush: function() {
    // call WebGL drawing methods
  }
});

var context = new BatchGL.Context(canvas),
    program = new Program(context, vertexShader, fragmentShader),
    sprite = new Texture(program, spriteSheet),
    otherSprite = new Texture(program, spriteSheet2),
    lion = new Uniform(sprite, someCoordinates),
    tiger = new Uniform(sprite, otherCoordinates),
    bear = new Uniform(otherSprite, otherOtherCoordinates);


/*
 * One-time setup is finished. You can now create sets of vertices pointing to
 * different leaves in the pipeline tree, and pass them around as renderable
 * objects.
 */

var v1 = new BatchGL.VertexSet(lion, [ /* some vertices */ ]);
var v2 = new BatchGL.VertexSet(lion, [ /* more vertices */ ]);
var v3 = new BatchGL.VertexSet(tiger, [ /* more vertices */ ]);
var v4 = new BatchGL.VertexSet(bear, [ /* more vertices */ ]);
var v5 = new BatchGL.VertexSet(bear, [ /* more vertices */ ]);

/*
 * You can buffer vertices in any order: BatchGL will optimize the underlying
 * calls so that it doesn't matter.
 */

v1.buffer();
v5.buffer();
v4.buffer();
v3.buffer();
v2.buffer();


/*
 * The following renders any buffered vertices. It optimizes the underlying
 * WebGL buffering and drawing according to the rendering tree set up above, to
 * maximize batching and to minimize expensive context switches.
 */

program.render();

API Docs

BatchGL.Context

The BatchGL Context object holds a reference to a <canvas> element and its corresponding WebGL context.

Methods:

Public Properties

BatchGL.TreeNode

TreeNode is the base class for any of the classes that make up the BatchGL rendering tree: Root, Step, and Leaf. TreeNodes are never instantiated directly, and are just a convenient holding place for shared callback stubs.

Class Methods:

Public Methods:

Framework-Reserved Methods

BatchGL.Root

The Root class defines the roots of rendering trees. You might set up a WebGL program in the root, and use it for all subsequent calls; if you have multiple programs, you might not do much here at all except for some basic environment setup.

Public Methods

Framework-Reserved Methods

Public Properties

BatchGL.Step

The Step class is for intermediate steps in the rendering tree. For example, you might bind textures in a step, which would ensure that any calls to the leaves beneath them would be batched into a single texture binding call. If you're using multiple programs, you probably want the programs to be implemented as Step classes underneath a single Root.

Public Methods

Framework-Reserved Methods

Public Properties

BatchGL.Leaf

The Leaf class defines the leaves of a rendering tree, and are what do the actual buffering and drawing of vertices. Leaves should ideally be cheap to switch: binding things like uniforms here is a good idea.

Public Methods

Framework-Reserved Methods

Public Properties

BatchGL.VertexSet

The VertexSet class defines a set of vertices for a particular leaf in the rendering tree. VertexSets are easy objects to pass around, and you can just call their .buffer() method when you want to tell the rendering tree that you want to render the set. Whenever you want to flush the frame, calling .render() on the tree's root node will flush all of the buffered vertices.

Public Methods

Public Properties

Development Notes

To run the tests, make sure you've run an npm install at some point, and then run script/test 8000 (or pass in the numerical port of your choice).

If you want to peruse the code, tell me about bugs, or submit patches: a link to the repo.