Having to deal with sprite/texture/background data is a pretty common task in DS programming. The best way to do it is to strip any sort of header information and undo compression that is part of many graphics formats so you can just link the binary data along with your code. The problem is you have to know how to do this.

It looks like a lot of people convert the image to a header file and then #include it in their code. For small demos this really isn't a big deal, but it's kind of bad once you go beyond loading a single image. Why? Since the data is included by the pre-processor you have to recompile it along with your code EVERY time you make a change.

I figured out the tools well enough to get around this so I thought I'd share two different ways of doing this. Anyway, the two methods are:
  1. Image->Source->Binary
  2. Image->Binary
The end result is essentially the same, the process is just a little different.

Both require a program call gfx2gba from gbadev.org (NOTE: There are two versions of gfx2gba around, but you want v0.13. v1.03 is a similar but different program from a different author. I'm pretty sure you could use it I just won't talk about it here). This program can read various graphics file formats and extract the image data from them in various ways and seems to be an indespensible part of both GBA and DS development (yes, despite its name it is also useful in DS development because the two platforms have several similarities).

Image->Source->Binary


  1. Use gfx2gba to convert your image (bmp/pcx/tga/...) to a C source file. I will assume your image file is called image.bmp.

    gfx2gba -t8 -f src -o arm9/source image.bmp

    This converts image.bmp into a master.pal.c file containing the palette information and a image.raw.c file containing the image data arranged as 8x8 tiles. This would be used for sprites. For backgrounds you don't want tiling so you leave off "-t8".

    "-f src" specifies that the output type will be source (C) files.

    "-o arm9/source" specifies the output directory that the *.c files will be placed it. Set this to your source directory.

    gfx2gba has several other options so be sure to try running it without arguments or looking at the readme.txt file.


  2. Next, you want to make sure that this image data will be compiled as part of your build process (when you type "make"). You will either have to add it if you are using a custom Makefile, or place it in a directory that is searched for *.c files.


  3. Finally, you have to make the data accessible from your program. This is done by adding a declaration to your code so the compiler will let you use the arrays in the external object files. You will have a palette array called master_Palette in master.pal.c and an image array called image_Bitmap in image.raw.c. Putting the following code somewhere in your program source code will allow you to use them:

    extern const unsigned char image_Bitmap[];
    extern const unsigned short master_Palette[];

    Unfortunately, there doesn't seem to be a way to determine the size of the arrays at compile-time when you use this method. sizeof() gave me an error since they are arrays of unspecified size. You either have to include the dimension of the arrays from the generated source files:

    extern const unsigned char image_Bitmap[4096]; // Or whatever the size is
    extern const unsigned short master_Palette[256];

    OR, declare additional variables that hold them:

    unsigned int image_Bitmap_size = 4096; // Or whatever
    unsigned int master_Palette_size = 256;

    OR, add two other variables to the generated source files to store the size and then declare them as well:

    /* Add to the end of image.raw.c */
    const unsigned int image_Bitmap_size = sizeof( image_Bitmap );
    /* Add to the end of master.pal.c */
    const unsigned int master_Palette_size = sizeof( master_Palette );

    /* In your program source code */
    extern const unsigned int image_Bitmap_size;
    extern const unsigned int master_Palette_size;
    /* Don't forget the data array externs as well */

    I prefer the latter method because it is the most automatic of the three. If you ever change the image files you will have to regenerate the source and re-add the lines, but they're quite short and you probably won't be changing the images often.



Now when you run "make" it will compile the image data source files once and then you won't have to compile them again. The compiled image data will be linked into the executatable (don't forget to tell the linker about them if necessary).

Personally, I don't really like this method because it requires some manual work. I like things to be as automated as possible so I don't screw something up when I forget to do some manual step. For this reason I prefer the second method.

Image->Binary



  1. First, extract the image data from the image file with gfx2gba (assuming an image file called image.bmp):
    gfx2gba -f raw -t8 -St.bin -pmaster.bin image.bmp

    Again, leave off "-t8" if you are working with a background rather than a sprite.

    "-f raw" for binary output is the default.

    "-St.bin" sets the extension of the image data to ".bin" instead of the default ".raw".

    "-pmaster.bin" sets the palette filename to "master.bin" instead of the default ("master.pal"). There is a "-Sp" option to set the palette extension similar to "-St", but it doesn't seem to work.

    This will generate two binary files: image.bin containing the image data, and master.bin containing the palette.

  2. Next, you need to make these files linkable. This requires a bit of "magic" as it's hard to see how the example programs do this.

    If you look at a Makefile for one of the example programs you will find the following rule way down at the bottom:

    %.bin.o : %.bin
    @echo $(notdir $<)  @$(bin2o)

    Basically, it takes *.bin files and trys to make them *.bin.o files by calling "bin2o". Now, if you look in devKitPro/devKitARM/base_rules (a file that gets included in all the Makefiles) you will find:

    define bin2o
    bin2s $< | $(AS) $(ARCH) -o $(@)   echo "extern const u8" `(echo $( `(echo $(> `(echo $(> `(echo $(

    What this basically does is convert a binary file to assembly language, assemble it so it can be linked to your program, then generates master_bin.h and image_bin.h files to be #include'd in your program source. They contain:

    /* In master_bin.h */
    extern const u8 master_bin_end[];
    extern const u8 master_bin[];
    extern const u32 master_bin_size;

    /* In image_bin.h */
    extern const u8 image_bin_end[];
    extern const u8 image_bin[];
    extern const u32 image_bin_size;


    The extern's from the first method all nice and automagically declared for you.



I've shown you 2 different approaches to getting away from header file #include'd data and moving to more professional linking of binary files. I prefer the latter method as it can be pretty much completely automated, but which method you use will largely depend on your needs.

This is not to say these are the only two methods, mind you. While trying to figure this all out I saw references to some program named "katie" and another called "bin2c" ("binary to C" I would assume) that sounded like they could likewise be used. I'll leave that to you. Also, I'm willing to bet that there's a plugin for The Gimp or some other graphics program that will do all of this.