
     VLSI Solution VS1005 LCD Icon File Format
             Revision 1.02: 2021-01-28


The VS1005 LCD Icon File Format has been designed to be as fast
to work on as possible with VS1005. Thus, its byte and bit orders
are not necessarily those that are the most common on PC machines.
This document describes the file format.

Another source of documentation for the format and how to use it
is the VS1005 BitMap Graphics document VS1005BitMapGraphics.pdf.



The file consists of four parts:

1: Header

2: Icon Descriptions

3: Icon Datas

4: Metadata



1. Header

  ID

  2 bytes: 0x1c 0x9a

  NUMBEROFICONS

  2 bytes: MSB LSB.

  Example: If there are 291 = 0x123 icons, the bytes are 0x01 0x23


2. Icon Descriptions

  ICONDESCR

  For each icon, there are 6 bytes:

  P2 P1 P0 W H BPP

  P = byte position of icon bitmap data in the file
    P2 = bits 23:16 of P
    P1 = bits 15:8  of P
    P0 = bits  7:0  of P

  W = icon width in pixels

  H = icon height in pixels

  BPP = bits per pixel. Must be between 1..8. Recommended are 1..4.

  Example, for a 32x24 pixels 4bpp icon that has its data starting at
  offset 0x12345 in the file, the bytes for that icon would be:

    0x01 0x23 0x45 0x20 0x18 0x04



3. Icon datas

  For each icon, there are two variable-length fields:

  PALETTE BITMAP

  3.1 PALETTE

    There are 2^BPP palette entries, each entry is 2 bytes:

    PAL1 PAL0
 
    PAL = Palette entry

      PAL1 = bits 15:8 of palette entry
      PAL0 = bits  7:0 of palette entry

      Palette entry is divided into 3 portions in so-called RGB565 format:

      PAL bits 15:11 = red (scale 0..31)
      PAL bits 10:5  = green (scale 0..63)
      PAL bits 4:0   = blue (scale 0:31)

    Example:
    For R=31, G=1, B=10, the following 2 bytes is the palette entry:

      0xF8 0x2a

  3.2 BITMAP

    BITMAP consists of 16-bit big-endian encoded words. For each pixel
    BPP least significant bits are read, an appropriate palette entry is
    applied, and the result is sent in the RGB565 format. If BPP isn't
    a power of two, words do not align with data.

    E.g. if BPP=3, and 5 pixels have been read from a 16-bit data word,
    there is 1 bit left. In this case, read the next word, shift it up
    by the amount of bits still left (in this case 1), then continue
    decoding.

    Because of the way the pixels are encoded, bitmaps are always padded
    up to a boundary of 16 bits.

    Example 1:
    8 4-bit pixels with values of 0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7
    are encoded in the file as:

      0x32 0x10 0x76 0x54

    Example 2:
    4 5-bit pixels with values of 0x0, 0x1, 0x2, 0x3
    are encoded in the file as:

      0x88 0x20 0x8a 0x41 0x00 0x39


4. Metadata

   METABYTES

   4 bytes: BITS31:24 BITS23:16 BITS15:8 BITS7:0

   Example:
   If the length is 0x19 bytes, the bytes are:

     0x00 0x00 0x00 0x19

   METADATA

   0 or more NUL-terminated strings.

   Example:

     0x44 0x41 0x54 0x45 0x3d 0x32 0x30 0x32 "DATE=202"
     0x31 0x2d 0x30 0x31 0x2d 0x32 0x38 0x20 "1-01-28 "
     0x31 0x30 0x3a 0x33 0x36 0x3a 0x30 0x35 "10:36:05"
     0x00                                    "\0"



