____ ____ ____  _____ _ _     _____ _____
|  _ ' _  |  _ \|_   _| | |   |  ___|  _  |
| | | | | | | | | | | | | |   | |__ | |_| |
| | | | | | | | | | | | | |   |  __||    _|
| | | | | | |_| | | | | | |___| |___| |\ \
|_| |_| |_|____/  |_| |_|_____|_____|_| \_\

mdtiler version 1.90
©2011, 2012, 2016, 2017, 2018 Sik

-----------------------------------------------------------------------------

Modified by andwn 2023
Added commands are marked with --->NEW!<---

-----------------------------------------------------------------------------

mdtiler is a command line tool to convert images into tiles that can be used
in Mega Drive software. It provides a quick build mode that will just convert
an entire bitmap into tiles and an advanced batch build mode that lets you
specify what tiles to convert, in what order and even lets you use multiple
files.

mdtiler is released under the GPL version 3 or later. Check the file LICENSE
for more details, or check http://www.gnu.org/licenses/gpl-3.0.txt

In order to build the current version of mdtiler you will need the following
libraries:

   - libpng (depends on zlib)

-----------------------------------------------------------------------------

Quick build is the simplest way to use mdtiler, but also it's really limited.
It takes a bitmap and converts all of it into tiles. To use this mode, you
need to use the -t or -s switches, depending in what order you want the tiles
to be stored.

To output tiles in the same order as tilemaps (left to right, then top to
bottom), call mdtiler as follows:

   mdtiler -t «in-file» «out-file»

To output tiles in the same order as sprites (top to bottom, then left to
right), call mdtiler as follows:

   mdtiler -s «in-file» «out-file»

It's also possible to specify the -1 switch to output 1bpp tiles instead of
4bpp tiles.

--->NEW!<--------------------------------------------------------------------

To output tiles (like with -t) but also include a mapping that de-duplicates
tiles, call mdtiler as follows:

   mdtiler -m «in-file» «out-pattern-file» «out-mapping-file»

In combination with `-m`, `-o` may also be used to specify the offset, or
"base tile". This includes the tile index and attributes/flags such as
palette, priority and flipping. For example:

   mdtiler -m image.png tiles.dat map.dat -o $2010

Both $ and 0x can be prepended for a hexadecimal number, otherwise the
parameter is assumed to be base 10. $2000 specifies the second palette and
$10 means the mapping assumes the tile data is located at VRAM index 16.
Here is a quick reference for the attributes:

   $8000 - priority bit
   $6000 - PAL3
   $4000 - PAL2
   $2000 - PAL1
   $1000 - Vertical Flip
   $0800 - Horizontal Flip

For the `-t', `-s', and `-m` commands, an additional option `-p` can be used
to dump the palette to a separate file, like so:

   mdtiler -t image.png tiles.dat -p palette.dat

These additional flags were added to reduce the need to write bespoke batch
files for most common use cases.

-----------------------------------------------------------------------------

Batch build is more complex but also provides the most flexibility. It lets
you process multiple images at the same time, and also lets you choose which
tiles to output and in which order. This is specially useful for sprite
mappings, and for compression since you can output multiple graphics as a
single blob file if you want. You will need to provide a "batch file"
(essentially a text file, see below) that tells mdtiler what to do.

To use batch build, call mdtiler as follows:

   mdtiler -b «batch-file»

Batch files consist of multiple commands, each command being in its own line
(blank lines are ignored), parsed from top to bottom, in order (i.e. settings
only apply to commands below them, not the ones above them).

If a # is found when the parser expects a token, it starts a comment and
everything in the line after that point is ignored. You can use this to
document what's going on.

