LBM file format: Amiga contiguous bitmap (IFF ACBM)

Introduction

ACBM, the Amiga Contiguous Bitmap, is a picture format that Carolyn Scheppner of Commodore submitted as an IFF form on 29 May 1986, for loading and saving screens quickly from AmigaBASIC. In the document’s words, “FORM ACBM has the same format as FORM ILBM except the normal BODY chunk” is replaced by an ABIT chunk, for “Amiga BITplanes”, which “contains sequential data for bitplane 0 through bitplane n”. A program can then load or save the picture’s “bitmaps with one DOS Read/Write per bitplane”.

The document came with AmigaBASIC example programs: LoadILBM-SaveACBM, which turns an ILBM into an ACBM, LoadACBM and SaveILBM. Like ILBM it is open: the document is published in the AmigaOS documentation. It names no file extension; on the Amiga, files often had none.

Because its pixel chunk has a different ID and a different layout, an ILBM reader cannot show an ACBM picture, and it is a separate format here. No ACBM file was among the files examined for this site; the explorer was checked against files built for the test. A file dropped on any page of this site opens in the explorer, which shows every chunk and every plane, with the picture and its palette.

Structure

An ACBM file is one IFF FORM chunk with the form type ACBM, holding the same chunks as an ILBM, with ABIT in place of BODY. All numbers are big-endian. On this page UBYTE, UWORD and ULONG are unsigned 8-, 16- and 32-bit numbers, and WORD and LONG signed 16- and 32-bit ones.

0FORM chunk ID, size and the form type ACBM12 bytes
1. 12BMHD the bitmap header: size, bitplanes, masking28 bytes
2. 40CMAP the colour map, 3 bytes a colourvaries
3. …CAMG the Amiga display mode12 bytes
4. …GRAB, CRNG … other optional chunksvaries
5. …ABIT plane 0 whole, then plane 1, and so onh × RowBytes a plane

An ACBM file: chunks inside one FORM

A complete file

An example built for this page: a 16 × 2 picture with one plane and two colours, 66 bytes. The FORM header, the BMHD’s data and the ABIT’s data are marked.

00000000  46 4F 52 4D 00 00 00 3A 41 43 42 4D 42 4D 48 44
00000010  00 00 00 14 00 10 00 02 00 00 00 00 01 00 00 00
00000020  00 00 0A 0B 01 40 00 C8 43 4D 41 50 00 00 00 06
00000030  00 00 00 FF FF FF 41 42 49 54 00 00 00 04 F0 0F
00000040  0F F0

FORM of 58 bytes; BMHD: 16 × 2, 1 plane, no masking, no compression, aspect 10:11; CMAP: black and white; ABIT: plane 0, two rows of 2 bytes

In the top row, F0 0F, pixels 0 to 3 and 12 to 15 are white and the rest black; the bottom row, 0F F0, is the reverse.

IFF container

The file follows Electronic Arts’ EA IFF 85 standard (Jerry Morrison, 14 January 1985). Every chunk has an 8-byte header and its data:

Offset	Size	Type	Name	Description
0	4	4 ASCII characters	`ckID`	The chunk ID, such as `BMHD` or `ABIT`.
4	4	ULONG	`ckSize`	The number of data bytes that follow, not counting this header or the pad byte.
8	`ckSize`	bytes	`ckData`	The data.
8 + `ckSize`	0 or 1	byte	pad	One pad byte when `ckSize` is odd, so that every chunk starts at an even offset. Written as zero, but “don’t count on that when reading”.

An ID is four characters from space to ~; it may end with spaces but not start with one, and upper and lower case differ. The smallest chunk is 8 bytes.
A reader skips any chunk it does not know.

The whole file is one FORM:

Offset	Size	Type	Name	Description
0	4	4 ASCII characters	ID	`FORM` (`46 4F 52 4D`).
4	4	ULONG	size	The bytes that follow: the form type and every chunk, with their pad bytes.
8	4	4 ASCII characters	form type	`ACBM` (`41 43 42 4D`).
12	…	chunks		The chunks of the picture.

