PCX.TXT

PCX.TXT


Remove Frame

Technical Reference Manual

Including information for:
Publisher's Paintbrushr
PC Paintbrush IVTM
PC Paintbrush IV PlusTM
PC Paintbrush PlusTM
PC Paintbrushr
FRIEZETM Graphics
PaintbrushTM

Revision 5

ZSoft Corporation
450 Franklin Rd. Suite 100
Marietta, GA  30067
(404) 428-0008
(404) 427-1150 Fax
(404) 427-1045 BBS

Copyright c 1985, 1987, 1988, 1990, 1991, ZSoft Corporation 
All Rights Reserved


Technical Reference Manual 	

Introduction 	2 
Image  File (.PCX) Format 	3 
ZSoft .PCX FILE HEADER FORMAT 	4 
Decoding .PCX Files 	6 
Palette Information Description 	7 
EGA/VGA 16 Color Palette Information 	7 
VGA 256 Color Palette Information 	7 
24-Bit .PCX Files 	8 
CGA Color Palette Information 	8 
CGA Color Map 	8 
PC Paintbrush Bitmap Character Format 	9 
Sample "C" Routines 	10 
FRIEZE Technical Information 	14 
General FRIEZE Information 	14 
7.00 and Later FRIEZE 	14 
FRIEZE Function Calls 	15 
FRIEZE Error Codes 	18 




Introduction

This booklet was designed to aid developers and users in understanding 
the technical aspects of the .PCX file format and the use of FRIEZE.  
Any comments, questions or suggestions about this booklet should be sent to:

ZSoft Corporation
Technical Services
ATTN: Code Librarian
450 Franklin Rd. Suite 100
Marietta, GA  30067



Technical Reference Manual information compiled by:
Dean Ansley


Revision 5

To down load additional information and the source for a complete 
Turbo Pascal program to show .PCX files on a CGA/EGA/VGA graphics 
display, call our BBS at (404)427-1045.  You may use a 9600 baud  
modem or a 2400 baud standard modem.  Your modem should be set for 
8 data bits, 1 stop bit, and NO parity.

Image  File (.PCX) Format

If you have technical questions on the format, please do not call 
technical support.  ZSoft provides this document as a courtesy to 
its users and developers.  It is not the function of Technical Support to 
provide programming assistance.  If something is not clear, leave a 
message on our BBS, Compuserve, or write us a letter at the above address.
The information in this section will be useful if you want to write 
a program to read or write PCX files (images).  If you want to write 
a special case program for one particular image format you should be able 
to produce something that runs twice as fast as "Load from..." in 
PC Paintbrush.  

Image files used by PC Paintbrush product family and FRIEZE (those with 
a .PCX extension) begin with a 128 byte header.  Usually you can ignore 
this header, since your images will probably all have the same 
resolution.  If you want to process different resolutions or colors, you 
will need to interpret the header correctly.  The remainder of the image 
file consists of encoded graphic data.  The encoding method is a simple 
byte oriented run-length technique.  We reserve the right to change 
this method to improve space efficiency.  When more than one color plane 
is stored in the file, each line of the image is stored by color plane 
(generally ordered red, green, blue, intensity), As shown below.

Scan line 0: 	RRR...	(Plane 0)
	GGG...	(Plane 1)
	BBB...	(Plane 2)
	III...		(Plane 3)
Scan line 1: 	RRR...
	GGG...
	BBB...
	III...		(etc.)

The encoding method is:
    FOR  each  byte,  X,  read from the file
        IF the top two bits of X are  1's then
            count = 6 lowest bits of X
            data = next byte following X
        ELSE
            count = 1
            data = X
Since the overhead this technique requires is, on average,  25% 
of the non-repeating data and is at least offset whenever bytes are 
repeated, the file storage savings are usually considerable.

ZSoft .PCX FILE HEADER FORMAT

Byte 	Item 	Size 	Description/Comments 

