com.badlogic.gdx.graphics.g2d
Class PolygonSpriteBatch

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

public class PolygonSpriteBatch
extends Object

A PolygonSpriteBatch is used to draw 2D polygons 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 PolygonSpriteBatch 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 PolygonSpriteBatch 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 PolygonSpriteBatch is managed. In case the OpenGL context is lost all OpenGL resources a PolygonSpriteBatch uses internally get invalidated. A context is lost when a user switches to another application or receives an incoming call on Android. A SpritPolygonSpriteBatcheBatch will be automatically reloaded after the OpenGL context is restored.

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

A PolygonSpriteBatch 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 PolygonSpriteBatch has to be disposed if it is no longer used.

Author:

mzechner, Stefan Bachmann, Nathan Sweet

Field Summary

int	maxTrianglesInBatch The maximum number of triangles rendered in one batch so far.
int	renderCalls Number of render calls since the last begin().
int	totalRenderCalls Number of rendering calls, ever.

Constructor Summary

PolygonSpriteBatch()
Constructs a new PolygonSpriteBatch with a size of 2000, the default shader, and one buffer.

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

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

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

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

Method Summary

void	begin() Sets up the PolygonSpriteBatch for drawing.
void	disableBlending() Disables blending for drawing sprites.
void	dispose() Disposes all resources associated with this PolygonSpriteBatch.
void	draw(PolygonRegion region, float x, float y) Draws a polygon region with the bottom left corner at x,y having the width and height of the region.
void	draw(PolygonRegion region, float x, float y, float width, float height) Draws a polygon region with the bottom left corner at x,y and stretching the region to cover the given width and height.
void	draw(PolygonRegion region, float x, float y, float originX, float originY, float width, float height, float scaleX, float scaleY, float rotation) Draws the polygon region with the bottom left corner at x,y and stretching the region to cover the given width and height.
void	draw(Texture texture, float[] polygonVertices, int verticesOffset, int verticesCount, short[] polygonTriangles, int trianglesOffset, int trianglesCount) Draws the polygon using the given vertices and triangles.
void	enableBlending() Enables blending for sprites.
void	end() Finishes off rendering.
void	flush() Causes any pending sprites to be rendered, without ending the PolygonSpriteBatch.
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 PolygonSpriteBatch.
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 PolygonSpriteBatch.
void	setShader(ShaderProgram shader)
void	setTransformMatrix(Matrix4 transform) Sets the transform matrix to be used by this PolygonSpriteBatch.

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.

maxTrianglesInBatch

public int maxTrianglesInBatch

The maximum number of triangles rendered in one batch so far.

Constructor Detail

PolygonSpriteBatch

public PolygonSpriteBatch()

Constructs a new PolygonSpriteBatch with a size of 2000, the default shader, and one buffer.

See Also:

PolygonSpriteBatch(int, int, ShaderProgram)

PolygonSpriteBatch

public PolygonSpriteBatch(int size)

Constructs a PolygonSpriteBatch with the default shader and one buffer.

See Also:

PolygonSpriteBatch(int, int, ShaderProgram)

PolygonSpriteBatch

public PolygonSpriteBatch(int size,
                          ShaderProgram defaultShader)

Constructs a new PolygonSpriteBatch with one buffer.

See Also:

PolygonSpriteBatch(int, int, ShaderProgram)

PolygonSpriteBatch

public PolygonSpriteBatch(int size,
                          int buffers)

Constructs a PolygonSpriteBatch with the default shader.

See Also:

PolygonSpriteBatch(int, int, ShaderProgram)

PolygonSpriteBatch

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

Constructs a new PolygonSpriteBatch. 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 SpriteBatch.createDefaultShader().

Parameters:

size - The max number of vertices and number of triangles in a single batch. Max of 10920.

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 PolygonSpriteBatch and must be disposed separately.

Method Detail

begin

public void begin()

Sets up the PolygonSpriteBatch 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 PolygonSpriteBatch. 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 PolygonSpriteBatch. Manipulating the returned instance has no effect.

draw

public void draw(PolygonRegion region,
                 float x,
                 float y)

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

draw

public void draw(PolygonRegion region,
                 float x,
                 float y,
                 float width,
                 float height)

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

draw

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

Draws the polygon region with the bottom left corner at x,y and stretching the region to cover the given width and height. The polygon region is offset by originX, originY relative to the origin. Scale specifies the scaling factor by which the polygon region should be scaled around originX, originY. Rotation specifies the angle of counter clockwise rotation of the rectangle around originX, originY.

draw

public void draw(Texture texture,
                 float[] polygonVertices,
                 int verticesOffset,
                 int verticesCount,
                 short[] polygonTriangles,
                 int trianglesOffset,
                 int trianglesCount)

Draws the polygon using the given vertices and triangles. Each vertices must be made up of 5 elements in this order: x, y, color, u, v.

flush

public void flush()

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

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 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, PolygonSpriteBatch won't change the blending function.

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

dispose

public void dispose()

Disposes all resources associated with this PolygonSpriteBatch.

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 PolygonSpriteBatch. 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 PolygonSpriteBatch. If this is called inside a begin()/end() block, the current batch is flushed to the gpu.

setShader

public void setShader(ShaderProgram shader)

See Also:

SpriteBatch.setShader(ShaderProgram)

isBlendingEnabled

public boolean isBlendingEnabled()

Returns:

whether blending for sprites is enabled