# HG changeset patch
# User Matti Hamalainen <ccr@tnsp.org>
# Date 1530095447 -10800
# Node ID cdf95a4d52822154bc0744a9a6ba723dfde6552a
# Parent  8d006508e6c1caff743e100679b9c69363507422
Update gfxconv documentation, and fix the various mistakes and obsolete
information that has crept in.

diff -r 8d006508e6c1 -r cdf95a4d5282 README.txt
--- a/README.txt	Wed Jun 27 13:13:57 2018 +0300
+++ b/README.txt	Wed Jun 27 13:30:47 2018 +0300
@@ -166,7 +166,7 @@
 -------
 Utility for "dumping" and converting various graphics in plain
 ASCII, or ANSI colored output, or into various image formats
-(including PNG, PCX, PPM, IFF ILBM and ARAW files).
+(including PNG, PCX, PPM, IFF ILBM and RAW/ARAW files).
 
 Input can also be interpreted as bitmap, sprite or character data,
 in multicolor or single color. Colors can be mapped as desired.
@@ -213,32 +213,38 @@
 
 Convert IFF ILBM format image to RGBA/32bit PNG:
 
-$ gfxconv -f png -o output.png input.lbm
+$ gfxconv -o output.png input.lbm
 
 
 Convert IFF ILBM format image to indexed/paletted PNG:
 
-$ gfxconv -f png -o output.png input.lbm -P
+$ gfxconv -o output.png input.lbm -P
 
 
 Convert DrazPaint format C64 bitmap image to indexed/paletted PNG:
 
-$ gfxconv -f png -o output.png input.drp -P
+$ gfxconv -o output.png input.drp -P
 
 
 Convert DrazPaint format C64 bitmap image to unpacked Koala Painter format:
 
-$ gfxconv -f kla -o output.png input.drp
+$ gfxconv -o output.kla input.drp
+
+NOTE: Desired output format is detected from the filename extension,
+but if you wish to use "non-standard" filename(s), you can specify the
+output format via option "-f", e.g. "-f kla", "-f png" etc.
 
 
 Image input to C64 char font conversion:
 
-$ gfxconv font16x16.pcx -f chr -o font16x16.chr
+$ gfxconv font16x16.pcx -o font16x16.chr
 
- - Input file "font16x16.pcx" is a paletted PCX image (preferably 2 colors),
+ - Input file "font16x16.pcx" is a 2-color indexed/paletted PCX image,
    containing a 16x16 pixel font.
- - "-f chr" specifies conversion to c64 char memory format, gfxconv
-   splits the input image to 8x8 blocks, outputting them in sequence.
+
+"Chr" (.chr or "-f chr") specifies conversion to c64 char memory format,
+gfxconv splits the input image to 8x8 blocks, outputting them in sequence
+to the output file.
 
 
 Convert input image to IFFMaster ARAW + assembler include file,
@@ -251,19 +257,26 @@
  - "-f araw" specifies output format to be IFFMaster ARAW.
  - "-B 3" _clamps_ output to be 3 bitplanes. Any bits above those are
    simply discarded.
+ - The assembler include file will be "output.inc" in this case.
 
 
-Single color C64 char font to PNG imge conversion:
+Single color C64 char font to PNG image conversion:
 
-$ gfxconv chars1.fnt -i chr:sc -s 2 -S 10 -c 255:1 -f png -o chars1.png
+$ gfxconv chars1.fnt -i chr:sc -s 2 -S 4 -c 255,1 -n 256 -o chars1.png
 
  - Input file is "chars1.fnt"
- - "-i chr:mc" specifies that input is interpreted as single color chars.
+ - "-i chr:sc" specifies that input is interpreted as single color chars.
  - "-s 2" skips first two bytes of the input file (loading address)
- - "-S 10" scales output image to be 10 times larger
- - "-c 255:1" defines background color (bit value 0) to be transparent
+ - "-S 4" scales output image to be 5 times larger
+ - "-c 255,1" defines background color (bit value 0) to be transparent
    (255, only works for PNG) and foreground to be C64 color 1 (white)
- - "-f png" sets output format to PNG
+ - "-n 256" specifies that up to 256 items (characters) worth of data
+   from input will be processed.
+
+By default the output image will be "vertical", e.g. each character will
+be subsequently below previous. If you specify a width via "-w <n>" option,
+the output will be <n> items (characters) wide, extending down as many rows
+as it will take to fill "-n 256" items.
 
 
 Extract sprites from a C64 memory dump, convert to PNG:
@@ -277,6 +290,8 @@
  - "-s 0x5800" skips 0x5800 bytes, basically the memory address as the
    input is a straight memory dump file.
  - "-n 20" sets max item count to 20, so 20 sprites will be dumped.
+ - "-f png" sets output format to PNG, required because next option
+   does not specify a filename extension.
  - "-o bub" sets filename prefix to "bub"
  - "-q" selects sequential output (separate files)
  - "-c 255:2:5:1" sets the multicolor color mappings