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:
-
context
WebGLContextthe context for this batch
-
size
Numberthe 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:
-
size
Numberthe 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:
-
texture
Texturethe Texture
-
x
Numberthe x position in pixels, defaults to zero
-
y
Numberthe y position in pixels, defaults to zero
-
width
Numberthe width in pixels, defaults to the texture width
-
height
Numberthe height in pixels, defaults to the texture height
-
u1
Numberthe first U coordinate, default zero
-
v1
Numberthe first V coordinate, default zero
-
u2
Numberthe second U coordinate, default one
-
v2
Numberthe 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:
-
texture
Texturethe Texture object
-
verts
Float32Arrayan array of vertices
-
off
Numberthe 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:
-
blendSrc
GLenumthe source blend parameter
-
blendDst
GLenumthe 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:
-
r
Numberthe red component, normalized
-
g
Numberthe green component, normalized
-
b
Numberthe blue component, normalized
-
a
Numberthe alpha component, normalized
setProjection
-
x
-
y
Sets the projection vector, an x and y defining the middle points of your stage.
Parameters:
-
x
Numberthe x projection value
-
y
Numberthe 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% opacity
If 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.