dstexcomp 0.1

This is an attempt at a Nintendo DS texture compressor.  It takes any image
as input, and can output the NDS formatted texture in a variety of ways.

Requirements:
-------------
dstexcomp requires Python 2.5 and the following libraries:
 - Python Imaging Library <http://www.pythonware.com/products/pil/>
 - NumPy <http://numpy.scipy.org/>
 - SciPy <http://www.scipy.org/>
 - pyprocessing <http://pyprocessing.berlios.de/>

It will optionally use Psyco <http://psyco.sourceforge.net/> if you have it.


Example use:
------------
Convert a PNG image to binary format, and also produce a preview image.
% dstexcomp.py source.png --binary-out=dest --preview-out=preview.png

After running, you will have these files:
dest_tex.bin
dest_idx.bin
dest_pal.bin
preview.png

The binary files are ready to be used on the NDS hardware, and you can view
preview.png to see what the result will look like.

Options detail
--------------

--binary-out=<basename>         -b basename

    Produce three binary files, in NDS format.  These can be copied as-is into
    the appropriate areas of VRAM.  The files are as follows:
  
    <basename>_tex.bin - Texture data.  Copy this into texture slot 0 or 2.
    <basename>_idx.bin - Index data.  Copy this into the first 32k of texture
                         slot 1 for a slot 0 texture, or into the last 32k of
                         texture slot 1 for a slot 2 texture.
    <basename>_pal.bin - Palette data.  Copy into palette VRAM.
 

--preview-out=<filename>        -p filename

    Produce an image file containing the compressed, then uncompressed image.
    This is only useful to preview the results.  Note: Include an extension on
    the filename so the script knows what image format you want.


--compressed-out=<filename>     -z filename

    Produce a single file containing the information in the 3 normal binary
    files.  This is only useful for a game project I'm working on.


--palette-size=<size>           -s <size>

    Specify the maximum palette size in bytes.  A compressed texture can
    address up to 64 KiB of palette data.  The default is 65536 bytes.


--block-modes=<list>            -m <list>

    Specify which block modes to use in a comma separated list, e.g.
    
    -m 1,2,3

    Modes 1 and 3 use two colors per block, while mode 2 uses four.  By
    default, only mode 2 blocks are created.


--egregious-threshold=<err>     -e <err>

    After palette reduction, any blocks with an error >= err will be
    redone.  This involves brute force searching the entire palette and is
    very slow.  To effectively disable this pass, pass in a large number,
    e.g. 999.


--correction-threshold=<err>    -c <err>

    The maximum amount of error acceptible for a block that is being redone
    due to its error exceeding the egregious threshold.  The lower this number,
    the slower it will take.


--help                          -h

    Print some help text.


--version                       -v

    Print some version information.


--quiet                         -q

    Suppress informational messages.


Legal Stuff
-----------
Copyright (C) 2009 Kevin Vance <kvance@kvance.com>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
