APIdia Launch Partner
Top Description Fields Methods
com.badlogic.gdx.graphics.g2d

public Interface Batch

extends Disposable
Known Direct Subinterfaces
com.badlogic.gdx.graphics.g2d.PolygonBatch
Known Direct Implementers
com.badlogic.gdx.graphics.g2d.SpriteBatch
Imports
com.badlogic.gdx.graphics.Color, .Texture, com.badlogic.gdx.graphics.glutils.ShaderProgram, com.badlogic.gdx.math.Affine2, .Matrix4, com.badlogic.gdx.utils.Disposable
A Batch 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 Batch one has to first call the Batch#begin() method which will setup appropriate render states. When you are done with drawing you have to call Batch#end() which will actually draw the things you specified.

All drawing commands of the Batch 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 Batch is managed. In case the OpenGL context is lost all OpenGL resources a Batch uses internally get invalidated. A context is lost when a user switches to another application or receives an incoming call on Android. A Batch will be automatically reloaded after the OpenGL context is restored.

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

A Batch works with OpenGL ES 2.0. It will use its own custom shader to draw all provided sprites. You can set your own custom shader via setShader(ShaderProgram).

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

Authors
mzechner, Nathan Sweet

Field Summary

Modifier and TypeField and Description
public static final int
C1

public static final int
C2

public static final int
C3

public static final int
C4

public static final int
U1

public static final int
U2

public static final int
U3

public static final int
U4

public static final int
V1

public static final int
V2

public static final int
V3

public static final int
V4

public static final int
X1

public static final int
X2

public static final int
X3

public static final int
X4

public static final int
Y1

public static final int
Y2

public static final int
Y3

public static final int
Y4

Method Summary

Modifier and TypeMethod and Description
public void
begin()

Sets up the Batch for drawing.

public void
disableBlending()

Disables blending for drawing sprites.

public void
draw(Texture texture, float
the x-coordinate in screen space
x, float
the y-coordinate in screen space
y, float
the x-coordinate of the scaling and rotation origin relative to the screen space coordinates
originX, float
the y-coordinate of the scaling and rotation origin relative to the screen space coordinates
originY, float
the width in pixels
width, float
the height in pixels
height, float
the scale of the rectangle around originX/originY in x
scaleX, float
the scale of the rectangle around originX/originY in y
scaleY, float
the angle of counter clockwise rotation of the rectangle around originX/originY, in degrees
rotation, int
the x-coordinate in texel space
srcX, int
the y-coordinate in texel space
srcY, int
the source with in texels
srcWidth, int
the source height in texels
srcHeight, boolean
whether to flip the sprite horizontally
flipX, boolean
whether to flip the sprite vertically
flipY)

Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels.

public void
draw(Texture texture, float
the x-coordinate in screen space
x, float
the y-coordinate in screen space
y, float
the width in pixels
width, float
the height in pixels
height, int
the x-coordinate in texel space
srcX, int
the y-coordinate in texel space
srcY, int
the source with in texels
srcWidth, int
the source height in texels
srcHeight, boolean
whether to flip the sprite horizontally
flipX, boolean
whether to flip the sprite vertically
flipY)

Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels.

public void
draw(Texture texture, float
the x-coordinate in screen space
x, float
the y-coordinate in screen space
y, int
the x-coordinate in texel space
srcX, int
the y-coordinate in texel space
srcY, int
the source with in texels
srcWidth, int
the source height in texels
srcHeight)

Draws a rectangle with the bottom left corner at x,y having the given width and height in pixels.

