|
Grit
|
The GBA Image Transmogrifier ("grit" for short) is a bitmap conversion tool for GBA/NDS development. It accepts a multitude of file types (by using the graphics library libplum) 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 GBFS files (tepples' GameBoy File system, see www.pineight.com), and a RIFF-format I call GRF. The data can be compressed to fit the BIOS decompression routines (LZ77, Huffman, RLE), as well as graphics bitpacking to allow graphic data of 1,2,4,8 and 16 bpp. The data arrays can be in byte, halfword or word formats and a header file can be created with the declarations of these.
Grit can do more than simply turn bitmap into arrays. It allows you to crop or enlarge the original work area, convert between bitdepths, 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 merge the palettes or tilesets from multiple files. The tilemapping option includes unique tile reduction, different map layouts and even metamapping with variable width and heights. This can also be used for 1D sprite-sheet conversions.
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.
Note: Grit tries to convert graphics to the requested format even if that means that the quality of the image has to be reduced. However, the result is usually much worse than if you reduce the quality beforehand with your graphics design tool. For example, if you're designing a background to be converted to a 4 BPP tiled background, make sure that the tiles can actually be expressed as 16 palettes of 16 colors each. If you want to export a 256 color bitmap, ensure that your bitmap doesn't use more than 256 colors (or 255 if you want color 0 to be transparent!).
The original author of Grit is Jasper Vijn (Cearn). For the basic CLI functionality I am indebted to gauauu (www.tolberts.net), who basically handed me a set of CLI functions, which proved a lot easier to use than what I had initially planned on using. Several others (in particular, Dave Murphy, www.devkitpro.org) have also been helpful in making this a multi-platform tool.
Contact email: cearn at coranac dot com
Please, report issues here.
Export options:
-g: Include graphics in output (default).-g!: Exclude graphics from output.Graphics type:
-gb: Bitmapped graphics output. NOTE: without an -gT option, this data will have a clear bit 15.-gt: Tiled graphics output (default).gx: Enable texture mode. You must also use -gb.Format of the output:
-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. It defaults to the bit depth of the original image.-ga <n>: Pixel offset for non-zero pixels (this value is added to all non-zero pixels of the output). Useful if the associated palette is at an offset.Transparency options:
-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. The default is FF00FF (magenta).-gT!: No transparent pixels / set the alpha-bit of the pixels. Only has effect for NDS bitmaps.C type used for the data arrays:
-gu8: Graphics data is in byte arrays.-gu16: Graphics data is in halfword arrays.-gu32: Graphics data is in word arrays (default).Graphics compression:
-gz!: Graphics data is not compressed. (default)-gz0: As -gz!, but with a 32-bit compression header similar to the ones used by the GBA/NDS BIOS. Byte 0: 0x00. Bytes 1-3: size of data.-gzh: Graphics data is 8-bit Huffman compressed.-gzl: Graphics data is LZ77 compressed.-gzr: Graphics data is RLE compressed.Shared graphics options:
-gS: Shared graphics. Build up a shared tileset for the multiple images. See also -fx, -S and -O.By default, the area used to generate graphics is as big as the image. You can reduce it with the following 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. Overrides -ab.-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. Overrides -ar.Export options:
-m: Include map in output. Enables tile-mapping of the image.-m!: Exclude map from output (default).Format of the output:
-ma <n>: Tile index offset for non-zero indices (this value is added to all non-zero pixels of the output). Useful if you intend to load the tiles at an offset.-mp <n>: Forces the palette-bank index to n.Custom map format options:
-mB...: Custom mapsel (map('s?) element) bitformat. The regexp format for it is "-mB((\d+):)([iphv_]\d*)+", that is, "-mB", followed by the bitdepth of the mapsel, a colon and a character-number pattern indicating the big-endian order and size of the bitfields. Available fields and their indicators:
i: tile-indexp: palette-bank indexh: horizontal flipv: vertical flip_: empty fieldFor example, the Text-BG mapsel format is: "16:p4vhi10"
Map layout options:
-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). This is also used for extended affine backgrounds in NDS.-mLs: Map layout for regular backgrounds. 16-bit entries, broken down into screenblocks.Map reduction options:
-mR!: Disable tile reduction for tilemaps. Not advised in general.-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, you'll regret it.-mRt: Tile reduction option: reduce for unique tiles. Can be combined with p and f reduction options (example: -mRtpf).C type used for the data arrays:
-mu8: Map data is in byte arrays.-mu16: Map data is in halfword arrays (default).-mu32: Map data is in word arrays.Graphics compression:
-mz!: Map data is not compressed. (default)-mz0: As -mz!, but with a 32-bit compression header similar to the ones used by the GBA/NDS BIOS. Byte 0: 0x00. Bytes 1-3: size of data.-mzh: Map data is 8-bit Huffman compressed.-mzl: Map data is LZ77 compressed.-mzr: Map data is RLE compressed.By default this is disabled (width and height are 1, and no reduction is done).
-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.Export options:
-p: Include palette in output (default).-p!: Exclude palette from output.Format of the output:
-ps <n>: Starting palette entry. -ps 16 would start the export at color-pe and -pn.-pe <n>: End' palette entry. For example, -pe 32 would output the palette up to, but not including, color 32. Works together with -ps.-pn <n>: Number of palette entries. Works together with -ps; overrules -pe.Transparency options:
-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 to truecolor conversion, the color of the transparent index will be used for transparency, working as a -gT option.C type used for the data arrays:
-pu8: Palette data is in byte arrays.-pu16: Palette data is in halfword arrays (default).-pu32: Palette data is in word arrays.Graphics compression:
-pz!: Palette data is not compressed. (default)-pz0: As -pz!, but with a 32-bit compression header similar to the ones used by the GBA/NDS BIOS. Byte 0: 0x00. Bytes 1-3: size of data.-pzh: Palette data is 8-bit Huffman compressed.-pzl: Palette data is LZ77 compressed.-pzr: Palette data is RLE compressed.Shared graphics options:
-pS: Shared palette data. The colors of the source bitmaps are merged into a single palette. See also -O and -S. NOTE: will alter the order of the original palette (unless the first bitmap happened to have all the colors in it (hint, hint)).Append mode:
-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.C header generation options:
-fh: Create header file with declarations and array length definitions (using array-name + Len). This is the default.-fh!: Do not create header file with declarations.GRF options:
-fr: Enables GRF format for .c and .s files. It groups the separate arrays into a GRF-formatted array. See also -ftr.File type export options:
-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.-ftB: Export to binary files. Each array will have its own file: palettes will go into *.pal; graphics data into *.img; map data into *.map; metamap data into *.meta.-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.-ftr: Export to GRF (Grit RIFF).-fts: Export to GNU assembly arrays. Default output filetype.External configuration options:
-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.External tileset options:
-fx <path>: External tileset bitmap which can then be shared between different tilemaps. Implies -gS. 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.Destination options:
-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.Shared data options:
-O <path>: Output file path for shared data.-D <path>: Destination folder for non-shared data.-S <path>: Base name for symbols for shared data.Tile configuration options:
-tc: Tiling is done in column-major order, instead of row-major. This can be useful for horizontal scrollers, or efficient tile rendering.-th <n>: Set height of basic tile (default: 8).-tw <n>: Set width of basic tile (default: 8).Global overrides for C type used for the data arrays:
-U8: Set all output to use byte arrays.-U16: Set all output to use halfword arrays.-U32: Set all output to use word arrays.Global overrides for compression options:
-Z!: Set all output to use no compression.-Z0: As -Z!, but with a 32-bit compression header similar to the ones used by the GBA/NDS BIOS. Byte 0: 0x00. Bytes 1-3: size of data.-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.Verbosity options:
-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.Version options:
-V: Print grit version string and exit.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.
-p/-g/-m! options). No compression.-gt). Or 16bpp bitmap for truecolor images (gb).-gT option is given. For a colorless -gT, magenta will be used to indicate the transparent color.-mR8). NOTE: grit will always start a new tileset with an empty tile.-mLf).-Mw and/or -Mh is greater than 1. If mapping is disabled, the meta-map settings indicate object tile groups.-fts -fh). Graphics are word-arrays, Palette and map data are halfword arrays.-fa)..c/.s/.bin/.gbfs. Anything else will be changed.-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.-fx requires mapping, but does not automatically set a -m option.-pT and -gT together is not advised.-ft options override the filetype given by -o.-U and -Z set the datatype and compression options for all arrays, but they can be overridden with data-specific options like -pu and -gz.The basic format for using grit is:
That is, grit, source bitmap(s) followed by any combination of options. Example for conversion of foo.bmp into a set of 16x16p 4bpp sprites, using only the first 16 palette entries, to 16bit C arrays:
Grit is relatively lenient in terms of what you enter. For one, it searches out correct options, so that incorrect or options are simply ignored, as are later version of option types in the case of multiple instances. Most options consist of a base and a value; the space between the two is optional. For example, the bitdepth option in the example (-gB4) would also have been excepted as -gB 4. There is also a complex system of defaults to simplify the input. These are given in brackets in the list below. but for easy reference, here's a list:
-m*), it will default to a flat regular tilemap, reduced for tiles and flips. u16 C arrayIf you explicitly mention a destination file during a multi-source run, be sure to add the -fa flag and DO NOT use the -s flag. In a shared-data run, the shared filename and symbol name can be controlled with
The external tilefile is experimental too. It seems to work well enough, but just to be sure, always start with an 8bpp bitmap that's already tiled (or non-existent), and use either bmp, gif or png. I'll try to add metatiling to it too at some point.
Mode 0 map (=regular), 4bpp tiles, tile/pal/flip reduced, sbb format:
or
Mode 2 map (=affine), tile reduced, map in bytes:
Mode 3 or 5 bitmap:
Mode 4 bitmap, forced to screen size:
Sprite, 4bpp, 16x16p (=2x2t):
Sprite, 4bpp using pal16-bank 4 (colors 0x40 - 0x4F):
or
Mode 0 metamap, 4x3 metatiles, full tileset reduction:
NDS 16bpp bitmap, with cyan as transparent color:
Shared data: multi-bitmap to tilemaps + single tileset conversion. If you want to convert a number of bitmaps to a single tileset and multiple maps, use -gS. If you want to save the tileset, or want to use a pre-made tileset, use -fx.
The output of this example is a single file with the combined tileset as sharedTiles, its palette as sharedPal and the separate maps as a1Map, a2Map, a3Map.
I made myself a RIFF binary format because a) different loose binaries are somewhat annoying and b) they lose all context. A RIFF chunk looks like this:
A 4-byte identifier, a 4-byte size field, indicating the size of the data (not the size of the whole chunk!) and a variable-length data array. A GRF chunk (pronounced “griff”) will look like this:
The names are the (sub-)chunk identifiers, '#'s the size field, and the accolades indicate the data arrays. Each of the chunks inside the GRF chunk is actually optional, with the exception of the header. What goes into the header is still tentative, but for now it looks like this:
The attributes here are just the bitdepths for now, or 0 if the the item isn't exported, but this behaviour may change later. The tileWidth and tileHeight are the tile dimensions in pixels, and metaWidth/Height are the metatile dimensions in tile-units.
GrfHeader is unfinished
I'm still considering what should go into the header here; things like map/metamap sizes may be useful, as would offsets, formats and other niceties. These may be added at a later date.
The following is a simple reader for GRF-formatted data.
Note that the header and metamap chunks are ignored here for simplicity's sake. Also note the decompression routine. I've made it a requirement that each item must have a header word compatible with the BIOS functions, even if there is no actual compression (hence the difference between -Z0 vs -Z!). That way you can get the compression-type from the data itself, even if there's no actual compression. Another requirement is that each chunk must be word-aligned. This is actually part of the RIFF-spec itself.
There is a reference to tonccpy() in grf_decomp(). This is a memcpy() replacement that also works properly for GBA-VRAM. You can get it from coranac:tonccpy, or you can just replace the call with memcpy() or any other copy routine if you're sure you won't run into trouble with those.
You can export to GRF using -ftr. You can also get GRF arrays by using -fr, but that presently only works for C and asm data. The extension used for the arrays there is .grf.
In previous versions, you could have build up shared tileset with the -fx option. This would add new tiles to the tileset if they couldn't be found and save it to a bitmap. This worked, but because the runs were still essentially singular you ended up with intermediary palettes and tilesets unless you took steps to prevent it. And you had to export the tileset separately afterwards.
As of v0.8 this is now different. If …
-gS, -pS or -fx is set… grit will exclude the temporary palette and/or tileset (whatever is appropriate) from the individual parts and only export the completed sets at the end. The name of the shared data can be controlled with -S and that of the shared output file with -O (uppercase for shared, versus lowercase for individual). If you don't add these names, they will be taken from the lowercase versions; if those are absent too, the name of the first source file will be used as a basis.
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.
Check the change log here.
1.9.8