com.badlogic.gdx.graphics.g2d
Class SpriteCache

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

All Implemented Interfaces:

Disposable

public class SpriteCache
extends Object
implements Disposable

Draws 2D images, optimized for geometry that does not change. Sprites and/or textures are cached and given an ID, which can later be used for drawing. The size, color, and texture region for each cached image cannot be modified. This information is stored in video memory and does not have to be sent to the GPU each time it is drawn.

To cache sprites or textures, first call beginCache(), then call the appropriate add method to define the images. To complete the cache, call endCache() and store the returned cache ID.

To draw with SpriteCache, first call begin(), then call draw(int) with a cache ID. When SpriteCache drawing is complete, call end().

By default, SpriteCache draws using screen coordinates and uses an x-axis pointing to the right, an y-axis pointing upwards and the origin is the bottom left corner of the screen. The default transformation and projection matrices can be changed. If the screen is resized, the SpriteCache's matrices must be updated. For example:
cache.getProjectionMatrix().setToOrtho2D(0, 0, Gdx.graphics.getWidth(), Gdx.graphics.getHeight());

Note that SpriteCache does not manage blending. You will need to enable blending (Gdx.gl.glEnable(GL10.GL_BLEND);) and set the blend func as needed before or between calls to draw(int).

SpriteCache is managed. If the OpenGL context is lost and the restored, all OpenGL resources a SpriteCache uses internally are restored.

SpriteCache is a reasonably heavyweight object. Typically only one instance should be used for an entire application.

SpriteCache works with OpenGL ES 1.x and 2.0. For 2.0, it uses its own custom shader to draw.

SpriteCache must be disposed once it is no longer needed.

Author:

Nathan Sweet

Field Summary

int	renderCalls Number of render calls since the last begin().
int	totalRenderCalls Number of rendering calls, ever.

Constructor Summary

SpriteCache()
Creates a cache that uses indexed geometry and can contain up to 1000 images.

SpriteCache(int size, boolean useIndices)
Creates a cache with the specified size, using a default shader if OpenGL ES 2.0 is being used.

SpriteCache(int size, ShaderProgram shader, boolean useIndices)
Creates a cache with the specified size and OpenGL ES 2.0 shader.

Method Summary

void	add(Sprite sprite) Adds the specified sprite to the cache.
void	add(Texture texture, float[] vertices, int offset, int length) Adds the specified vertices to the cache.
void	add(Texture texture, float x, float y) Adds the specified texture to the cache.
void	add(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) Adds the specified texture to the cache.
void	add(Texture texture, float x, float y, float width, float height, int srcX, int srcY, int srcWidth, int srcHeight, boolean flipX, boolean flipY) Adds the specified texture to the cache.
void	add(Texture texture, float x, float y, int srcWidth, int srcHeight, float u, float v, float u2, float v2, float color) Adds the specified texture to the cache.
void	add(Texture texture, float x, float y, int srcX, int srcY, int srcWidth, int srcHeight) Adds the specified texture to the cache.
void	add(TextureRegion region, float x, float y) Adds the specified region to the cache.
void	add(TextureRegion region, float x, float y, float width, float height) Adds the specified region to the cache.
void	add(TextureRegion region, float x, float y, float originX, float originY, float width, float height, float scaleX, float scaleY, float rotation) Adds the specified region to the cache.
void	begin() Prepares the OpenGL state for SpriteCache rendering.
void	beginCache() Starts the definition of a new cache, allowing the add and endCache() methods to be called.
void	beginCache(int cacheID) Starts the redefinition of an existing cache, allowing the add and endCache() methods to be called.
void	clear() Invalidates all cache IDs and resets the SpriteCache so new caches can be added.
void	dispose() Releases all resources held by this SpriteCache.
void	draw(int cacheID) Draws all the images defined for the specified cache ID.
void	draw(int cacheID, int offset, int length) Draws a subset of images defined for the specified cache ID.
void	end() Completes rendering for this SpriteCache.f
int	endCache() Ends the definition of a cache, returning the cache ID to be used with draw(int).
Color	getColor()
Matrix4	getProjectionMatrix()
Matrix4	getTransformMatrix()
void	setColor(Color tint) Sets the color used to tint images when they are added to the SpriteCache.
void	setColor(float color)
void	setColor(float r, float g, float b, float a)
void	setProjectionMatrix(Matrix4 projection)
void	setShader(ShaderProgram shader) Sets the shader to be used in a GLES 2.0 environment.
void	setTransformMatrix(Matrix4 transform)

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.

