Tutorial: How to use the LibGDX TexturePacker

packed texture result

This post is dedicated to the LibGDX TexturePacker in order to learn how to pack images together into a single texture.

In this tutorial, we will use it to combine 17 images into the texture you see above. Let’s get started! You can download the images for this tutorial here: TexturePackerTutorialImages

 

Their is going to be 4 parts to this tutorial. Here is a video of it of the end result. If the video is fuzzy, just increase the resolution.

 

Downloading the LibGDX TexturePacker

Now we need to download the libgdx-texturepacker-gui at:

https://code.google.com/p/libgdx-texturepacker-gui/downloads/detail?name=gdx-texturepacker-3.2.0.zip

website for the libgdx texturepacker.

This is the website where you can find the libgdx texturepacker.

 

Download the file: gdx-texturepacker-3.2.0.zip. This is what the file should look like if you use Google Chrome:

libgdx texturepacker file

This is the file that you should see downloading.

 

In your library explorer, unzip it. In the same folder, create a new folder called, Packed Images. Inside that folder, create two more folders called: input and output.

Directory setup for the libgdx texturepacker

A folder that contains two sub-folders, input and output.

The input folder is where our unpacked images will be placed. The output folder is where the result will be.

Getting the Textures:

If you have not already, you can download the textures for this tutorial here: TexturePackerTutorialImages

As with any file(s) you download from the internet, make sure to scan them first. Then, extract the files and place them in the folder named input. Interesting fact: these images are actual placeholder artwork that I am using for my game. Feel free to use them in your own games. I am releasing these images under the GPL for any and all to share.

Image files to be texture packed

Place all the images in your input folder.

If you are curious, the images with words are actually a custom font that I made. If you would like to learn more about making custom fonts, feel free to read my tutorial about LibGDX Custom Fonts.

 

 

Exploring the LibGDX TexturePacker

 No more stalling. Open up the texturepacker-gui.jar file and this is what you will see.

texturepacker graphical user interface

Tada! The graphical user interface (GUI).

Whenever we want to pack more images together, we press the New Pack button. Go ahead, let’s call it texturetutorialpack. Press OK.

Now for the fun part: What exactly are we looking at? Luckily, I have done some work ahead of time so you do not have too. Here is the rundown of the following image.

libgdx texturepacker tutorial on the interface

Each letter in in the image corresponds to the lettered sub-heading below.

A.    Input directory: The input directory should be set to the input folder where our images are stored. The program will pack any images included in this directory.

B.    Output directory: This is where our packed texture will be saved. We will choose the output folder as the output directory.

Note: We do not add a file name because we want a .pack file to be generated. I will explain what a .pack file is at the end.

C.    Pack Selected Button: This packs our images together. You can press it as many times as you desire. It will not stack new files in your output directory. Rather, it will just overwrite the existing one.

 D.   Encoding Format: The encoding format determines the color profile of our texture. There are seven options: RGBA8888, RGBA4444, RGB 565, RGB 888, Alpha, Luminosity, and Intensity. We will use RGBA8888 since our images have transparencies and because we do not want to see color banding. Feel free to change it up. Experimenting is really cool too!

E.   Output Format: Do we want jpeg, or png? I always choose png. If you would like to pack your images into a jpeg, the encoding format cannot be RGBA.

F.   Min & Mag Filter: What do these mean? A Min Filter is a OpenGL variable used to render objects farther away by scaling textures down in order to fit them into a small polygon. A Mag filter does the opposite. It scales a texture up to fit on larger, and closer, polygons.

Source: http://gregs-blog.com/2008/01/17/opengl-texture-filter-parameters-explained/

G.   Min Page Width & Height: Since we have a collection of images to pack, our texture needs to have some bounds defined. The texture’s dimensions will not be smaller than these. I like the default setting, 16. Note: It is also a good idea to set these dimensions to a power-of-two.

H.   Padding X & Y: These values add boarders around the images. I usually leave them at 2.

I.    Max Page Width & Height: Same a letter G, except we define the max size of the packed texture.

J.   Wrap X & Y: I like to leave these values at ClampToEdge.

K.   Use fast algorithm: I left this unchecked. If checked, it packs images using a different algorithm. Either way, it is not going to matter because in the next tutorial, the code generation algorithm we will create will take care of it for us.

L.   Duplicate padding: I keep this checked, since unchecking this seems to smears the edge pixels.

M.   Edge padding: I also keep this checked. It creates a border around the packed texture.

N.   Strip whitespace X & Y: This will remove whitespace within our images.

O.   Allow rotations: Yet another option for texture placement. It will allow the program to rotate the images during packing. It is best to keep this unchecked unless you plan on rotating these images in your game.

P.   Jpeg quality & Alpha threshold: I like to keep these as their default values, 0.9 and 0 respectively. Jpeg quality allows us to set the compression rate for jpeg images. Alpha values that are greater than the alpha threshold will be converted into solid pixels.

Q.   Force PoT (Power of Two): Power of two images perform better, in my opinion. Though, with current technologies, we can use non-PoT images just fine. I like this option checked.

R.   Ignore blank images & Debug: It would be wasteful to pack an image of nothing into our texture. Let’s keep this checked.

S.   Save project: Self-explanatory, I hope.

T.   Open Project: Self-explanatory as well.

Finishing it up:

Press the Pack Selected Button when you’re your finishing with the settings. Wait for it to finish, and navigate to the output folder. This should take less than 5 seconds. Do not worry if your image does not match the one in this post. It will not matter in the next tutorial.

Congratulation, you have just packed a texture. Two file were created: An image and a .pack file. The image is the packed texture. The .pack file is a text document that holds data which is used to draw the individual images contained in the texture.

In the Next Tutorial:

In the next part, I will show you how to extract the data located in the .pack file using the Android Studio debugger. Then we will use it to generate variables, function, and strings needed to access the texture data from anywhere in you game without the need to use a LibGDX Sprite.

Read this offline! Download a copy here: HowToUseTheLibgdxTexturePacker

EDIT: 11/12/2014, added a video showing why this tutorial is useful.

 

Comments

Tutorial: How to use the LibGDX TexturePacker — 2 Comments

  1. Pingback: Tutorial 2: TextureRegion Generator in Android Studio - Programming Money

  2. Pingback: Tutorial 2: TextureRegion Code Generator - Programming Money