=== 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