Editing ILBM (section)

== File format ==
ILBM is an implementation of the [[Interchange File Format|IFF]] file format consisting of a number of consecutive chunks, whose order can, to some extent, be varied. Each chunk has a different function and has the same basic format. This means that a program does not have to read or decode every chunk in a file, only the ones it wants to deal with or the ones it can understand.<ref name="ilbm_spec"/>

ILBM files usually contain enough information to allow them to be displayed by an image editing program, including image dimensions, palette and pixel data. Some files were designed to act as palettes for paint programs (pixel data left blank) or to be merged into another image. This makes them much more flexible, but also much more complex than other formats such as BMP.{{citation needed|date=February 2018}}

For ILBMs the '''BMHD''' (Bit Map HeaDer) chunk and any other 'vital' chunks must appear before the '''BODY''' chunk. Any chunks appearing after '''BODY''' are considered 'extra' and many programs will leave them unread and unchanged.<ref name="ilbm_spec"/>

{|class="wikitable"
! Type !! Name !! Description
|-
| FOURCC || chunkID || "FORM"
|-
| [[UINT32BE]] || lenChunk || Length of chunk data, in bytes.  Does not include the pad byte.  Will be the same as the file size minus eight bytes (this field and <code>chunkID</code> are not included in the count)
|-
| FOURCC || formatID || "ILBM" or "PBM "
|-
| BYTE[lenChunk - 12] || content || Actual data of the chunk, made up of the other sub-chunks below
|-
| BYTE || pad || Optional padding byte, only present if <code>lenChunk</code> is not a multiple of 2.
|}

=== BMHD: Bitmap header ===
The '''BMHD''' chunk specifies how the image is to be displayed and is usually the first chunk inside the '''FORM'''.  It not only defines the image's height/width, but where it is drawn on the screen, how to display it in various screen resolutions and if the image is compressed.  The content of this chunk is as follows:<ref name="ilbm_spec"/>

{|class="wikitable"
! Type !! Name !! Description
|-
| [[UINT16BE]] || width || Image width, in pixels
|-
| [[UINT16BE]] || height || Image height, in pixels
|-
| [[INT16BE]] || xOrigin ||rowspan=2| Where on screen, in pixels, the image's top-left corner is. Value is usually 0,0 unless image is part of a larger image or not fullscreen.
|-
| [[INT16BE]] || yOrigin
|-
| [[UINT8]] || numPlanes || Number of planes in bitmap; 1 for monochrome, 4 for 16 color, 8 for 256 color, or 0 if there is only a colormap, and no image data. (i.e., this file is just a colormap.)
|-
| [[UINT8]] || mask || 1 = masked, 2 = transparent color, 3 = lasso (for MacPaint).  Mask data is not considered a bit plane.
|-
| [[UINT8]] || compression || If 0 then uncompressed. If 1 then image data is RLE compressed. If 2 "Vertical RLE" from Deluxe Paint for Atari ST. Other values are theoretically possible, representing other compression methods.
|-
| [[UINT8]] || pad1 || Ignore when reading, set to 0 when writing for future compatibility 
|-
| [[UINT16BE]] || transClr || Transparent colour, useful only when <code>mask</code> >= 2
|-
| [[UINT8]] || xAspect ||rowspan=2| Pixel aspect, a ratio width:height; used for displaying the image on a variety of different screen resolutions for 320x200 5:6 or 10:11
|-
| [[UINT8]] || yAspect
|-
| [[INT16BE]] || pageWidth ||rowspan=2| The size of the screen the image is to be displayed on, in pixels, usually 320×200
|-
| [[INT16BE]] || pageHeight
|}

=== BODY: Image data ===
The '''BODY''' chunk is usually the last chunk in a file,<ref name="ilbm_spec"/> and the largest{{citation needed|date=February 2018}}.

