Object Files Flexible Precision Images File Formats Table of Contents

"ILBM" IFF Interleaved Bitmap

Document Date:
From:
Status of Standard:
 
  January 17, 1986
  Jerry Morrison, Electronic Arts
  Released and in use
 

1. Introduction

"EA IFF 85" is Electronic Arts' standard for interchange format files. "ILBM" is a format for a 2 dimensional raster graphics image, specifically an InterLeaved bitplane BitMap image with color map. An ILBM is an IFF "data section" or "FORM type", which can be an IFF file or a part of one. (See the IFF reference.)

[Ed.: Editorial remarks (the text appearing between "[Ed.:" and "End ed.]" brackets) have been inserted at certain points in this document to update information about the way ILBM is currently implemented. EW. End ed.]

An ILBM is an archival representation designed for three uses. First, a standalone image that specifies exactly how to display itself (resolution, size, color map, etc.). Second, an image intended to be merged into a bigger picture which has its own depth, color map, and so on. And third, an empty image with a color map selection or "palette" for a paint program. ILBM is also intended as a building block for composite IFF FORMs like "animation sequence" and "structured graphics". Some uses of ILBM will be to preserve as much information as possible across disparate environments. Other uses will be to store data for a single program or highly cooperative programs while maintaining subtle details. So we're trying to accomplish a lot with this one format.

This memo is the IFF supplement for FORM ILBM. Section 2 defines the purpose and format of property chunks bitmap header BMHD, color map CMAP, hotspot GRAB, destination merge data DEST, sprite information SPRT, and Commodore Amiga viewport mode CAMG. Section 3 defines the standard data chunk BODY. These are the "standard" chunks. Section 4 defines the nonstandard color range data chunk CRNG. Additional specialized chunks like texture pattern can be added later. The ILBM syntax is summarized in Appendix A as a regular expression and in Appendix B as a box diagram. Appendix C explains the optional run encoding scheme. Appendix D names the committee responsible for this FORM ILBM standard.

Details of the raster layout are given in part 3, "Standard Data Chunk". Some elements are based on the Commodore Amiga hardware but generalized for use on other computers. An alternative to ILBM would be appropriate for computers with true color data in each pixel, though the wealth of available ILBM images makes import and export important. [Ed.: A standard for 24-bit RGB, 8-bit grayscale and 32-bit RGBA is described in Appendix E. End ed.]

Reference:

"EA IFF 85" Standard for Interchange Format Files describes the underlying conventions for all IFF files.

Amiga« is a registered trademark of Commodore-Amiga, Inc.
Electronic Arts™ is a trademark of Electronic Arts.
Macintosh™ is a trademark licensed to Apple Computer, Inc.
MacPaint™ is a trademark of Apple Computer, Inc.


2. Standard Properties

ILBM has several property chunks that act on the main data chunk. The required property BMHD and any optional properties must appear before any BODY chunk. (Since an ILBM has only one BODY chunk, any following properties would be superfluous.) Any of these properties may be shared over a LIST of FORMs ILBM by putting them in a PROP ILBM. (See the EA IFF 85 document.)

[Ed.: BMHD is the only essential property chunk for ILBMs used with LightWave. For broader support of different image types, you may also want to support CMAP and possibly CAMG. The other property chunks (and CAMG) have Amiga-specific semantics. It's also safe to assume that you'll never encounter PROPs. End ed.]

BMHD

The required property BMHD holds a BitMapHeader as defined in the following documentation. It describes the dimensions of the image, the encoding used, and other data necessary to understand the BODY chunk to follow.

   typedef UBYTE Masking;  /* Choice of masking technique. */

   #define mskNone   0
   #define mskHasMask   1
   #define mskHasTransparentColor   2
   #define mskLasso  3

   typedef UBYTE Compression;    /* Choice of compression algorithm
      applied to the rows of all source and mask planes.  "cmpByteRun1"
      is the byte run encoding described in Appendix C.  Do not compress
      across rows! */
   #define cmpNone   0
   #define cmpByteRun1  1

   typedef struct {
      UWORD w, h;             /* raster width & height in pixels      */
      WORD  x, y;             /* pixel position for this image        */
      UBYTE nPlanes;          /* # source bitplanes                   */
      Masking masking;
      Compression compression;
      UBYTE pad1;             /* unused; ignore on read, write as 0   */
      UWORD transparentColor; /* transparent "color number" (sort of) */
      UBYTE xAspect, yAspect; /* pixel aspect, a ratio width : height */
      WORD  pageWidth, pageHeight;  /* source "page" size in pixels   */
   } BitMapHeader;

