====================

gfx2gba v0.13 README

====================



this tool converts



PCX - 8 bit (256 color)

TGA - 8 bit (256 color)

SPR - 8 bit (256 color)

BMP - 8 bit (256 color) or 4 bit (16 color)

TIM - 8 bit (256 color) or 4 bit (16 color)



graphic files to GBA useable data (raw, tiles, map). The special thing

about this tool is that it is able to combine the palettes of several

gfx files into one single "master palette". it removes/remaps double

colors. of course if you try to combine 2 files with 256 unique colors

each it will fail, heh ... :p



Usage: gfx2gba [options] bmp/pcx/tga/spr/tim files ...



Options are:

 

 -pPalettename                    -m generate map (optimized)

 -oOutputdir                      -M generate map (not optimized)

 -fOutput format                  -mm generate metatiled map (optimized)

 -sSection                        -MM generate metatiled map (not optimized)

 -SpSuffix for palette            -bBank for map

 -SmSuffix for map                -mc save map in column order *new*

 -StSuffix for tiledata           -F turn off check for flipped tiles

 -TMetatilesize                   -rs output a rotate/scale BG screen map

 -tTilesize                       -P don't save palette data

 -tc save tiles as columns *new*  -G don't save tile/image data

 -cColordepth                     -D don't save map data

 -CColor-Offset                   -X don't save anything

 -A force color offset add        -Z compress everything

 -aTransparent color              -zt compress tile/bitmap data

 -vVRAM-Offset                    -zp compress palette data

 -x don't merge palettes          -zm compress map data

 -q quiet mode                    -ap use aPLib as compressor

 -B only optimize blank tiles     -aps use aPLib (safe) as compressor

                                  -align add alignment info for GCC *new*



-align adds alignment info to arrays (needed sometimes for GCC)



-mc saves map's in column order instead of rows



-tc saves the tiles in column order instead of rows



-B only optimize/remove BLANK tiles and don't touch others



-A forces color offset adding to ALL colors (it doesn't add the offset to

   index 0 by default)



-ap use aPLib as compressor instead of lz77



-aps use aPLib (safe mode) as compressor instead of lz77



NOTE: for detailed info about aPLib check http://home19.inet.tele.dk/jibz/apack/

      thanks to Jrgen Ibsen for this excellent piece of software



-q quiet mode reduces output to a minimum



-p specifies the name of the master palette (default: master.pal)



-o specifies the output directory (default is current dir)



-f specifies the output format (raw/src/asm/arm) (default is raw)



-s will allow you to select the ROM section used in the assembler

   outputfiles (default is .rodata)



-Sp specifices a custom extension for palette files (ie replace

    ".pal" by something else)



-Sm like above but to customize/replace ".map"



-St like above but to customize/replace ".raw"



NOTE: if C or ASM output is selected, .c or .s will ALWAYS be added

      to the filename, regardless of what custom extension you

      selected!



-T specifies the metatilesize (1/8/16/32/64) (default is 1, which

   means NO metatiling at all)



-t specifies the tilesize (1/8/16/32/64) (default is 1, which means

   NO tiling at all, giving you plain raw data for mode4/5 bg's)



-c specifies input/output color depth (16/256/32k) (default is 256)

   NOTE: in 256 color mode you can also READ 16 color images, but

         they'll be saved as 256 color images!

   NOTE2: 32k setting only works for OUTPUT of raw 15+1bit gfx data

          for use in MODE3/5, you can NOT READ other formats than

          16/256 color BMP or 256 color PCX. this tool was not

          designed for this mode anyway, so expect some bugs there

          (especially if you mix it with other options)



-C will add an offset (0-255) to the bitmap color indexes (default 0)

   it will NOT add the offset to color index #0 (transparent) !!!



-a changes the transparent color (0-255). (default 0)



-v specifies the offset to be added when saving tilemaps (default

   is 0)



-b specifies the color bank to use for 16 color tile maps (0-15)

   (default is 0)



NOTE: DO NOT USE SPACES between -p/-o/-s/-Sp/-Sm/-St-t/-c/-v/-C/-b

      and it's parameter!!! use -t16 or something like that, but

      -t 16 won't work!!!



-m will generate an optimized tile map from the inputfile. optimized

   means it removes double tiles and also checks for horizontal,

   vertical and h+v flipped doubles. of course it sets the correct

   flags in the tile map data. the output .raw file will ONLY contain

   the used tiles (of course).



-M will generate a NON optimized tilemap



-mm will tile a generated map into 32x32 tile sub-maps for easy DMA'ing

    them around



-MM same as -mm just for non optimized maps



-F will turn off check for flipped tiles in map. only "real" doubles will

   be removed.



NOTE: activating map generation will change default tile size from 1 to

      a more GBA friendly size of 8. you can still set your own size using

      the -t option.

      fixed a stupid bug that produced an endless loop in v0.6 if your

      input gfx bitmap was >= 4mbyte.



-rs will force the map to be saved in 1 byte per tile format making it

    suitable for rotate/scale backgrounds. you lose color bank info and

    h/v flip info obviously and the max number of tiles is 256. but hey,

    you knew that already, don't ya?

    NOTE: this one is fixed now, had a silly bug that was not catched

          by -Wall ... :/



-P will disable palette output at all



-G will disable graphics (tiles/images) output at all



-D will disable map output at all



-X will disable all data output



-x will prevent gfx2gba from merging/optimizing your palettes and save

   a separate .pal file for each input gfx file.



-zt will lz77 compress tile/gfx data



-zp will lz77 compress palette data



-zm will lz77 compress map data



-Z will lz77 compress everything



NOTE: all compression stuff is compatible to the GBA internal Lz77 depacker.

      if it fails to compress it will show you a warning and save the normal

      data.



==========================

Frequently Asked Questions

==========================



Q: so far so good, but what if i want to convert all my 36 .bmp files and

   12 .pcx files ?!

A: easy: gfx2gba *.pcx *.bmp

   could it be any simpler?! :)