In ILBM files the '''BODY''' chunk stores the actual image data as interleaved bitplanes (and optional mask) by row. The bitplanes appear first from 1 to n, followed by the mask plane. If the image is uncompressed then each line will be made up of <code>(width + 15) / 16</code> 16-bit values (i.e. one bit per pixel, rounded up to the nearest multiple of 16-bits.) If it is compressed then each line is compressed individually and is always a multiple of 16-bits long when compressed.<ref name="ilbm_spec"/>

In PBM files, the '''BODY''' chunk is simpler as uncompressed it is just a continuous stream of bytes containing image data.{{citation needed|date=February 2018}}

==== Compression ====
If an image is compressed, each row of data (but not each bitplane) is compressed individually, including the mask data if present.  The compression is a variety of [[RLE Compression]] using flags.  It can be decoded as follows:<ref name="ilbm_spec"/>

* Loop until we have [Final length] bytes worth of data (final length calculated from image size.)
* While [Decompressed data length] < [Final length]:
*# Read a byte [Value]
*# If [Value] > 128, then:
*#* Read the next byte and output it (257 - [Value]) times.
*#* Move forward 2 bytes and return to step 1.
*# Else if [Value] < 128, then:
*#* Read and output the next [value + 1] bytes
*#* Move forward [Value + 2] bytes and return to step 1.
*# Else [Value] = 128, exit the loop (stop decompressing)

For the compression routine, 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 is best to merge the three into one literal run. Always encode >3 byte repeats as replicate runs.<ref name="ilbm_spec"/>

=== CAMG: Amiga mode ===
A '''CAMG''' chunk is specifically for the Commodore Amiga computer. It stores a LONG "viewport mode". This lets you specify Amiga display modes like "dual playfield" and "hold and modify". It is, not surprisingly, rare outside of Amiga games.{{citation needed|date=July 2018}}

{|class="wikitable"
! Type !! Name !! Description
|-
| [[UINT32BE]] || viewportMode|| bit flags; directly interpreted by Amiga hardware
|}
If you need to convert or display files that might contain meaningful CAMG chunks, see the 'Notes on working with ILBM files' below.

=== CMAP: Palette ===
The '''CMAP''' chunk contains the image's palette and consists of 3-byte RGB values for each colour used.  Each byte is between 0 and 255 inclusive.  The chunk is <code>3 × numColours</code> bytes long.  The number of colours in the palette will be <code>2 ^ numBitplanes</code>. This chunk is optional and a default palette will be used if it is not present.  It is possible to have fewer entries than expected (e.g. 7 colours for a 4-plane '16 colour' bitmap for example.)  Remember that if this has an odd number of colours, as per the IFF specification the chunk will be padded by one byte to make it an even number of bytes long, but the pad byte is not included in the chunk's length field.<ref name="ilbm_spec"/>

