Using a texture atlas

Daniel Sperl on February 12, 2010

When using OpenGL on the iPhone (you do when you use Sparrow), you can speed up rendering quite a bit when you group your textures in one big texture atlas. The reasons:

• In OpenGL, there’s always one texture active at a given moment. Whenever you change the active texture, a “texture-switch” has to be executed, and that switch takes time.
• To use a texture in OpenGL, its height and width must each be a power of 2. Sparrow hides this limitation from you, but you will nevertheless use more memory if you do not follow that rule.

By using a texture atlas, you avoid both texture switches and the power-of-two limitation. All textures are within one big “super-texture”, and Sparrow takes care that the correct part of this texture is displayed. In Sparrow, a texture atlas is very easy to use, so you should definitely take advantage of that.

As an example, here is how a part of PenguFlip’s texture atlas looks like:

The positions of each sub-texture are defined in an XML file like this one:

<TextureAtlas imagePath="atlas.png">
 <SubTexture name="moon" x="0" y="0" width="30" height="30"/>
 <SubTexture name="jupiter" x="30" y="0" width="65" height="78"/>
 ...
</TextureAtlas>

You can create a texture atlas manually, or you let a tool to create it for you. Sparrow will get its own atlas generator in a future version, but until then, we recommend a tool called “Packer” which can be accessed here: slick.cokeandcode.com

[Update: Sparrow now has its own atlas generator! This blog post shows how to use it, and how it makes it easy to create HD games with Sparrow.]

Just upload your images, and “Packer” will create a texture atlas for you (consisting of an XML and a PNG file). The file format of “Packer”, however, is a little different from the format Sparrow expects. Thus, we have provided a small utility script that converts it to Sparrow’s native format. That tool is not part of the current Sparrow version (0.7); for now, access it by getting the latest development version of Sparrow via Subversion (the download page shows you how to do that). The tool is in the “sparrow/util/packer2sparrow” directory.

The converter is written in Ruby, and is executed via the terminal. Recent versions of OS X have Ruby already installed, so it should work out-of-the-box. (The README file shows you how to use it.)

So, now you have a texture atlas. But how do you use it?

// load the atlas
SPTextureAtlas *atlas = [SPTextureAtlas 
    atlasWithContentsOfFile:@"atlas.xml"];

// display a sub-texture
SPTexture *jupiterTexture = [atlas textureByName:@"jupiter"];
SPImage *jupiterImage = [SPImage imageWithTexture:jupiterTexture];

Create the atlas only once when the game is initialized, and reference it throughout your game. That’s all there is to it!