GFF Format Summary: Microsoft Windows Cursor and Icon

This is G o o g l e's cache of http://www.oreilly.com/centers/gff/formats/miccur/. G o o g l e's cache is the snapshot that we took of the page as we crawled the web. The page may have changed since that time. Click here for the current page without highlighting. To link to or bookmark this page, use the following url: `http://www.google.com/search?q=cache:dgpSCZ8_GJwC:www.oreilly.com/centers/gff/formats/miccur/+windows++icon+transparent&hl=en&ie=UTF-8` Google is not affiliated with the authors of this page nor responsible for its content.
These search terms have been highlighted: | windows | icon | transparent

# Microsoft Windows Cursor and Icon

Also Known As: CUR, ICO

Type | Bitmap
Colors | 1-bit and 4-bit
Compression | None
Maximum Image Size | 4Gx4G pixels
Multiple Images Per File | Yes
Numerical Format | Little-endian
Originator | Microsoft
Platform | Microsoft Windows
Supporting Applications | Microsoft Windows
See Also | Microsoft Bitmap, OS/2 Bitmap, Microsoft RIFF

Usage
The Windows environment uses icons as graphical links to objects (data files and executable programs). Cursors are used by the pointing device as graphical indications of the current state of the Windows environment.

Comments
Windows icons and cursors are almost identical in format. In fact, cursor and icon bitmaps can be used interchangeably.

In an object-oriented graphical user interface--as Microsoft Windows is sometimes described--icons are small bitmaps containing an iconographic picture that makes an object accessible to the user. The "objects" made available by icons are: collections of data (files); executable programs (more files); and peripheral devices (the toys you have hooked up to your computer). Rather than typing a file or program name on a command line, applications are started and files manipulated by clicking on an icon, or "dragging and dropping" an icon on to a window or another icon.

A cursor, or pointer as they are also called, is a special type of icon that is used to track the location of the pointing device on the user interface. The cursor changes its appearance to indicate the state of the system and the user interface. Such states include that a search is in progress, an application is starting or stopping, or a user-initiated action is being processed. The appearance of the cursor also indicates what action may be performed based on the current position of the pointer on the display. For example, actions such as resizing a window or entering text may only be performed at specific locations within a window.

Although a wide variety of physical pointing devices (mouse, joystick, trackball, touch pad, light pen, pointing stick, etc.) are typically supported by a user interface, the input received by Windows is identical from all types of pointing devices.

Contents:
File Organization
File Details
For Further Information

Icons and cursors themselves are types of resources available in the Windows environment. When an application makes a request for Windows to display an icon or cursor, Windows must locate the appropriate file and choose which of the bitmaps stored in the file best fits the resolution and color depth of the display.

The icon displayed is chosen based on its size and number of colors. For example, a two-color icon 16x16 pixels in size might look good on a monochrome display at 640x480 resolution, but the same icon bitmap will probably look terrible on a 256-color, 1024x768 display. For such a high-resolution display, the choice of the 16-color, 64x64 pixel version of the icon would look much better. However, if the icon file only contains one bitmap, then that is the icon bitmap that will be displayed.

Icon and cursor bitmaps are typically very small. Under the 16-bit Windows environment (Win16) icons are traditionally square (16x16, 32x32, or 64x64 pixels in size) and have 16 or fewer colors. The 32-bit Windows (Win32) environment allows icons to be larger and have a greater pixel depth, such as 72x72 pixels with 256 colors. Win32 is also tolerant of rectangular icon formats.

Cursors under Windows 3.x are two-color (1-bit) bitmaps. Under Windows 4.x cursors with 8, 16, or more colors are possible. Cursors are also not limited to a specific range of sizes as are icons, although most cursors are 32x32 pixels in size.

Both cursor and icon data may be stored in separate file formats (*.ico and *.cur) on disk, or be stored as a Windows resource file (*.res) and embedded directly into a Windows executable file (*.exe), Dynamic Link Library (*.dll), Visual Basic control (*.vbx), or OLE control (*.ocx). (This article only discusses the ICO and CUR file formats and will leave the Windows Resource format to a future article.)

Simple animations may be created by the sequential display of several icon or cursor bitmaps in a continuous loop. These "flipbook" animations are not directly supported by the Win16 environment, but they do appear in some Windows applications.