Fields are filed in the order shown. The UBYTE fields are byte-packed (the C compiler must not add pad bytes to the structure).

The fields w and h indicate the size of the image rectangle in pixels. Each row of the image is stored in an integral number of 16 bit words. The number of words per row is words=((w+15)/16) or Ceiling(w/16). The fields x and y indicate the desired position of this image within the destination picture. Some reader programs may ignore x and y. A safe default for writing an ILBM is (x, y) = (0, 0).

The number of source bitplanes in the BODY chunk (see below) is stored in nPlanes. An ILBM with a CMAP but no BODY and nPlanes = 0 is the recommended way to store a color map.

Note: Color numbers are color map index values formed by pixels in the destination bitmap, which may be deeper than nPlanes if a DEST chunk calls for merging the image into a deeper image.

The field masking indicates what kind of masking is to be used for this image. The value mskNone designates an opaque rectangular image. The value mskHasMask means that a mask plane is interleaved with the bitplanes in the BODY chunk (see below). [Ed.: These are usually the only masking options you'll encounter. End ed.] The value mskHasTransparentColor indicates that pixels in the source planes matching transparentColor are to be considered "transparent". (Actually, transparentColor isn't a "color number" since it's matched with numbers formed by the source bitmap rather than the possibly deeper destination bitmap. Note that having a transparent color implies ignoring one of the color registers. See CMAP, below.) The value mskLasso indicates the reader may construct a mask by lassoing the image as in MacPaint. To do this, put a 1 pixel border of transparentColor around the image rectangle. Then do a seed fill from this border. Filled pixels are to be transparent.

Issue: Include in an appendix an algorithm for converting a transparent color to a mask plane, and maybe a lasso algorithm.

A code indicating the kind of data compression used is stored in compression. Beware that using data compression makes your data unreadable by programs that don't implement the matching decompression algorithm. So we'll employ as few compression encodings as possible. The run encoding byteRun1 is documented in Appendix C, below.

The field pad1 is a pad byte reserved for future use. It must be set to 0 for consistency.

The transparentColor specifies which bit pattern means "transparent". This only applies if masking is mskHasTransparentColor or mskLasso (see above). Otherwise, transparentColor should be 0 (see above).

The pixel aspect ratio is stored as a ratio in the two fields xAspect and yAspect. This may be used by programs to compensate for different aspects or to help interpret the fields w, h, x, y, pageWidth, and pageHeight, which are in units of pixels. The fraction xAspect/yAspect represents a pixel's width/height. It's recommended that your programs store proper fractions in BitMapHeaders, but aspect ratios can always be correctly compared with the test

   xAspect * yDesiredAspect = yAspect * xDesiredAspect

Typical values for aspect ratio are width : height = 10 : 11 (Amiga 320 x 200 display) and 1 : 1 (Macintosh).

The size in pixels of the source "page" (any raster device) is stored in pageWidth and pageHeight, e.g. (320, 200) for a low resolution Amiga display. This information might be used to scale an image or to automatically set the display format to suit the image. Note that the image can be larger than the page.

CMAP

The optional (but encouraged) property CMAP stores color map data as triplets of red, green, and blue intensity values. The n color map entries ("color registers") are stored in the order 0 through n-1, totaling 3n bytes. Thus n is the ckSize/3. Normally, n would equal 2nPlanes.

A CMAP chunk contains a ColorMap array as defined below. Note that these typedefs assume a C compiler that implements packed arrays of 3-byte elements.

   typedef struct {
      UBYTE red, green, blue;       /* color intensities 0..255 */
   } ColorRegister;                 /* size = 3 bytes */

   typedef ColorRegister ColorMap[n];  /* size = 3n bytes */

The color components red, green, and blue represent fractional intensity values expressed in 256ths in the range 0 through 255 (e.g., 24/256). White is (255, 255, 255--i.e., hex 0xFF, 0xFF, 0xFF) and black is (0, 0, 0). If your machine has less color resolution, use the higher order color bits when displaying by simply shifting the CMAP R, G, and B values to the right. When writing a CMAP, storage of less than 8 bits each of R, G, and B was previously accomplished by left justifying the significant bits within the stored bytes (i.e., a 4-bit per gun value of 0xF, 0xF, 0xF was stored as 0xF0, 0xF0, 0xF0). This provided correct color values when the ILBM was redisplayed on the same hardware since the zeros were shifted back out.

However, if color values stored by the above method were used as-is when redisplaying on hardware with more color resolution, diminished color could result. For example, a value of (0xF0, 0xF0, 0xF0) would be pure white on 4-bit-per-gun hardware (i.e., 0xF, 0xF, 0xF), but not quite white (0xF0, 0xF0, 0xF0) on 8-bit-per-gun hardware.

Therefore, when storing CMAP values, it is now suggested that you store full 8 bit values for R, G, and B which correctly scale your color values for eight bits. For 4-bit RGB values, this can be as simple as duplicating the 4-bit values in both the upper and lower parts of the bytes--i.e., store (0x1, 0x7, 0xF) as (0x11, 0x77, 0xFF). This will provide a more correct color rendition if the image is displayed on a device with 8 bits per gun.

When reading in a CMAP for 8-bit-per-gun display or manipulation, you may want to assume that any CMAP which has 0 values for the low bits of all guns for all registers was stored shifted rather than scaled, and provide your own scaling. Use defaults if the color map is absent or has fewer color registers than you need. Ignore any extra color registers.

The example type Color4 represents the format of a color register in working memory of an Amiga computer, which has 4 bit video DACs. (The ":4" tells the C compiler to pack the field into 4 bits.)

   typedef struct {
      unsigned pad1 :4, red :4, green :4, blue :4;
   } Color4;   /* Amiga RAM format. Not filed. */

Remember that every chunk must be padded to an even length, so a color map with an odd number of entries would be followed by a 0 byte, not included in the ckSize.

[Ed: Information on storing 8-bit grayscale, 24-bit color, and 32-bit color plus alpha ILBMs can be found in Appendix E. End ed.]

GRAB

The optional property GRAB locates a "handle" or "hotspot" of the image relative to its upper left corner, e.g. when used as a mouse cursor or a "paint brush". A GRAB chunk contains a Point2D.

   typedef struct {
      WORD x, y;  /* relative coordinates (pixels) */
   } Point2D;

DEST

The optional property "DEST" is a way to say how to scatter zero or more source bitplanes into a deeper destination image. Some readers may ignore DEST.

The contents of a DEST chunk is a DestMerge structure:

   typedef struct {
      UBYTE depth;      /* # bitplanes in the original source  */
      UBYTE pad1;       /* unused; for consistency put 0 here  */
      UWORD planePick;  /* how to map source planes into destination */
      UWORD planeOnOff; /* default bitplane data for planePick */
      UWORD planeMask;  /* selects which bitplanes to store into */
   } DestMerge;

The low order depth number of bits in planePick, planeOnOff, and planeMask correspond one-to-one with destination bitplanes. Bit 0 with bitplane 0, etc. (Any higher order bits should be ignored.) "1" bits in planePick mean "put the next source bitplane into this bitplane", so the number of "1" bits should equal nPlanes. "0" bits mean "put the corresponding bit from planeOnOff into this bitplane". Bits in planeMask gate writing to the destination bitplane: "1" bits mean "write to this bitplane" while "0" bits mean "leave this bitplane alone". The normal case (with no DEST property) is equivalent to planePick = planeMask = 2nPlanes - 1.

Remember that color numbers are formed by pixels in the destination bitmap (depth planes deep) not in the source bitmap (nPlanes planes deep).

SPRT

The presence of an "SPRT" chunk indicates that this image is intended as a sprite. It's up to the reader program to actually make it a sprite, if even possible, and to use or overrule the sprite precedence data inside the SPRT chunk:

   typedef UWORD SpritePrecedence;
   /* relative precedence, 0 is the highest */

Precedence 0 is the highest, denoting a sprite that is foremost.

Creating a sprite may imply other setup. E.g. a 2 plane Amiga sprite would have transparentColor = 0. Color registers 1, 2, and 3 in the CMAP would be stored into the correct hardware color registers for the hardware sprite number used, while CMAP color register 0 would be ignored.

CAMG

A CAMG chunk is specifically for the Commodore Amiga computer. All Amiga-based reader and writer software should deal with CAMG. A CAMG chunk contains a single long word (length = 4) which specifies the Amiga display mode of the picture.

[Ed.: The Amiga has built-in support for interpreting the bits in a CAMG. Most of them are only meaningful on an Amiga, but two bits in the low word directly affect the interpretation of the data in the BODY chunk. Readers that attempt to support all ILBMs should test for these bits so that they can correctly translate the BODY. The bits are

   #define CAMG_HAM 0x800   /* hold and modify */
   #define CAMG_EHB 0x80    /* extra halfbrite */

HAM (hold-and-modify) mode allows the Amiga to display 12-bit and 18-bit RGB images using only 6 or 8 bits per pixel. HAM images store pixel values in the BODY chunk as codes that are divided into a mode in the high two bits and data in the other bits. The mode bits have the following interpretation.

00 - data bits are an index into the CMAP palette
01 - data bits contain the blue level
10 - data bits contain the red level
11 - data bits contain the green level

Unless a pixel is color-mapped (mode 00), only one of its three RGB levels is given in its code. The other two are assumed to be the same as those for the pixel to its left. If the pixel is the first one (the leftmost) in a scanline, the hold color is assumed to be (0, 0, 0). The number of data bits is 4 for standard HAM and 6 for HAM8, and the corresponding BitMapHeader nPlanes value will normally be 6 or 8.

It is possible for the mode to be a single bit. nPlanes will then be either 5 or 7. The single bit is the low bit, while the high bit is assumed to be 0, implying that only the blue level can be modified. For obvious reasons, this is rarely if ever encountered.

As described in the CMAP section, the data bits should be precision-extended when the levels are decoded to 24-bit. Regardless of the number of data bits, the maximum level should translate to 255 at 8 bits per RGB channel.

The iff SDK sample, which reads and writes IFF ILBM images, includes an unHam function that shows how the BODY data for a HAM image can be translated into more conventional 24-bit RGB.

Extra-Halfbrite is another Amiga variant, now quite rare. EHBs are 64-color pictures with 32-color palettes. Colors 32 to 63 are "half-bright" versions of colors 0 to 31, computed by bit shifting the RGB levels right by one. The easiest way to read EHB images is to extend the color table to include colors 32 to 63 and then interpret the BODY data as you would for any other indexed color image. End ed.]


3. Standard Data Chunk

Raster Layout

Raster scan proceeds left-to-right (increasing X) across scan lines, then top-to-bottom (increasing Y) down columns of scan lines. The coordinate system is in units of pixels, where (0,0) is the upper left corner.

The raster is typically organized as bitplanes in memory. The corresponding bits from each plane, taken together, make up an index into the color map which gives a color value for that pixel. The first bitplane, plane 0, is the low order bit of these color indexes.

A scan line is made of one "row" from each bitplane. A row is one plane's bits for one scan line, but padded out to a word (2 byte) boundary (not necessarily the first word boundary). Within each row, successive bytes are displayed in order and the most significant bit of each byte is displayed first.

[Ed: A conventional indexed color display stores the value of a pixel in a single byte (below, left). For a pixel at (x, y), the memory offset from the start of an image w pixels wide is just wy + x (ignoring any scanline padding), and the value stored there is an index into a table of RGB color records. In an ILBM, the bits of a given pixel aren't contiguous in memory. They are instead stored in separate bitplanes, each of which contains a single bit from a given pixel (below, right).

                                        plane 0:  10000011b
                                        plane 1:  00110010b
                                        plane 2:  10001001b
            pixel:  00111010b           plane 3:  11010100b
                                        plane 4:  01010111b
                                        plane 5:  10011010b

To retrieve a pixel value (na´vely), you must read bytes at different addresses (six of them in the above example), mask off all but one bit from each of them, and string the bits together. For the pixel at (x, y), the byte offset into each bitplane is (wy + x) / 8, and the bit is 7 - (x mod 8). Bitplane n contains the n-th bit of the pixel value. End ed.]

A "mask" is an optional "plane" of data the same size (w, h) as a bitplane. It tells how to "cut out" part of the image when painting it onto another image."One" bits in the mask mean "copy the corresponding pixel to the destination" while "zero" mask bits mean "leave this destination pixel alone". In other words, "zero" bits designate transparent pixels.

The rows of the different bitplanes and mask are interleaved in the file (see below). This localizes all the information pertinent to each scan line. It makes it much easier to transform the data while reading it to adjust the image size or depth. It also makes it possible to scroll a big image by swapping rows directly from the file without random-accessing to all the bitplanes.

BODY

The source raster is stored in a BODY chunk. This one chunk holds all bitplanes and the optional mask, interleaved by row.

The BitMapHeader, in a BMHD property chunk, specifies the raster's dimensions w, h, and nPlanes. It also holds the masking field which indicates if there is a mask plane and the compression field which indicates the compression algorithm used. This information is needed to interpret the BODY chunk, so the BMHD chunk must appear first. While reading an ILBM's BODY, a program may convert the image to another size by filling (with transparentColor) or clipping.

The BODY's content is a concatenation of scan lines. Each scan line is a concatenation of one row of data from each plane in order 0 through nPlanes-1 followed by one row from the mask (if masking = hasMask ). If the BitMapHeader field compression is cmpNone, all h rows are exactly (w+15)/16 words wide. Otherwise, every row is compressed according to the specified algorithm and their stored widths depend on the data compression.

Reader programs that require fewer bitplanes than appear in a particular ILBM file can combine planes or drop the high-order (later) planes. Similarly, they may add bitplanes and/or discard the mask plane.

Do not compress across rows and don't forget to compress the mask just like the bitplanes. Remember to pad any BODY chunk that contains an odd number of bytes and skip the pad when reading.


4. Nonstandard Data Chunks

The following data chunks were defined after various programs began using FORM ILBM so they are "nonstandard" chunks.

CRNG

A CRNG chunk contains "color register range" information. It's used by Electronic Arts' Deluxe Paint program to identify a contiguous range of color registers for a "shade range" and color cycling. There can be zero or more CRNG chunks in an ILBM, but all should appear before the BODY chunk. Deluxe Paint normally writes 4 CRNG chunks in an ILBM when the user asks it to "Save Picture".

   typedef struct {
      WORD  pad1;       /* reserved for future use; store 0 here    */
      WORD  rate;       /* color cycle rate                         */
      WORD  flags;      /* see below                                */
      UBYTE low, high;  /* lower and upper color registers selected */
   } CRange;

The bits of the flags word are interpreted as follows: if the low bit is set then the cycle is "active", and if this bit is clear it is not active. Normally, color cycling is done so that colors move to the next higher position in the cycle, with the color in the high slot moving around to the low slot. If the second bit of the flags word is set, the cycle moves in the opposite direction. As usual, the other bits of the flags word are reserved for future expansion. Here are the masks to test these bits:

   #define RNG_ACTIVE 1
   #define RNG_REVERSE 2

The fields low and high indicate the range of color registers (color numbers) selected by this CRange.

The field rate determines the speed at which the colors will step when color cycling is on. The units are such that a rate of 60 steps per second is represented as 214 = 16384. Slower rates can be obtained by linear scaling: for 30 steps/second, rate = 8192; for 1 step/second, rate = 16384 / 60, or 273.

Warning! One popular paint package always sets the RNG_ACTIVE bit, but uses a rate of 36 (decimal) to indicate cycling is not active.

CCRT

Commodore's Graphicraft program uses a similar chunk CCRT (for Color Cyling Range and Timing). This chunk contains a CycleInfo structure.

   typedef struct {
      WORD  direction;     /*  0 = don't cycle, 1 = cycle forwards,  */
                           /* -1 = cycle backwards                   */
      UBYTE start, end;    /* lower, upper color registers selected  */
      LONG  seconds;       /* # seconds between changing colors plus */
      LONG  microseconds;  /* # microseconds between changing colors */
      WORD  pad;           /* reserved for future use; store 0 here  */
   } CycleInfo;

This is very similar to a CRNG chunk. A program would probably only use one of these two methods of expressing color cycle data. New programs should use CRNG. You could write out both if you want to communicate this information to both Deluxe Paint and Graphicraft.


Appendix A. ILBM Regular Expression

Here's a regular expression summary of the FORM ILBM syntax. This could be an IFF file or a part of one.

   ILBM ::= "FORM" #{   "ILBM" BMHD [CMAP] [GRAB] [DEST] [SPRT] [CAMG]
                        CRNG* CCRT* [BODY]   }

   BMHD ::= "BMHD" #{   BitMapHeader   }
   CMAP ::= "CMAP" #{   (red green blue)* } [0]
   GRAB ::= "GRAB" #{   Point2D  }
   DEST ::= "DEST" #{   DestMerge   }
   SPRT ::= "SPRT" #{   SpritePrecendence }
   CAMG ::= "CAMG" #{   LONG  }

   CRNG ::= "CRNG" #{   CRange   }
   CCRT ::= "CCRT" #{   CycleInfo   }
   BODY ::= "BODY" #{   UBYTE*   } [0]