Q: what -t value do i need for correct sprites and background tiles?

A: use -t8 to get what you need ...



Q: but i am using Linux for GBA dev?!

A: just use the included Linux binary (you may have to set exec flag)



Q: wtf is -v good for? why would i want to add an offset?!

A: HINT: to maximize the number of useable tiles.



Q: is it possible that your tool is the only free available one that

   also supports 16 color / 4 bit gfx?!

A: erm... well... seems so... looks like other tool coders ignore the

   presence of the 16 color modes on GBA ...



Q: v0.4 features are the same as in v0.3?! what's new or changed?!

A: *cough* this release has 2 major bugs fixed. bitmap export to 4bit

   (16 color) was broken (pixel swapped) (export to tiles was working,

   that's why i found this nasty bug so late) and my color optimizing

   stuff made ALL black (0x0000) colors transparent (thanks to Michael

   Jagger for yelling at me about this)



Q: soo, what's new in v0.5 ? i still can't see any new options?!

A: *cough*cough* the black color bug was nastier than i thought but at

   the end they all DIE ... or short: the last bug in color optimizing

   is removed now ... fixed bitmap remapping (last pixel wasn't remapped)

   and finally it compiles now without even a warning! :-)



Q: hey, i can mix all kind of options and gfx2gba doesn't complain about

   stuff that doesn't make sense?!

A: it is a tool to help you developing GBA stuff, not a brain replacement

   and it assumes you know at least a little bit what you are doing.



Q: I have a problem with 32k mode...

A: I don't care ... 32k mode is just a little add-on and not something

   high-priority for me ... :)



Q: hey, who's responsible for the color bank & rot/scale option? i don't

   think you're smart enough to think about 'em yourself!?

A: sad but true ... thanks to Alex D. for this obviously useful ideas.

   cheers mate, keep the ideas coming (even if they arrive in my inbox

   at 00:30 in the morning)!



Q: are there any other people who are giving you their valuable ideas

   free of charge?

A: yeah! many thanks to Dennis R. for the idea to change some of the

   default values and kicking my butt to implement C/C++ array output

   at least. and then we have Bengt Johannesson who found out that the

   symbol name creation was f*cked when you used files not placed in

   the current directory (it had the complete path in the label name

   instead of just the filename) ...



Q: who wanted the l33t flipped tile check to be removable!?

A: Nikita Mikros needed it so i added it ... :)



Q: metatiling? wow! cool name for a feature, BUT WHAT THE HELL IS IT?!

A: it more or less means that your input gfx will get tiled twice. for

   example my game "engine" is building large objects from 16x16 sprites.

   but 16x16 sprites have to made from 8x8 data internally anyway. so

   with a normal tool you have to group your objects in 16xY gfx to get

   a good result. now here comes metatiling into play: it first tiles

   your gfx into X*X and then in Y*Y. so -T16 -t8 will split up the gfx

   into 16x16 blocks first and then this blocks into 8x8 blocks ...

   i hope you get the idea ... :-)



Q: who's responsible for the compressing stuff?

A: thanks to Tony McB. for permisson to use his packer source!



Q: what else is changed/added/fixed in v0.9?

A: added check for incorrect BMP headers (some tools don't set the

   "used colors" entry) and use the depth as default if header info is

   missing.

   also fixed rot/scale BG generation (thanks to Alex D. for reporting)

   added some headers in asm/c outputfiles (that's for you Alex! :) )

   added size info for linker to asm outputfiles



Q: who brought up the idea to add options to disable data output?

A: Erik G. asked for it and now he got it ... :p



Q: not many *NEW*'s in v0.10, what has changed?

A: added function to convert artist-filenames to coder-filenams

   (ie replacing illegal characters in label names by _'s)

   fixed filename generation and handling if sourcefiles are in

   a sub-directory

   message if saving was successful or not

   (thanks to Dennis R. for all this ideas/reports)

   Andreas T. told me that -p together with -x was not working so

   i fixed it :)

   also for Andreas T. are the -mm and -MM options

   thanks to Peter H. (PED) you can now also enjoy the -q option

   made -C work with -x ( thanks to Thomas H. for this one)

   added -a option to set the transparent color (also for Thomas H.)



Q: any updates in v0.11 ?

A: added -B (only blank tile optimize) for light1

   added -A (for Thomas H.)

   added -ap and -aps (aPlib compression) (for Dennis R.)

   added -farm

   added TGA 256 color (packed/unpacked) loader

   fixed color index 0 color in master.pal (for Tyler Gregg)

   fixed GCC ASM .align 4 to .align 2

   fixed "***ERROR: need 256 free colors, only 255 available!" problem

   included a static linked linux version (for Joeri)



Q: no new features in v0.12???

A: no, just 2 important bug fixes:

   - fixed -mm and -MM for metatiled maps (thanks to Phantasm for this one)

   - fixed RAW palette output



Q: what's really new in v0.13?

A: added ProMotion .spr loader

   added Playstation(tm) .tim loader

   added more precise error texts to image loader

   added -mc option to convert row based maps to column based maps (Luc B.)

   added -tc option to convert tiles/bitmaps to columns (Luc B.)

   added possibility to have a ' ' (space) between argument and parameter (Krystian W.)

   added -align option to add  __attribute__ ((aligned (4))) to C/C++ arrays (Thomas H.)

   added extern to C/C++ arrays (Thomas H.)

   added try{} catch(){} around new to prevent termination without error message





=======

Contact

=======



any questions, reports, suggestions are welcome ...

contact me at: markus@console-dev.de



