===

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

