Tutorial 2.4: Atlas Texture

We were making a Sprite Entity, but it isn’t finished yet. As we saw in earlier code, the LibGDX sprite needs to be connected with an image, something to draw. We could simply add a few lines to the class that will load an image and apply that to the sprite. But there are two problems with that.

First, a sprite may need multiple images, and animations. So we actually need a collection of some sort. Animations on themselves have properties too, like animation-speed, frameCount, and whether the animation is looped or should trigger another animation when it’s done.

Second, we don’t want to load the same image many times. If we have 10 explosive barrels, they can all share the same image(collection), instead of loading there own stuff individually. In general, try to make your game (classes) in such a way that there will be one resource, that can be used by multiple users (entities). Resources are typically static (just loaded once, never changing from there on), Entities dynamic (they come and go).

Pretty much every visual entity will be linked to an Image (collection). Sounds like we need an Image class then! We’ll be creating a “GxImage.java” file, which is basically a wrapper around the LibGDX “TextureAtlas” (instead of Image) class.

An Atlas image is just a bigger picture with multiple smaller images inside. Like, uhh, an atlas. Remember your teacher pointing at Eskimo county or Pizza land? Let's say you have 10 different "Crate" objects - thus 10 different images. You could create 10 separate image files. Or just put them all together in the same file.

The benefit of that? Computers like bulk stuff. Loading 1 (big) file is more comfortable than loading 10 (small) files. And also rendering may speed up a bit. If you render 10 entities with 10 different images, LibGDX (or actually OpenGL) has to swap the active texture 10 times, which isn’t for free. If you have 10 entities all using the same image (but different sub-sections or "regions" of it), only 1 swap is needed. If you group/sort your entities on Image, that is. It makes a lot sense if you plan to make a tile based map, like this one:

The map here is made of bricks, solid grey concrete blocks, and green shit. Furthermore we see bombs, skulls, roller skates and… a carrot that kicks a grenade or something. 4 different bonus item (tiles). We could make an atlas image for this world type, and another image that contains all the different bonus items. Then we first draw all floor/wall tiles, then all bonus tiles. Only 2 texture swaps needed, regardless how many tiles there are on the screen. Finally, the (animated) character sprites are drawn on top.

LibGDX offers a simple tool called “gdx-texturepacker” (got version 4.8.2 here) to make these Atlas images, as well as a “descriptor” file that you will later on load into your game, that tells how the image has been divided in sub-regions.

In the example above, I made 11 pictures of a (clay orb), to make sort of a "sparkling" animation. The packer tool throws them all together, and generates a single imge file + an atlas descriptor file. This file describes the "regions", where each region is one of the 11 images. A region has (sub-rect) coordinates and an idName that equals the original input filename. Now that we have some stuff for testing purposes, let’s proceed with GxImage.java in the Graphics section:

public class GxImage {
    String          idName;
    String          imageFilePath;
    String          atlasFilePath;
    boolean         loadedInGPU;
    TextureAtlas    texture;

    public GxImage( String idName, String imageFilePath, String atlasFilePath )
    {
        this.idName         = idName;
        this.imageFilePath  = imageFilePath;
        this.atlasFilePath  = atlasFilePath;
        this.loadedInGPU    = false;

        System.out.println( "GxImage created: "+ idName+" path: "+this.imageFilePath );
    } // create


    public String getIdName()
    {
        return this.idName;
    } // getIdName


    public TextureRegion findRegion( String regionName )
    {
        if ( !this.loadedInGPU )
            this.loadToGPU();

        return this.texture.findRegion( regionName );
    } // findRegion


    public void loadToGPU()
    {
        if ( this.loadedInGPU == false ) {
            this.texture    = new TextureAtlas( this.atlasFilePath );
            this.loadedInGPU = true;
        }
    } // loadToGPU


    public void releaseFromGPU()
    {
        if ( this.loadedInGPU ) {
            this.texture.dispose();
            this.texture     = null;
            this.loadedInGPU = false;
        }
    } // releaseFromGPU

} // GxImage

That’s it for now, just a really simple file. Last but not least, we add yet another file called “GxImageLibrary.java”. This is a collection that contains ALL available Images. During bootup, we’ll be adding all our images via this library, and if you need one later on, ask the library to find it (by idName).