0 	Manufacturer 	1 	Constant Flag, 10 = ZSoft .pcx 
1 	Version 	1 	Version information 
			0 = Version 2.5 of PC Paintbrush 
			2 = Version 2.8 w/palette information 
			3 = Version 2.8 w/o palette information 
			4 = PC Paintbrush for Windows(Plus for Windows 
                            uses Ver 5) 
			5 = Version 3.0 and > of PC Paintbrush and 
                        PC Paintbrush +, includes Publisher's Paintbrush . 
                        Includes 24-bit .PCX files 
2 	Encoding 	1 	1 = .PCX run length encoding 
3 	BitsPerPixel 	1 	Number of bits to represent a pixel (per 
                                Plane) - 1, 2, 4, or 8 
4 	Window 	8 	Image Dimensions: Xmin,Ymin,Xmax,Ymax 
12 	HDpi 	2 	Horizontal Resolution of image in DPI* 
14 	VDpi 	2 	Vertical Resolution of image in DPI* 
16 	Colormap 	48  	Color palette setting, see text 
64 	Reserved 	1 	Should be set to 0. 
65 	NPlanes 	1 	Number of color planes 
66 	BytesPerLine 	2 	Number of bytes to allocate for a scanline 
                                plane.  MUST be an EVEN number.  Do 
                                NOT calculate from Xmax-Xmin. 
68 	PaletteInfo 	2 	How to interpret palette- 1 = Color/BW, 
                                2 = Grayscale (ignored in PB IV/ IV +) 
70 	HscreenSize 	2 	Horizontal screen size in pixels. New field 
                                found only in PB IV/IV Plus 
72 	VscreenSize 	2 	Vertical screen size in pixels. New field 
                                found only in PB IV/IV Plus 
74 	Filler 	54 	Blank to fill out 128 byte header.  Set all bytes to 0 

NOTES:

All sizes are measured in BYTES. 
All variables of SIZE 2 are integers.  
*HDpi and VDpi represent the Horizontal and Vertical resolutions which the image was created (either printer or scanner); i.e. an image which was scanned might have 300 and 300 in each of these fields.

Decoding .PCX Files

First, find the pixel dimensions of the image by calculating 
[XSIZE = Xmax - Xmin + 1] and [YSIZE = Ymax - Ymin + 1].  
Then calculate how many bytes are required to hold one complete 
uncompressed scan line:

TotalBytes = NPlanes * BytesPerLine

Note that since there are always an even number of bytes per scan line, 
there will probably be unused data at the end of each scan line.  
TotalBytes shows how much storage must be available to decode each scan 
line, including any blank area on the right side of the image.  You 
can now begin decoding the first scan line - read the first byte of 
data from the file.  If the top two bits are set, the remaining six bits 
in the byte show how many times to duplicate the next byte in the 
file.  If the top two bits are not set, the first byte is the data 
itself, with a count of one.  Continue decoding the rest of the line.  
Keep a running subtotal of how many bytes are moved and duplicated into 
the output buffer.  

When the subtotal equals TotalBytes, the scan line is complete.  There 
should always be a decoding break at the end of each scan line.  But 
there will not be a decoding break at the end of each plane within 
each scan line.  When the scan line is completed, there may be 
extra blank data at the end of each plane within the scan line.  Use 
the XSIZE and YSIZE values to find where the valid image data is.  
If the data is multi-plane, BytesPerLine shows where each plane ends 
within the scan line.

Continue decoding the remainder of the scan lines (do not just read 
to end-of-file).  There may be additional data after the end of 
the image (palette, etc.)

Palette Information Description

EGA/VGA 16 Color Palette Information

In standard RGB format (IBM EGA, IBM VGA) the data is stored as 16 
triples.  Each triple is a 3 byte quantity of Red, Green, Blue values.  
The values can range from 0-255, so some interpretation may be necessary.  
On an IBM EGA, for example, there are 4 possible levels of RGB for each 
color.  Since 256/4 = 64, the following is a list of the settings and 
levels:

Setting		Level

0-63		0
64-127		1
128-192		2
193-254		3

VGA 256 Color Palette Information