As in an ILBM, BMHD comes first and is required, and every property chunk comes before the pixel chunk, here ABIT. If a property appears twice, the last one before the ABIT counts.
Anything after the end of the FORM is not part of the picture; the explorer reports such bytes.
IFF also has the group chunks LIST, CAT and PROP, which hold several forms. The explorer reads only files that start with FORM and ACBM, and shows any group inside the form with its type and chunks.

BMHD, the bitmap header

Required, and the same 20-byte BitMapHeader as in an ILBM. Offsets are from the start of the chunk’s data.

Offset	Size	Type	Name	Description
0	2	UWORD	`w`	The width in pixels.
2	2	UWORD	`h`	The height in pixels.
4	2	WORD	`x`	Where the picture sits on the page, from the left. Usually 0.
6	2	WORD	`y`	Where the picture sits on the page, from the top. Usually 0.
8	1	UBYTE	`nPlanes`	The number of bitplanes, not counting a mask plane.
9	1	UBYTE	`masking`	0 none; 1 a mask plane; 2 colour `transparentColor` is transparent; 3 lasso: that colour is transparent only where it joins the edge.
10	1	UBYTE	`compression`	0 none; 1 ByteRun1 in an ILBM. The ACBM document says nothing of compression; see ABIT.
11	1	UBYTE	`pad1`	Unused, 0.
12	2	UWORD	`transparentColor`	The transparent colour number, with masking 2 or 3.
14	1	UBYTE	`xAspect`	The pixel aspect ratio: a pixel is `xAspect` wide…
15	1	UBYTE	`yAspect`	…for every `yAspect` high. 10:11 for an Amiga 320 × 200 screen in the ILBM document.
16	2	WORD	`pageWidth`	The width of the screen the picture was made on.
18	2	WORD	`pageHeight`	The height of that screen.

The explorer reads exactly 20 bytes, reports any more, and turns the file down when the BMHD is missing or shorter than 20 bytes, or comes after the ABIT. It applies masking 2 and 3 in its preview.

CMAP, the colour map

Three bytes for each colour number from 0: red, green and blue, each 0 to 255. The number of colours is ckSize ÷ 3, normally 2^nPlanes; fewer is allowed. Without a CMAP the explorer shows greys.

Offset	Size	Type	Name	Description
0	1	UBYTE	`red`	Red.
1	1	UBYTE	`green`	Green.
2	1	UBYTE	`blue`	Blue.

Old Amiga programs stored the hardware’s 4-bit values in the high half of each byte. When every value’s low four bits are zero, the explorer scales the map, as the ILBM document asks: each value becomes v | (v >> 4), so 0xF0 is shown as 0xFF.

CAMG, the Amiga display mode

One ULONG: the Amiga viewport mode. Its low 16 bits are mode flags:

Bit	Name	Meaning
`0x8000`	`HIRES`	High resolution, 640 pixels wide.
`0x1000`	`EXTENDED_MODE`	The value is a whole AmigaOS 2.0 ModeID, with the monitor in the upper 16 bits.
`0x0800`	`HAM`	Hold-and-modify.
`0x0080`	`EXTRA_HALFBRITE`	Extra Half-Brite.
`0x0004`	`LACE`	Interlaced.

The other bits are as in an ILBM: SPRITES 0x4000, VP_HIDE 0x2000, DUALPF 0x0400, GENLOCK_AUDIO 0x0100, PFBA 0x0040, SUPERHIRES 0x0020, DOUBLESCAN 0x0008 and GENLOCK_VIDEO 0x0002.

Extra Half-Brite: 6 planes. Plane 5 halves the colour picked by the other five, so colours 32 to 63 are colours 0 to 31 with each component shifted right one bit.
HAM6: 6 planes. Bits 5 and 4 of each pixel say what the lower four do: 00 pick a colour from the map, 01 change the previous pixel’s blue, 10 its red, 11 its green. A 4-bit value v becomes v × 17.
HAM8 (AGA): 8 planes, the top two control, six data bits, and the lower two bits of a changed component kept.
Without a CAMG, the explorer guesses HAM6 for 6 planes and up to 16 colours, and Extra Half-Brite for 6 planes and 32 colours, and says so.
A picture of 24 or 32 planes has no colour map: the planes are red, green, blue and alpha, 8 each, lowest bit first. The explorer paints these too.