5. Very Simple Example File

  Below is a very simple example file with two small entries.

    0000  1c 9a 00 02 00 00 00 46  00 00 14 02 02 02 00 00  |.......F........|
    0010  1e 08 02 04 00 00 f8 00  07 e0 00 1f 00 e4 00 00  |.............|
    0020  00 1f 07 e0 07 ff f8 00  f8 1f ff e0 ff ff 10 82  |........|
    0030  21 04 31 86 42 08 52 8a  63 0c 84 10 c6 18 32 10  |!.1.B.R.c....2.|
    0040  76 54 ba 98 fe dc 00 00  00 19 44 41 54 45 3d 32  |vT.....DATE=2|
    0050  30 32 31 2d 30 31 2d 32  38 20 31 30 3a 33 36 3a  |021-01-28 10:36:|
    0060  30 35 00                                          |05.|

  Offset 0x00:

    0x1c 0x9a                      ID 0x1c9a

  Offset 0x02:

    0x00 0x02                      NUMBEROFICONS = 2

  Offset 0x04

    0x00 0x00 0x00 0x46            METAADDR = 0x46

  Offset 0x08:

    0x00 0x00 0x14 0x02 0x02 0x02  ICONDESCR0: Data at 0x14, W=2, H=2, BPP=2

  Offset 0x0e:

    0x00 0x00 0x1e 0x08 0x02 0x04  ICONDESCR0: Data at 0x1e, W=8, H=2, BPP=4

  Offset 0x14:

    0x00 0x00                      PALETTE0_0: R= 0, G= 0, B= 0
    0xf8 0x00                      PALETTE0_1: R=31, G= 0, B= 0
    0x07 0xe0                      PALETTE0_2: R= 0, G=63, B= 0
    0x00 0x1f                      PALETTE0_3: R= 0, G= 0, B=31

  Offset 0x01d:

    0x00 0xe4   BITMAP pixels 0x0, 0x1, 0x2, 0x3 (black, reg, green, blue)
                Note: only half of the 16 bits were needed to encode 4 2-bit
                pixels.

  Offset 0x1e:

    0x00 0x00                      PALETTE1_0: R= 0, G= 0, B= 0
    0x00 0x1f                      PALETTE1_1: R= 0, G= 0, B=31
    0x07 0xe0                      PALETTE1_2: R= 0, G=63, B= 0
    0x07 0xff                      PALETTE1_3: R= 0, G=63, B=31
    0xf8 0x00                      PALETTE1_4: R=31, G= 0, B= 0
    0xf8 0x1f                      PALETTE1_5: R=31, G= 0, B=31
    0xff 0xe0                      PALETTE1_6: R=31, G=63, B= 0
    0xff 0xff                      PALETTE1_7: R=31, G=63, B=31
    0x10 0x82                      PALETTE1_8: R= 2, G= 4, B= 2
    0x21 0x04                      PALETTE1_9: R= 4, G= 8, B= 4
    0x31 0x86                      PALETTE1_A: R= 6, G=12, B= 6
    0x42 0x08                      PALETTE1_B: R= 8, G=16, B= 8
    0x52 0x8a                      PALETTE1_C: R=10, G=20, B=10
    0x63 0x0c                      PALETTE1_D: R=12, G=24, B=12
    0x84 0x10                      PALETTE1_E: R=16, G=32, B=16
    0xc6 0x18                      PALETTE1_F: R=24, G=48, B=24

  Offset 0x3e:

    0x32 0x10   BITMAP pixels 0x0, 0x1, 0x2, 0x3 (black, blue, green, cyan)
    0x76 0x54   BITMAP pixels 0x4, 0x5, 0x6, 0x7 (red, magenta, yellow, white)
    0xba 0x98   BITMAP pixels 0x8, 0x9, 0xa, 0xb (greyscale, dark to middle)
    0xfe 0xdc   BITMAP pixels 0xc, 0xd, 0xe, 0xf (greyscale, middle to light)

  Offset 0x46:

    0x00 0x00 0x00 0x19            METABYTES = 0x19

  Offset 0x4A:

    0x44 0x41 0x54 0x45 0x3d 0x32 0x30 0x32 "DATE=202"
    0x31 0x2d 0x30 0x31 0x2d 0x32 0x38 0x20 "1-01-28 "
    0x31 0x30 0x3a 0x33 0x36 0x3a 0x30 0x35 "10:36:05"
    0x00                                    "\0"

  File size: 0x63 bytes.