The token "#" represents a ckSize LONG count of the following {braced} data bytes. E.g. a BMHD's "#" should equal sizeof(BitMapHeader). Literal strings are shown in "quotes", [square bracket items] are optional, and "*" means 0 or more repetitions. A sometimes-needed pad byte is shown as "[0]".

The property chunks (BMHD, CMAP, GRAB, DEST, SPRT, and CAMG) and any CRNG and CCRT data chunks may actually be in any order but all must appear before the BODY chunk since ILBM readers usually stop as soon as they read the BODY. If any of the 6 property chunks are missing, default values are inherited from any shared properties (if the ILBM appears inside an IFF LIST with PROPs) or from the reader program's defaults. If any property appears more than once, the last occurrence before the BODY is the one that counts since that's the one that modifies the BODY.

Appendix B. ILBM Box Diagram

Here's a box diagram for a simple example: an uncompressed image 320 x 200 pixels x 3 bitplanes. The text to the right of the diagram shows the outline that would be printed by the IFFCheck utility program for this particular file.

'FORM' 24070
'ILBM'
 
'BMHD' 20
320, 200, 0, 0, 3, 0, 0, ...
'CMAP' 21
0, 0, 0; 32, 0, 0; 64, 0, 0 ...

0

'BODY' 24000
0, 0, 0, ...
FORM 24070 ILBM
 
.BMHD 20
 
.CMAP 21
 

 

.BODY 24000
 

The "0" after the CMAP chunk is a pad byte.

Appendix C. ByteRun1 Run Encoding

The run encoding scheme byteRun1 is best described by psuedo code for the decoder Unpacker (called UnPackBits in the Macintosh toolbox):

   UnPacker:
      LOOP until produced the desired number of bytes
         Read the next source byte into n
         SELECT n FROM
            [0..127] => copy the next n+1 bytes literally
            [-1..-127]  => replicate the next byte -n+1 times
            -128  => noop
            ENDCASE;
         ENDLOOP;

In the inverse routine Packer, it's best to encode a 2 byte repeat run as a replicate run except when preceded and followed by a literal run, in which case it's best to merge the three into one literal run. Always encode 3 byte repeats as replicate runs.

Remember that each row of each scan line of a raster is separately packed.

[Ed: Some versions of Adobe Photoshop incorrectly use the n=128 no-op as a repeat code, which breaks strictly conforming readers. To read Photoshop ILBMs, allow the use of n=128 as a repeat. This is pretty safe, since no known program writes real no-ops into their ILBMs. The reason n=128 is a no-op is historical: the Mac Packbits buffer was only 128 bytes, and a repeat code of 128 generates 129 bytes. End ed.]

