Tutorial One

This tutorial demonstrates how to initialize the system, display an image in mode 4 (the bitmap mode) and how to convert a bitmap image so it can be used in conjunction with HEL.

Overview

Getting the graphics ready

HAM SDK comes with a commandline program called gfx2gba. This program can do almost everything you need to get your graphics into a Game Boy Advance supported format. You should not miss to read the gfx2gba readme.txt, all of its features as well as supported parameters are mentioned in that file.

Take a bitmap image with the dimension of 240x160 pixels, 240 pixels wide, 160 pixels high and save it in 8bit format using the name "bg.bmp".

To convert the bg.bmp file into Game Boy Advance mode 4 format, you need following command:

	gfx2gba -t1 -D -fraw -ogfx/raw -pbg.pal gfx/bg.bmp

For details about the commandline, especially the parameters, see gfx2gba readme. I will give a briefly overview only.

We told gfx2gba to convert the file "gfx/bg.bmp" to raw format, output the converted file(s) into the folder "gfx/raw", save the palette using the name "bg.pal" and prevent it from creating a map (-D). -t1 is the tilesize, and must be -t1 in in this case.

Once you have executed the commandline, you should find "bg.raw" and "bg.pal" in "gfx/raw" directory.

The next step is to convert the graphics into sourcecode, so it can be linked into the ROM. I use "katie" for this. Katie is a tool to concatenate binary files and output them as different kinds of sourcecode such as assembler or C, as well as writing out a headerfile to access the files included. Katie comes with the HEL archive and can be found in "hel/tools/win32".

The commandline to convert the just converted bitmap ,located in "gfx/raw", using katie is:

	katie --output-asm-arm --output-h gfx/raw/*.*
This tells katie to use all files in "gfx/raw" and output an assembler and header file. After executing this commandline, you'll find two further files in the root of your project: "ResourceData.s" and "ResourceData.h".

I always put the graphics-conversion-commands into the project makefile, so everything is located at one place. If you look at the example project makefiles, you'll notice the "gfx:" target.

Here is it as I would store it in a makefile:

.PHONY gfx: makefile
	gfx2gba -t1 -D -fraw -ogfx/raw -pbg.pal gfx/bg.bmp
	katie --output-asm-arm --output-h gfx/raw/*.*
The tabs infront of gfx2gba and katie must not be removed, otherwise "make" does not want to process the file anymore.

When you included the graphics-conversion-commands into the makefile, you can convert the graphics with just one command:

	make gfx

Sometimes make says it is uptodate, even when it is not. In this case just pass the -B parameter to make and it will start the process, no matter if it is uptodate or not:

	make -B gfx

Adding the graphics to the project

Once you converted the graphics as described above, you must add ResourceData.s to the files to compile. To do this, open "makefile" from your project and add this line:
	OFILES += ResourceData.o
This tells the HAM makefile-system to compile and link ResourceData.s.

Display it on the Game Boy Advance

Alright, lets get started with some code. The first thing you want to do is to include hel2.h. This file must be included in every file where you call any of HEL's functions. Also include the header file which katie did ouput.
    #include <hel2.h>
    #include "ResourceData.h"

Every project needs a program entry point. Using the HAM SDK, it must be called "main":

    void main()
    {

The very first function called must be ham_Init, to initialize HAMlib, where HEL Library is based on.

        ham_Init();

Since we want to display an image in mode 4, we have to switch to that mode:

        hel_BgSetMode(4);

Remember that we got two files, bg.pal and bg.raw? The .pal file is the palette data. In this case it contains 256 entries and we must store it in Vram (Videoram), otherwise the image will be displayed entirely in black and you probably think nothing is on the screen. So here we go, we use the palette loading function from HEL Library to store a palette with 256 entires into palette Vram:

        hel_PalBgLoad256(ResData16(RES_BG_PAL));

hel_PalBgLoad256 will copy the palette data specified by the RES_BG_PAL resource identifier to Vram. RES_BG_PAL is a definition which has been generated automatically by katie, see above. ResData is also generated by katie. All resource identifiers and ResData macros are located in ResourceData.h, just take a look at it and refer to the katie program documentation.

Next we also need to store the actual image data into Vram, so far we only have copied the palette data. Because we using a 240x160 pixels image, we can use another function from HEL Library:

        hel_BmpLoad(ResData(RES_BG_RAW));

This call will load the image data to Vram. However, you don't see anything yet, because mode 4 (the graphic mode we use), supports double buffering and hel_BmpLoad writes to the backbuffer. In order to display the backbuffer, where the image data is located, we have to swap the front and backbuffer:

        hel_BmpFlipBackBuffer();

Now is the image only a very short time visible. Let's put the CPU into low-power mode and wait for VBlank-Interrupt, which never occurs because we don't enable any interrupt, so the application runs forever, or at least until the battery is empty:

        hel_SwiVBlankIntrWait();

Don't miss to add the final curly brace.

    }

Complete source code

    #include <hel2.h>
    #include "ResourceData.h"
    
    void main()
    {
        ham_Init(); 
        hel_BgSetMode(4);
        
        hel_PalBgLoad256(ResData16(RES_BG_PAL));
        hel_BmpLoad(ResData(RES_BG_RAW));
        
        hel_BmpFlipBackBuffer();
        
        hel_SwiVBlankIntrWait();
    }   

Final words

Voila, that's it! You just learned the basics of resource management using katie, as well as how to convert graphics into a Game Boy Advance compatible format with gfx2gba as well as using HEL and HAM.
Generated on Sat Aug 12 13:54:07 2006 for HEL 2 Library by  doxygen 1.4.7