From 6a3cf023968180b00a1f67880ea5f58ad899cd1e Mon Sep 17 00:00:00 2001
From: Pavol Rusnak <stick@gk2.sk>
Date: Mon, 25 Apr 2016 20:01:16 +0200
Subject: [PATCH] add documentation about toif

---
 docs/README.md |  1 +
 docs/toif.md   | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++
 tools/png2toi  |  6 +++---
 3 files changed, 56 insertions(+), 3 deletions(-)
 create mode 100644 docs/toif.md

diff --git a/docs/README.md b/docs/README.md
index ef8395f95..590349b54 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,3 +2,4 @@
 
 * [TREZOR OS API](api.md)
 * [TREZOR OS Bootloader](bootloader.md)
+* [TREZOR OS Image Format](toif.md)
diff --git a/docs/toif.md b/docs/toif.md
new file mode 100644
index 000000000..9535d4b25
--- /dev/null
+++ b/docs/toif.md
@@ -0,0 +1,52 @@
+#TREZOR Optimized Image Format
+
+##Header
+
+| offset | length | name | description |
+|-------:|-------:|------|-------------|
+| 0x0000 | 3      | magic | `TOI` |
+| 0x0003 | 1      | fmt | data format: `f` or `g` (see below) |
+| 0x0004 | 2      | width | width of the image (big endian) |
+| 0x0006 | 2      | height | height of the image (big endian) |
+| 0x0008 | 4      | datasize | length of the compressed data (big endian) |
+| 0x000A | ?      | data | compressed data (see below) |
+
+##Format
+
+TOI currently supports 2 variants:
+
+* `f`: full-color, file extension `.toif`
+* `g`: gray-scale, file extension `.toig`
+
+###Full-color
+
+For each pixel a big endian 16-bit value is used. First 5 bits are used for red component, next 6 bits are green, final 5 bits are blue, so it looks like this:
+
+| 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+|----|----|----|----|----|----|---|---|---|---|---|---|---|---|---|---|
+| R | R | R | R | R | G | G | G | G | G | G | B | B | B | B | B |
+
+###Gray-scale
+
+Each pixel is encoded using a 4-bit value. Each byte contains color of two pixels, so it looks like this:
+
+| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+|---|---|---|---|---|---|---|---|
+| Po | Po | Po | Po | Pe | Pe | Pe | Pe |
+
+Where Po is odd pixel and Pe is even pixel.
+
+##Compression
+
+Pixel data is compressed using DEFLATE algorithm with 10-bit sliding window and no header. This can be achieved with ZLIB library by using the following:
+
+``` python
+import zlib
+z = zlib.compressobj(level=9, wbits=10)
+zdata = z.compress(pixeldata) + z.flush()
+zdata = zdata[2:-4] # strip header and checksum
+```
+
+##Tools
+
+* [png2toi](../tools/png2toi) - tool for converting PNG into TOI format
diff --git a/tools/png2toi b/tools/png2toi
index 86fd34821..b1899e970 100755
--- a/tools/png2toi
+++ b/tools/png2toi
@@ -54,11 +54,11 @@ def process_image(ifn):
             f.write(bytes('TOIg', 'ascii'))
         f.write(struct.pack('>HH', w, h))
         if im.mode == 'RGB':
-            data = process_rgb(w, h, pix)
+            pixeldata = process_rgb(w, h, pix)
         else:
-            data = process_grayscale(w, h, pix)
+            pixeldata = process_grayscale(w, h, pix)
         z = zlib.compressobj(level=9, wbits=10)
-        zdata = z.compress(data) + z.flush()
+        zdata = z.compress(pixeldata) + z.flush()
         zdata = zdata[2:-4] # strip header and checksum
         f.write(struct.pack('>I', len(zdata)))
         f.write(zdata)