com.badlogic.gdx.graphics.g2d
Class SpriteBatch

java.lang.Object
  com.badlogic.gdx.graphics.g2d.SpriteBatch

All Implemented Interfaces:

Disposable

public class SpriteBatch
extends 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 the last begin().
int	totalRenderCalls Number of rendering calls, ever.
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 with a size of 1000, one buffer, and the default shader.

SpriteBatch(int size)
Constructs a SpriteBatch with one buffer and the default shader.

SpriteBatch(int size, int buffers)
Constructs a SpriteBatch with the default shader.

SpriteBatch(int size, int buffers, ShaderProgram defaultShader)
Constructs a new SpriteBatch.

SpriteBatch(int size, ShaderProgram defaultShader)
Constructs a new SpriteBatch with one buffer.

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 count) 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 texture coordinates rotated 90 degrees.
void	enableBlending() Enables blending for drawing sprites.
void	end() Finishes off rendering.
void	flush() Causes any pending sprites to be rendered, without ending the SpriteBatch.
int	getBlendDstFunc()
int	getBlendSrcFunc()
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

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

renderCalls

public int renderCalls

Number of render calls since the last begin().

totalRenderCalls

public int totalRenderCalls

Number of rendering calls, ever. Will not be reset unless set 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 with a size of 1000, one buffer, and the default shader.

See Also:

SpriteBatch(int, int, ShaderProgram)

SpriteBatch

public SpriteBatch(int size)

Constructs a SpriteBatch with one buffer and the default shader.

See Also:

SpriteBatch(int, int, ShaderProgram)

SpriteBatch

public SpriteBatch(int size,
                   ShaderProgram defaultShader)

Constructs a new SpriteBatch with one buffer.

See Also:

SpriteBatch(int, int, ShaderProgram)

SpriteBatch

public SpriteBatch(int size,
                   int buffers)

Constructs a SpriteBatch with the default shader.

See Also:

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 current screen resolution.

The defaultShader specifies the shader to use. Note that the names for uniforms for this default shader are different than the ones expect for shaders set with setShader(ShaderProgram). See createDefaultShader().

Parameters:

size - The max number of sprites in a single batch. Max of 5460.

buffers - The number of meshes to use. This is an expert function. It only makes sense with VBOs (see Mesh.forceVBO).

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:

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:

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:

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:

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:

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 count)

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. The getColor() from the SpriteBatch is not applied.

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 texture coordinates rotated 90 degrees. 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.

Parameters:

clockwise - If true, the texture coordinates are rotated 90 degrees clockwise. If false, they are rotated 90 degrees counter clockwise.

flush

public void flush()

Causes any pending sprites to be rendered, without ending the SpriteBatch.

disableBlending

public void disableBlending()

Disables blending for drawing sprites. Calling this within begin()/end() will flush the batch.

enableBlending

public void enableBlending()

Enables blending for drawing sprites. Calling this within begin()/end() will flush the batch.

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. If set to -1, SpriteBatch won't change the blending function.

dstFunc - the destination function, e.g. GL11.GL_ONE_MINUS_SRC_ALPHA

getBlendSrcFunc

public int getBlendSrcFunc()

getBlendDstFunc

public int getBlendDstFunc()

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 within begin()/end() results in undefined behaviour.

getTransformMatrix

public Matrix4 getTransformMatrix()

Returns the current transform matrix. Changing this within begin()/end() results in undefined behaviour.

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.

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.

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 "a_texCoord0", 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 combined transform and projection matrx 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.

This method will flush the batch before setting the new shader, you can call it in between begin() and end().

Parameters:

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

isBlendingEnabled

public boolean isBlendingEnabled()

Returns:

whether blending for sprites is enabled