libgdx API

com.badlogic.gdx.graphics.g2d
Class PolygonSpriteBatch

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

public class PolygonSpriteBatch
extends java.lang.Object

A PolyongSpriteBatch 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.

THIS STUFF IS WIP

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

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

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

Author:
mzechner, Stefan Bachmann

Field Summary
 int maxVerticesInBatch
          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
 
Constructor Summary
PolygonSpriteBatch()
          Constructs a new PolygonSpriteBatch.
PolygonSpriteBatch(int size)
          Constructs a PolygonSpriteBatch with the specified size in vertices and (if GL2) the default shader.
PolygonSpriteBatch(int size, int buffers)
          Constructs a PolygonSpriteBatch with the specified size and number of buffers and (if GL2) the default shader.
PolygonSpriteBatch(int size, int buffers, ShaderProgram defaultShader)
           Constructs a new PolygonSpriteBatch.
PolygonSpriteBatch(int size, ShaderProgram defaultShader)
           Constructs a new PolygonSpriteBatch.
 
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(PolygonRegion region, float[] spriteVertices, int offset, int length)
          Draws the polygon region using the given vertices.
 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 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 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


maxVerticesInBatch

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

Constructor Detail

PolygonSpriteBatch

public PolygonSpriteBatch()
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 screen resolution.


PolygonSpriteBatch

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


PolygonSpriteBatch

public PolygonSpriteBatch(int size,
                          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 screen resolution.

The size parameter specifies the maximum size of a single batch in number of vertices(!)

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 the createDefaultShader() method.

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

PolygonSpriteBatch

public PolygonSpriteBatch(int size,
                          int buffers)
Constructs a PolygonSpriteBatch with the specified size and number of buffers and (if GL2) the default shader. See 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 screen resolution.

The size parameter specifies the maximum size of a single batch in number of vertices(!)

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 the createDefaultShader() method.

Parameters:
size - the batch size in number of vertices(!)
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 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(PolygonRegion region,
                 float[] spriteVertices,
                 int offset,
                 int length)
Draws the polygon region using the given vertices. 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. 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


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.

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

libgdx API

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