This page is a rather technical one, on Macintosh icon resources. Since I had a pretty hard time finding out several of those pieces of information, I decided to publish it on the Web site.
Technically, the matter is not very complicated. Custom icons are normal icon resources, but must bear the "magical" -16455 identification number. More, the "custom icon" flag of the folder record must be set.
In the case of files, the same graphic resources must be stored in the resource fork of the file. This time, the flag is set in the file record.
Those icon resources are not stored by the Finder in its database (Desktop).
The folder (the root folder for the volume) must contain a hidden file named "icon " (0x0D as the last character) holding correct graphic resources (see the page on Macintosh Icons in WinComposer help for more technical information).
Under Mac OS 9 and below, the root folder is treated like a normal folder, and should contain the same 'icon
Under Mac OS X, the file holding the icon must be named '.VolumeIcon.icns' and the icon format must be an 'icns' resource. This resource is stored in the data fork.
If you target all versions of the Macintosh operating system, you may include both files. Older versions won't do anything with the '.VolumeIcon.icns' file. Under Mac OS X, all files beginning with a dot are (like under Unix) treated as system and hidden files. This is not the case under Mac OS 9 and below. You should therefore hide those files (set the hidden flag) to avoid perplexity amongst users.
Visitors interested by a more basic presentation of Macintosh (custom) icons should visit our page on WinComposer, a Windows utility to compose Macintosh icons.
See also our page on Macintosh Custom Icons, how to produce them with WinComposer and how to integrate them in the CD-ROMs built by MacImage.
|Icons for menus and dialogs, color (cicn = color icon), containing a palette, a bitmap and a mask. It can be an icon (32*32) with mask or an icon of any size without mask. The color depth can be specified. See IM:Imaging with QuickDraw.|
|Color Look-Up Table. Resource containing the look-up table (palette) used by the Palette Manager. Main default palettes are the B&W palette, the 16 color palette, the icon palette and the 256 color palette. See the 256 color palette displayed by WinComposer.|
|Mask 32*32, 256 transparency levels, length 2304 bytes (0x900).|
|Icon 48*48, B&W + mask, length 576 bytes (0x240)|
|Icon 48*48, 16 colors, size 1152 bytes (0x480)|
|Icon 48*48, 256 colors, size 2304 bytes (0x900)|
|Icon 32*32, 16 colors (4 bits), size 512 bytes (0x200)|
|Icon 32*32, 256 colors (8 bits), size 1024 bytes (0x400)|
|Mini-icons (12*16), B&W + mask|
|Mini-icons (12*16), 16 colors, 4 bits|
|Mini-icons (12*16), 256 colors, 8 bits|
|Icon 32*32 B&W (1 bit/pixel) + mask, size 256 bytes (2 * 128).|
|Single resource container containing several icon resources. Under Mac OS X, this icon resource can appear in a file with the *.icns extension.|
|Icons for menus and dialogs, 32*32, B&W, without mask. Always displayed on a white background, therefor no need for a mask.|
|Icon 16*16, B&W, length 64 bytes|
|Icon 16*16, 16 colors, size 128 bytes|
|Icon 16*16, 256 colors, size 256 bytes|
|Icon 48*48, 32 bits, variable length (compressed resource).|
|Icon 32*32, 32 bits, variable length (compressed resource).|
|Icon 16*16, 32 bits, variable length (compressed resource).|
|Icon 128*128, 32 bits, variable length (compressed resource).|
|Mask 32*32, 256 transparency levels, size 1024 bytes|
|Mask 16*16, 256 transparency levels, size 256 bytes|
|System (S) or small icons. Format 12*16, stored in a 16*16 matrix. The format allows storing any number of icons, but, by convention, there is always a single one (B&W with mask).|
|Mask 128*128, 256 transparency levels, length 0x00004008 (payload 16384)|
Most of above icon resources have a rather historical nature. The current trend is to use exclusively the icns resource. This resource is a container, with several individual icon resources contained within it. The system accesses therefore in a single stroke all necessary icon resources.
This resource kind, which is not known by the old and trusty ResEdit utility (which only displays the hex contents), was introduced with Mac OS 8.5.
For safety reasons, one should always include in the resource file an older ICN# resource, which can be drawn by all versions of the system, even if the probability of being used on an older system is now rather low.
In the same vein, it is probably overkill to include in such a resource the older 4bpp icon resources (16 color palette).
A modern icns resource should therefore contain the ICN# resource and the 32 bpp icons, in 32*32 pixels, 48*48 pixels and maybe 128*128 pixels.
The data of 32 bits/pixel icons may be compressed. One should check whether the data length corresponds to the theoretical length (width * height). If not, the data is compressed, channel by channel. The alpha channel is not stored in the data set. It should be recovered from the corresponding ?8mk resource (see the table above).
In some icon sizes, there is a 32bit integer at the beginning of the run, whose role remains unknown.
The compression method is not documented by Apple. It was reverse-engineered, probably by Peter Stuer. I used as a basis the code of ResCafé, an exploration utility for Macintosh resources, written in Java by G. Brannon Smith.
For each of the color channels (red, green, blue), and for the maximum length (width * height of the icon), read a byte.
if bit 8 of the byte is set:
This is a compressed run, for some value (next byte).
The length is byte - 125.
Put so many copies of the byte in the current color channel.
This is an uncompressed run, whose values follow.
The length is byte +1.
Read the bytes and put them in the current color channel.