Sparrow Framework – The Open Source Game Engine for iOS

Almost any game will have to display some text sooner or later. Sparrow makes it easy to do so:

SPTextField *textField =
    [SPTextField textFieldWithWidth:300 height:100
                 text:@"This is some text."];
textField.fontName = @"Georgia-Bold";
textField.fontSize = 18;
textField.hAlign = SPHAlignCenter; // horizontal alignment
textField.vAlign = SPVAlignCenter; // vertical alignment

There are quite a number of different fonts already available on the iPhone. Click on the following image to get a bigger view of the fonts and their names.

When you create a textfield in the way shown above, Sparrow asks Cocoa to render the text to a bitmap. The bitmap is then used as a texture, just like any other image.

Creating this texture is relatively fast, and once it is created, the textfield will be rendered very quickly — it’s just an image, after all.

However, there are times where this method is not perfect, e.g.:

• when you need different fonts than those installed on the iPhone, or fonts with fancy effects
• when you need to change the text of a textfield very often, and constantly creating new textures turns out to be too slow

That’s what bitmap fonts are for. A bitmap font is very similar to a texture atlas (see last article), only that it contains characters instead of images. Here is how a bitmap font looks like:

In addition to a texture like this, there is also an xml-file that describes which character can be found at which position in the image, and other information.

To create a bitmap font, we recommend one of the following tools:

• Bitmap Font Generator by AngelCode (Windows only)
• Hiero by CokeAndCode
• Update (2011/06): Glyph Designer.

The tool from AngelCode has more options, but is only available in Windows. When you use it, export the font data in XML format, and the texture as a png with white characters on a transparent background (32 bit).

The second tool works in any operating system (it’s a Java application), but does not create the XML format that Sparrow requires. So you need to convert its output before being able to use it in Sparrow. For this reason, we created another small Ruby script (“hiero2sparrow.rb”) that does the conversion for you. Like the texture atlas converter, you have to get it via subversion for now, as it’s not part of the 0.7 release of Sparrow.

Now, let’s say you created your bitmap font — that means you have 2 files: “myfont.fnt” and “myfont.png”. Using this bitmap font is a little complicated. No, just kidding . It could not be easier:

[SPTextField registerBitmapFontFromFile:@"myfont.fnt"];

That’s it! When you register the bitmap font like this, you can use it just like any other font. Just set the “font”-property of a textfield to the name of the font (if you are unsure, find the “face”-attribute in the “.fnt”-file, or examine the NSString-object that is returned by the "registerBitmapFontFromFile:"-method).

For even more speed, you can add the font image to your texture atlas, as well. In that case, you have to register the font the following way:

[SPTextField registerBitmapFontFromFile:@"myfont.fnt"
    texture:[myAtlas textureByName:@"myfont"]];

That should be all you need to know about bitmap fonts!

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!

Hello everyone,

my name is Holger and I am, amongst other things, responsible for the Sparrow website.

In order to have a place where we can have discussions and answer your Sparrow questions, I would like to draw your attention to the new Sparrow Forum, which went online just a few minutes ago. This is going to be the place where all of the supporting and helping happens.

We are looking forward to your posts and comments!

’nuff said, see you there!
Holger