From 2569e268ae9b81938d00592a86b8205fb0df623c Mon Sep 17 00:00:00 2001
From: "Juan J. Martinez" <jjm@usebox.net>
Date: Thu, 24 Jun 2021 20:49:44 +0100
Subject: Documented png2tiles.py

---
 docs/tools.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/docs/tools.md b/docs/tools.md
index d94de8b..92fef88 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -10,12 +10,55 @@ tools (with `-h` flag), and the example game itself.
 
 ### png2tiles.py
 
-TODO
+This tool converts an image in PNG RGB image into a tileset of up to 256 tiles.
+
+The image is expected to use an approximation to RGB for the colours in the
+Toshiba palette.
+
+| Palette index | RGB value | Notes |
+| --- | --- | --- |
+| 0 | 255, 0, 255 | Transparent |
+| 1| 0,   0,   0 | |
+| 2 | 102, 204, 102 | |
+| 3 | 136, 238, 136 | |
+| 4 | 68,  68, 221 | |
+| 5 | 119, 119, 255 | |
+| 6 | 187,  85,  85 | |
+| 7 | 119, 221, 221 | |
+| 8 | 221, 102, 102 | |
+| 9 | 255, 119, 119 | |
+| 10 | 204, 204,  85 | |
+| 11 | 238, 238, 136 | |
+| 12 | 85, 170,  85 | |
+| 13 | 187,  85, 187 | |
+| 14 | 204, 204, 204 | |
+| 15 | 238, 238, 238 | |
+
+Any other colour will result in an error converting the image.
+
+The tool ensures that the tiles follow the *screen 2* mode restrictions: 2
+colours per line on each 8x8 tile.
+
+By default the generated file will include a colour map, with `ID_colors` as
+identifier (if the default "tiles" is used, the table will use `tiles_colors`).
+
+The colour table can be omitted using the `--no-colors` flag.
+
+Example of use:
+```
+png2tiles.py tiles.png > tiles.h
+```
+This will result in a C include output. To generate assembler, use `--asm` flag.
+
+The output can be used with [ubox_set_tiles](ubox-lib-ref.html#ubox_set_tiles) and
+[ubox_set_tiles_colors](ubox-lib-ref.html#ubox_set_tiles_colors), and the rest
+of the [tiles functions](ubox-lib-ref.html#tile-functions).
 
 ### png2sprites.py
 
-The tool converts an image that is a multiple of 16x16 into a sprite (or
-sprites), to be used by [ubox's sprite functions](ubox-lib-ref.html#sprite-functions).
+This tool converts a PNG RGB image that is a multiple of 16x16 into a sprite
+(or sprites), to be used by [ubox's sprite
+functions](ubox-lib-ref.html#sprite-functions).
 
 The result is 1 bit per pixel data without colour information. The colour will
 be provided as part of the `attr` field in the `sprite_attr` struct when
@@ -39,8 +82,6 @@ Usage following the example:
 png2sprites.py -i player_sprite player.png > player.h
 ```
 
-Use `-h` for the full list of options.
-
 ### map.py
 
 TODO
-- 
cgit v1.2.3