SpriteBatch Class
A basic implementation of a batcher which draws 2D sprites. This uses two triangles (quads) with indexed and interleaved vertex data. Each vertex holds 5 floats (Position.xy, Color, TexCoord0.xy).
The color is packed into a single float to reduce vertex bandwidth, and the data is interleaved for best performance. We use a static index buffer, and a dynamic vertex buffer that is updated with bufferSubData.
Constructor
SpriteBatch
-
context -
size
Parameters:
-
contextWebGLContextthe context for this batch
-
sizeNumberthe max number of sprites to fit in a single batch
Example:
var SpriteBatch = require('kami').SpriteBatch;
//create a new batcher
var batch = new SpriteBatch(context);
function render() {
batch.begin();
//draw some sprites in between begin and end...
batch.draw( texture, 0, 0, 25, 32 );
batch.draw( texture1, 0, 25, 42, 23 );
batch.end();
}Item Index
Methods
Properties
Attributes
Methods
_createMesh
-
size
Called from the constructor to create a new Mesh based on the expected batch size. Should set up verts & indices properly.
Users should not call this directly; instead, it should only be implemented by subclasses.
Parameters:
-
sizeNumberthe size passed through the constructor
_createShader
()
ShaderProgram
protected
Creates a default shader for this batch.
Returns:
a new instance of ShaderProgram
_createVertexAttribuets
()
type
protected
Used internally to return the Position, Color, and TexCoord0 attributes.
Returns:
[description]
_createVertexAttributes
()
Array
Returns an array of vertex attributes for this mesh; subclasses should implement this with the attributes expected for their batch.
This method initially throws an error; so it must be overridden by subclasses of BaseBatch.
Returns:
an array of Mesh.VertexAttrib objects
_preRender
()
protected
Called before rendering, and binds the current texture.
begin
()
Binds the shader, disables depth writing, enables blending, activates texture unit 0, and sends default matrices and sampler2D uniforms to the shader.
destroy
()
Destroys the batch, deleting its buffers and removing it from the WebGLContext management. Trying to use this batch after destroying it can lead to unpredictable behaviour.
If ownsShader is true, this will also delete the defaultShader object.
draw
-
texture -
x -
y -
width -
height -
u1 -
v1 -
u2 -
v2
Adds a sprite to this batch. The sprite is drawn in screen-space with the origin at the upper-left corner (y-down).
Parameters:
-
textureTexturethe Texture
-
xNumberthe x position in pixels, defaults to zero
-
yNumberthe y position in pixels, defaults to zero
-
widthNumberthe width in pixels, defaults to the texture width
-
heightNumberthe height in pixels, defaults to the texture height
-
u1Numberthe first U coordinate, default zero
-
v1Numberthe first V coordinate, default zero
-
u2Numberthe second U coordinate, default one
-
v2Numberthe second V coordinate, default one
drawVertices
-
texture -
verts -
off
Adds a single quad mesh to this sprite batch from the given array of vertices. The sprite is drawn in screen-space with the origin at the upper-left corner (y-down).
This reads 20 interleaved floats from the given offset index, in the format
{ x, y, color, u, v, ... }
Parameters:
-
textureTexturethe Texture object
-
vertsFloat32Arrayan array of vertices
-
offNumberthe offset into the vertices array to read from
end
()
Ends the sprite batcher and flushes any remaining data to the GPU.
flush
()
Flushes the batch to the GPU. This should be called when state changes, such as blend functions, depth or stencil states, shaders, and so forth.
getVertexSize
()
Number
The number of floats per vertex for this batcher (Position.xy + Color + TexCoord0.xy).
Returns:
the number of floats per vertex
setBlendFunction
-
blendSrc -
blendDst
Sets the blend source and destination parameters. This is a convenience function for the blendSrc and blendDst setters. If we are currently drawing, this will flush the batch.
Setting either to null or a falsy value tells the SpriteBatch
to ignore gl.blendFunc. This is useful if you wish to use your
own blendFunc or blendFuncSeparate.
Parameters:
-
blendSrcGLenumthe source blend parameter
-
blendDstGLenumthe destination blend parameter
setColor
-
r -
g -
b -
a
Sets the color of this sprite batcher, which is used in subsequent draw calls. This does not flush the batch.
If r, g, b, are all numbers, this method assumes that RGB or RGBA float values (0.0 to 1.0) are being passed. Alpha defaults to one if undefined.
If the first three arguments are not numbers, we only consider the first argument and assign it to all four components -- this is useful for setting transparency in a premultiplied alpha stage.
If the first argument is invalid or not a number, the color defaults to (1, 1, 1, 1).
Parameters:
-
rNumberthe red component, normalized
-
gNumberthe green component, normalized
-
bNumberthe blue component, normalized
-
aNumberthe alpha component, normalized
setProjection
-
x -
y
Sets the projection vector, an x and y defining the middle points of your stage.
Parameters:
-
xNumberthe x projection value
-
yNumberthe y projection value
updateMatrices
()
protected
This is called during rendering to update projection/transform matrices and upload the new values to the shader. For example, if the user calls setProjection mid-draw, the batch will flush and this will be called before continuing to add items to the batch.
You generally should not need to call this directly.
Properties
blendDst
GLenum
Sets the blend source parameters. If we are currently drawing, this will flush the batch.
Setting either src or dst to null or a falsy value tells the SpriteBatch
to ignore gl.blendFunc. This is useful if you wish to use your
own blendFunc or blendFuncSeparate.
blendingEnabled
Boolean
A property to enable or disable blending for this sprite batch. If we are currently drawing, this will first flush the batch, and then update GL_BLEND state (enabled or disabled) with our new value.
blendSrc
GLenum
Sets the blend destination parameters. If we are currently drawing, this will flush the batch.
Setting either src or dst to null or a falsy value tells the SpriteBatch
to ignore gl.blendFunc. This is useful if you wish to use your
own blendFunc or blendFuncSeparate.
color
Number
The ABGR packed color, as a single float. The default value is the color white (255, 255, 255, 255).
drawing
Boolean
Whether we are currently drawing to the batch. Do not modify.
ownsShader
Boolean
By default, a SpriteBatch is created with its own ShaderProgram,
stored in defaultShader. If this flag is true, on deleting the SpriteBatch, its
defaultShader will also be deleted. If this flag is false, no shaders
will be deleted on destroy.
Note that if you re-assign defaultShader, you will need to dispose the previous
default shader yoursel.
premultiplied
Boolean
Whether to premultiply alpha on calls to setColor. This is true by default, so that we can conveniently write:
batch.setColor(1, 0, 0, 0.25); //tints red with 25% opacityIf false, you must premultiply the colors yourself to achieve the same tint, like so:
batch.setColor(0.25, 0, 0, 0.25);Default: true
projection
Float32Array
The projection Float32Array vec2 which is used to avoid some matrix calculations.