GEOPAINT FILE FORMAT

Cards and color on the C64 (background info)
--------------------------------------------
The graphics mode used by GEOS on the c64 supports 320 by 200 resolution,
organized as a 40 by 25 matrix of 8 by 8 pixel cards.  These cards are stored
in the frame buffer from left to right, top to bottom. The diagram below better
illustrates this format.


ON SCREEN:
card 0  card 1  card 2 ...   card39
card40  card41  card42 ...   card79
 .  
 .  
 .  
card960 card961 card962 ...  card999


EACH CARD:  byte0
            byte1
            ... 
            byte6
            byte7

Each byte contains 8 bits, 1 per pixel on the screen. These eight bytes make
up an 8 by 8 pixel image.


IN FRAME BUFFER:
               CARD0    CARD1    CARD2
CARD ROW 0 ->  byte0    byte8   byte 16
 
                ...      ...      ...
               byte7    byte15  byte23


              CARD40   CARD41   CARD42
CARD ROW 1 -> byte320  byte328 byte336
                ...      ...      ...
              byte327  byte335 byte443
 
This graphics mode supports 16 colors, but the color resolution is limited to
card boundaries. That is, two colors can be specified for each card on the
screen -- a background color (bits set to 0 in the card) and a foreground
color (bits set to 1 in the card). This color information is stored separately
from the frame buffer, one byte per card. The high 4 bits in the byte
specify one of 16 colors to be used for the foreground, and the low four bits
specify the background color.


GEOPaint FILE FORMAT
--------------------

A geoPaint data file is a VLIR file with 45 records.  (For info on what a
VLIR file is, see the GEOS Programmer's Reference Manual). Each record holds
the image and color data for an area of the page 16 lines high by 640 pixels
wide. A geoPaint document is 720 lines high by 640 pixels wide, so each record
represents two card rows of the entire document. The image data is stored in
the same card format used by the 320 by 200 graphics mode on the c64, discussed
above.

When a geoPaint file is created, all 45 records are marked as used in the index
table of the VLIR file. The track and sector pointers are set to $00,$FF to
indicate an empty record; instead of $00,$00 which indicates an unused
record.

The 45 records are assigned to alternate card rows, from top to bottom
on the document. That is, record 0 contains the image and color data for
card rows 0 and 1; record 1 for card rows 2 and 3, etc.

The image and color info is compacted before being written to the record. The
pre-compacted layout of the data is:


#bytes  start/end ($)  description  
------  -------------  -----------  
 640     000 - 27F     image data for 1st card row
 640     280 - 4ff     image data for 2nd card row
   8     500 - 507     all zeroes
  80     508 - 557     color info for first card row
  80     558 - 5a7     color info for 2nd card row
 
(The eight bytes of zero were included in geoPaint 1.0 files through an
oversight, and retained after that for compatability.)
 
 
COMPACTION FORMAT
-----------------

The compaction routine operates on the entire 1448 bytes at once, resulting
in a string of bytes in the following format.


  +---------------+---------------+
  ! command/count !     data      !
  !     byte      !    byte(s)    !
  +---------------+---------------+
 
Where there is one command/count byte, and from 1 to 63 data bytes. This
pattern is repeated until all 1448 bytes are represented. The command/count
 byte is interpreted as follows:
 
 
Hex Value  Interpretation
---------  --------------------------------------------------------------
$00        End of record.
$01 - $3F  Use command byte as COUNT.  The following COUNT data bytes are
           uncompacted.
$40        Invalid command byte.
$41 - $7F  Subtract $40 from the command byte, use the result as COUNT.
           The next 8 data bytes comprise a card to repeat COUNT times.
           These 8 data bytes expand to 8*COUNT image bytes.
$80        Invalid command byte.
$81 - $FF  Subtract $80 from the command byte, use the result as COUNT.
           Repeat the single data byte that follows COUNT times. This
           single byte expands to COUNT image bytes.


===========================================================================

GEOPAINT DATAFILE STRUCTURE 

The VLIR application data file that GeoPaint creates contains bitmap
information for a page with dimensions of 640 horizontal by 720 vertical
pixels.

This page is divided into 8 line high card-rows, just like the C-64 graphics
screen. Each card-row is 640 pixels wide by 8 lines high, and requires 640
bytes of storage to describe the bitmap in that area. Also, each card-row
requires 80 bytes of color information, one byte per card.

GeoPaint stores two card-rows worth of bitmap and color information in each
VLIR record, in the following order:

  640 bytes bitmap info for row #0           (80 cards * 8 bytes each)
  640 bytes bitmap info for row #1           (80 cards * 8 bytes each)
   80 bytes color info for row #0            (80 cards * 1 byte each)
   80 bytes color info for row #1            (80 cards * 1 byte each)


Note that the 640 bytes of bitmap information are structured by cards;
the first eight bytes specify card #0, the next eight specify card #1, and so
on. The first byte of each eight-byte group defines the top line of the card,
the secod byte defines the second line, and so forth. Within each byte, the
most significant bit specifies the left-most pixel in an eight-pixel line
within the card.
 
Each byte which defines color for a card is split up into two four-bit
nibbles. The higher-order nibble (bits 7 through 4) specifies the color of the
foreground in that card while the lower order nibble (bits 3 through 0)
specifies the background color for that card.
 
Before these 1440 bytes are written out to the record, they are compacted using
a run-length encoding scheme. This compaction technique is the same one
used for bitmap images by GEOS. See page 89 of the Programmer's Reference
Manual for an explanation.