=== CRNG: Colour range ===
The colour range chunk is 'nonstandard'.  It is used by Electronic Arts' Deluxe Paint program to identify a contiguous range of colour registers or a "shade range" and colour cycling.  There can be zero or more '''CRNG''' chunks in an ILBM file, 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".<ref name="ilbm_spec"/>

{|class="wikitable"
! Type !! Name !! Description
|-
| [[INT16BE]] || padding || 0x0000
|-
| [[INT16BE]] || rate || Colour cycle rate.  The units are such that a rate of 60 steps per second is represented as 2<sup>14</sup> = 16384.  Lower rates can be obtained by linear scaling: for 30 steps/second, rate = 8192.
|-
| [[INT16BE]] || flags || Flags which control the cycling of colours through the palette. If bit0 is 1, the colours should cycle, otherwise this colour register range is inactive and should have no effect. If bit1 is 0, the colours cycle upwards, i.e. each colour moves into the next index position in the colour map and the uppermost colour in the range moves down to the lowest position. If bit1 is 1, the colours cycle in the opposite direction. Only those colours between the '''low''' and '''high''' entries in the colour map should cycle.
|-
| [[UINT8]] || low || The index of the first entry in the colour map that is part of this range.
|-
| [[UINT8]] || high || The index of the last entry in the colour map that is part of this range.
|}

=== CCRT: Colour cycling ===
Commodore's Graphicraft program uses '''CCRT''' for ''Colour Cycling Range and Timing''. This chunk contains a CycleInfo structure. Like '''CRNG''' it is a nonstandard chunk.<ref name="ilbm_spec"/>

{|class="wikitable"
! Type !! Name !! Description
|-
| [[INT16BE]] || direction || Cycle direction: 0=no cycling, 1=forwards, -1=backwards
|-
| [[UINT8]] || low || lowest color register selected
|-
| [[UINT8]] || high || highest color register selected
|-
| [[INT32BE]] || delaySec || Seconds between changing colors
|-
| [[INT32BE]] || delayuS || Microseconds between changing colors (added to '''delaySec''' to get total delay time)
|-
| [[INT16BE]] || padding || 0x0000
|}

The data is similar to a '''CRNG''' chunk.  A program would probably only use one of these two methods of expressing colour cycle data. You could write out both if you want to communicate this information to both DeluxePaint and Graphicraft.<ref name="ilbm_spec"/>

=== DEST: Bitplane combining ===
The optional property '''DEST''' is a way to control how to scatter zero or more source bitplanes into a deeper destination image.  Some readers may ignore DEST.<ref name="ilbm_spec"/>

{|class="wikitable"
! Type !! Name !! Description
|-
| [[UINT8]] || numPlanes || Number of bitplanes in source image
|-
| [[UINT8]] || pad1 || unused; use 0 for consistency
|-
| [[UINT16BE]] || planePick || How to pick planes to scatter them into the destination image
|-
| [[UINT16BE]] || planeOnOff || Default data for Plane Pick
|-
| [[UINT16BE]] || planeMask || Selects which bitplanes to store into
|}

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.<ref name="ilbm_spec"/>

"1" bits in planePick mean "put the next source bitplane into this bitplane", so the number of "1" bits should equal numPlanes. "0" bits mean "put the corresponding bit from planeOnOff into this bitplane".<ref name="ilbm_spec"/>

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''' chunk) is equivalent to <code>planePick = planeMask = (2 ^ numPlanes) - 1</code>.<ref name="ilbm_spec"/>

Remember that color numbers are formed by pixels in the destination bitmap (depth planes deep) not in the source bitmap (numPlanes planes deep).<ref name="ilbm_spec"/>

=== GRAB: Hotspot ===
The optional '''GRAB''' chunk 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". It is optional.<ref name="ilbm_spec"/>

{|class="wikitable"
! Type !! Name !! Description
|-
| [[INT16BE]] || x || X coordinate of hotspot, in pixels relative to top-left corner of the image
|-
| [[INT16BE]] || y || Y coordinate of hotspot, in pixels relative to top-left corner of the image
|}

=== SPRT: Z-order ===
The '''SPRT''' chunk indicates that an image is intended to be a sprite. It should thus have a mask plane or transparent colour and shouldn't be fullscreen. How this is handled depends on the program using the image. The only data stored here is the sprite order, used by many programs to place the sprite in the foreground (a sprite of order 1 appears behind one of order 0, etc.)  It is optional.<ref name="ilbm_spec"/>

{|class="wikitable"
! Type !! Name !! Description
|-
| [[UINT16BE]] || order || Z-order of image (0 is closest to the foreground, larger numbers are further away/behind)
|}

=== TINY: Thumbnail ===
The '''TINY''' chunk contains a small preview image for various graphics programs, including Deluxe Paint. It is compressed and is similar in format to the '''BODY''' chunk.{{citation needed|date=February 2018}}

{|class="wikitable"
! Type !! Name !! Description
|-
| [[UINT16BE]] || width || Thumbnail width, in pixels
|-
| [[UINT16BE]] || height || Thumbnail height, in pixels
|-
| BYTE[] || data || Pixel data, stored in exactly the same way as the '''BODY''' chunk. Use exactly the same algorithm, substituting the width and height from the '''TINY''' chunk in place of those taken from the '''BMHD''' chunk.
|}