libgdx API

com.badlogic.gdx.graphics.g2d
Class SpriteBatch

java.lang.Object
  extended by com.badlogic.gdx.graphics.g2d.SpriteBatch
All Implemented Interfaces:
Disposable

public class SpriteBatch
extends java.lang.Object
implements Disposable

A SpriteBatch is used to draw 2D rectangles that reference a texture (region). The class will batch the drawing commands and optimize them for processing by the GPU.

To draw something with a SpriteBatch one has to first call the begin() method which will setup appropriate render states. When you are done with drawing you have to call end() which will actually draw the things you specified.

All drawing commands of the SpriteBatch operate in screen coordinates. The screen coordinate system has an x-axis pointing to the right, an y-axis pointing upwards and the origin is in the lower left corner of the screen. You can also provide your own transformation and projection matrices if you so wish.

A SpriteBatch is managed. In case the OpenGL context is lost all OpenGL resources a SpriteBatch uses internally get invalidated. A context is lost when a user switches to another application or receives an incoming call on Android. A SpriteBatch will be automatically reloaded after the OpenGL context is restored.

A SpriteBatch is a pretty heavy object so you should only ever have one in your program.

A SpriteBatch works with OpenGL ES 1.x and 2.0. In the case of a 2.0 context it will use its own custom shader to draw all provided sprites. You can set your own custom shader via setShader(ShaderProgram).

A SpriteBatch has to be disposed if it is no longer used.

Author:
mzechner

Field Summary
static int C1
           
static int C2
           
static int C3
           
static int C4
           
 int maxSpritesInBatch
          the maximum number of sprites rendered in one batch so far
 int renderCalls
          number of render calls since last begin()
 int totalRenderCalls
          number of rendering calls ever, will not be reset, unless it's done manually
static int U1
           
static int U2
           
static int U3
           
static int U4
           
static int V1
           
static int V2
           
static int V3
           
static int V4
           
static int X1
           
static int X2
           
static int X3
           
static int X4
           
static int Y1
           
static int Y2
           
static int Y3
           
static int Y4
           
 
Constructor Summary
SpriteBatch()
          Constructs a new SpriteBatch.
SpriteBatch(int size)
          Constructs a SpriteBatch with the specified size and (if GL2) the default shader.
SpriteBatch(int size, int buffers)
          Constructs a SpriteBatch with the specified size and number of buffers and (if GL2) the default shader.
SpriteBatch(int size, int buffers, ShaderProgram defaultShader)
           Constructs a new SpriteBatch.
SpriteBatch(int size, ShaderProgram defaultShader)
           Constructs a new SpriteBatch.
 
Method Summary
 void begin()
          Sets up the SpriteBatch for drawing.
static ShaderProgram createDefaultShader()
          Returns a new instance of the default shader used by SpriteBatch for GL2 when no shader is specified.
 void disableBlending()
          Disables blending for drawing sprites.
 void dispose()
          Disposes all resources associated with this SpriteBatch
 void draw(Texture texture, float[] spriteVertices, int offset, int length)
          Draws a rectangle using the given vertices.
 void draw(Texture texture, float x, float y)
          Draws a rectangle with the bottom left corner at x,y having the width and height of the texture.
 void draw(Texture texture, float x, float y, float width, float height)
          Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height.
 void draw(Texture texture, float x, float y, float width, float height, float u, float v, float u2, float v2)
          Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels.
 void draw(Texture texture, float x, float y, float originX, float originY, float width, float height, float scaleX, float scaleY, float rotation, int srcX, int srcY, int srcWidth, int srcHeight, boolean flipX, boolean flipY)
          Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels.
 void draw(Texture texture, float x, float y, float width, float height, int srcX, int srcY, int srcWidth, int srcHeight, boolean flipX, boolean flipY)
          Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels.
 void draw(Texture texture, float x, float y, int srcX, int srcY, int srcWidth, int srcHeight)
          Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels.
 void draw(TextureRegion region, float x, float y)
          Draws a rectangle with the bottom left corner at x,y having the width and height of the region.
 void draw(TextureRegion region, float x, float y, float width, float height)
          Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height.
 void draw(TextureRegion region, float x, float y, float originX, float originY, float width, float height, float scaleX, float scaleY, float rotation)
          Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height.
 void draw(TextureRegion region, float x, float y, float originX, float originY, float width, float height, float scaleX, float scaleY, float rotation, boolean clockwise)
          Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height.
 void enableBlending()
          Enables blending for sprites
 void end()
          Finishes off rendering.
 void flush()
          Causes any pending sprites to be rendered, without ending the SpriteBatch.
 Color getColor()
           
 Matrix4 getProjectionMatrix()
          Returns the current projection matrix.
 Matrix4 getTransformMatrix()
          Returns the current transform matrix.
 boolean isBlendingEnabled()
           
 void setBlendFunction(int srcFunc, int dstFunc)
          Sets the blending function to be used when rendering sprites.
 void setColor(Color tint)
          Sets the color used to tint images when they are added to the SpriteBatch.
 void setColor(float color)
           
 void setColor(float r, float g, float b, float a)
           
 void setProjectionMatrix(Matrix4 projection)
          Sets the projection matrix to be used by this SpriteBatch.
 void setShader(ShaderProgram shader)
          Sets the shader to be used in a GLES 2.0 environment.
 void setTransformMatrix(Matrix4 transform)
          Sets the transform matrix to be used by this SpriteBatch.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

