Category : Tutorials + Patches
Archive   : TECHREF.ZIP
Filename : TECHREF.TXT

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

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


Image File (PCX) Format
-------------------------
If you have technical questions on the format, please do not call technical
support. If something is not clear leave a message on our BBS, Compuserve,
or write us a letter at the above address.

ZSoft does not accept any responsibility for this document or with how the
reader uses it.

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 all have the same resolution.

Scan line 0: RRR...
GGG...
BBB...
III...
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. The format of the file
header is shown on the next page.ZSoft .PCX FILE HEADER FORMAT
Byte item size Description/Comments

0 manufacturer 1 Constant Flag = 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
2 Encoding 1 1 = .PCX run length encoding
3 Bits per pixel 1 Number of bits/pixel per plane
4 Window 8 Picture Dimentions
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
65 NPlanes 1 Number of color planes
66 Bytes per Line 2 Number of bytes per scan line
68 Palette info 2 How to interpret palette
1 = Color/BW,
2 = Grayscale (ignored in PB IV/ IV +)
70 Hscreensize 2 Horizontal screen size in Pels
72 Vscreensize 2 Vertical screen size in Pels
74 Filler 54 Blank to fill out 128 byte header.

NOTES:
All sizes are measured in BYTES. All variables of SIZE are integers. HDpi
and VDpi represent the Horizontal and Vertical resolutions which the image
was created (either printer or scanner); ie. an image which was scanned
might have 300 and 300 in each of these fields. 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 integral number of bytes, 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, i 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. Continue decoding the remainder of the scan lines.
There may be extra scan lines at the bottom of the image, to round to 8
or 16 scan lines.



Palette Information Description
-------------------------------
EGA/VGA 16 Color Palette Information
The palette information is stored in one of two different formats.
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.
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
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.
CGA Color Palette Information
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
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 (2 bytes)
font width db 0a0h + character width (in dots)
font height db character height (in dots)
Character Widths (256 bytes)
char widths db 256 dup(each char's width +1)
Character Images
(remainder of the file)
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 cur

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. 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; /* safety play */
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 */
while (EOF != encget(&chr, &cnt, fp))
for (i = 0; i < cnt; i++)
*bufr++ = chr;
The following is a set of C subroutines to write data to a .PCX file.
/* This subroutine encodes one scanline and writes it to a file */
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 */
{ /* returns number of bytes written into outBuff, 0 if failed */
unsigned char this, last;
int srcIndex, i;
register int total;
register unsigned char runCount; /* max single runlength is 63 */
total = 0;
last = *(inBuff); runCount = 1;

for (srcIndex = 1; srcIndex < inLen; srcIndex++) {
this = *(++inBuff);
if (this == last) {
runCount++; /* it encodes */
if (runCount == 63) {
if (!(i=encput(last, runCount, fp)))
return(0);
total += i;
runCount = 0;
}
}
else { /* 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);
}

/* subroutine for writing an encoded byte pair
(or single byte if it doesn't encode) to a file */
encput(byt, cnt, fid) /* returns count of bytes written, 0 if err */
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);
}FRIEZE Technical Information


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 almost 85K of DOS RAM, depending on your configuration). To do this, you can choose to release FRIEZE from memory in the PCINSTAL menu (

7.00 and Later FRIEZE

The FRIEZE command line format is:
FRIEZE {PD} {Xnaarr} {flags} {video} {hres} {vres} {vnum}
Where:
{PD} Printer driver filename (without the .PDV extension)
{Xnaarr}
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
rr = Two digit hex code for which return bits cause
a retry
{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
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.
{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, on
Disk 1 (or Setup Disk) of your PC Paintbrush diskettes.
Parallel printer return codes:
80h - Busy Signal (0=busy)
40h - Acknowledge
20h - Out of paper
10h - Selected
08h - I/O error
04h - Unused
02h - Unused
01h - Time out
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,
the function number into the CL register and then, either load AL with the
function argument or load ES and BX with a segment and offs
FRIEZE will return a result code number in AX--zero means success, other
values show error conditions. All other registers are unchanged.
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 Reserved
13 Reserved
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 Reserved
18 Reserved
19 Reserved
20 Get FRIEZE Version. AH gets the whole number portion
and AL gets the decimal portion of
the version number. If AH=0, it
can be assumed that it is a
pre-7.00 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
2 - use Hres, Vres for output
resolution. Print resolutions are
specified in DPI. Any parameter
which should be left unchanged may
be filled with a (-1) (0FFFF hex).
The reserved setting 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) where printer resolution
pairs (6 pairs) are held.
24 Reserved (8.00 FRIEZE ONLY)

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:
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.