A library for easy WebGL batching.
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.
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.
Here's how you might set up a texture-rendering pipeline:
/** One-time setup of the rendering pipeline starts here:*/var Program = BatchGLRootextend// compile shaders, link program here// tell WebGL to use the program;var Texture = BatchGLStepextend// setup// buffer, bind textures;var Uniform = BatchGLLeafextend// setup// bind uniforms here// buffer vertices to WebGL// call WebGL drawing methods;var context = canvasprogram = context vertexShader fragmentShadersprite = program spriteSheetotherSprite = program spriteSheet2lion = sprite someCoordinatestiger = sprite otherCoordinatesbear = 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 = lion /* some vertices */ ;var v2 = lion /* more vertices */ ;var v3 = tiger /* more vertices */ ;var v4 = bear /* more vertices */ ;var v5 = bear /* more vertices */ ;/** You can buffer vertices in any order: BatchGL will optimize the underlying* calls so that it doesn't matter.*/v1buffer;v5buffer;v4buffer;v3buffer;v2buffer;/** 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.*/programrender;
The BatchGL Context object holds a reference to a
<canvas> element and its
corresponding WebGL context.
new Context(canvas). The Context constructor takes a canvas object and initializes its
globject by calling the HTML5
.updateSize(). This updates the
heightproperties of the
<canvas>element to be equal to their container's CSS box-sizing. It also updates the WebGL viewport to be the same.
gl, the WebGL context object.
TreeNode is the base class for any of the classes that make up the BatchGL
Leaf. TreeNodes are never instantiated
directly, and are just a convenient holding place for shared callback stubs.
.extend(Derived)sets up the prototype chain so that Derived extends the class, and also copies over any class methods from the base class to Derived. If Derived is a function, it will use the function as the constructor; if Derived is an object, it will create a constructor, make it extend the base class, and then add any properties from the given object to the derived constructor's prototype. In any case, it returns the derived constructor function.
new TreeNode(). The TreeNode constructor takes any number of arguments, and passes them all to its overridable
.init(), a method stub. Client code can override the
initmethod to do something when a node is initialized.
.run(), a method stub. Client code can override the
runmethod to do work when BatchGL is processing a
rendercall and has reached the current node in the tree.
.render(), a method stub that gets overridden by the derived node classes. Client code probably shouldn't override this method.
renderis called to render the current node.
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.
new Root(context)creates a new Root object for the given Context object. It also calls the overridable
.init()method inherited from TreeNode.
.run()method, and then calls
renderon all of the root's children.
.add(child)adds a TreeNode child to the Root. Steps (and Leaves) call this method automatically on their parents, so you shouldn't need to call this method manually when constructing a rendering tree.
contextholds the Context object for the root.
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.
new Step(parent)creates a new Step object underneath the given parent Root or Step node. It also calls the overridable
.init()method inherited from TreeNode.
.render(), much like the Root object, calls the Step's
run()method and then calls
renderon all of its children.
.add(child), like the Root's
.add()method, adds a TreeNode child to the Step. Since Steps and Leaves call this automatically in their constructors, you shouldn't need to call this manually when constructing a rendering tree.
contextis the Step's Context object.
parentis the Step's parent.
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.
new Leaf(parent)creates a new Leaf object underneath the given Root or Step parent. It also calls the overridable
.init()method inherited from TreeNode.
.buffer(vertexSet)is an overriddable method stub for buffering VertexSet instances. You should put WebGL buffering calls in here.
flush()is an overridable method stub for flushing buffered vertices. You should put WebGL draw calls here.
.render(), much like the other TreeNode rendering methods, calls the Leaf's
.run()method. However, the similarities stop there: it then calls its own
.buffer()method on each buffered VertexSet, and assuming that it buffered some vertices, then calls
._bufferVertex()buffers a VertexSet into the Leaf's rendering queue. VertexSets call this method automatically when you call their
.buffer()method, so you should never have to call this yourself.
parentis the Leaf's TreeNode parent.
contextis the Leaf's Context object.
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
.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.
new VertexSet(leaf, vertices)creates a new VertexSet for the given leaf. The vertices array is an optional array of numeric vertices; if you don't pass one into the constructor, you'll have to pass one in later with a
.setVerticescall before attempting to buffer the set.
.setVertices(vertices)takes an array of numeric vertices, and creates a Float32Array out of them and assigns it to the
.buffer()buffers the vertex into its Leaf parent for rendering. Note that it won't actually be rendered until a subsequent
.render()call on the root of the rendering tree (which you should probably call at the end of your frame).
leafis the parent Leaf object.
verticesis a Float32Array of vertices.
To run the tests, make sure you've run an
npm install at some point, and then
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.