libGDX 1.14.2 · com.badlogic.gdx.graphics.g2d.SpriteCache

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 SpriteCache#beginCache(), then call the appropriate add method to define the images. To complete the cache, call SpriteCache#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.

Modifier and Type	Class and Description
private static class	SpriteCache.Cache

Field Summary

Modifier and Type	Field and Description
private Array<SpriteCache.Cache>	caches
private final Color	color
private float	colorPacked
private final Matrix4	combinedMatrix
private final IntArray	counts
private SpriteCache.Cache	currentCache
private ShaderProgram	customShader
private boolean	drawing
private final Mesh	mesh
private final Matrix4	projectionMatrix
public int	renderCalls Number of render calls since the last `begin()`.
private final ShaderProgram	shader
private static final float[]	tempVertices
private final Array<Texture>	textures
public int	totalRenderCalls Number of rendering calls, ever.
private final Matrix4	transformMatrix

Constructor Summary

Access	Constructor and Description
public	SpriteCache() Creates a cache that uses indexed geometry and can contain up to 1000 images.
public	SpriteCache(int The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 8191 if indices are used. size, boolean If true, indexed geometry will be used. useIndices) Creates a cache with the specified size, using a default shader if OpenGL ES 2.0 is being used.
public	SpriteCache(int The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 8191 if indices are used. size, ShaderProgram shader, boolean If true, indexed geometry will be used. useIndices) Creates a cache with the specified size and OpenGL ES 2.0 shader.

Method Summary

Modifier and Type	Method and Description
public void	add(Texture texture, float[] vertices, int offset, int length) Adds the specified vertices to the cache.
public void	add(Texture texture, float x, float y) Adds the specified texture to the cache.
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.
public void	add(Texture texture, float x, float y, int srcX, int srcY, int srcWidth, int srcHeight) Adds the specified texture to the cache.
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.
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.
public void	add(TextureRegion region, float x, float y) Adds the specified region to the cache.
public void	add(TextureRegion region, float x, float y, float width, float height) Adds the specified region to the cache.
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.
public void	add(Sprite sprite) Adds the specified sprite to the cache.
public void	begin() Prepares the OpenGL state for SpriteCache rendering.
public void	beginCache() Starts the definition of a new cache, allowing the add and `endCache()` methods to be called.
public void	beginCache(int cacheID) Starts the redefinition of an existing cache, allowing the add and `endCache()` methods to be called.
public void	clear() Invalidates all cache IDs and resets the SpriteCache so new caches can be added.
pack-priv static ShaderProgram	createDefaultShader()
public void	dispose() Implements com.badlogic.gdx.utils.Disposable.dispose. Releases all resources held by this SpriteCache.
public void	draw(int cacheID) Draws all the images defined for the specified cache ID.
public void	draw(int cacheID, int The first image to render. offset, int The number of images from the first image (inclusive) to render. length) Draws a subset of images defined for the specified cache ID.
public void	end() Completes rendering for this SpriteCache.
public int	endCache() Ends the definition of a cache, returning the cache ID to be used with `draw(int)`.
public Color	getColor()
public ShaderProgram	getCustomShader() Returns the custom shader, or null if the default shader is being used.
public float	getPackedColor()
public Matrix4	getProjectionMatrix()
public Matrix4	getTransformMatrix()
public boolean	isDrawing()
public void	setColor(Color tint) Sets the color used to tint images when they are added to the SpriteCache.
public void	setColor(float r, float g, float b, float a)
public void	setPackedColor(float packedColor) Sets the color of this sprite cache, expanding the alpha from 0-254 to 0-255.
public void	setProjectionMatrix(Matrix4 projection)
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)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

caches	back to summary
private Array<SpriteCache.Cache> caches

color	back to summary
private final Color color

colorPacked	back to summary
private float colorPacked

combinedMatrix	back to summary
private final Matrix4 combinedMatrix

counts	back to summary
private final IntArray counts

currentCache	back to summary
private SpriteCache.Cache currentCache

customShader	back to summary
private ShaderProgram customShader

drawing	back to summary
private boolean drawing

mesh	back to summary
private final Mesh mesh

projectionMatrix	back to summary
private final Matrix4 projectionMatrix

renderCalls	back to summary
public int renderCalls Number of render calls since the last `begin()`.

shader	back to summary
private final ShaderProgram shader