Appendix D. Standards Committee

The following people contributed to the design of this FORM ILBM standard:

Bob "Kodiak" Burns, Commodore-Amiga
R. J. Mical, Commodore-Amiga
Jerry Morrison, Electronic Arts
Greg Riker, Electronic Arts
Steve Shaw, Electronic Arts
Dan Silva, Electronic Arts
Barry Walsh, Commodore-Amiga

Appendix E. IFF Hints

Hints on ILBM files from Jerry Morrison, Oct 1988. How to avoid some pitfalls when reading ILBM files:

  • Don't ignore the BitMapHeader masking field. A bitmap with a mask (such as a partially transparent DPaint brush or a DPaint picture with a stencil) will read as garbage if you don't de-interleave the mask.
  • Don't assume all images are compressed. Narrow images aren't usually run-compressed since that would actually make them longer.
  • Don't assume a particular image size. You may encounter overscan pictures and PAL pictures.

Different hardware display devices have different color resolutions:

Device R:G:B bits maxColor
Mac SE 1 1
IBM EGA 2:2:2 3
Atari ST 3:3:3 7
Amiga 4:4:4 15
CD-I 5:5:5 31
IBM VGA 6:6:6 63
Mac II 8:8:8 255

An ILBM CMAP defines 8 bits of Red, Green and Blue (i.e., 8:8:8 bits of R:G:B). When displaying on hardware which has less color resolution, just take the high order bits. For example, to convert ILBM's 8-bit Red to the Amiga's 4-bit Red, right shift the data by 4 bits (R4 := R8 >> 4).

