Format Name: Apple IIGS Icon data structure
Used on: Apple IIGS only
Size: variable, mimimum=8 bytes
Compression: None
Unpacks to: Icons, variable size
Information from Apple IIGS Toolbox Reference: Volume II
  (written by Apple Computer Co, pub Addison-Wesley. ISBN 0-201-17747-1)

Conventions: bit[7..0] is one byte, with 0 in the least significant
place. A word is 2 bytes, least significant byte stored first in ram:
bits[7..0], bits [15..8]. All hexadecimal numbers will be prefaced
with the C-style '0x'; all other numbers may be assumed to be base 10.
To read one word, this code fragment may help:

short readword(char *ptr)
{ return ((*ptr) + ((*(ptr+1))<<8)); }

Icons are used mainly for program / document icons in the Apple IIGS
Finder, though some programs will use them on occasion. They can either
be stored in the resource fork of a files, or bundled together in a
Finder Icons file (see descrtiption of Finder Icons file)

The icon record is a variable length data structure, consisting of
the following info.

Offset     Description
+0         Word: iconType. Bit [15] =1 for a color icon, =0 for black & white.
+2         Word: iconSize Number of bytes in icon image
+4         Word: iconHeight . Height of icon in pixels
+6         Word: iconWidth. Width of icon in pixels
+8         Icon image, iconSize bytes long, each row of pixels is
            1+(iconWidth-1)/2  bytes wide
+8+iconSize Icon mask, iconSize bytes long, each row of pixels is
            1+(iconWidth-1)/2  bytes wide

   The icon image and mask are both written in rows from top to bottom
in linear order. Each byte contains 2 4-bit pixels; bits [7..4] are
the left pixel, and bits [3..0] are the right pixel.

   The mask affects how it is drawn to the screen. For most icons, the
calls to draw them produce the following effect. The mask is ANDed
to the target region, and then the icon image is ORed on top of that.
This allows transparent icons by setting a pixel's nibble in both the
icon image and mask to 0xF. 

Description written by Nathan Mates (nathan@visi.com), August 1996.