A true animated cursor format was defined by Microsoft in 1992 as part of the RIFF multimedia specification. Animated cursors are the *.ani files you might have noticed on your hard drive if you use Windows 95 or Windows NT. They are actually little more than a collection of ICO files stored in a single ANI file. For more information on the format of Windows animated icons, see the Microsoft RIFF article.

If you are interested in the icon and pointer file formats used by OS/2, then have a look at the OS/2 Bitmap article. OS/2 uses its own flavor of the BMP format to store icon and pointer data.

It should also be noted that there is no formal specification for either the Windows icon or cursor file formats. In fact, there are no definitions for these file formats in the Windows Software Development Kit (SDK) header files. What information that can be found must be scraped up from Windows SDK manuals, Knowledge Base articles, and several sample applications. See the For Further Information section in this article for more details on additional reference material for Windows icons and cursors.

## File Organization

The Windows icon (ICO) and cursor (CUR) file formats are identical. Only the interpretation of the file data differs slightly. In fact, icon and cursor files may be used interchangeably by applications that realize this fact.

Every ICO and CUR file contains a header, a directory of bitmap entries, and one or more bitmaps that describes the appearance of an icon or cursor (shown below).

Header
Bitmap Directory
Bitmap 1
Bitmap 2
...
Bitmap N

The header stores information that is used to determine how many bitmaps are in the file. ICO and CUR files will contain one or more uncompressed bitmaps. Each entry in the bitmap directory will contain information that describes one of the bitmaps stored in the file. The directory will contain one entry per bitmap.

### File Details

As Windows ICO and CUR files are nearly identical, we will first look at the ICO format and then discuss the differences between the ICO and CUR formats.

The ICO header contains only a Windows resource identification value and the count of the number of icons stored in the file. The header is immediately followed by a directory that contains information for all the icons stored in the ICO file. The directory is followed by the icon bitmaps themselves.

The following structure illustrates the entire format of an ICO (or CUR) file:

    typedef struct _IconFile
    {
        WORD      Reserved;      /* Reserved (always 0) */
        WORD      ResourceType;  /* Resource ID (always 1) */
        WORD      IconCount;     /* Number of icon bitmaps in file */
        ICONENTRY IconDir[];     /* Directory of icon entries */
        ICONDATA  IconData[];    /* Listing of ICO bitmaps */
    } ICONFILE;

Reserved is a two-byte value that is always zero in all ICO files.

ResourceType is the Windows resource identifier type value. For icons this value is always 1.

IconCount is the number of icons stored in the ICO file. It is also the number of elements in the Icons array.

IconDir is an array of directory entries that describe the icons stored in the ICO file. There will be one entry per icon stored. The number of entries will also equal the value of the IconCount field. Each ICONENTRY element has the following format:

    typedef struct _IconEntry
    {
        BYTE  Width;        /* Width of icon in pixels */
        BYTE  Height;       /* Height of icon in pixels */
        BYTE  NumColors;    /* Maximum number of colors */
        BYTE  Reserved;     /* Not used (always 0) */
        WORD  NumPlanes;    /* Not used (always 0) */
        WORD  BitsPerPixel; /* Not used (always 0) */
        DWORD DataSize;     /* Length of icon bitmap in bytes */
        DWORD DataOffset;   /* Offset position of icon bitmap in file */
    } ICONENTRY;

Width and Height are the size of the icon in pixels. Only the values of 16, 32, and 64 for these fields are accepted by Win16. Other values are also accepted by Win32. And as square icons are the most common, both of these fields will typically store the same value (although 32x16 icons were commonly used for the now antiquated 300x200 CGA display mode).

NumColors is the maximum number of colors that may appear in the icon. The values 2, 8, and 16 are the only values accepted by Win16. Other values are accepted by Win32. If the bitmap contains 256 or more colors the value of NumColors will be 0.

Reserved is not used and is always zero. This field was probably included as an element-alignment padding structure.

NumPlanes and BitsPerPixel are not used and are always 0. Earlier revisions of the ICO format may have used these fields, but in the current revision of ICO this information is now stored in the icon data itself.

DataSize is the length of the icon data in bytes for this entry. This value is the total size of both bitmaps used to render the icon (explained below).

DataOffset is the location of the icon data for this entry. The offset is measured in bytes from the start of the ICO file.

