ZSoft PCX File Format 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.
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