To convert hardware colors to ILBM colors, the ILBM specification says just set the high bits (R8 := R4 << 4). But you can transmit higher contrast to foreign display devices by scaling the data [0..maxColor] to the full range [0..255]. In other words, R8 := (Rn x 255 ) / maxColor. (Example #1: EGA color 1:2:3 scales to 85:170:255. Example #2: Amiga 15:7:0 scales to 255:119:0). This makes a big difference where macColor is less than 15. In the extreme case, Mac SE white (1) should be converted to ILBM white (255), not to ILBM gray (128).

CGA and EGA subtleties

IBM EGA colors in 350 scan line mode are 2:2:2 bits of R:G:B, stored in memory as xxR'G'B'RGB. That's 3 low-order bits followed by 3 high-order bits.

IBM CGA colors are 4 bits stored in a byte as xxxxIRGB. (EGA colors in 200 scan line modes are the same as CGA colors, but stored in memory as xxxIxRGB.) That's 3 high-order bits (one for each of R, G, and B) plus one low-order "Intensity" bit for all 3 components R, G, and B. Exception: IBM monitors show IRGB = 0110 as brown, which is really the EGA color R:G:B = 2:1:0, not dark yellow 2:2:0.

24-bit ILBMs

When storing deep images as ILBMs (e.g., images with 8 bits each of R, G, and B), the bits for each pixel represent an absolute RGB value for that pixel rather than an index into a limited color map. The order for saving the bits is critical since a deep ILBM would not contain the usual CMAP of RGB values (such a CMAP would be too large and redundant).

To interpret these "deep" ILBMs, it is necessary to have a standard order in which the bits of the R, G, and B values will be stored. A number of different orderings have already been used in deep ILBMs and a default has been chosen from them.

The following bit ordering has been chosen as the default bit ordering for deep ILBMs.

   Default standard deep ILBM bit ordering:
   saved first -----------------------------------------------> saved last
   R0 R1 R2 R3 R4 R5 R6 R7 G0 G1 G2 G3 G4 G5 G6 G7 B0 B1 B2 B3 B4 B5 B6 B7

[Ed.: Recall from Section 3 that the bits representing the value at a given pixel are divided into separate bitplanes. A 24-bit RGB image uses 24 bitplanes. Also recall that images are stored in the BODY one complete scanline at a time, so one row from each of the 24 bitplanes is written before moving to the next scanline. For each scanline, the red bitplane rows are stored first, followed by green and blue. The first plane holds the least significant bit of the red value for each pixel, and the last holds the most significant bit of the blue value.

8-bit Grayscale

The original standard doesn't prescribe the form of an 8-bit grayscale image, but we can infer one from the convention for 24-bit color. Grayscale images also lack a CMAP, and their bitplanes are saved in least to most significant bit order.

   Grayscale ILBM bit ordering:
   saved first -----> last
   I0 I1 I2 I3 I4 I5 I6 I7

Some programs fail to recognize 8-bit ILBMs with no color table. For maximum portability, ILBM writers can include a CMAP containing 256 entries, with the RGB levels ranging from (0, 0, 0) for the first entry to (255, 255, 255) for the last. Strictly speaking, this creates an indexed color image in which all of the colors happen to be shades of gray, but this distinction may not make any difference in practice.

32-bit RGB plus Alpha

A more recent (and much less widely supported) extension of the standard is the 32-bit RGBA. This adds an 8-bit grayscale alpha image to the red, green and blue stored in 24-bit ILBMs. The alpha bitplanes are stored after the R, G and B planes for each scanline.

   32-bit RGBA ILBM bit ordering:
   saved first -----------------------------------> last
   R0 ... R7 G0 ... G7 B0 ... B7 A0 A1 A2 A3 A4 A5 A6 A7

End ed.]