Following the icon directory is the data for the icon(s) themselves (the IconData array in the ICONFILE structure). Each icon stored in an ICO file is actually an independent file format in itself, and contains a header, a color palette, icon bitmap data, and a display bit mask.

The start of each section of icon data is specified by the IconOffset field in each icon directory entry. Each section of icon data has the following format:

    typedef struct _IconData
    {
        WIN3XBITMAPHEADER   Header;         /* Bitmap header data */
        WIN3XPALETTEELEMENT Palette[];      /* Color palette */
        BYTE                XorMap[];       /* Icon bitmap */
        BYTE                AndMap[];       /* Display bit mask */
    } ICONDATA;

Header is a 40-byte Windows 3.x BMP file header structure. Only the Size, Width, Height, Planes, BitsPerPixel, and SizeOfBitmap fields of this header are actually used. All other fields in this structure (Compression, SizeOfBitmap, HorzResolution, VertResolution, ColorsUsed, and ColorsImportant) are set to zero. Refer to the Microsoft Windows Bitmap article for more information on this header structure.

Palette is the color palette for the data in the XorMap array. The BitsPerPixel field of the Header is used to determine the number of elements in the Palette array (BitsPerPixel >= 1). For two-color icons there will be two palette entries; for 8- and 16-color icons there will be 16 entries. Each palette element is a four-byte RGB structure as described in the Microsoft Windows Bitmap article.

XorMap contains the icon's foreground bitmap. The size of the pixels is indicated by the BitsPerPixel values in the header. Two-color (monochrome) bitmaps are stored as one bit per pixel; 8- and 16-color bitmap data is stored as 4 bits per pixel. Each pixel value is actually an index into the Palette color map.

AndMap is the icon's background bit mask. This is a 1-bit-per-pixel mask that is the same size (in pixels) as the XorMap. This mask is used to map the visible area of the icon on the screen before the icon is actually displayed.

At first it may seem redundant to have Height and Width fields in both the icon entry (ICONENTRY) and the icon header (WIN3XBITMAPHEADER) structures. In fact, the Height and Width values stored in the icon header are the combined size of the XorMap and AndMap bitmaps. The Width values in the two structures will be the same, but the Height value in the icon header will be double that of the Height value in the icon directory entry. The icon directory specifies the actual size of the icon as it appears on the display, and the icon header specifies the size of the data used to create the icon.

Under the Windows environment an icon is displayed by first looking through an ICO file and determining which icon bitmap best matches the number of colors and resolution of the display. The AND bit mask for the chosen icon is bitwise ANDed with the pixels on the display where the icon will appear. This removes the pixels from the display and leaves a virtual "hole" in the display where the non-transparent parts of the icon will appear. Finally, the XOR map is bitwise XORed to the same pixels on the display. This operation adds the icon's color to the display.

Let's look at this process in more detail. Assume we have an ICO file that contains several "happy face" icon bitmaps. The ICO file actually stores four different bitmap variations of the same happy face:

Width | Height | Number of Colors | BitsPerPixel
--- | --- | --- | ---
8 | 8 | 16 | 4
16 | 16 | 16 | 4
32 | 32 | 16 | 4
48 | 48 | 64 | 8

When happyfac.ico is loaded, one of the icon bitmaps must be chosen that matches resolution of the display. The ICO reader searches each ICO directory entry for a "best fit" icon bitmap. For a 320x240x16 display the 8x8, 16-color "happy face" icon would probably look best. The reader then seeks to the offset of the selected icon data.

Next, the AndMap bitmap must be loaded and ANDed to proper location on the display. The AndMap data follows the XorMap data, so the ICO reader must skip past the XorMap data to read the AndMap data. It is important to note that the scan lines of data in the AndMap and XorMap bitmaps are stored from the bottom up (the origin is in the lower left-hand corner). That is, the first scan line of the bitmap is actually the last scan line of the icon.

In the 8x8x16 bitmap chosen, the AndMap contains only eight bytes of data (8 rows x 8 columns):

    FF 99 99 E7 66 BD C3 FF

