Package arc.graphics.g2d

Class SpriteCache

java.lang.Object
arc.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 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.getProjection().setToOrtho2D(0, 0, Core.graphics.getWidth(), Core.graphics.getHeight());

Note that SpriteCache does not manage blending. You will need to enable blending (Gl.enable(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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    int
    renderCalls
    Number of render calls since the last begin().
    int
    totalRenderCalls
    Number of rendering calls, ever.

  • Constructor Summary

    Constructors
    Constructor
    Description
    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.
    SpriteCache(int size, int cacheSize, boolean useIndices)
     
    SpriteCache(int size, int cacheSize, Shader shader, boolean useIndices)
    Creates a cache with the specified size and OpenGL ES 2.0 shader.

  • Method Summary

    Modifier and Type
    Method
    Description
    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
    add(Texture texture, float[] vertices, int offset, int length)
    Adds the specified vertices 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.
    static Shader
    createDefaultShader()
     
    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.
    int
    endCache()
    Ends the definition of a cache, returning the cache ID to be used with draw(int).
    Seq<arc.graphics.g2d.SpriteCache.Cache>
    getCaches()
     
    Color
    getColor()
     
    float
    getPackedColor()
     
    Mat
    getProjectionMatrix()
     
    Mat
    getTransformMatrix()
     
    boolean
    isDrawing()
     
    int
    reserve(int sprites)
    Ensures that this cache can hold this amount of sprites.
    void
    setColor(float r, float g, float b, float a)
     
    void
    setColor(Color tint)
    Sets the color used to tint images when they are added to the SpriteCache.
    void
    setPackedColor(float packedColor)
    Sets the color of this sprite cache, expanding the alpha from 0-254 to 0-255.
    void
    setProjectionMatrix(Mat projection)
     
    void
    setShader(Shader shader)
    Sets the shader to be used in a GLES 2.0 environment.
    void
    setTransformMatrix(Mat transform)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface arc.util.Disposable

    isDisposed

  • Field Details

    • 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 Details

    • 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.
      Parameters:
      size - 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 - If true, indexed geometry will be used.

    • SpriteCache

      public SpriteCache(int size, int cacheSize, boolean useIndices)

    • SpriteCache

      public SpriteCache(int size, int cacheSize, Shader 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 8191 if indices are used.
      useIndices - If true, indexed geometry will be used.

  • Method Details

    • createDefaultShader

      public static Shader createDefaultShader()

    • getCaches

      public Seq<arc.graphics.g2d.SpriteCache.Cache> getCaches()

    • setColor

      public void setColor(float r, float g, float b, float a)
      See Also:

    • getColor

      public Color getColor()

    • setColor

      public void setColor(Color tint)
      Sets the color used to tint images when they are added to the SpriteCache. Default is Color.white.

    • getPackedColor

      public float getPackedColor()

    • setPackedColor

      public void setPackedColor(float packedColor)
      Sets the color of this sprite cache, expanding the alpha from 0-254 to 0-255.
      See Also:

    • 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. 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.

    • reserve

      public int reserve(int sprites)
      Ensures that this cache can hold this amount of sprites. Only call at the end of cache.
      Returns:
      number of new sprites actually reserved.

    • 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(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.

    • begin

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

    • end

      public void end()
      Completes rendering for this SpriteCache.

    • 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 Mat getProjectionMatrix()

    • setProjectionMatrix

      public void setProjectionMatrix(Mat projection)

    • getTransformMatrix

      public Mat getTransformMatrix()

    • setTransformMatrix

      public void setTransformMatrix(Mat transform)

    • setShader

      public void setShader(Shader 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 Shader or null to use the default shader.

    • isDrawing

      public boolean isDrawing()