Category : Printer + Display Graphics
Archive   : GX2FILE.ZIP
Filename : GX2SPEC.DOC

GX2 File Specification
May 12, 1988



This describes a file format for graphic bitmaps which is
screen hardware independant. GX2 incorporates the bitmap
compression method of GX1 for pixel data and adds certain
information fields which serve to fully describe the visual
appearance of the bitmap.

Name Position Length Description

ID 0 3 bytes ASCII chars "GX2"
Version 3 1 byte Value is BINARY 1
Head_Size 4 1 word Offset to palette/bitmap
If there are no tags present
this value is 10 hex.
Pixel_Bits 6 1 byte Bits per pixel
Gx2_ResX 7 1 word Pixels per Line
Gx2_ResY 9 1 word Scan lines in file
Hor_Size B 1 word Horizontal measure
Ver_Size D 1 word Vertical measure
Size_Units F 1 byte Unit of measure
0 = Arbitrary (Aspect)
1 = Inches * 100
2 = Centimeters * 100

After the above header, an application can add information
TAGS peculiar to its requirements by alterring Head_Size
appropriately and adhereing to the following format.

Tag_Length Word Byte length of the tag
App_Id 4 bytes 4 chars used to identify
your application
Tag_Info (Tag_Length-6) bytes Your app specific info


After the header and all application-specific tags come the
palette and bitmap data. This information is organized as
follows :

Palette_Type Byte
Block_Count Byte
RGB Lookup Table Variable Size
Bitmap data Variable Size

The first byte in this section describes the information in
the RGB lookup table. There are four types of palettes
available and two bitmap types as follows:

Palette_Type d0..d3 bits Type of color table
0 = Monochrome Text
1 = RGB Text Bitmap
2 = RGB Lookup Table
3 = RGB Pixels
d7 bit Bitmap Type
0 = Uniplanar
1 = Bit Planes

If the high order bit (D7) of the palette type is set then
the bitmap is in the form of bit planes, least significant
bit first. In terms of the vertical compression (described
below) only the first scan line of the first bit plane
is represented normally. All other scan lines of all bit
planes are represented as changes from the previous scan
line as if succeeding planes vertically followed each
other.



RGB LOOKUP TABLE FORMAT

If Palette_Type is 0 (Monochrome text) there is no lookup
table and the attribute bytes reflect the (blinking,
highlight, underscore etc.) attributes in the format
specified for the IBM MONOCHROME DISPLAY adapter.

If Palette_Type is 1 (RGB Text) there should be 16 color
entries in the RGB Lookup table. The attribute bytes of the
text screen bitmap shall specify a background color in their
high order nibble and a foreground color in their low order
nibble (See item 6 below).

If Palette_Type is 2 there should be (2^Pixel_Bits) color
entries in the RGB Lookup table. Each color entry is three
bytes long; first byte RED, second byte GREEN, third byte
BLUE. These 8 bit quantaties will represent output levels
as defined by the IBM VGA graphics adapter.

If Palette_Type is 3 (RGB Pixels) there is no lookup table
and each pixel contains its own RGB specification. The
Pixel_Bits parameter is integer divided by three giving a
number of bits per color gun. BLUE bits are considered the
low order bits of the pixel number with RED in the high
order bits and GREEN in between. The pixel number should be
right justified with unused bits in the highest order
positions.


BLOCKED AND UNBLOCKED GX2 FILES

After Palette_Type is a byte which represents the
number of blocks (rectangular subsets of the resolution
space defined by Gx2_ResX and Gx2_ResY) that are present
in the file. If Blk_Count=0, no block header is required
and it is assumed that data for the entire resolution space
follows. If Blk_Count is NOT zero, then the data for each
block must be preceeded by a BLOCK HEADER of the following
form :

blk_pixels WORD pixels per scan
blk_lines WORD scan lines per block
blk_x WORD left ordinate
blk_y WORD top ordinate

