Documented png2sprites.py

2 files changed, 26 insertions, 1 deletions

diff --git a/docs/images/player.png b/docs/images/player.png
new file mode 100644
index 0000000..8ea64b1
--- /dev/null
+++ b/docs/images/player.png
diff --git a/docs/tools.md b/docs/tools.md
index ec8b56f..d94de8b 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -14,7 +14,32 @@ TODO
 
 ### png2sprites.py
 
-The png2sprites.py tool converts an image that is a multiple of 16x16 into multiple sprites. Sprites are also separated by colour values. Dark grey (#1c1c1c) is assigned to transparent in the MSX colour index.
+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).
+
+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
+calling [ubox_set_sprite_attr](ubox-lib-ref.html#ubox_set_sprite_attr).
+
+The tool interprets dark grey (RGB: 28, 28, 28) as transparent in the MSX
+palette, and any other colour will be used as visible the monochrome data. If
+the image has more than one colour, it will be used to identify different
+sprites.
+
+For example:
+
+![Example sprite with 2 colours per frame](images/player.png)
+
+Will be translated into 6 sprites: 3 frames (16x16) with 2 sprites per frame,
+corresponding to the sprite defined by the green colour and the sprite
+defined by the white colour.
+
+Usage following the example:
+```
+png2sprites.py -i player_sprite player.png > player.h
+```
+
+Use `-h` for the full list of options.
 
 ### map.py