Constructor Detail

SpriteCache

public SpriteCache()

Creates a cache that uses indexed geometry and can contain up to 1000 images.

SpriteCache

public SpriteCache(int size,
                   boolean useIndices)

Creates a cache with the specified size, using a default shader if OpenGL ES 2.0 is being used.

Parameters:

size - The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 5460 if indices are used.

useIndices - If true, indexed geometry will be used.

SpriteCache

public SpriteCache(int size,
                   ShaderProgram shader,
                   boolean useIndices)

Creates a cache with the specified size and OpenGL ES 2.0 shader.

Parameters:

size - The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 5460 if indices are used.

useIndices - If true, indexed geometry will be used.

Method Detail

setColor

public void setColor(Color tint)

Sets the color used to tint images when they are added to the SpriteCache. 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()

beginCache

public void beginCache()

Starts the definition of a new cache, allowing the add and endCache() methods to be called.

beginCache

public void beginCache(int cacheID)

Starts the redefinition of an existing cache, allowing the add and endCache() methods to be called. If this is not the last cache created, it cannot have more entries added to it than when it was first created. To do that, use clear() and then begin().

endCache

public int endCache()

Ends the definition of a cache, returning the cache ID to be used with draw(int).

clear

public void clear()

Invalidates all cache IDs and resets the SpriteCache so new caches can be added.

add

public void add(Texture texture,
                float[] vertices,
                int offset,
                int length)

Adds the specified vertices to the cache. Each vertex should have 5 elements, one for each of the attributes: x, y, color, u, and v. If indexed geometry is used, each image should be specified as 4 vertices, otherwise each image should be specified as 6 vertices.

add

public void add(Texture texture,
                float x,
                float y)

Adds the specified texture to the cache.

add

public void add(Texture texture,
                float x,
                float y,
                int srcWidth,
                int srcHeight,
                float u,
                float v,
                float u2,
                float v2,
                float color)

Adds the specified texture to the cache.

add

public void add(Texture texture,
                float x,
                float y,
                int srcX,
                int srcY,
                int srcWidth,
                int srcHeight)

Adds the specified texture to the cache.

add

public void add(Texture texture,
                float x,
                float y,
                float width,
                float height,
                int srcX,
                int srcY,
                int srcWidth,
                int srcHeight,
                boolean flipX,
                boolean flipY)

Adds the specified texture to the cache.

add

public void add(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)

Adds the specified texture to the cache.

add

public void add(TextureRegion region,
                float x,
                float y)

Adds the specified region to the cache.

add

public void add(TextureRegion region,
                float x,
                float y,
                float width,
                float height)

Adds the specified region to the cache.

add

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

Adds the specified region to the cache.

add

public void add(Sprite sprite)

Adds the specified sprite to the cache.

begin

public void begin()

Prepares the OpenGL state for SpriteCache rendering.

end

public void end()

Completes rendering for this SpriteCache.f

draw

public void draw(int cacheID)

Draws all the images defined for the specified cache ID.

draw

public void draw(int cacheID,
                 int offset,
                 int length)

Draws a subset of images defined for the specified cache ID.

Parameters:

offset - The first image to render.

length - The number of images from the first image (inclusive) to render.

dispose

public void dispose()

Releases all resources held by this SpriteCache.

Specified by:

dispose in interface Disposable

getProjectionMatrix

public Matrix4 getProjectionMatrix()

setProjectionMatrix

public void setProjectionMatrix(Matrix4 projection)

getTransformMatrix

public Matrix4 getTransformMatrix()

setTransformMatrix

public void setTransformMatrix(Matrix4 transform)

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_texCoords", the color attribute is called "a_color". 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.