renderCalls

public int renderCalls
number of render calls since last begin()


totalRenderCalls

public int totalRenderCalls
number of rendering calls ever, will not be reset, unless it's done manually


maxSpritesInBatch

public int maxSpritesInBatch
the maximum number of sprites rendered in one batch so far


X1

public static final int X1
See Also:
Constant Field Values

Y1

public static final int Y1
See Also:
Constant Field Values

C1

public static final int C1
See Also:
Constant Field Values

U1

public static final int U1
See Also:
Constant Field Values

V1

public static final int V1
See Also:
Constant Field Values

X2

public static final int X2
See Also:
Constant Field Values

Y2

public static final int Y2
See Also:
Constant Field Values

C2

public static final int C2
See Also:
Constant Field Values

U2

public static final int U2
See Also:
Constant Field Values

V2

public static final int V2
See Also:
Constant Field Values

X3

public static final int X3
See Also:
Constant Field Values

Y3

public static final int Y3
See Also:
Constant Field Values

C3

public static final int C3
See Also:
Constant Field Values

U3

public static final int U3
See Also:
Constant Field Values

V3

public static final int V3
See Also:
Constant Field Values

X4

public static final int X4
See Also:
Constant Field Values

Y4

public static final int Y4
See Also:
Constant Field Values

C4

public static final int C4
See Also:
Constant Field Values

U4

public static final int U4
See Also:
Constant Field Values

V4

public static final int V4
See Also:
Constant Field Values
Constructor Detail

SpriteBatch

public SpriteBatch()
Constructs a new SpriteBatch. Sets the projection matrix to an orthographic projection with y-axis point upwards, x-axis point to the right and the origin being in the bottom left corner of the screen. The projection will be pixel perfect with respect to the screen resolution.


SpriteBatch

public SpriteBatch(int size)
Constructs a SpriteBatch with the specified size and (if GL2) the default shader. See SpriteBatch(int, ShaderProgram).


SpriteBatch

public SpriteBatch(int size,
                   ShaderProgram defaultShader)

Constructs a new SpriteBatch. Sets the projection matrix to an orthographic projection with y-axis point upwards, x-axis point to the right and the origin being in the bottom left corner of the screen. The projection will be pixel perfect with respect to the screen resolution.

The size parameter specifies the maximum size of a single batch in number of sprites

Parameters:
size - the batch size in number of sprites
defaultShader - the default shader to use. This is not owned by the SpriteBatch and must be disposed separately.

SpriteBatch

public SpriteBatch(int size,
                   int buffers)
Constructs a SpriteBatch with the specified size and number of buffers and (if GL2) the default shader. See SpriteBatch(int, int, ShaderProgram).


SpriteBatch

public SpriteBatch(int size,
                   int buffers,
                   ShaderProgram defaultShader)

Constructs a new SpriteBatch. Sets the projection matrix to an orthographic projection with y-axis point upwards, x-axis point to the right and the origin being in the bottom left corner of the screen. The projection will be pixel perfect with respect to the screen resolution.

The size parameter specifies the maximum size of a single batch in number of sprites

Parameters:
size - the batch size in number of sprites
buffers - the number of buffers to use. only makes sense with VBOs. This is an expert function.
defaultShader - the default shader to use. This is not owned by the SpriteBatch and must be disposed separately.
Method Detail

