Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-FileIMG_HEADER
ataripf.hyp/img

                            The .IMG File Format


The IMG file format was designed to support raster images with a varying
number of planes. In practice, almost all IMG files currently available
are simple black and white single plane images because the original file
format did not specify a method of storing palette information with the
file. To fill this need, several unofficial extensions to the format were
put into use (some of which were incorrectly implemented by applications
supporting them). The color extension which will be discussed here to
cover color images is the 'XIMG' format.

The IMG Header (see IMG_HEADER structure)

Image headers consist of at least 8 WORDs as follows:

    WORD    Meaning

      0     Image file version (Usually 0x0001).

      1     Header length in WORDs.

      2     Number of planes.

      3     Pattern definition length.

      4     Source device pixel width (in microns).

      5     Source device pixel height (in microns).

      6     Scan line width (in pixels).

      7     Number of scan lines.

Some IMG files will have additional header information which should be
skipped or interpreted as discussed below.

Interpreting Extra Palette Information

If WORD #2 is set to 1, then the image data consists of one plane (i.e.
monochrome) and any extra header information should be ignored.

If WORD #2 is set to 16 or 24 then the image data consists of that many
planes of high color or true color data and any extra header information
should be ignored. In a high color image, planes appear in the order
RRRRR GGGGGG BBBBB. In a true-color image, planes appear in the order
RRRRRRRR GGGGGGGG BBBBBBBB.

If WORD #2 is set to 2, 4, or 8, the image consists of palette based
color image data. If no extra header information is given then the creator
did not specify palette data for this image. If extra header WORDs appears
they may be useful in determining the color palette. The two primary
extensions to the IMG format are 'XIMG' and 'STTT'. 'STTT' will not be
discussed here as it does not serve well as a machine or device
independent format. The 'XIMG' header extension is as follows:

     WORD     Meaning

     8 & 9    ASCII 'XIMG'

     10       Color format (Almost always 0 - RGB).

     11...    RGB WORD triplets. Three WORDs appear for each pen. There are
              (2 ^ numplanes) pens. Each word contains a value from 0 to
              1000 for direct passage to vs_color().

Image Data Format

Each scanline contains data in VDI device independent format which must
be converted using the VDI call vr_trnfm(). Each scanline is padded to the
nearest byte. Every plane for each scanline should appear prior to the
beginning of data for the next scanline. This allows interpreters to
decompress and transform the image data a scanline at a time to conserve
on time and memory. A sample ordering for a four-plane image is listed
below:

               Scanline #0 - Plane #0

               Scanline #0 - Plane #1

               Scanline #0 - Plane #2

               Scanline #0 - Plane #3

               Scanline #1 - Plane #0

               Scanline #1 - Plane #1

               Scanline #1 - Plane #2

               Scanline #1 - Plane #3

               etc.

Image Compression

Each scanline is individually compressed. This means that compression
codes should not transgress over scanline boundaries. This enables
decompression routines to work scanline by scanline.

Scanline data should consist of two components, a vertical replication
count and encoded scanline data. In practice, however, some older .IMG
files may not contain a vertical replication count for each scan line.

The vertical replication count specifies the number of times the
following scanline data should be used to replicate an image row. It is
formatted as follows:

    BYTE    Contents

      0     0x00

      1     0x00

      2     0xFF

      3     Replication Count

.IMG files do not always contain a vertical replication count at the
beginning of every scanline.

Immediately following the vertical replication count is the encoded
scanline data. This runlength encoding can by looking for three separate
flag BYTEs. A 0x80 BYTE indicates the beginning of a bit-string item.
A bit-string item is formatted as follows:

    BYTE    Contents

      0     0x80

      1     Byte count 'n'.

      2...  'n' BYTEs of unencoded data.

A pattern-run item begins with a BYTE of 0x00. It specifies a fixed
number of times that the pattern which follows it should be repeated. It
is formatted as follows:

    BYTE    Contents

      0     0x00

      1     Length of run.

      2...  Pattern bytes (length of pattern is determined by header
            WORD #3).

Finally, a solid-run item begins with any other BYTE code. If the high
order bit is set then this indicates a run of black pixels, otherwise it
indicates a run of white pixels. The lower 7 bits of the byte indicates
the length of the run in bytes. For example a BYTE code of 0x83 indicates
a run of 24 black pixels (3 bytes).