PICTOR.TXT

PICTOR.TXT


Remove Frame

 The enclosed document contains a description of the ".PIC"
 file format that is used in the PCPAINT and PICTOR programs.  If you need
 any additional information on the file format for compatibility purposes,
 please contact the Grasp Bulletin Board at 503 482-7435.

 Thank you for your help.

 Sincerely yours,
 Paul Mace Software Inc.


------------------------------------------------------------------------


                   PCPAINT/Pictor Page Format Description

                          Format by John Bridges.

                   Document by Microtex Industries, Inc.





Revision Date: 2/9/88



Global Notes:
------------

PCPAINT 1.0 - Revision 1.0 was developed for Mosue Systems in 1984 supported
only BSAVE files in CGA 4 color mode. In the space between the scan buffers
was a string that read PCPAINT 1.0 followed by 2 bytes which were the pallete
and border information for that picture.

PCPAINT 1.5 - Revision 1.5 was the same as 1.0 except that it contained larger
than screen images and also had a primative packing format. This was sold for
so short a time that it won't be covered here.

PCPAINT 2.0 thru Pictor 3.1 - This document describes these formats. The file
description is identical for all revisions in this range. However, in
PCPAINT 2.0, the bit-planes were packed together so that the pictures
resembled a PCjr picture, or 4 bits per pixel, 1 bit plane. Starting with
Pictor 3.0, the files were saved with the bitplanes separated. This takes a
little more memory in some cases, but the speed in loading and saving was a
desireable consideration.

NOTE TO PROGRAMMERS: A good PCPAINT/Pictor file decoder will use the variables
                     in the header to decode the image and thus be compatible
                     with all formats since the October, 1985 release of
                     PCPAINT 2.0.

Also please note that PCPAINT/Pictor are stored from the bottom up. This is
opposite that of most of the screen adapters it supports. This really causes
no problem, but be aware that you should use a Y table to look up scan lines.
In all PCPAINT/Pictor pictures, the scan lines are continuous. If a picture 
is to be displayed on a particular adapter, the programmer is responsible for
using a y-table to properly interleave the lines if necessary.

Also note that Pictor was designed for speed, so no inter-mode loading is
possible. If you are writing applications that create Pictor images that you
want to load into Pictor, you must remain mode dependent. 

Header - A full description of the file header information.

offset	type	name	description
-------	-------	-------	----------------------------------------------------- 
  0	word	marker	marker that is always 01234h

  2	word	xsize	x size of page in pixels 

  4	word	ysize	y size of page in pixels

  6	word	xoff	x offset into page where lower left hand corner of
			viewport is located (default of 0 is ok)

  8	word	yoff	y offset into page where lower left hand corner of
			viewport is located (default of 0 is ok)

 10	byte	bitsinf	bits 0-3 is the number of bits per pixel per bit
			plane and bits 4-7 is the number of bit planes (so
			4 color cga mode would be 02h and 16 color ega would
			be 31h and plantronics 16 color would be 12h)

 11	byte	emark	marker that is always a 0ffh

 12	byte	evideo	single uppercase letter indicating which video mode
			this picture was created in, can default to 0.

			0 - 40 col text
			1 - 80 col text
			2 - mono text
			3 - 43 line text

			A=320x200x4 cga
			B=320x200x16 pcjr, stbplus, tandy 1000
			C=640x200x2 cga
			D=640x200x16 ega
			E=640x350x2 ega
			F=640x350x4 ega
			G=640x350x16 ega
			H=720x348x2 hercules
			I=320x200x16 plantronics
			J=320x200x16 ega
			K=640x400x2 AT&T or Toshiba 3100
			L=320x200x256 vga
			M=640x480x16 ega plus(video 7, tseng, paradise), vga
			N=720x348x16 Hercules InColor
			O=640x480x2 vga

 13	word	edesc	extra information descriptor defines what is in
			the extra information that follows this header,
			0=nothing
			1=pallet (single byte) border (single byte)[CGA]
			2=pcjr or non ECD 16 color registers (0-15), 1 byte each
			3=EGA with ECD 16 color registers (0-63) 1 byte each
			4=VGA 256 color info - 256 colors, 1 byte each rgb gun.  

 15	word	esize	size of extra information in bytes

 17	byte	edata[]	the actual extra data the size which is defined
			by esize (at offset 15).
 17+
 esize	word	numblks	the number of packed blocks in this file. if this is
			a zero, then data is unpacked. 


Structures - These C structures describe the header information.

struct head {
	unsigned int mark=0x1234;	/* marks begining of a page file */
	unsigned int xsize;		/* x size of page */
	unsigned int ysize;		/* y size of page */
	unsigned int xoff;		/* current x offset into picture of viewport */
	unsigned int yoff;		/* current y offset into picture of viewport */
	unsigned char bitsinf;
}