The available commands are as follows (where «» specify parameters):

   input «filename»
   
      Specify input file. All following tiles will be read from this image.
      You need to specify an input file before you can output tiles.
      
      You must enclose the filename inside quotes if it has spaces (e.g.
      "this name has spaces"). Quotes are optional if there aren't spaces
      (e.g. thisisaname or "thisisaname").
   
   output «filename»
   
      Specify output file. All following tiles will be written to this file.
      You need to specify an output file before you can output tiles.
      
      You must enclose the filename inside quotes if it has spaces (e.g.
      "this name has spaces"). Quotes are optional if there aren't spaces
      (e.g. thisisaname or "thisisaname").
   
   output2 «filename»
   
      Secondary output file, used by the map command (see below). The tilemap
      will be written to this file.
   
   palette «color1» «color2» «color3» ... «color16»
   
      TRUE COLOR BITMAPS ONLY: tells mdtiler which palette to use. 16 colors
      have to be specified, as hexadecimal values in the same format the VDP
      wants (e.g. AAA would be light gray, E00 would be blue, 08E would be
      orange, etc.).
      
      For performance reasons, the palette is applied only when the bitmap is
      loaded (i.e. when the "input" command is issued). If you want to apply
      a new palette make sure that the bitmap is loaded again after this.
      
      This command does nothing for paletted bitmaps, in which case mdtiler
      will use the color indices directly.
   
   remappal «group» -> «palette»
   
      PALETTED BITMAPS ONLY: tells mdtiler how to remap the colors to each
      palette. The upper four bits of the color index are used as the «group»
      (i.e. colors 0-15 are group 0, colors 16-31 are group 1, etc.). This
      command lets you decide how each group maps to each VDP palette
      (palettes 0-3 for low priority, palettes 4-7 for high priority).
      
      The default mappings are
      
          0 -> 0      1 -> 1      2 -> 2      3 -> 3
          4 -> 4      5 -> 5      6 -> 6      7 -> 7
          8 -> 0      9 -> 1     10 -> 2     11 -> 3
         12 -> 4     13 -> 5     14 -> 6     15 -> 7
      
      And yes, that's literally -> in the command.
   
   dumppal «filename»
   
      Saves the current palette into the specified file. The resulting file
      is 32 bytes long, where each 16-bit value (big endian) is a color in
      the same format as the VDP takes it.
      
      The palette dumped comes from whichever has been the last used 'input'
      or 'palette' command (i.e. you can dump the palette of a PNG file or
      a palette specified as a command).
   
   tiles «x» «y» «width» «height»
   
      Reads a block of tiles from the input image and converts them into the
      output file. The parameters «x» and «y» specify the coordinates of the
      top-left corner, while the parameters «width» and «height» specify the
      dimensions of the block. They're always measured in tiles.
      
      If you just want to read individual tiles, you can just pass 1 as
      both width and height.
   
   map «x» «y» «width» «height»
   
      Takes a block of tiles and generates a tilemap. The tiles will be
      written to the main output file (see output) and the tilemap itself
      will be written to the secondary output file (see output2). This tool
      will look for redundant tiles (flipping, same but other palette, etc.)
      
      The tilemap consists of a word for each tile, starting from $0000. Each
      word can include flipping, palette and priority flags. To have mdtiler
      proces palette and priority, you must use an 8bpp PNG (256 colors) then
      arrange colors as follows:
      
         - Every 16 colors is a different palette row
         - The first 64 colors are low priority
         - The next 64 colors are high priority
   
   sprite «x» «y» «width» «height»
   
      Makes a sprite entry for a sprite mapping. The tiles will be written
      to the main output file (see output), while the entry will be written
      to the secondary output file (see output2). Call this command for
      every sprite needed in the mapping, then "sprite end" (see below) to
      finish the mapping.
      
      Each entry in the mapping consists of four words:
      
         - X offset in pixels (relative to origin)
         - Y offset in pixels (relative to origin)
         - Tile ID + flags (same format as VDP)
         - Sprite size (same format as VDP)
      
      Only works when layout = sprite and for sizes from 1×1 to 4×4.
      Currently it can't detect repeated sprites (it won't optimize those)
      or different palettes (everything uses the same palette).
   
   sprite end
   
      Writes the sentinel value to the secondary output file (see output2)
      indicating the end of the sprite mappings. The sprite tile IDs return
      back to the initial offset value here too (if they aren't continuous,
      see below).
      
      The sentinel entry is a single word with value $8000.
   
   origin «x» «y»
   
      Changes the origin coordinates for sprite commands. These coordinates
      are given in pixels (*not* tiles) and should point to the pixel in the
      metasprite to be used as origin (i.e. these coordinates are substracted
      from the sprites' own).
   
   offset «offset»
   
      Sets the first tile ID that will be generated by following map and
      sprite commands. If not called then it'll be 0 by default.
   
   offset continuous
   
      Turns on "continuous" mode. Each map command will increment the offset
      by the number of tiles it generated. This allows consecutive map
      commands to be issued all with consecutive tile IDs (without having to
      know how many tiles to offset ahead of time).
   
   offset restarting
   
      The opposite of the above. The offset value will not be changed after
      each map command and every map will be using the same base tile ID.
   
   layout tilemap
   
      Since now on, all groups of tiles will be output following tilemap
      ordering (i.e. left-to-right, then top-to-bottom). This is the default
      setting.
   
   layout sprite
   
      Since now on, all groups of tiles will be output following sprite
      ordering (i.e. same order used for sprites in the Mega Drive).
   
   format 4bpp
   
      All following tiles will be output in 4BPP format (4 bits per pixel,
      same as Mega Drive hardware). This is the default setting.
   
   format 1bpp
   
      All following tiles will be output in 1BPP format (1 bit per pixel).

-----------------------------------------------------------------------------

List of all switches:

   -b or --batch ..... Batch build
   -t or --tilemap ... Quick build (tilemap ordering)
   -s or --sprite .... Quick build (sprite ordering)
   
   -4 or --4bpp ...... Output 4bpp tiles in quick build (default)
   -1 or --1bpp ...... Output 1bpp tiles in quick build
   
   -h or --help ...... Print program usage to stdout
   -v or --version ... Print program version to stdout

   --- New options ---
   -m or --map ....... like -t but deduplicate and generate mapping
   -p or --dumppal <file> . Output palette data to a separate file
   -o or --offset <num> ... Set tilemap offset / base tile (only affects -m)