Generating Tiles and Maps with gconvert

Gconvert is a C++ port of Uzebox Tool's gfx converter and it has an interface, which means you no longer have to edit code, compile and run to get the job done. This tutorial will teach you how to make your tileset ready for conversion and configure gconvert. I'm going to use The Gimp, but you can use any other tool that can convert your tileset to either raw (8bpp, no headers) or PNG-8.

Our Tileset

We are going to use this tileset I made just for this tutorial:

I am also providing you a version with the visible grid, coordinates and maps to help you understand this guide.

As your can see, the top left tile(which is gonna be tile 0) is black, because it is the tile used by the ClearVram() function, it doesn't have to be like that (maybe it has in mode 2), but that most people wouldn't want a brick wall to be their "empty" screen.

Converting

Now that we have everything we need, it's time to start working.

Generating an Image File That Can Be Converted

1. Open Urbanmess.png with The Gimp and go to Image > Mode > Indexed

2. Select use custom palette, open the palette selection dialog and import and select the Uzebox palette located in

where_you_checked_out_the_svn/gfx/uzebox.act

Make sure you uncheck remove unused colors from colormap and click convert.

3. Now save it as a Raw Image Data file, I'm naming it urbanmess.raw. Select Planar as the RGB Save Type and Normal as the Indexed Palette Type. Note that it can also be saved as a PNG-8 file.

Writing Our XML File

Gconvert reads an xml file to know what to do. This is what our urbanmess.xml looks like:

<?xml version="1.0" ?>
<gfx-xform version="1">
    <input file="/home/flavio/imagens/urbanmess.raw" type="raw" tile-width="8" tile-height="8" width="96" height="80" />
    <output file="/home/flavio/uzebox/work/urbanmess.inc">
        <tiles var-name="uMTiles"/>
        <maps pointers-size="8">
	    <map var-name="map_graffiti" left="0" top="2" width="3" height="4"/>
	    <map var-name="map_title" left="3" top="0" width="9" height="7"/>
	    <map var-name="map_window" left="0" top="7" width="2" height="2"/>			
	</maps>	
    </output>
</gfx-xform>

Edit the input and output values to match your needs. As you can see on the "big tileset", the tiles are 8x8 and it is 12 tiles wide by 10 tiles tall. Width and height of the image are in pixels, not in tiles and have to be specified if you're converting a raw image. The exact coordinates and size of the maps are also indicated. Pointer-size depends on the mode you're going to use, mode 3 uses 8 bit map indexes.

Running gconvert

1. Cd into the directory where gconvert is and run it indicating the path to the xml

flavio@flavio ~/uzebox/svn/tools/gconvert $ ./gconvert urbanmess.xml

2. If the xml doesn't have any problems, you should get an output similar to this one:

Current working directory: /home/flavio/uzebox/svn/tools/gconvert
Loading transformation file: urbanmess.xml ...
File version: 1
Input file: /home/flavio/imagens/urbanmess.raw
Input file type: raw
Input width: 96px
Input height: 80px
Tile width: 8px
Tile height: 8px
Output file: /home/flavio/uzebox/work/urbanmess.inc
Tiles variable name: uMTiles
Maps pointers size: 8
Map elements: 3
Blank Tile index: 0
File exported successfully!
Unique tiles found: 61
Total size (tiles + maps): 4074 bytes

Note that duplicated tiles were eliminated. Instead of having 120 tiles, we only have 61.

The Generated Inc File

The tiles and maps are all going to be in the same file, unlike Uzebox Tools where you would get a file for maps and a file for tiles. There are also defines, such as:

#define UMTILES_SIZE 61

These can be very useful when programing your game. The arrays are, pretty much, ready to be used, since they are already declared with PROGMEM.

Testing The Results

This is the main function from a simple c file I wrote that draws all three maps and a brick wall:

int main(){
	SetTileTable(uMTiles);
	//Draw the title
	DrawMap2(10,1,map_title);
	//Make a brick wall
	Fill(0,10,30,18,1);
	//Draw some windows
	for (unsigned int x = 2; x < 27; x += 3){
		for (unsigned int y = 12; y < 22; y += 3){
			DrawMap2(x,y,map_window);
		}
	}
	//And the graffiti
	DrawMap2(15,23,map_graffiti);
	while(1);
}

You can download the hex, the c file and everything else here. Just don't forget to adjust the paths on the Makefile.

Makefile integration

By invoking gconvert in your makefile, the conversion process can happen automagically whenever changes happen to your graphics or xml transform file. To do this simply modify your Makefile in the following way:

...

## Objects explicitly added by the user
LINKONLYOBJECTS = 

## Include Directories
INCLUDES = -I"$(KERNEL_DIR)" 

## Build
all: ../data/my-graphics.inc $(TARGET) $(GAME).hex $(GAME).eep $(GAME).lss $(GAME).uze size 

## Regenerate the graphics include file
../data/my-graphics.inc: ../data/my-graphics.png ../data/my-gconvert-config.xml
	gconvert ../data/my-gconvert-config.xml

## Compile Kernel files
uzeboxVideoEngineCore.o: $(KERNEL_DIR)/uzeboxVideoEngineCore.s
	$(CC) $(INCLUDES) $(ASMFLAGS) -c  $<

...