Posted: 10 May 2012
TexturePacker is a slick GUI for building an optimized texture atlas for texture-heavy applications. This tutorial walks through the most basic aspects of using it with libGDX.
This tutorial is based on the Pro version of TexturePacker 2.4.2. And I'm using the 0.9.3 version of libGDX. I'm running on Windows, but that shouldn't matter.
I assume you've got your libGDX application set up already (especially the part about configuring the asset folder). Ideally, you should have an application that already works with individual texture files, and you just want to switch to a texture atlas.
Generate the Atlas
- Start TexturePacker. By default a new, empty project is started. Note that you can have multiple atlases open for editing (each time you click 'New' a new TexturePacker window is opened.)
- Click 'Add Sprites' on the toolbar or in the
Editmenu. Add a couple sprites to this Atlas, you can add more later.
- Click 'Save As...' in the
Filemenu to save your state and give the output files some default names. I use "packed.tps" as the save-file name in this example.
- In the
Texture Settingsalong the left side, make sure the
Outputsection is open. Under
Outputchange the "Data Format" to "LibGDX". TexturePacker will generate two files for a libGDX atlas: a
.txtfile that describes the atlas (in a format that libGDX expects), and an image file (
.pngby default) that is the atlas.
- The libGDX TextureAtlas expects these two files to be in the same directory (and the name of the image file is embedded in the
- Change the "Data file" and "Texture file" entries in
Texture Settingsto save directly to your libGDX project's Android "asset" folder. The basename of the files should be fine at this point, but feel free to change them as you see fit. (Or, manually copy the files after publishing them.)
- If you are targeting OpenGL ES 1.x make sure "Allow free sizes" is unchecked in the
Geometrysection of the settings. This will ensure the atlas image dimensions are a power of two.
- The other settings in TexturePacker should be fine at their defaults.
- Click "Publish" on the toolbar to create the
.txtand image file in your asset directory. (Note that "Save" does not generate the atlas, it just saves the configuration.)
- Now is a good time to
Saveyour state. You can exit TexturePacker now, and concentrate on the libGDX side.
Use the Atlas
- Let Eclipse know you made changes behind its back by refreshing the assets directory (right-click on the "assets" directory and select
Refresh). You should see your
.png(or whatever) images files here.
- Inside your libGDX application, the atlas published to your Android application's assets directory should now be accessible as a libGDX "internal" file.
- You can open the atlas by referencing the
.txtfile that TexturePacker generated, as in:
TextureAtlas myTextures = new TextureAtlas("packed.txt");
- Texture regions can be pulled out of the atlas by looking them up with
findRegion(names are based on the original file names, without an extension). So, for an original image named "foo.png", something like
myTextures.findRegion("foo")will fetch the
TextureAtlas.AtlasRegionrepresenting that original image. See TextureAtlas for additional APIs for looking up elements.
- When rendering, either use the
SpriteBatch, or bind the atlas texture, and set your mesh's (u, v) texture attributes to those provided by the TextureRegion.
That should cover the basics for hooking up your libGDX application with a texture atlas generated from TexturePacker.