createDefaultShader

public static ShaderProgram createDefaultShader()
Returns a new instance of the default shader used by SpriteBatch for GL2 when no shader is specified.


begin

public void begin()
Sets up the SpriteBatch for drawing. This will disable depth buffer writting. It enables blending and texturing. If you have more texture units enabled than the first one you have to disable them before calling this. Uses a screen coordinate system by default where everything is given in pixels. You can specify your own projection and modelview matrices via setProjectionMatrix(Matrix4) and setTransformMatrix(Matrix4).


end

public void end()
Finishes off rendering. Enables depth writes, disables blending and texturing. Must always be called after a call to begin()


setColor

public void setColor(Color tint)
Sets the color used to tint images when they are added to the SpriteBatch. Default is Color.WHITE.


setColor

public void setColor(float r,
                     float g,
                     float b,
                     float a)
See Also:
setColor(Color)

setColor

public void setColor(float color)
See Also:
setColor(Color), Color.toFloatBits()

getColor

public Color getColor()
Returns:
the rendering color of this SpriteBatch. Manipulating the returned instance has no effect.

draw

public void draw(Texture texture,
                 float x,
                 float y,
                 float originX,
                 float originY,
                 float width,
                 float height,
                 float scaleX,
                 float scaleY,
                 float rotation,
                 int srcX,
                 int srcY,
                 int srcWidth,
                 int srcHeight,
                 boolean flipX,
                 boolean flipY)
Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels. The rectangle is offset by originX, originY relative to the origin. Scale specifies the scaling factor by which the rectangle should be scaled around originX, originY. Rotation specifies the angle of counter clockwise rotation of the rectangle around originX, originY. The portion of the Texture given by srcX, srcY and srcWidth, srcHeight is used. These coordinates and sizes are given in texels. FlipX and flipY specify whether the texture portion should be fliped horizontally or vertically.

Parameters:
texture - the Texture
x - the x-coordinate in screen space
y - the y-coordinate in screen space
originX - the x-coordinate of the scaling and rotation origin relative to the screen space coordinates
originY - the y-coordinate of the scaling and rotation origin relative to the screen space coordinates
width - the width in pixels
height - the height in pixels
scaleX - the scale of the rectangle around originX/originY in x
scaleY - the scale of the rectangle around originX/originY in y
rotation - the angle of counter clockwise rotation of the rectangle around originX/originY
srcX - the x-coordinate in texel space
srcY - the y-coordinate in texel space
srcWidth - the source with in texels
srcHeight - the source height in texels
flipX - whether to flip the sprite horizontally
flipY - whether to flip the sprite vertically

draw

public void draw(Texture texture,
                 float x,
                 float y,
                 float width,
                 float height,
                 int srcX,
                 int srcY,
                 int srcWidth,
                 int srcHeight,
                 boolean flipX,
                 boolean flipY)
Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels. The portion of the Texture given by srcX, srcY and srcWidth, srcHeight is used. These coordinates and sizes are given in texels. FlipX and flipY specify whether the texture portion should be fliped horizontally or vertically.

Parameters:
texture - the Texture
x - the x-coordinate in screen space
y - the y-coordinate in screen space
width - the width in pixels
height - the height in pixels
srcX - the x-coordinate in texel space
srcY - the y-coordinate in texel space
srcWidth - the source with in texels
srcHeight - the source height in texels
flipX - whether to flip the sprite horizontally
flipY - whether to flip the sprite vertically

draw

public void draw(Texture texture,
                 float x,
                 float y,
                 int srcX,
                 int srcY,
                 int srcWidth,
                 int srcHeight)
Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels. The portion of the Texture given by srcX, srcY and srcWidth, srcHeight are used. These coordinates and sizes are given in texels.

Parameters:
texture - the Texture
x - the x-coordinate in screen space
y - the y-coordinate in screen space
srcX - the x-coordinate in texel space
srcY - the y-coordinate in texel space
srcWidth - the source with in texels
srcHeight - the source height in texels

draw

public void draw(Texture texture,
                 float x,
                 float y,
                 float width,
                 float height,
                 float u,
                 float v,
                 float u2,
                 float v2)
Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels. The portion of the Texture given by u, v and u2, v2 are used. These coordinates and sizes are given in texture size percentage. The rectangle will have the given tint Color.