public void
draw(Texture texture, float
the x-coordinate in screen space
x, float
the y-coordinate in screen space
y, float
the width in pixels
width, float
the height in pixels
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.

public void
draw(Texture texture, float
the x-coordinate in screen space
x, float
the y-coordinate in screen space
y)

Draws a rectangle with the bottom left corner at x,y having the width and height of the texture.

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.

public void
draw(Texture texture, float[] spriteVertices, int offset, int count)

Draws a rectangle using the given vertices.

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.

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.

public void
draw(TextureRegion region, float x, float y, float originX, float originY, float width, float height, float scaleX, float scaleY, float
rotation in degrees
rotation)

Draws a rectangle with the bottom left corner at x,y and stretching the region to cover the given width and height.

public void
draw(TextureRegion region, float x, float y, float originX, float originY, float width, float height, float scaleX, float scaleY, float
rotation in degrees
rotation, boolean
If true, the texture coordinates are rotated 90 degrees clockwise. If false, they are rotated 90 degrees counter clockwise.
clockwise)

Draws a rectangle with the texture coordinates rotated 90 degrees.

public void
draw(TextureRegion region, float width, float height, Affine2 transform)

Draws a rectangle transformed by the given matrix.

public void
enableBlending()

Enables blending for drawing sprites.

public void
end()

Finishes off rendering.

public void
flush()

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

public int
getBlendDstFunc()

public int
getBlendDstFuncAlpha()

public int
getBlendSrcFunc()

public int
getBlendSrcFuncAlpha()

public Color
getColor()

Returns: the rendering color of this Batch.

public float
getPackedColor()

Returns: the rendering color of this Batch in vertex format (alpha compressed to 0-254)

public Matrix4
getProjectionMatrix()

Returns the current projection matrix.

public ShaderProgram
getShader()

Returns: the current ShaderProgram set by setShader(ShaderProgram) or the defaultShader

public Matrix4
getTransformMatrix()

Returns the current transform matrix.

public boolean
isBlendingEnabled()

Returns: true if blending for sprites is enabled

public boolean
isDrawing()

Returns: true if currently between begin and end.

public void
setBlendFunction(int
the source function, e.g. GL20.GL_SRC_ALPHA. If set to -1, Batch won't change the blending function.
srcFunc, int
the destination function, e.g. GL20.GL_ONE_MINUS_SRC_ALPHA
dstFunc)

Sets the blending function to be used when rendering sprites.

public void
setBlendFunctionSeparate(int
the source color function, e.g. GL20.GL_SRC_ALPHA. If set to -1, Batch won't change the blending function.
srcFuncColor, int
the destination color function, e.g. GL20.GL_ONE_MINUS_SRC_ALPHA.
dstFuncColor, int
the source alpha function, e.g. GL20.GL_SRC_ALPHA.
srcFuncAlpha, int
the destination alpha function, e.g. GL20.GL_ONE_MINUS_SRC_ALPHA.
dstFuncAlpha)

Sets separate (color/alpha) blending function to be used when rendering sprites.

public void
setColor(Color tint)

Sets the color used to tint images when they are added to the Batch.

public void
setColor(float r, float g, float b, float a)

public void
setPackedColor(float packedColor)

Sets the rendering color of this Batch, expanding the alpha from 0-254 to 0-255.

public void
setProjectionMatrix(Matrix4 projection)

Sets the projection matrix to be used by this Batch.

public void
setShader(ShaderProgram
the ShaderProgram or null to use the default shader.
shader)

Sets the shader to be used in a GLES 2.0 environment.

public void
setTransformMatrix(Matrix4 transform)

Sets the transform matrix to be used by this Batch.

Inherited from com.badlogic.gdx.utils.Disposable:
dispose

Field Detail

C1back to summary
public static final int C1
C2back to summary
public static final int C2
C3back to summary
public static final int C3
C4back to summary
public static final int C4
U1back to summary
public static final int U1
U2back to summary
public static final int U2
U3back to summary
public static final int U3
U4back to summary
public static final int U4
V1back to summary
public static final int V1
V2back to summary
public static final int V2
V3back to summary
public static final int V3
V4back to summary
public static final int V4
X1back to summary
public static final int X1
X2back to summary
public static final int X2
X3back to summary
public static final int X3
X4back to summary
public static final int X4
Y1back to summary
public static final int Y1
Y2back to summary
public static final int Y2
Y3back to summary
public static final int Y3
Y4back to summary
public static final int Y4

Method Detail

beginback to summary
public void begin()

Sets up the Batch for drawing. This will disable depth buffer writing. 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).

disableBlendingback to summary
public void disableBlending()

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

drawback to summary
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 flipped horizontally or vertically.

Parameters
x:float

the x-coordinate in screen space

y:float

the y-coordinate in screen space

originX:float

the x-coordinate of the scaling and rotation origin relative to the screen space coordinates

originY:float

the y-coordinate of the scaling and rotation origin relative to the screen space coordinates

width:float

the width in pixels

height:float

the height in pixels

scaleX:float

the scale of the rectangle around originX/originY in x

scaleY:float

the scale of the rectangle around originX/originY in y

rotation:float

the angle of counter clockwise rotation of the rectangle around originX/originY, in degrees

srcX:int

the x-coordinate in texel space

srcY:int

the y-coordinate in texel space

srcWidth:int

the source with in texels

srcHeight:int

the source height in texels

flipX:boolean

whether to flip the sprite horizontally

flipY:boolean

whether to flip the sprite vertically

drawback to summary
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 flipped horizontally or vertically.

Parameters
x:float

the x-coordinate in screen space

y:float

the y-coordinate in screen space

width:float

the width in pixels