tempVertices	back to summary
private static final float[] tempVertices

textures	back to summary
private final Array<Texture> textures

totalRenderCalls	back to summary
public int totalRenderCalls Number of rendering calls, ever. Will not be reset unless set manually.

transformMatrix	back to summary
private final Matrix4 transformMatrix

Constructor Detail

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

SpriteCache	back to summary
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:int The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 8191 if indices are used. useIndices:boolean If true, indexed geometry will be used.

SpriteCache

back to summary

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:int: The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 8191 if indices are used.
useIndices:boolean: If true, indexed geometry will be used.

SpriteCache	back to summary
public SpriteCache(int size, ShaderProgram shader, boolean useIndices) Creates a cache with the specified size and OpenGL ES 2.0 shader. Parameters size:int The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 8191 if indices are used. useIndices:boolean If true, indexed geometry will be used.

SpriteCache

back to summary

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

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

Parameters

size:int: The maximum number of images this cache can hold. The memory required to hold the images is allocated up front. Max of 8191 if indices are used.
useIndices:boolean: If true, indexed geometry will be used.

Method Detail

add	back to summary
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	back to summary
public void add(Texture texture, float x, float y) Adds the specified texture to the cache.

add	back to summary
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	back to summary
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	back to summary
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	back to summary
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	back to summary
public void add(TextureRegion region, float x, float y) Adds the specified region to the cache.

add	back to summary
public void add(TextureRegion region, float x, float y, float width, float height) Adds the specified region to the cache.

add	back to summary
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	back to summary
public void add(Sprite sprite) Adds the specified sprite to the cache.

begin	back to summary
public void begin() Prepares the OpenGL state for SpriteCache rendering.

beginCache	back to summary
public void beginCache() Starts the definition of a new cache, allowing the add and `endCache()` methods to be called.

beginCache	back to summary
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()`.

clear	back to summary
public void clear() Invalidates all cache IDs and resets the SpriteCache so new caches can be added.

createDefaultShader	back to summary
pack-priv static ShaderProgram createDefaultShader()

dispose	back to summary
public void dispose() Implements com.badlogic.gdx.utils.Disposable.dispose. Releases all resources held by this SpriteCache.

dispose

back to summary

public void dispose()

Implements com.badlogic.gdx.utils.Disposable.dispose.

Releases all resources held by this SpriteCache.

draw	back to summary
public void draw(int cacheID) Draws all the images defined for the specified cache ID.

draw	back to summary
public void draw(int cacheID, int offset, int length) Draws a subset of images defined for the specified cache ID. Parameters offset:int The first image to render. length:int The number of images from the first image (inclusive) to render.

draw

back to summary

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

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

Parameters

offset:int: The first image to render.
length:int: The number of images from the first image (inclusive) to render.

end	back to summary
public void end() Completes rendering for this SpriteCache.

endCache	back to summary
public int endCache() Ends the definition of a cache, returning the cache ID to be used with `draw(int)`.

getColor	back to summary
public Color getColor()

getCustomShader	back to summary
public ShaderProgram getCustomShader() Returns the custom shader, or null if the default shader is being used.

getPackedColor	back to summary
public float getPackedColor()

getProjectionMatrix	back to summary
public Matrix4 getProjectionMatrix()

getTransformMatrix	back to summary
public Matrix4 getTransformMatrix()

isDrawing	back to summary
public boolean isDrawing()

setColor	back to summary
public void setColor(Color tint) Sets the color used to tint images when they are added to the SpriteCache. Default is `Color#WHITE`.

setColor	back to summary
public void setColor(float r, float g, float b, float a) See Also `setColor(Color)`

setPackedColor back to summary

public void setPackedColor(float packedColor)

Sets the color of this sprite cache, expanding the alpha from 0-254 to 0-255.

See Also: Color#toFloatBits()

setProjectionMatrix	back to summary
public void setProjectionMatrix(Matrix4 projection)

setShader back 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 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:ShaderProgram: the ShaderProgram or null to use the default shader.

setTransformMatrix	back to summary
public void setTransformMatrix(Matrix4 transform)

Modifier and Type	Field and Description
pack-priv int[]	counts
pack-priv final int	id
pack-priv int	maxCount
pack-priv final int	offset
pack-priv int	textureCount
pack-priv Texture[]	textures

public Class SpriteCache

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class SpriteCache.Cache

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail