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.
- -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
-
Exported data: palette and graphics data is exported
by default, tile-maps are not (-p -g -m! options). No
compression.
-
Palette: palette data will consist of the full palette
of the input bitmap. What this actually means depends on the
bitdepth.
-
Graphics format. Tiled graphics in the input bitmap's
bitdepth for paletted images (-gt). Or 16bpp bitmap for
truecolor images (gb).
-
Bitmap transparency. The alpha-bit will be clear if
no -gT option is given. For a colorless -gT,
magenta will be used to indicate the transparent color.
-
Area: size of the input bitmap.
-
Mapping: tile reduction: reduce for unique and flipped tiles
(-mR8).
NOTE: grit will always start a new tileset with an empty
tile.
-
Mapping: layout: regular screen entries, flat map
(-mLf).
-
Meta-mapping. A meta-map will be generated if mapping is
enabled and -Mw and/or -Mh is greater than 1.
If mapping is disabled, the meta-map settings indicate object tile
groups.
-
Data formats. The default output is asm arrays with a
header file (-fts -fh). Graphics are word-arrays, Palette
and map data are halfword arrays.
-
Append/replace. Currently, the default is to overwrite the
existing file, but it may make more sense to use append/replace
instead (-fa).
-
Filenames. If no output name is given, it will be based
on the input name (which should always exist). The extension
will be one of the following: .c / .s /
.bin / .gbfs. Anything else will be changed.
-
Symbol names. If no symbol name is given (-s),
it is based on the output name in overwrite mode, or the
input name in append mode (-fa). Invalid characters for
identifiers are replaced with underscores.
-
Directories. Unless an absolute path is given, the base
directory will be the current working directory. This means
no Drag&Drop over a grit shortcut, because the cwd
there won't be what you'd want. Use the gritbat.bat file
for that if you must.
-
External tilefile. -fx requires mapping, but
does not automatically set a -m option.
3.2.
Overrides
-
Transparent color vs palette. This is ... complicated.
Use of -pT and -gT together is not advised.
-
Graphic types. -gB16 automatically means
bitmap graphics and no mapping (-gb -m!).
-
Filetypes. The -ft options override the
filetype given by -o.
-
Global datatype/compression. -U and -Z
set the datatype and compression options for all arrays, but they
can be overridden with data-specifoc options like -pu
and -gz.
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.
-
The way the tile-file is handled now is kinda screwed up. Needs
to be straightened out.
-
External meta-tileset. Right now it's just yer average 8x8 tiles.
-
PCX support for external tileset. FreeImage doesn't allow PCX
writing.
-
Better batch-run options. Possibly including the ability to
clump the data together somehow in a matrix.
-
Grouped data. For example, if you have a bitmap with several sprite
animation frames, it's not useful to compress the whole thing
because you might want to uncompress them separately into VRAM.
It'd be nice to have the compression apply per frame and use a
frame table.
-
Column-based instead of row-based map data. Could be useful for
horizontally scrolling maps.
-
Long option names.
5.2.
Last changes
v0.7 (20070414)
-
Added batch file grind.bat for drag/drop conversion.
(Yes, Dave, it's a batchfile, but sometimes you just want a
quick sample without fussing.)
-
Project rename. git's now grit.
-
Changed the way directories work. All relative paths start from
the current working directory, whatever that may be. This also
fixes a bug when for dir-less -fx options (thanks dovoto).
-
Default filetype is now assembly (-fts). If you're using
DKP or tonc template makefiles, this should not be a problem.
-
Added -We, -Ww, -Ws aliases for
-W<n>.
-
Added no converted output option -ft!.
v0.7b (20070317)
-
Batchrun: Multiple bitmaps in one go (no wildcards though).
-
Dwimming for transparency options (i.e., -gT and
-pT interaction)
-
Error/warning/status logging functions (-W).
-
External tilefile support (-fx).
The batchrun and external tilefile support is still experimental.
YHBW.