Grit

1. Introduction

The GBA Image Transmogrifier (“grit” for short) is a bitmap conversion tool for GBA/NDS development. It accepts a multitude of file types (bmp, pcx, png, gif, etc) at any bitdepth and can convert them to palette, graphics and/or map data that can be used directly in GBA code. The output formats are C/asm arrays, raw binary files, or GBFS files, with different datatypes and GBA-compatible compression schemes.

Grit can do more than simply turn bitmap into arrays. It allows you so crop or enlarge the original work area, can convert between bitdepths, can break the images up into tiles or metatiles and supports NDS bitmaps with transparency. It also has a number of tile-mapping options: it can take the bitmap and turn it into a tilemap (and metamap) and a set of unique tiles; it can also use an external tileset, which can then be shared with different maps.

If you need more, feel free to add your own code. This is an open-source project and the code should compile on all platforms, though you'll have to write your own makefiles for non-Windows environments.


Grit comes in two flavors: a command-line version, grit, and a Windows GUI, wingrit. This is the documentation for the command-line version.

2. List of options

2.1. Graphics options

-g
Include graphics in output.
-g!
Exclude graphics in output.
-gb
Bitmapped graphics output. NOTE: without an -gT option, this data will have a clear bit 15.
-gt
Tiled graphics output (default).
-ga <n>
Pixel offset for non-zero pixels. Useful if the associated palette is at an offset.
-gB <n>
Bit depth of the output. Can be 1, 2, 4, 8 or 16. 16 bpp is a truecolor mode, the rest are paletted. If the source image is not of this bitdepth yet, it will be converted.
-gT [ <h> ]
Transparent color. The color should be a 16bit BGR color or 24bit RGB color in hex. For truecolor output, all pixels will have the alpha-bit set except this color. For paletted output, this color will be transferred into index 0.
-gT!
No transparent pixels / set the alpha-bit of the pixels. Only has effect for NDS bitmaps.
-gu8
Graphics data is in byte arrays.
-gu16
Graphics data is in halfword arrays.
-gu32
Graphics data is in word arrays (default).
-gz!
Graphics data is not compressed. (default)
-gzh
Graphics data is 8-bit Huffman compressed.
-gzl
Graphics data is LZ77 compressed.
-gzr
Graphics data is RLE compressed.

2.2. Area options

-ab <n>
Bottom side of the work bitmap's rectangle. If this falls outside of the source bitmap, the latter will be extended.
-ah <n>
Height side of the work bitmap's rectangle. If this makes the bottom fall outside of the source bitmap, the latter will be extended.
-al <n>
Left side of the work bitmap's rectangle. If this falls outside of the source bitmap, the latter will be extended.
-ar <n>
Right side of the work bitmap's rectangle. If this falls outside of the source bitmap, the latter will be extended.
-at <n>
Top side of the work bitmap's rectangle. If this falls outside of the source bitmap, the latter will be extended.
-aw <n>
Width of the work bitmap's rectangle. If this makes the right side fall outside of the source bitmap, the latter will be extended.

2.3. Map options

-m
Include map in output. Enables tile-mapping of the image.
-m!
Exclude map in output (default).
-ma <n>
Tile index offset (non-zero indices only). Useful if you intend to load the tiles at an offset.
-mLa
Map layout for affine tilemaps: 8-bit screen entries and a flat map.
-mLf
Map layout for regular backgrounds. 16-bit entries, but a flat map (i.e., not broken down into screenblocks).
-mLs
Map layout for regular backgrounds. 16-bit entries, broken down into screenblocks.
-mR!
Disable tile reduction for tilemaps.
-mR4
Tile reduction combo for regular backgrounds with 4bpp tiles: tile, palette and flip reduction.
-mR8
Tile reduction combo for regular backgrounds with 8bpp tiles: tile and flip reduction.
-mRa
Tile reduction combo for affine backgrounds: tile reduction only.
-mRf
Tile reduction option: reduce for flipped tiles. Can be combined with t and p reduction options (example: -mRtpf).
-mRp
Tile reduction option: reduce for 16-color palette banks. Can be combined with t and f reduction options (example: -mRtpf). Do not use this for 8bpp tiles ^ndash; you'll regret it.
-mRt
Tile reduction option: reduce for unique tiles. Can be combined with p and f reduction options (example: -mRtpf).
-mu8
Map data is in byte arrays.
-mu16
Map data is in halfword arrays (deafult).
-mu32
Map data is in word arrays.
-mz!
Map data is not compressed. (default)
-mzh
Map data is 8-bit Huffman compressed.
-mzl
Map data is LZ77 compressed.
-mzr
Map data is RLE compressed.

2.4. Metamap/object options

-Mh
Metatile height. Useful for keeping the tiles in a metatile/object together. If tile-mapping is enabled, this will enable metamapping. Works together with -Mw.
-Mw
Metatile width. Useful for keeping the tiles in a metatile/object together. If tile-mapping is enabled, this will enable metamapping. Works together with -Mh.
-MRp
Metatile palette reduction.

2.5. Palette options

-p
Include palette in output (default).
-p!
Exclude palette in output.
-pe <n>
End' palette entry. For example, -pe 32 would output the palette up to, but not including, color 32. Works together with -ps.
-ps <n>
Starting palette entry. -ps 16 would start the export at color 16. Works together with -pe and -pw.
-pT <n>
Transparent palette index. Only works if the input or output is paletted. For paletted output, it'll swap the transparent index with index 0 so that that becomes the transparent index. For paletted → truecolor conversion, the color of the transparent index will be used for transparency, working as a -gT option.
-pu8
Palette data is in byte arrays.
-pu16
Palette data is in halfword arrays (default).
-pu32
Palette data is in word arrays.
-pw <n>
Starting palette entry. -ps 16 would start the export at color 16. Works together with -pe and -pw.
-pz!
Palette data is not compressed. (default)
-pzh
Palette data is 8-bit Huffman compressed.
-pzl
Palette data is LZ77 compressed.
-pzr
Palette data is RLE compressed.

2.6. Input/output options

-fa
Append to output file instead of overwriting. If data with the symbol name already exists in the file, it will be replaced. Has no effect for binary output.
-ff <path>
Flag file for additional options. Instead of adding all the options to the makefile, you can use an external file to store and modify them.
-fh
Create header file with declarations and array length definitions (using array-name + Len).
-fh!
Do not create header file with declarations.
-ftb
Export to binary files. Each array will have its own file: palettes will go into *.pal.bin; graphics data into *.img.bin; map data into *.map.bin; metamap data into *.meta.bin.
-ftc
Export to C arrays.
-ftg
Export to PinEight GBFS format. Note that the GBFS entry names are limited to 24 characters, 6 of which are already used for data affixes.
-fts
Export to GNU assembly arrays. Default output filetype.
-fx <path>
External tileset bitmap which can then be shared between different tilemaps. NOTE. This is still a little fickle. The file must already be in the correct format: a column or reduced tiles with 8bpp. If the file-type does not support 8bpp, a .bmp of the same name will be used. Also, at present, because the input files are still processed individually, you'll still get palettes and graphics for the partial runs. Because this is probably undesired, I recommend using &ksquo;-g! -p!’ and process the tile-file separately. Yes it's a hack, but even determining what the Right Thing to do here is a little hard.
-o <path>
Output file path.
-s <name>
Base name for array symbols. Invalid identifier characters will be replaced by underscores. If this option is not given, then the name follows from the output title, or from the input title if -fa is given.

2.7. Misc options

-q
Quiet mode. Don't print report at the end. May be obsolete thanks to the new logging functions.
-U8
Set all output to use byte arrays.
-U16
Set all output to use halfword arrays.
-U32
Set all output to use word arrays.
-Z!
Set all output to use no compression.
-Zh
Set all output to use 8-bit Huffman compression.
-Zl
Set all output to use LZ77 compression.
-Zr
Set all output to use RLE compression.
-W1
Log error messages.
-W2
Log errors and warning messages.
-W3
Log error, warning and status messages. There are a lot of status messages, so this is mainly for debugging.
-We
See -W1.
-Ws
See -W2.
-Ww
See -W3.

3. DWIM

For those who don't know, “DWIM” stands for “Do What I mean”, in the sense that grit attempts to guess at options that aren't specified explicitly, or correct for options that conflict, rather than quite and yell at you. In principle, this can be considered a Good Thing, but it does make it harder to predict exactly what will happen at times.

The list here covers the various defaults and overrides that Grit uses. I'll try to make it as complete and accurate as possible, but it sometimes gets so convoluted that even I don't know anymore ^_^;;. If you find something that's wring or missing here, please let me know.


3.1. Default settings


3.2. Overrides

4. Examples

[[TODO]]

5. Additional information

5.1. Todo list

Here are a few things that I'd like to add at some point. If anyone want to help flesh it out, that'd be great.


5.2. Last changes

v0.7 (20070414)


v0.7b (20070317)

The batchrun and external tilefile support is still experimental. YHBW.




Modified Apr 1, 2007, J Vijn. Get grit here