struct extra {
	unsigned char emark=0xff;
	unsigned char evideo;
	unsigned int edesc;
	unsigned int esize;
}

int edata[esize];
unsigned int numblks;

If the file is packed then what follows is a multi block packed file,
otherwise (if the file is not packed, numblks=0) the actual data follows.

Bit planes follow each other in the file and when packed each bit plane
must start in a new packed block.


Packed Block Description


Packed block header

PBSIZE	dw		;Packed block size. The size of this block
BSIZE	dw		;Unpacked block size
MBYTE	db		;Unique marker byte. This is a byte that does not
			; exist in the current unpacked block. If no unique
			; byte exists, then pick one that is used rarely
			; to avoid too much redundancy.

Packed block data - variable size depending on whether 16 bit run is needed.

MARKER	db		;mark a run (this is where MBYTE goes) 
LENGTH	db		;length of run. if 0, then look at BIGLEN

BIGLEN	dw		;16 bit run count (only exists if LENGTH==0)
DATA	db		;byte to fill run with


Example 1 - a 320x200, 4 color, packed page file, of a white screen. 

	dw	0x1234		;marker
	dw	320		;x size
	dw	200		;y size
	dw	0		;x offset
	dw	0		;y offset
	db	02h		;2 bits per pixel and 1 bit plane

	db	0xff		;extra info flag
	db	'A'		;vidmode
	dw	1		;extra area descriptor (pal and bord)
	dw	2		;bytes in extra area
	db	2,0		;pallet and border (extra information)

	dw	2		;number of packed blocks

;first block
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;second block
	dw	5+5		;packed block size
	dw	7808		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	7808		;16 bit run count
	db	0xff		;byte to fill run with




Example 2 - a 640x350, 16 color, packed page file, of a red screen (color 4).

	dw	0x1234		;marker
	dw	640		;x size
	dw	350		;y size
	dw	0		;x offset
	dw	0		;y offset
	db	31h		;bits per pixel and 1 bit plane

	db	0xff		;new extra info flag
	db	'G'		;vidmode
	dw	3		;extra area descriptor (pal and bord)
	dw	16		;bytes in extra area
	db	0,1,2,3,4,5,14h,7
	db	38h,39h,3ah,3bh,3ch,3dh,3eh,3fh

	dw	16		;number of packed blocks
;block 1 of first bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 2 of first bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 3 of first bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 4 of first bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0		;byte to fill run with
;block 1 of second bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 2 of second bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 3 of second bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 4 of second bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0		;byte to fill run with
;block 1 of third bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;block 2 of third bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;block 3 of third bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0xff		;byte to fill run with
;block 4 of third bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0xff		;byte to fill run with
;block 1 of fourth bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 2 of fourth bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 3 of fourth bit plane
	dw	5+5		;packed block size
	dw	8192		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	8192		;16 bit run count
	db	0		;byte to fill run with
;block 4 of fourth bit plane
	dw	5+5		;packed block size
	dw	3424		;unpacked block size
	db	0		;marker byte
	db	0		;mark a run
	db	0		;a 16 bit run count follows
	dw	3424		;16 bit run count
	db	0		;byte to fill run with



Example 3 - For more detail lets consider a block that isn't all the same.
Say the data consists of 30 2's, and 8, a 4, and 300 1's.

; the block would look like this 

	dw	5+10		;packed block size
	dw	332		;30 + 1 + 1 + 300 bytes as above
	db	ff		;what to mark a run with,
                                ; because there are no ff's in our example.

	db	ff		;mark a run 
	db	30		;8 bit run count
	db	2		;byte to fill run with - 2

	db	8		;not a run marker, so must be data

	db	4		;not a run marker, so must be data

	db	ff		;mark a run
	db	0		;means 16 bit run count follows
	dw	300		;run count	
	db	1		;byte to fill run with - 1


The actual unpacked data that resides in memory consists 2 seperate
sections.

1. The control structure: contains x size, y size, x offset, y offset,
   segment of bit mapped data, number of bits per pixel and number of
   additional bit planes. this information is kept in pcpaint's data segment.

2. The actual bit mapped data: contains the actual page image, mapped from
   bottom left (so bottom scan line is first). The data is contiguous within
   each bit plane, so scan line 1 follows scan line 0 directly. the page
   can and does cross segment boundires (a bit plane can be larger than
   64k). each bit plane follows the previous but starts on a paragraph
   boundary, the printer driver will be passed the offset in paragraphs
   between bit planes and the number of additional planes.
   The bit planes start with bit 0, each additional plane is the next bit.