PC Games

Orb
Lasagne Monsters
Three Guys Apocalypse
Water Closet
Blob Wars : Attrition
The Legend of Edgar
TBFTSS: The Pandoran War
Three Guys
Blob Wars : Blob and Conquer
Blob Wars : Metal Blob Solid
Project: Starfighter
TANX Squadron

Android Games

DDDDD
Number Blocks
Match 3 Warriors

Tutorials

2D shoot 'em up
2D top-down shooter
2D platform game
Sprite atlas tutorial
Working with TTF fonts
2D adventure game
Widget tutorial
2D shoot 'em up sequel
SDL 1 tutorials (outdated)

Latest Updates

SDL2 Shooter 2 tutorial
Tue, 13th July 2021

SDL2 Widget tutorial
Fri, 18th June 2021

SDL2 Adventure tutorial
Tue, 8th June 2021

New tutorials
Tue, 11th May 2021

Orb source code
Sun, 25th April 2021

All Updates »

Tags

android (3)
battle-for-the-solar-system (9)
blob-wars (9)
brexit (1)
code (6)
edgar (6)
games (37)
lasagne-monsters (1)
making-of (5)
match3 (1)
numberblocksonline (1)
orb (2)
site (1)
tanx (4)
three-guys (3)
three-guys-apocalypse (3)
tutorials (6)
water-closet (3)

Books


Project Starfighter

In his fight back against the ruthless Wade-Ellen Asset Protection Corporation, pilot Chris Bainfield finds himself teaming up with the most unlikely of allies - a sentient starfighter known as Athena.

Click here to learn more and read an extract!

« Back to tutorial listing

— Sprite Atlas Tutorial —
Part 3: Creating the atlas meta data

Note: this tutorial assumes knowledge of C, as well as prior tutorials.

Introduction

In the previous two tutorials, we gathered the details of the images we wanted to add to our atlas, and ran through the process of actually creating it. The final step is to output the meta data, so the atlas can be used by games and applications that require it. We'll be outputting the details of the added images as a JSON array, since the format is easy to read and understand, and is well supported. Using some C code written by Dave Gamble, we can easily marshall our data into JSON (and read it back later). Compile the code using make, and then run it with ./gen03. You'll now see both the atlas.png and an atlas.json file. Open up the JSON file and take a look at the contents. You'll find it matches what was added to the atlas.

Inspecting the code

Outputting the meta data of the atlas is very easy, thanks for Dave's code. After adding the cJSON.h header to our own atlasGen.h, we can call the CJSON functions. All this is done in main. The first thing we want to do is create a JSON array:


rootJSON = cJSON_CreateArray();

Simple enough. Now we need to add the details of the images themselves. Within the main for-loop, after we've added the image to the atlas, we want to create a JSON object, and add the details of the image to it.


entryJSON = cJSON_CreateObject();

cJSON_AddStringToObject(entryJSON, "filename", images[i].filename);
cJSON_AddNumberToObject(entryJSON, "x", dest.x);
cJSON_AddNumberToObject(entryJSON, "y", dest.y);
cJSON_AddNumberToObject(entryJSON, "w", dest.w);
cJSON_AddNumberToObject(entryJSON, "h", dest.h);
cJSON_AddNumberToObject(entryJSON, "rotated", rotated);

The first thing we do is create the JSON object by calling cJSON_CreateObject. With that done, we want to add the image's filename, by calling cJSON_AddStringToObject. The key of the string is "filename", with the value being the image filename itself. Next, we want to add the coordinates where the image resides on the atlas (its x, y, w, and h values). We can do this by calling cJSON_AddNumberToObject, and specifying the appropriate key and value. We also want to add the rotated value (which will either be a 0 or 1) to the object.

The above will create a JSON object that will resemble the following:

{
	"filename": "gfx/tall/long.png",
	"x": 0,
	"y": 0,
	"w": 34,
	"h": 128,
	"rotated": 0
}

As you can see, working with cJSON makes things very easy. With all the image data added to the object, we need only add it to the main JSON array. This is a single function call using cJSON_AddItemToArray, passing in the rootJSON variable as the array we wish to use and the entryJSON as the object we want to add:


cJSON_AddItemToArray(rootJSON, entryJSON);

This is done for all the valid images in the atlas (we don't want to add images that we failed to add to the atlas, for whatever reason). When we have completed looping through the images and creating the JSON object, the last thing we need to do is save the data. Once again, cJSON makes this very easy. A call to cJSON_Print, passing in the rootJSON reference, will return use a char array with the nicely formatted JSON:


out = cJSON_Print(rootJSON);

We then just need to save this data by writing it to a file, using the standard C IO calls:


fp = fopen("atlas.json", "wb");
fprintf(fp, "%s", out);
fclose(fp);

Opening the atlas.json file, we'll see we've got data like this:

[{
	"filename":	"gfx/tall/long.png",
	"x":	0,
	"y":	0,
	"w":	34,
	"h":	128,
	"rotated":	0
}, {
	"filename":	"gfx/misc/pinkTextured.png",
	"x":	35,
	"y":	0,
	"w":	121,
	"h":	123,
	"rotated":	0
}, {
	"filename":	"gfx/cubes/bigGrey.png",
	"x":	157,
	"y":	0,
	"w":	62,
	"h":	63,
	"rotated":	0
}, {
	"filename":	"gfx/cubes/bigGreen.png",
	"x":	0,
	"y":	129,
	"w":	62,
	"h":	63,
	"rotated":	0
}, {
...

The very final thing we need to do is clean up the memory we used. We can delete the JSON array and all its child objects with one call to cJSON_Delete, passing in the rootJSON variable. We also need to free the char array that was created when we printed it out, with a call to free.


cJSON_Delete(rootJSON);

free(out);

There we have it, a basic sprite atlas generator! The nice thing about this generator is that since the output is JSON, it's very flexible and can be used in a variety of places. In the next tutorial, we'll look into how we can use the atlas in an SDL application.

Purchase

The source code for all parts of this tutorial (including assets) is available here:

It is also available as part of the SDL2 tutorial bundle (with on-going updates):

Comments

Mobile site