===
IZX
===

  IZX is a royalty-free standard format and reference implementation for
  ZX-Spectrum icons.

  An IZX icon has 18x18 pixels, centered on a 2x2 char attribute area on screen,
  with an additional pixel line/column in every direction. This somewhat unusual
  format allows far more interesting images than a more conventional 16x16 size.


=============
SPECIFICATION
=============

  The IZX icon size is 18x18 pixels. It's divided in 4 quadrants of 9x9 pixels
  each, such that each quadrant contains 1 entire char position (i.e. 8x8 pixels
  with attribute), plus an extra outer pixel line and column.

  Each quadrant attribute can be either "opaque" (black ink against non-bright
  white paper) or "transparent" (black ink but preserving previous paper color).
  The extra pixels in the "outer pixel line and column" are always rendered as
  "transparent".

  The IZX file format contains 324 bits of bitmap pixel data (18 lines with 18
  bits each) and 4 bits of mask (0 as "transparent" or 1 as "opaque" for each
  quadrant), thus taking 41 bytes (328 bits) per icon. The bits are ordered in
  such a way to maximize rendering efficiency, as described below:

  * All bits from first and last pixel columns are grouped together, in the
    following order: left side of first pixel line, right side of first pixel
    line, left side of second pixel line, etc. This data takes 18x2 = 36 bits.
    Afterwards there are another 4 bits corresponding to the attribute mask, in
    the following order: top left mask, top right mask, lower left mask, lower
    right mask. Therefore the total is 5 bytes (40 bits). Let's call them G1,
    G2, ... G5.

  * The remaining image (corresponding to the central 2x2 char area) is simply
    stored as entire bytes, ordered from left to right, top down. This takes
    18x2 = 36 bytes. Let's call them B1, B2, ... B36.

  * These bytes are "intercalated" in the IZX format, in the following order:
    G1, B1-B8, G2, B9-B16, G3, B17-B24, G4, B25-B32, G5, B33-B36.


======
DRIVER
======

  The IZX icon driver is a free reference implementation of the IZX icon format
  standard for the ZX-Spectrum.

  Two variants are provided in this package: the simpler version "IZXdriver" is
  both smaller and faster, although the enhanced version "IZXdriver+" provides
  support for clipping.


========
CLIPPING
========

  The enhanced version "IZXdriver+" supports clipping, that controls visibility
  for each quadrant. Moreover, pixels and attributes are controlled separately.
  An additional parameter called "clip" indicates quadrant pixels and/or
  attributes that must be hidden, according to the following table:


      PIXEL CLIP     PIXEL CLIP
      (IN HEX)       (DECIMAL)
      +---+---+      +---+---+
      |$01|$02|      | 1 | 2 |
      +---+---+      +---+---+
      |$04|$08|      | 4 | 8 |
      +---+---+      +---+---+


      ATTR CLIP      ATTR CLIP
      (IN HEX)       (DECIMAL)
      +---+---+      +---+---+
      |$10|$20|      | 16| 32|
      +---+---+      +---+---+
      |$40|$80|      | 64|128|
      +---+---+      +---+---+


  By default, all parts are displayed (i.e. clip = 0). If you need to hide
  certain parts, simply calculate clip by adding the corresponding values from
  above. For instance:

  * to draw an icon without top right quadrant use: clip = 2+32 = 34
  * to draw an icon without changing lower attributes use: clip = 64+128 = 192


=====
USAGE
=====

  To use "IZXdriver+" from BASIC, first load it from tape, together with a
  collection of IZX icons, as follows:

CLEAR 54999: LOAD "IZXdriver+"CODE : LOAD "IZX icons"CODE

  By default, the IZX driver is compiled at address 55000 and the IZX icons are
  stored starting at address 55200.

  Afterwards declare a user-defined function to access the driver, as follows:

DEF FN z(r,c,i,p)=USR 55000

  Now whenever you want to draw an icon at a position (row,col) on screen, using
  a certain clip value, you just need to execute something like this:

RANDOMIZE FN z(row, col, icon, clip)

  In the user-defined function above, all parameters must be integers. Be aware
  that some mathematical expressions may provide floating point results that
  merely seem like integers, in this case you will need to use function "INT" to
  convert them.

  Since this user-defined function will always return zero, it can also be used
  with other commands instead of RANDOMIZE (if you need to avoid interfering
  with function "RND"). For instance:

FLASH FN z(row, col, icon, clip)

  Notice that the simpler version "IZXdriver" works exactly the same way, except
  the user-defined function doesn't have the 4th parameter above.

  If you prefer to call the IZX driver directly from an Assembly routine, it's
  easier to access "entry point" 2 or 3 instead. Check the source code for
  further details.


======
CONFIG
======

  The driver code is compiled starting at address 55000 by default. If you want
  a different address, change "org 55000" at the beginning of the source code,
  then recompile it.

  All icons are stored starting at address 55200 by default, occupying 41 bytes
  each. Therefore icon 0 is stored at 55200, icon 1 at 55241, icon 2 at 55282,
  and so on. If you want to store them at another address, either edit "ICONS"
  in the source code and recompile it, or directly modify the 2 bytes address
  at E=55025 (version "IZXdriver") or E=55030 (version "IZXdriver+"):

POKE E+1,INT (ICONS/256): POKE E,ICONS-256*PEEK (E+1)

  The opaque quadrants of an icon have BRIGHT 0;PAPER 7;INK 0 by default. If you
  want to use a different color, change address Q=55105 (version "IZXdriver") or
  Q=55073 (version "IZXdriver+"):

POKE Q,paper*8+bright*64


=======
LICENSE
=======

  The IZX icon format is an open standard. You can freely use it to design and
  distribute new icons, or use it inside your programs (even commercial 
  releases). The only requirement is that this standard should be strictly
  followed, without making irregular changes that could potentially cause
  incompatibilities.

  The IZX driver code is also freely available. You can use it in your programs
  (even for commercial releases), or adapt this code according to your needs. 
  The only requirement is that you must clearly indicate in your documentation
  that you have either used this code or created a derivative work based on it.


=======
CREDITS
=======

  IZX icon format - Copyright (c) 2013 Andrew Owen & Einar Saukas

  IZX icon driver - Copyright (c) 2013 Einar Saukas

  IZX icon images - Copyright (c) 1999-2013 Andrew Owen