In this form the data looks meaningless. Looking at the AndMap as an array of bits we can see our happy face more clearly:

    1 1 1 1 1 1 1 1
    1 0 0 1 1 0 0 1
    1 0 0 1 1 0 0 1
    1 1 1 0 0 1 1 1
    0 1 1 0 0 1 1 0
    1 0 1 1 1 1 0 1
    1 1 0 0 0 0 1 1
    1 1 1 1 1 1 1 1

If we ANDed this bitmap to a location on the display that was all the same color we would see this result:

    C C C C C C C C     1 1 1 1 1 1 1 1     C C C C C C C C
    C C C C C C C C     1 0 0 1 1 0 0 1     C 0 0 C C 0 0 C
    C C C C C C C C     1 0 0 1 1 0 0 1     C 0 0 C C 0 0 C
    C C C C C C C C  +  1 1 1 0 0 1 1 1  =  C C C 0 0 C C C
    C C C C C C C C     0 1 1 0 0 1 1 0     0 C C 0 0 C C 0
    C C C C C C C C     1 0 1 1 1 1 0 1     C 0 C C C C 0 C
    C C C C C C C C     1 1 0 0 0 0 1 1     C C 0 0 0 0 C C
    C C C C C C C C     1 1 1 1 1 1 1 1     C C C C C C C C
       Display              AndMap           ANDed Display

Each 1 bit in the AndMap preserved a display pixel (the transparent portion of the icon) and each 0 bit removed a display pixel (the opaque portion of the icon).

Finally, we need to XOR the XorMap icon pixel values into the hole we punched into the display. Remember that the actual pixel color values are stored in the color palette, and the bitmap data is only an index map that indicates where the pixel colors should be written.

In our happy face icon each pixel in the bitmap is four bits in size and packed two pixels per byte. The XorMap bitmap data appears as such:

    00 00 00 00
    04 40 04 40
    04 40 04 40
    00 0F F0 00
    90 0F F0 09
    09 00 00 90
    00 99 99 00
    00 00 00 00

In case you can't see the happy face, the eyes are the value 0x4, the nose 0xF, and the smile 0x9. We now need to map the bitmap index values to color values in the palette. Let's assume that index 0x04 maps to color value 0x1, 0xF to 0xF, and 0x9 to 0x07.

With the color values determined, we XOR the pixel values to the same region we applied the AndMap mask. The 0 bits on the display (the black regions) indicate the non-transparent pixels of the icon. It is the pixel represented by the 0 bits that will have their color changed to that of the icon. The transparent pixels will retain the original color of the display:

    C C C C C C C C     0 0 0 0 0 0 0 0     C C C C C C C C
    C 0 0 C C 0 0 C     0 1 1 0 0 1 1 0     C 1 1 C C 1 1 C
    C 0 0 C C 0 0 C     0 1 1 0 0 1 1 0     C 1 1 C C 1 1 C
    C C C 0 0 C C C  +  0 0 0 F F 0 0 0  =  C C C F F C C C
    0 C C 0 0 C C 0     7 0 0 F F 0 0 7     7 C C F F C C 7
    C 0 C C C C 0 C     0 7 0 0 0 0 7 0     C 7 C C C C 7 C
    C C 0 0 0 0 C C     0 0 7 7 7 7 0 0     C C 7 7 7 7 C C
    C C C C C C C C     0 0 0 0 0 0 0 0     C C C C C C C C
     ANDed Display       XORed values       Icon on Display

A monochrome (1-bit) icon or cursor will contain only four possible pixels values: black, white, transparent, and inverted. A transparent or inverted pixel may be either black or white in color. The color palette will contain only two colors, which are black (entry zero) and white (entry one). The transparent color is the original color of the display pixels. Inverted is the inverse color of the display pixels. Inverted pixels are responsible for the shadowy or shimmering effect you may have noticed when some cursors are moved across the display.

The possible combined bitmaps values are shown in Table Microsoft Windows Cursor and Icon-1.

Table Microsoft Windows and Cursor Icon-1. Monochrome icon and cursor mask value combinations
| AndMap Value | XorMap Value | Display Pixel Value | Resulting Color
--- | --- | --- | --- | ---
Black | 0 | 0 | 0 or 1 | 0
White | 0 | 1 | 0 or 1 | 1
Transparent | 1 | 0 | 0 | 0
| 1 | 0 | 1 | 1
Inverted | 1 | 1 | 0 | 1
| 1 | 1 | 1 | 0

### CUR File Format