height:float

the height in pixels

srcX:int

the x-coordinate in texel space

srcY:int

the y-coordinate in texel space

srcWidth:int

the source with in texels

srcHeight:int

the source height in texels

flipX:boolean

whether to flip the sprite horizontally

flipY:boolean

whether to flip the sprite vertically

drawback to summary
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:float

the x-coordinate in screen space

y:float

the y-coordinate in screen space

srcX:int

the x-coordinate in texel space

srcY:int

the y-coordinate in texel space

srcWidth:int

the source with in texels

srcHeight:int

the source height in texels

drawback to summary
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:float

the x-coordinate in screen space

y:float

the y-coordinate in screen space

width:float

the width in pixels

height:float

the height in pixels

drawback to summary
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:float

the x-coordinate in screen space

y:float

the y-coordinate in screen space

drawback to summary
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.

drawback to summary
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 Batch is not applied.

drawback to summary
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.

drawback to summary
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.

drawback to summary
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.

Parameters
rotation:float

rotation in degrees

drawback to summary
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
rotation:float

rotation in degrees

clockwise:boolean

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

drawback to summary
public void draw(TextureRegion region, float width, float height, Affine2 transform)

Draws a rectangle transformed by the given matrix.

enableBlendingback to summary
public void enableBlending()

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

endback to summary
public void end()

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

flushback to summary
public void flush()

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

getBlendDstFuncback to summary
public int getBlendDstFunc()
getBlendDstFuncAlphaback to summary
public int getBlendDstFuncAlpha()
getBlendSrcFuncback to summary
public int getBlendSrcFunc()
getBlendSrcFuncAlphaback to summary
public int getBlendSrcFuncAlpha()
getColorback to summary
public Color getColor()
Returns:Color

the rendering color of this Batch. If the returned instance is manipulated, setColor(Color) must be called afterward.

getPackedColorback to summary
public float getPackedColor()
Returns:float

the rendering color of this Batch in vertex format (alpha compressed to 0-254)

See Also
Color#toFloatBits()
getProjectionMatrixback to summary
public Matrix4 getProjectionMatrix()

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

getShaderback to summary
public ShaderProgram getShader()
Returns:ShaderProgram

the current ShaderProgram set by setShader(ShaderProgram) or the defaultShader

getTransformMatrixback to summary
public Matrix4 getTransformMatrix()

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

isBlendingEnabledback to summary
public boolean isBlendingEnabled()
Returns:boolean

true if blending for sprites is enabled

isDrawingback to summary
public boolean isDrawing()
Returns:boolean

true if currently between begin and end.

setBlendFunctionback to summary
public void setBlendFunction(int srcFunc, int dstFunc)

Sets the blending function to be used when rendering sprites.

Parameters
srcFunc:int

the source function, e.g. GL20.GL_SRC_ALPHA. If set to -1, Batch won't change the blending function.

dstFunc:int

the destination function, e.g. GL20.GL_ONE_MINUS_SRC_ALPHA

setBlendFunctionSeparateback to summary
public void setBlendFunctionSeparate(int srcFuncColor, int dstFuncColor, int srcFuncAlpha, int dstFuncAlpha)

Sets separate (color/alpha) blending function to be used when rendering sprites.

Parameters
srcFuncColor:int

the source color function, e.g. GL20.GL_SRC_ALPHA. If set to -1, Batch won't change the blending function.

dstFuncColor:int

the destination color function, e.g. GL20.GL_ONE_MINUS_SRC_ALPHA.

srcFuncAlpha:int

the source alpha function, e.g. GL20.GL_SRC_ALPHA.

dstFuncAlpha:int

the destination alpha function, e.g. GL20.GL_ONE_MINUS_SRC_ALPHA.

setColorback to summary
public void setColor(Color tint)

Sets the color used to tint images when they are added to the Batch. Default is Color#WHITE.

setColorback to summary
public void setColor(float r, float g, float b, float a)
See Also
setColor(Color)
setPackedColorback to summary
public void setPackedColor(float packedColor)

Sets the rendering color of this Batch, expanding the alpha from 0-254 to 0-255.

See Also
setColor(Color), Color#toFloatBits()
setProjectionMatrixback to summary
public void setProjectionMatrix(Matrix4 projection)

Sets the projection matrix to be used by this Batch. If this is called inside a begin()/end() block, the current batch is flushed to the gpu.

setShaderback to summary
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" appended 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:ShaderProgram

the ShaderProgram or null to use the default shader.

setTransformMatrixback to summary
public void setTransformMatrix(Matrix4 transform)

Sets the transform matrix to be used by this Batch.