ZSoft has recently added the capability to store palettes containing more 
than 16 colors in the .PCX image file.  The 256 color palette is 
formatted and treated the same as the 16 color palette, except that it 
is substantially longer.  The palette (number of colors x 3 bytes in 
length) is appended to the end of the .PCX file, and is preceded by a 
12 decimal.  Since the VGA device expects a palette value to be 0-63 
instead of 0-255, you need to divide the values read in the palette by 4.
To access a 256 color palette:

First, check the version number in the header; if it contains a 5 
there is a palette.

Second, read to the end of the file and count back 769 bytes.  The value 
you find should be a 12 decimal, showing the presence of a 256 color 
palette.

24-Bit .PCX Files

24 bit images are stored as version 5 or above as 8 bit, 3 plane images.
24 bit images do not contain a palette.
Bit planes are ordered as lines of red, green, blue in that order.

CGA Color Palette Information

NOTE: This is no longer supported for PC Paintbrush IV/IV Plus.

For a standard IBM CGA board, the palette settings are a bit more 
complex.  Only the first byte of the triple is used.  The first triple 
has a valid first byte which represents the background color.  To 
find the background, take the (unsigned) byte value and divide by 16.  
This will give a result between 0-15, hence the background color.  The 
second triple has a valid first byte, which represents the foreground 
palette.  PC Paintbrush supports 8 possible CGA palettes, so when the 
foreground setting is encoded between 0 and 255, there are 8 ranges 
of numbers and the divisor is 32.

CGA Color Map

Header Byte #16 

Background color is determined in the upper four bits.

Header Byte #19

Only upper 3 bits are used, lower 5 bits are ignored.  The first three bits 
that are used are ordered C, P, I.  These bits are interpreted as follows:

c: color burst enable - 0 = color; 1 = monochrome
p: palette - 0 = yellow; 1 = white
i: intensity - 0 = dim; 1 = bright

PC Paintbrush Bitmap Character Format

NOTE: This format is for PC Paintbrush (up to Vers 3.7) and PC 
Paintbrush Plus (up to Vers 1.65)

The bitmap character fonts are stored in a particularly simple format.  The 
format of these characters is as follows:

Header

font width	byte		0xA0 + character width  (in pixels)
font height	byte		character height  (in pixels)

Character Width Table

char widths	(256 bytes) 	each char's width + 1 pixel of kerning

Character Images

(remainder of the file)		starts at char 0  (Null)
The characters are stored in ASCII order and as many as 256 may be 
provided.  Each character is left justified in the character block, all 
characters take up the same number of bytes.
Bytes are organized as N strings, where each string is one scan 
line of the character.  For example, each character in a 5x7 font 
requires 7 bytes.  A 9x14 font uses 28 bytes per character (stored 
two bytes per scan line in 14 sets of 2 byte packets).  Custom 
fonts may be any size up to the current maximum of 10K bytes allowed 
for a font file.  There is a maximum of 4 bytes per scan line.

Sample "C" Routines

The following is a simple set of C subroutines to read data from a 
.PCX file.

/* This procedure reads one encoded block from the image file and stores a 
count and data byte.
Return result:  0 = valid data stored, EOF = out of data in file */

encget(pbyt, pcnt, fid)
int *pbyt;	/* where to place data */
int *pcnt;	/* where to place count */
FILE *fid;	/* image file handle */
{
int i;
	*pcnt = 1;	/* assume a "run" length of one */
	if (EOF == (i = getc(fid)))
		return (EOF);
	if (0xC0 == (0xC0 & i))
		{
		*pcnt = 0x3F & i;
		if (EOF == (i = getc(fid)))
			return (EOF);
		}
	*pbyt = i;
	return (0);
}

/* Here's a program fragment using encget.  This reads an entire file and 
stores it in a (large) buffer, pointed to by the variable "bufr". 
"fp" is the file pointer for the image */

