Piper's Pit BBS/FTP: ibm 0020 - 0029/ibm0020-0029/ibm0028.tar/ibm0028/CSCAP321.ZIP/PCXSPEC.TXT

Text File | 1990-12-21 | 19.3 KB | 868 lines

                       .PCX Technical Reference Manual
                                 Revision 4


         Copyright (c) 1988, ZSoft Corporation.  All rights reserved.







The following technical specification for the .PCX file format is used by
permission of the ZSoft Corporation.  Oakland Group takes no responsibility
for any information listed here.  This information was created by ZSoft and
Oakland presents it here (as received) as a courtesy to those programmers who
wish to have more information about the .PCX file format.

This document includes information for Publisher's Paintbrush (tm), PC
Paintbrush (r) Plus, PC Paintbrush, and FRIEZE Graphics (tm).  (All product
names are trademarks of the ZSoft Corporation.)






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




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 [phone].
You may use a 9600 baud Telebit 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

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

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

SettingLevel

0-630

64-1271

128-1922

193-2543



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.

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 widthbyte0xA0 + character width  (in pixels)

font heightbytecharacter 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

0Reserved

1Load Window

ES:BX - string  (filename to read from)

2Save Window

ES:BX - string  (filename to write to)

3Reserved

4Reserved

6Reserved

7Set Window Size

ES:BX - 4 element word vector of window settings:

Xmin, Ymin, Xmax, Ymax

8Reserved

9Set Patterns

ES:BX - 16 element vector of byte values containing the

screen-to-printer color correspondence

10Get Patterns

ES:BX - room for 16 bytes as above

11Set Mode

12, 13, 14Reserved

15Get 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, 19Reserved

20Get 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).

21Set 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).

22Get Parameters

ES:BX points to an 8 word table  (16 bytes) where parameter
settings

are held.

23Get Printer Res

ES:BX points to a 12 word table (24 bytes) that holds six printer

resolution pairs.

24Reserved (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.

0No Error

1Printout was stopped by user with the ESC key

2Reserved

3File read error

4File write error

5File not found

6Invalid Header - not an image, wrong screen mode

7File close error

8Disk error - usually drive door open

9Printer error - printer is off or out of paper

10Invalid command - CL was set to call a nonexistent  FRIEZE
function

11Can't create file - write protect tab or disk is full

12Wrong 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 4



ZSoft Corporation

450 Franklin Rd. Suite 100

Marietta, GA  30067

[phone]

[phone] Fax

[phone] BBS



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