// // (win)grit source code, v0.8.1 // (20050313-20080512, cearn)

// === TOC ===

• Introduction / basic working
• Change log
• Future Work
• Licences

// -------------------------------------------------------------------- // Introduction // --------------------------------------------------------------------

What you have here is the source code to grit, the GBA Raster Image Transmogrifier. Grit is actually two applications: there's grit and wingrit, which are command-line and a windows tool, respectively. Grit uses three libraries: my own two cldib and libgrit for basic bitmap routines and the exporter part, and FreeImage for the bitmap file reading. The original versions had some Windows/Intel-specific work in here, but thanks to Wintermute that should be taken care of, and it should compile under Windows, Linux and Mac OSX now. If there are any problems, please let me know.

The exporter works in stages, as it should. This may waste a lot of cycles, but also keeps it maintainable. The basic process is:

• read image
• read and validate all the options
• Prepare a 'work' bitmap
  • crop image to requested size
  • resample bitdepth (16bpp for 16bpp bitmaps, 8bpp for everything else)
  • NEW,20060803: set transparent palette entry/color
• for bitmaps:
  • prepare bitmap (which is in fact already complete)
• for tiles:
  • re-arrange to screenblock
  • re-arrange to meta-tiles
  • re-arrange to tiles
  • prepare map
    • tile-reduce
    • add tile offset
    • meta-map
    • resample to affine format (bytes)
    • compress
• prepare image
  • resample bit-depth
  • compress
• write header file
• prepare palette (go to 16bpp colors)
• write data file(s) in C, GAS, binary or GBFS

NOTE: while grit supports the use of an external tileset now as well, loading/saving it actually happens OUTSIDE of grit_run(). This should/will probably be changed later, but just so you know.

NOTE: wingrit is an MFC app. Since the Visual C Express versions do not have the required MFC libraries, you won't be able to build it with those.

// -------------------------------------------------------------------- // Future work // --------------------------------------------------------------------

• Make tile reducing general purpose: i..e, not limited to 8x8@8 tiles.
• Clean up. No, really: parsing, shared data and tile mapping is a fracking mess, and needs to be cleaned. More STL would be good too.
• External meta-tileset. This would require some changes in the current ext-tile setup as well.
• Grouped data. Right now the bitmap exists as one chunk of data, to be converted, compressed and exported. That's nice, but sometimes it's more convenient to compress/export in smaller chunks, like animation frames. Particularly compression becomes a problem, because the next frame would start an an indeterminate offset. So: split into separate arrays. Do NOT store in a matrix, because that'd ruin the compression. OTOH, it might work fine for non-compressed images. Also create a toc-array to the individual frames. This functionality should probably be controlled through the meta-tile settings, although possibly under a different name.
• PONDER: ALIGN4 attribute to C arrays?

• Separate GRIT_INCL into processing and export bits (DONE: v0.8)

• Add pcx write support to FreeImage. / Record array for the fields (gfx, map, etc) instead of separate records. This will remove many near-duplicate pieces of code.

• Apply compression only at the end, not at preparation.

• Fix Huffman better :P

• Batch-operations (and toc-array ? )

• Merge palette with other files (DONE: v0.8)

• Documentation (Mostly done)

There are a few snippets of doxygen in cldib and libgrit, but not enough to cover everything. I'd like to do the other stuff at some time, but I really don't think I can find the time and it's not that high on my list of priorities.

// -------------------------------------------------------------------- // Change Log // --------------------------------------------------------------------

• v0.8.2, 20081116
  • Fixed GRF format. A group field (RIFF/LIST)'s data is 'name'+sub-fields, not 'name'+sub-size+sib-fields.
• v0.8.1, 20080512
  • Added column-major tiling order.
  • Fixed shared items without -O or -S options. Thanks again, Quirky.
• v0.8, 20080329
  • Renamed grit structs and members. Most of the bitfields have been replaced with normal members.
  • Made a DataItem class for the exporters, allowing the actual exporting functions to be a little shorter.
  • Code for new options. See grit.txt for list.
  • Split runs into different types : shared vs separate data, and single vs multiple inputs.
  • Exit codes for grit.exe
  • Diverted compression routines to cprs_* so that they are stand-alone items. I'll add accompanying decompressors in due time.
  • The map-offset option ('-ma') is not an ERROR. Idjit.
• v0.7, 20070403
  • Rename due to clash with Linux kernel version control (also git :( ). It's now grit. Everything's been changed from 'git' to 'grit'.
  • Code for -We, -Ww, -Ws aliases for -W; -ft!.
  • Changed the way paths are handled. No directories conjured out of thin air anymore.
• v0.7b, 20070317: Batch runs, external tilesets, error logging and some extra transparency items.
• v0.6, 20060803: platform independence should be complete, but I can't test for it myself. If there are any undefined things, go to winglue.h and add something; if it's an endian problem (reversed bits/bytes), use BYTE_ORDER to switch between Big and Little systems. Oh, and notify me of course.
• v0.6, 20060803: Added -pT and -gT flags for transparent palette entry (is switched with pal[0]) and transparent 16bpp color, respectively.
• v0.6, 20060803: Added -ff option, for getting the command line arguments from a file, which is easier on makefiles.

// -------------------------------------------------------------------- // Licences and other info // --------------------------------------------------------------------

// === Grit licence ===

Apart from FreeImage, the LZ77 compressor and GBFS, everything is licenced under the MIT licence (see mit-licence.txt)

// === FreeImage ===

The code only includes the required .h, .exp and .lib to compile the thing, but not the .dll. You'll have to get it from the binary distribution of grit. Or from the FreeImage website (http://freeimage.sourceforge.net). FreeImage is covered under the GPL license and its own licence (see fi-licence.txt).

// === LZ77 compression and gbfs functionality ===

Both the LZ77 compressor and GBFS were taken from the website of Damian Yerrick's (http://www.pineight.com) and modified to suit my own need. Both are covered by GPL as well (see gpl-licence.txt).

--- Misc -------------------------------------------------------------- You know the drill:

Use, distribute, and modify this code freely.

"I do not accept responsibility for any effects, adverse or otherwise, that this code may have on you, your computer, your sanity, your dog, and anything else that you can think of. Use it at your own risk."

Have fun with the code, and don't laugh too loudly please.

• J Vijn