ABIT, the bitplanes

The pixel chunk. It holds plane 0 whole, from the top row to the bottom, then plane 1 whole, and so on to plane nPlanes − 1. Plane 0 holds the lowest bit of each pixel’s colour number. Within each row of a plane the highest bit of each byte is the leftmost pixel.

0Plane 0 row 0, row 1 … row h − 1h × RowBytes
…Plane 1 row 0 … row h − 1h × RowBytes
…Plane nPlanes − 1 the last colour planeh × RowBytes
…Mask plane only with masking 1: an inference from ILBMh × RowBytes

The ABIT chunk; an ILBM BODY has the same rows in another order, one line of each plane a row

The document does not say how long a row is, whether the planes can be compressed, or where a mask plane goes. The explorer, like FFmpeg, follows ILBM for the row length:

RowBytes = 2 × floor((w + 15) ÷ 16)

A row of whole 16-bit words, as in ILBM

The size of each plane is h × RowBytes.
The explorer, like FFmpeg, reads the planes as stored, whatever the compression field says. The document’s purpose, one read a plane straight into memory, suggests they were never packed.
When masking is 1, the explorer shows one more plane after the colour planes as a mask plane, where a 0 bit is transparent. That is an inference from ILBM.
When the data ends early, the explorer reports the plane it ends in.

Other chunks

The chunks an ILBM may hold may also appear in an ACBM. The explorer reads all those it knows, and shows any other as bytes. A TINY thumbnail is shown as a chunk but not painted.

ID	Size	Fields
`GRAB`	4	`x`, `y`, WORDs: a brush’s hotspot from the top-left corner.
`DEST`	8	`depth` UBYTE, `pad1` UBYTE, `planePick`, `planeOnOff`, `planeMask` UWORDs: how the planes go into a deeper bitmap.
`SPRT`	2	The sprite precedence, UWORD; 0 is the foremost.
`CRNG`	8	`pad1` WORD, `rate` WORD (16,384 = 60 steps a second), `flags` WORD (bit 0 active, bit 1 reverse), `low` and `high` UBYTEs: a colour range for cycling.
`CCRT`	14	`direction` WORD, `start` and `end` UBYTEs, `seconds` and `microseconds` LONGs, `pad` WORD: Graphicraft’s colour cycle.
`DRNG`	8 and more	`min`, `max` UBYTEs, `rate`, `flags` WORDs, `ntrue`, `nregs` UBYTEs, then 4-byte colours and 2-byte indexes: Deluxe Paint IV’s colour range.
`DPPV`	104	Deluxe Paint’s perspective settings; the explorer shows the first nine fields.
`DPI`	4	`dpi_x`, `dpi_y` UWORDs: the resolution.
`CLUT`	264	`type` ULONG, `res0` ULONG, 256 UBYTEs: a lookup table for one channel.
`ANNO`, `AUTH`, `NAME`, `(c)` , `TEXT`	any	Plain text: a note, the author, the name, the copyright, other text.

Each is described field by field on the ILBM chunks page; they mean the same here.

Telling it apart

The explorer’s parser for this format checks that the file starts with FORM and that the form type, the four bytes at offset 8, is ACBM (41 43 42 4D). It turns the file down if there is no BMHD chunk or the BMHD is shorter than 20 bytes, and the explorer then tries the parsers for the other formats of the family.

An ILBM has the same chunks but the form type ILBM and a BODY instead of an ABIT.

Variants

Interleaved bitmap (IFF ILBM) – the Amiga’s format: interleaved bitplanes, with HAM, EHB and 24-bit pictures
Deluxe Paint PC bitmap (IFF PBM) – Deluxe Paint for MS-DOS: one byte a pixel
Amiga contiguous bitmap (IFF ACBM) – AmigaBASIC’s form: each bitplane stored whole

.LBM File Format