Logo LSD Macintosh Icons

Summary: Information page on Macintosh icons. What are they? How are they built? Is it possible to produce them on a PC?

Introduction

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.

Technical Aspects of Custom Icons

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).

Folder Custom Icons

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).

Volume Custom Icons

Under Mac OS 9 and below, the root folder is treated like a normal folder, and should contain the same 'icon ' file.
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.

WinComposer

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.

Different Resource Types Used for Icons

SignatureComments
cicnIcons 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.
clutColor 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.
h8mkMask 32*32, 256 transparency levels, length 2304 bytes (0x900).
ich#Icon 48*48, B&W + mask, length 576 bytes (0x240)
ich4Icon 48*48, 16 colors, size 1152 bytes (0x480)
ich8Icon 48*48, 256 colors, size 2304 bytes (0x900)
icl4Icon 32*32, 16 colors (4 bits), size 512 bytes (0x200)
icl8Icon 32*32, 256 colors (8 bits), size 1024 bytes (0x400)
icm#Mini-icons (12*16), B&W + mask
icm4Mini-icons (12*16), 16 colors, 4 bits
icm8Mini-icons (12*16), 256 colors, 8 bits
ICN#Icon 32*32 B&W (1 bit/pixel) + mask, size 256 bytes (2 * 128).
icnsSingle resource container containing several icon resources. Under Mac OS X, this icon resource can appear in a file with the *.icns extension.
IconMenu icons
ICONIcons for menus and dialogs, 32*32, B&W, without mask. Always displayed on a white background, therefor no need for a mask.
ics#Icon 16*16, B&W, length 64 bytes
ics4Icon 16*16, 16 colors, size 128 bytes
ics8Icon 16*16, 256 colors, size 256 bytes
ih32Icon 48*48, 32 bits, variable length (compressed resource).
il32Icon 32*32, 32 bits, variable length (compressed resource).
is32Icon 16*16, 32 bits, variable length (compressed resource).
it32Icon 128*128, 32 bits, variable length (compressed resource).
l8mkMask 32*32, 256 transparency levels, size 1024 bytes
s8mkMask 16*16, 256 transparency levels, size 256 bytes
SICNSystem (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).
t8mkMask 128*128, 256 transparency levels, length 0x00004008 (payload 16384)

The Modern icns Resource

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.

Compression Scheme

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.

Pseudocode:

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.
else:
   This is an uncompressed run, whose values follow.
   The length is byte +1.
   Read the bytes and put them in the current color channel.

Pomme LSD

Logiciels & Services Duhem
3, rue Pierre Haret - F-75009 Paris (France) - Tel. (+33) [0]149 700 455 - SIRET 381 149 996 00047 - EEC VAT FR32 381 149 996
email : sales (at) macdisk.com - web : http://www.macdisk.com
© Pierre Duhem 1995-2014 - All trademarks acknowledged. MacDisk is a trademark or a registered trademark of L&S Duhem under certain jurisdictions. Any comments are welcome.