Format Name: Apple IIGS Finder Icons file
Used on: Apple IIGS only
Size: Variable, minimum = 0x001C
Compression: None.
Unpacks to: Icons of variable sizes
Filename Extensions: None defined (not used on Apple IIs)
ProDOS Filetypes: Filetype $CA, Auxtype $xxxx

Finder Icon data files are used by the Apple IIGS (not Macintosh)
Finder to associate icons with files. GS System 6.0 and later added
the capability to store raw icons in the resource fork and associate
them with rBundle information, but the information needed to take
apart a GS/OS resource fork (i.e. miniature filesystem) is far beyond
the scope of this document.

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]. A 'long' is 4 bytes, stored bits [7..0],
bits [15..8], bits [23..16], bits [31..24]. All hexadecimal numbers
will be prefaced with the C-style '0x'; all other numbers may be
assumed to be base 10. A 'Pascal String' consists of a length byte
followed by the ascii characters in the string, no terminator.  To
read one word, this code fragment may help:

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

long readlong(chat *ptr)
{ return (readword(ptr) + (readword(ptr+2)<<16)); }

An icon file has the following mandatory header. 

Offset     Description
+0x00      Long, used internally by the Finder. Must be 0x00000000 on disk
+0x04      Word, used to identity icon files. Must be 0x0001 on disk
+0x06      Long, used internally by the Finder. Must be 0x00000000 on disk
+0x0A      Pascal String, name of file (optional). This field is fixed
           at 16 bytes long, so the maximum string length is 15 characters
+0x1A      First Icon Data record

It then consists of any number of Icon Data Structures, each with the
following structure:

Offset     Description
+0x00      Word, length of icon data structure, including this value.
           A value of 0x0000 signals the end of records.
+0x02      Pascal string, pathname of app that owns icon. This field is
           fixed at 64 bytes, and can be empty (string length =0)
+0x42      Pascal string, containing a filename. '*' is a wildcard. This
           field is fixed at 16 bytes, and can be empty
+0x52      Word, GS Filetype of icon.
+0x54      Word, GS Auxillary Filetype of icon.
+0x56      Icon Data Structure for 'Large' icon of this file. See the
           Apple IIGS Icon Data Structure reference for how to decode this.
+(varies)  Icon Data Structure for 'Small' icon of file. Usually size is
           8x8, but may vary. See the Apple IIGS Icon Data Structure for
           how to decode this.

   Icons are internally 4-bit color lookup table entries. In the Finder,
the following colors are the standards:

0= Black, 1= Dark Blue, 2= Olive, 3= Gray 1 (*)
4= Dark Red, 5=Purple, 6= Orange, 7= Pink
8= Dark Green, 9= Blue-Green, 10=Bright Green, 11= Light green
12= Gray 2 (*), 13= Light Blue, 14= Yellow, 15=White

   As these colors are derived from the dithered pallette of the
Apple IIGS, it is hard to give exact RGB values. I'll see about
what color values conversion programs give. 

(*) Gray 1 and 2 look pretty much identical onscreen, but they
dither differently. Gray 2 is essentially 'White-Black', while
1 is 'Black-White'. Thus, they can be used to anti-alias lines
and the like for slightly wider lines.


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