Parameters:
texture - the Texture
x - the x-coordinate in screen space
y - the y-coordinate in screen space
width - the width in pixels
height - the height in pixels

draw

public void draw(Texture texture,
                 float x,
                 float y)
Draws a rectangle with the bottom left corner at x,y having the width and height of the texture.

Parameters:
texture - the Texture
x - the x-coordinate in screen space
y - the y-coordinate in screen space

draw

public void draw(Texture texture,
                 float x,
                 float y,
                 float width,
                 float height)
Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height.


draw

public void draw(Texture texture,
                 float[] spriteVertices,
                 int offset,
                 int length)
Draws a rectangle using the given vertices. There must be 4 vertices, each made up of 5 elements in this order: x, y, color, u, v.


draw

public void draw(TextureRegion region,
                 float x,
                 float y)
Draws a rectangle with the bottom left corner at x,y having the width and height of the region.


draw

public void draw(TextureRegion region,
                 float x,
                 float y,
                 float width,
                 float height)
Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height.


draw

public void draw(TextureRegion region,
                 float x,
                 float y,
                 float originX,
                 float originY,
                 float width,
                 float height,
                 float scaleX,
                 float scaleY,
                 float rotation)
Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height. The rectangle is offset by originX, originY relative to the origin. Scale specifies the scaling factor by which the rectangle should be scaled around originX, originY. Rotation specifies the angle of counter clockwise rotation of the rectangle around originX, originY.


draw

public void draw(TextureRegion region,
                 float x,
                 float y,
                 float originX,
                 float originY,
                 float width,
                 float height,
                 float scaleX,
                 float scaleY,
                 float rotation,
                 boolean clockwise)
Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height. The rectangle is offset by originX, originY relative to the origin. Scale specifies the scaling factor by which the rectangle should be scaled around originX, originY. Rotation specifies the angle of counter clockwise rotation of the rectangle around originX, originY.


flush

public void flush()
Causes any pending sprites to be rendered, without ending the SpriteBatch.


disableBlending

public void disableBlending()
Disables blending for drawing sprites. Does not disable blending for text rendering


enableBlending

public void enableBlending()
Enables blending for sprites


setBlendFunction

public void setBlendFunction(int srcFunc,
                             int dstFunc)
Sets the blending function to be used when rendering sprites.

Parameters:
srcFunc - the source function, e.g. GL11.GL_SRC_ALPHA
dstFunc - the destination function, e.g. GL11.GL_ONE_MINUS_SRC_ALPHA

dispose

public void dispose()
Disposes all resources associated with this SpriteBatch

Specified by:
dispose in interface Disposable

getProjectionMatrix

public Matrix4 getProjectionMatrix()
Returns the current projection matrix. Changing this will result in undefined behaviour.

Returns:
the currently set projection matrix

getTransformMatrix

public Matrix4 getTransformMatrix()
Returns the current transform matrix. Changing this will result in undefined behaviour.

Returns:
the currently set transform matrix

setProjectionMatrix

public void setProjectionMatrix(Matrix4 projection)
Sets the projection matrix to be used by this SpriteBatch. If this is called inside a begin()/end() block. the current batch is flushed to the gpu.

Parameters:
projection - the projection matrix

setTransformMatrix

public void setTransformMatrix(Matrix4 transform)
Sets the transform matrix to be used by this SpriteBatch. If this is called inside a begin()/end() block. the current batch is flushed to the gpu.

Parameters:
transform - the transform matrix

setShader

public void setShader(ShaderProgram shader)
Sets the shader to be used in a GLES 2.0 environment. Vertex position attribute is called "a_position", the texture coordinates attribute is called called "a_texCoords0", the color attribute is called "a_color". See ShaderProgram.POSITION_ATTRIBUTE, ShaderProgram.COLOR_ATTRIBUTE and ShaderProgram.TEXCOORD_ATTRIBUTE which gets "0" appened to indicate the use of the first texture unit. The projection matrix is uploaded via a mat4 uniform called "u_proj", the transform matrix is uploaded via a uniform called "u_trans", the combined transform and projection matrx is is uploaded via a mat4 uniform called "u_projTrans". The texture sampler is passed via a uniform called "u_texture". Call this method with a null argument to use the default shader.

Parameters:
shader - the ShaderProgram or null to use the default shader.

isBlendingEnabled

public boolean isBlendingEnabled()
Returns:
whether blending for sprites is enabled

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)