587 lines
22 KiB
Plaintext
587 lines
22 KiB
Plaintext
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
|
||
|
||
|
||
|
||
|