Everything we have covered for the ICO format also applies to the CUR format with only a few exceptions:

The value of the ResourceType field in the header (ICONFILE) is 2, indicating the file contains cursor bitmap data.

The cursor directory entry redefines two unused fields to store hot spot information and modifies the possible values of two additional fields:

    typedef struct _IconEntry
    {
        BYTE  Width;        /* Width of cursor in pixels */
        BYTE  Height;       /* Height of cursor in pixels */
        BYTE  NumColors;    /* Maximum number of colors */
        BYTE  Reserved;     /* Not used (always 0) */
        WORD  XHotSpot;     /* X location of cursor's hot spot */
        WORD  YHotSpot;     /* Y location of cursor's hot spot */
        DWORD DataSize;     /* Length of cursor bitmap in bytes */
        DWORD DataOffset;   /* Offset position of cursor bitmap in file */
    } ICONENTRY;

Width and Height values in the icon directory may be any size, although 32x32 pixels is the most common size for Windows cursors.

NumColors is always 2 (1-bit, black and white) in a Win16 cursor file. Win32 cursors have the same color ranges as icons.

XHotSpot and YHotSpot store the coordinates of the cursor's hot spot. The X coordinate is relative to the cursor bitmap's left edge; the Y coordinate is relative to the cursor's top edge. Both coordinates are measured in pixels.

The hot spot is a single pixel in size. When the user clicks the pointing device, the coordinates of the hot spot are sent to Windows. Windows then performs an action based on where the hot spot is on the display and on the current state of Windows itself.

And finally, ICO and CUR files do not contain any type of identification signature or "magic number". A file reader may assume that all .ico files are Windows icons and all .cur files are Windows cursors, but it would haphazard to do so. If we assume instead that all ICO files will never contain more than 256 bitmaps (a very safe assumption) then an ICO file will begin with the byte sequence 00 00 01 00 XX 00, where XX may be any byte value. Making the same assumption for cursors, all CUR files will begin with the byte sequence 00 00 02 00 XX 00.

## For Further Information

The primary sources of ICO and CUR information are the Microsoft Win16 and Win32 Software Development Kits (SDK) and the Microsoft Developer Network Library (MSDN) CD-ROMs.

The Win16 and Win32 SDKs are distributed with the Microsoft Visual C++ compiler and the MSDN CD-ROMs. The following SDK references and Knowledge Base articles discuss the ICO, CUR, and DIB bitmap formats:

> Microsoft Windows Software Development Kit, Programmers' Reference, Volume 4: Resources

> Win32 SDK on-line help for the BITMAPINFO structure

> Q81498 SAMPLE: DIBs and Their Uses

> Q94326 SAMPLE: 16 and 32 Bits-Per-Pel Bitmap Formats

> Specs: Icons in Win32

> Technical Articles: Win32 Binary Resource Formats

You can find the SDK documents on the MSDN Library CD-ROMs. The MSDN Library is only available by subscription. However, Microsoft has made the October 1995 MSDN library available at:

> ftp://ftp.microsoft.com/developr/MSDN/OctCD/

One other MSDN Library file of interest is:

> MSDN Frequently Asked Questions (FAQ)
> PSS ID Number: Q116437, 02-16-1996
> ftp://ftp.microsoft.com/developr/MSDN/kb/Q116/4/37.txt
> http://www.microsoft.com/msdn/msdnfaq.htm

The Win32 SDK also contains two sample applications that are necessary for understanding icons and cursors. They are IconPro and imagedit (an icon and cursor bitmap editor). Both of these sample applications are distributed with complete source code, but no compiled binaries. The binaries are only distributed with the Windows 95 and Windows NT Resource Kits.

You can contact the Microsoft MSDN group at:

> Microsoft Developers Network
> Voice: 206-936-2490
> Email: msdn@microsoft.com
> WWW: http://www.microsoft.com/msdn/

And here's the addresses of Microsoft. Try getting what you need from their FTP and web sites first:

> Microsoft Corporation
> One Microsoft Way
> Redmond, WA 98052-6399
> FTP: ftp://ftp.microsoft.com/
> WWW: http://www.microsoft.com/
> CIS: WINSDK and MSWIN32 forums

Copyright © 1996, 1994 O'Reilly & Associates, Inc. All Rights Reserved.