Changes between Initial Version and Version 1 of Develop/FileFormats/PCX

Timestamp:

Jan 19, 2018, 10:42:34 AM (6 years ago)

Author:

Thomas Bernard

Comment:

Soft PCX File Format Technical Reference Manual

Develop/FileFormats/PCX

@@ +1 @@
+PCX is the format used by ZSoft PC Paintbrush.
+Below is the Reference manual from ZSoft :
+{{{
+Soft 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
+
+
+
+}}}