int i;
long l, lsize;
	lsize = (long )hdr.BytesPerLine * hdr.Nplanes * (1 + hdr.Ymax - hdr.Ymin);
	for (l = 0; l < lsize; )             /* increment by cnt below */
		{
		if (EOF == encget(&chr, &cnt, fp))
			break;
		for (i = 0; i < cnt; i++)
			*bufr++ = chr;
		l += cnt;

		}
The following is a set of C subroutines to write data to a .PCX file.

/* Subroutine for writing an encoded byte pair (or single byte if it doesn't 
encode) to a file.
It returns the count of bytes written, 0 if error */

encput(byt, cnt, fid)
unsigned char byt, cnt;
FILE *fid;
{
  if (cnt) {
	if ((cnt == 1) && (0xC0 != (0xC0 & byt)))
		{
		if (EOF == putc((int )byt, fid))
			return(0);     /* disk write error (probably full) */
		return(1);
		}
	else
		{
		if (EOF == putc((int )0xC0 | cnt, fid))
			return (0);      /* disk write error */
		if (EOF == putc((int )byt, fid))
			return (0);      /* disk write error */
		return (2);
		}
	}
   return (0);
}

/* This subroutine encodes one scanline and writes it to a file.
It returns number of bytes written into outBuff, 0 if failed. */

encLine(inBuff, inLen, fp)
unsigned char *inBuff;    /* pointer to scanline data */
int inLen;			/* length of raw scanline in bytes */
FILE *fp;			/* file to be written to */
{
unsigned char this, last;
int srcIndex, i;
register int total;
register unsigned char runCount;     /* max single runlength is 63 */
  total = 0;
  runCount = 1;
  last = *(inBuff);

/* Find the pixel dimensions of the image by calculating 

[XSIZE = Xmax - Xmin + 1] and [YSIZE = Ymax - Ymin + 1].  
Then calculate how many bytes are in a "run" */
  for (srcIndex = 1; srcIndex < inLen; srcIndex++)
	{
	this = *(++inBuff);
	if (this == last)     /* There is a "run" in the data, encode it */
		{
		runCount++;
		if (runCount == 63)
			{
			if (! (i = encput(last, runCount, fp)))
				return (0);
			total += i;
			runCount = 0;
			}
		}
	else		/* No "run"  -  this != last */
		{
		if (runCount)
			{
			if (! (i = encput(last, runCount, fp)))
				return(0);
			total += i;
			}
		last = this;
		runCount = 1;
		}
	}	/* endloop */
  if (runCount)	/* finish up */
	{
	if (! (i = encput(last, runCount, fp)))
		return (0);
	return (total + i);
	}
  return (total);
}

FRIEZE Technical Information

General FRIEZE Information

FRIEZE is a memory-resident utility that allows you to capture and save 
graphic images from other programs.  You can then bring these images 
into PC Paintbrush for editing and enhancement.
FRIEZE 7.10 and later can be removed from memory (this can return you 
up to 90K of DOS RAM, depending on your configuration). To remove FRIEZE 
from memory, change directories to your paintbrush directory and type the 
word "FRIEZE".

7.00 and Later FRIEZE

The FRIEZE command line format is:

FRIEZE {PD} {Xn[aarr]} {flags} {video} {hres} {vres} {vnum}

Where:

{PD}	Printer driver filename (without the .PDV extension)
{Xn[aarr]}
		X=S for Serial Printer, P for Parallel Printer, D for disk file.
			(file is always named FRIEZE.PRN)
		n = port number
		aa = Two digit hex code for which return bits cause
			 an abort (optional)
		rr = Two digit hex code for which return bits cause
			a retry (optional)
		NOTE:  These codes represent return values from serial 
or parallel port  BIOS calls.  For values see and IBM BIOS reference 
(such as Ray Duncan's Advanced MS-DOS Programming).

{flags}Four digit hex code
	First Digit controls Length Flag
	Second Digit controls Width Flag
		Third Digit controls Mode Flag
		Fourth Digit controls BIOS Flag
			0 - None
			1 - Dual Monitor Present
			2 - Use internal (true) B/W palette for dithering
				2 color images
			4 - Capture palette along with screen IN VGA ONLY
				Frieze 8.08 & up ONLY)