NO COMPRESSION IS PERFORMED ON ANY OF THE ABOVE AREAS.

Bitmap data follows the palette data and is organized as
follows:

1. Scan lines are processed in top-down order.

2. Pixels in a scan line are processed left to right.

3. Where more than 1 pixel fits in a byte, the leftmost
pixel is in the highest order bits.

3a. If a group of pixels will not completely fill a
byte, the pixels are in the highest order bits
and the extra bits are ZERO (left justified).

4. Where a pixel requires more than 1 byte, the least
significant byte is stored first. For RGB pixels, Red
is considered most significant and Blue least.

4a. If Pixel_Bits is not a multiple of 8, extra high
order bits are ZERO (pixel num right justified).

5. The bytes of pixel data are compressed in the GX1 manner
which is as follows:

5a. The first scan line is sent to the run-length
encoder (described in 5c) verbatum.

5b. Subsequent scan lines are represented by a CHANGE
MAP wherein each set bit describes the position of
a byte whose value differs from that of the
previous scan line, followed by the new values
themselves. Thus vertically redundant bytes are
compressed to 1 ZERO bit in the change map.

5c. The output data of 5a and 5b are then further
processed by the RUN-LENGTH ENCODER which serves
to minimize horizontally redundant data. Each
run-length packet consists of a byte count 0..127
with the high order bit set if it is a count of
repeating bytes. The run-length count (n) is then
followed by 1 byte of repeating data or n bytes of
non-repeating data. Four identical bytes in a row
is the minimum for a repeating run-length (e.g.
run-length values 80..83 hex are illegal).

6. Text bitmaps also subscribe to the GX1 format. All
character codes are stored first, optionally followed
by all CGA-style text attribute codes. If no attribute
codes are present, the text screen is assumed to be
monochrome. For Text bitmaps, the Pixel_Bits header
parameter is ignored and the Gx2_ResX parameter
should be set to the number of characters per line.


EXAMPLES

Below are two examples of a GX2 file header for a CGA picture.
The first is unblocked and the second contains two blocks.

UNBLOCKED GX2 FILE HEADER EXAMPLE

gx2_id dw 'GX2'
gx2_version db 1
head_size dw (offset palette_type) - (offset gx2_id)
pixel_bits db 2
line_pixels dw 320
file_lines dw 200
hor_size dw 4
ver_size dw 3
size_units db 0
tag_area label byte
tag_size dw 10
tag_id db 'TGID'
tag_data db 7,8,9,10
palette_type db 2
num_blocks db 0
palette_data db 0,0,0 ;Color 0 = Black
db 0,0,255 ;Color 1 = Green
db 255,0,0 ;Color 2 = Red
db 255,0,255 ;Color 3 = Yellow

; data for the entire screen is compressed here


BLOCKED GX2 FILE HEADER EXAMPLE

gx2_id dw 'GX2'
gx2_version db 1
head_size dw (offset palette_type) - (offset gx2_id)
pixel_bits db 2
line_pixels dw 320
file_lines dw 200
hor_size dw 4
ver_size dw 3
size_units db 0
tag_area label byte
tag_size dw 10
tag_id db 'MyTg'
tag_data db 7,8,9,10
palette_type db 2
num_blocks db 2
palette_data db 0,0,0 ;Color 0 = Black
db 0,0,255 ;Color 1 = Green
db 255,0,0 ;Color 2 = Red
db 255,0,255 ;Color 3 = Yellow
blk_head1 label word
blk_pixels dw 160 ;Top-Left quarter of screen
blk_lines dw 100
blk_x dw 0
blk_y dw 0

; Compressed data for for block 1 goes here

blk_head2 label word
blk_pixels dw 160 ;Bottom-right quarter of screen
blk_lines dw 100
blk_x dw 160
blk_y dw 100

; Compressed data for for block 2 goes here

blk_eof dw 0 ;No more blocks