A GEM Image file starts with a header of at least eight 16-bit words, big-endian on both the PC and the Atari ST. Word 1 gives the header’s full length, so a reader can skip anything it does not understand and find the image data straight after.
Fields
| Offset | Word | Type | Name | Description |
|---|---|---|---|---|
| 0 | 0 | u16 | version | 1 |
| 2 | 1 | u16 | header length | the length of the whole header in words: 8 for GEM Paint, 9 for Ventura Publisher, more for XIMG. The image data starts at twice this many bytes |
| 4 | 2 | u16 | planes | the number of bitplanes, which is the bits per pixel (below) |
| 6 | 3 | u16 | pattern length | the length in bytes, 1 to 8, of the pattern in each pattern run; GEM Paint uses 2. See Image data |
| 8 | 4 | u16 | pixel width | the width of one pixel on the source device, in microns (thousandths of a millimetre) |
| 10 | 5 | u16 | pixel height | the height of one pixel, in microns |
| 12 | 6 | u16 | line width | the image width in pixels |
| 14 | 7 | u16 | lines | the image height in scan lines |
| 16 | 8… | extra words | optional; a 9-word Ventura header or an XIMG extension (below) |
The pixel size gives the resolution and the aspect ratio. A value of 85 means 1/300 inch, a 300 dpi scanner or printer. One set of notes, John Elliott’s, gives the unit as tenths of a millimetre; the Atari Compendium and other descriptions give microns, which match the values found in files.
Files are usually version 1. No published description gives a meaning to any other version number.
Planes and colour
| Planes | Meaning | Palette |
|---|---|---|
| 1 | monochrome: 1 is black, 0 white | none; extra header words are ignored |
| 2, 4, 8 | palette-based: the planes form a colour number per pixel | none in the original format; an XIMG extension can supply one |
| 16 | high colour, 5-6-5: red in the top 5 bits, then 6 of green, then 5 of blue | none; extra header words are ignored |
| 24 | true colour: 8 bits each of red, green and blue | none; extra header words are ignored |
The original format has no palette, so a colour picture without one depends on the screen it was made on. For a four-plane picture, John Elliott’s notes and the Encyclopedia of Graphics File Formats give the planes as red, green, blue and intensity, in that order. Readers without a palette fall back on a fixed 16-colour table; which table varies between programs.
The 9-word header
Ventura Publisher writes a ninth word. The Encyclopedia of Graphics File Formats calls it a grey-or-colour flag for pictures with more than one plane: 0 colour, 1 greyscale. It is ignored for one-plane pictures. The Atari Compendium does not list it, and its meaning is not confirmed by any other published source.
XIMG palette
XIMG is an unofficial but widely used extension that stores a palette for 2, 4 and 8-plane pictures. It follows the eight standard words:
| Offset | Word | Type | Name | Description |
|---|---|---|---|---|
| 16 | 8–9 | ASCII | signature | XIMG: bytes 58 49 4D 47 |
| 20 | 10 | u16 | colour model | 0 RGB, almost always. xloadimage’s source also names 1 CMY and 2 HLS, but no reader is known to handle them |
| 22 | 11… | 3 × u16 per pen | palette | 2planes entries of red, green and blue, each 0 to 1000 |
The values 0 to 1000 are the units of the GEM VDI call vs_color(), to
which they are meant to be passed directly: 1000 is full intensity. To get 0 to 255,
multiply by 255 and divide by 1000. A four-plane XIMG header is 8 + 3 + 3 × 16 =
59 words long; an eight-plane one is 8 + 3 + 3 × 256 = 779 words.
The palette entries are VDI pen numbers. How a pixel’s colour number maps to a pen number depends on the VDI driver, and the published descriptions do not settle it; most readers use the pixel value as the pen number.
Other extensions
Other programs added their own header extensions, among them one with the signature
STTT. Their layouts are not publicly documented, and the Atari Compendium
leaves STTT out as not device-independent. A reader that does not recognise the words
after the eighth should skip them using the header length.
Example
An 8-word header for a 640 × 400 one-plane picture at 300 dpi:
| Offset | Bytes | Field | Value |
|---|---|---|---|
| 0 | 00 01 | version | 1 |
| 2 | 00 08 | header length | 8 words: data at byte 16 |
| 4 | 00 01 | planes | 1, black and white |
| 6 | 00 02 | pattern length | 2 bytes |
| 8 | 00 55 | pixel width | 85 µm |
| 10 | 00 55 | pixel height | 85 µm |
| 12 | 02 80 | line width | 640 pixels |
| 14 | 01 90 | lines | 400 |
A four-plane XIMG file would have 00 3B (59) as its header length,
00 04 as its planes, then 58 49 4D 47 00 00 and 16 triples
such as 03 E8 03 E8 03 E8 for white.