NOTE:	The length, width and mode flags are printer driver specific.  
See PRINTERS.DAT on disk 1 (or Setup Disk) for correct use.  In general 
width flag of 1 means wide carriage, and 0 means standard width.  Length 
flag of 0 and mode flag of 0 means use default printer driver settings.
If you need to use more than one BIOS flag option, add the needed 
flag values and use the sum as the flag value.

{video} Video driver combination, where the leading digit signifies the high 
level video driver and the rest signifies the low level video driver
		Example = 1EGA - uses DRIVE1 and EGA.DEV
{hres}	Horizontal resolution of the desired graphics mode
{vres}	Vertical resolution of the desired graphics mode
{vnum}	Hardware specific parameter (usually number of color planes)

Note: The last four parameters can be obtained from the CARDS.DAT file, in your PC Paintbrush product directory.

FRIEZE Function Calls

FRIEZE is operated using software interrupt number 10h (the video 
interrupt call).

To make a FRIEZE function call, load 75 (decimal) into the  AH register 
and the function number into the CL register, then either load AL with 
the function argument or load ES and BX with a segment and offset which 
point to the function argument. Do an int 10h. FRIEZE will return a 
result code number in AX.  All other registers are preserved.  In general, 
a result code of 0 means success and other values indicate errors.  However, 
function 20 (get Frieze Version) behaves differently; see below.

No.	Definition 	Arguments
0	Reserved
1	Load Window
	ES:BX - string  (filename to read from)
2	Save Window
	ES:BX - string  (filename to write to)
3	Reserved
4	Reserved	
6	Reserved	
7	Set Window Size
	ES:BX - 4 element word vector of window settings:
	Xmin, Ymin, Xmax, Ymax
8	Reserved
9	Set Patterns	
	ES:BX - 16 element vector of byte values containing the
	screen-to-printer color correspondence
10	Get Patterns
	ES:BX - room for 16 bytes as above
11	Set Mode
12, 13, 14	Reserved
15	Get Window
	ES:BX - room for 4 words of the current window settings
16 	Set Print Options
	ES:BX - character string of printer options.
	Same format as for the FRIEZE command.
17, 18, 19	Reserved
20	Get FRIEZE Version.
	AH gets the whole number portion and AL gets the decimal portion of
	the version number.  (eg. for Freize vesion 7.41, AH will contain 7 and
	AL will contain 41.  If AH =0, you are calling a pre-7.0 version of FRIEZE).
21	Set Parameters
	ES:BX points to an 8 word table  (16 bytes) of parameter settings: 
	TopMargin, LeftMargin, HSize,VSize, Quality/Draft Mode, PrintHres, 
	PrintVres, Reserved.
	Margins and sizes are specified in hundredths  of inches.
		Q/D mode parameter values:
		0 - draft print mode
		1 - quality print mode
		Print resolutions are specified in DPI.
	Any parameter which should be left unchanged may be filled with
	a (-1) (0FFFF hex).  The reserved settings should be filled with a (-1).
22	Get Parameters
	ES:BX points to an 8 word table  (16 bytes) where parameter settings
	are held.
23	Get Printer Res
	ES:BX points to a 12 word table (24 bytes) that holds six printer
	resolution pairs.
24	Reserved (versions 8.00 & up)

FRIEZE Error Codes

When FRIEZE is called using interrupt 10 hex, it will return an error code 
in the AX register.  A value of zero shows that there was no error.  A 
nonzero result means there was an error.  These error codes are explained below.

0	No Error
1	Printout was stopped by user with the ESC key
2	Reserved
3	File read error
4	File write error
5	File not found
6	Invalid Header - not an image, wrong screen mode
7	File close error
8	Disk error - usually drive door open
9	Printer error - printer is off or out of paper
10	Invalid command - CL was set to call a nonexistent  FRIEZE function
11	Can't create file - write protect tab or disk is full
12	Wrong video mode - FRIEZE cannot capture text screens.