home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / PCGPEV10.ZIP / PCX.TXT < prev    next >
Text File  |  1994-05-10  |  24KB  |  587 lines

  1.  
  2. ZSoft PCX File Format Technical Reference Manual        
  3.         
  4.         
  5.         
  6. Introduction                            2 
  7. Image  File (.PCX) Format               3 
  8. ZSoft .PCX FILE HEADER FORMAT           4 
  9. Decoding .PCX Files                     6 
  10. Palette Information Description         7 
  11. EGA/VGA 16 Color Palette Information    7 
  12. VGA 256 Color Palette Information       7 
  13. 24-Bit .PCX Files                       8 
  14. CGA Color Palette Information           8 
  15. CGA Color Map                           8 
  16. PC Paintbrush Bitmap Character Format   9 
  17. Sample "C" Routines                    10 
  18. FRIEZE Technical Information           14 
  19. General FRIEZE Information             14 
  20. 7.00 and Later FRIEZE                  14 
  21. FRIEZE Function Calls                  15 
  22. FRIEZE Error Codes                     18 
  23.  
  24.  
  25.  
  26.  
  27.  
  28. Introduction
  29.  
  30. This booklet was designed to aid developers and users in understanding
  31. the technical aspects of the .PCX file format and the use of FRIEZE.
  32. Any comments, questions or suggestions about this booklet should be
  33. sent to:
  34.  
  35.         ZSoft Corporation
  36.         Technical Services
  37.         ATTN: Code Librarian
  38.         450 Franklin Rd. Suite 100
  39.         Marietta, GA  30067
  40.  
  41.  
  42.  
  43. Technical Reference Manual information compiled by:
  44. Dean Ansley
  45.  
  46.  
  47. Revision 5
  48.  
  49. To down load additional information and the source for a complete
  50. Turbo Pascal program to show .PCX files on a CGA/EGA/VGA graphics
  51. display, call our BBS at (404)427-1045.  You may use a 9600 baud 
  52. modem or a 2400 baud standard modem.  Your modem should be set for
  53. 8 data bits, 1 stop bit, and NO parity.
  54.  
  55. Image  File (.PCX) Format
  56.  
  57. If you have technical questions on the format, please do not call
  58. technical support.  ZSoft provides this document as a courtesy to
  59. its users and developers.  It is not the function of Technical Support
  60. to provide programming assistance.  If something is not clear, leave a
  61. message on our BBS, Compuserve, or write us a letter at the above address.
  62.  
  63. The information in this section will be useful if you want to write a
  64. program to read or write PCX files (images).  If you want to write a
  65. special case program for one particular image format you should be able
  66. to produce something that runs twice as fast as "Load from..." in
  67. PC Paintbrush.  
  68.  
  69. Image files used by PC Paintbrush product family and FRIEZE (those with a
  70. .PCX extension) begin with a 128 byte header.  Usually you can ignore this
  71. header, since your images will probably all have the same resolution.  If
  72. you want to process different resolutions or colors, you will need to
  73. interpret the header correctly.  The remainder of the image file consists
  74. of encoded graphic data.  The encoding method is a simple byte oriented
  75. run-length technique.  We reserve the right to change this method to
  76. improve space efficiency.  When more than one color plane is stored in
  77. the file, each line of the image is stored by color plane (generally ordered
  78. red, green, blue, intensity), As shown below.
  79.  
  80. Scan line 0:         RRR...        (Plane 0)
  81.                      GGG...        (Plane 1)
  82.                      BBB...        (Plane 2)
  83.                      III...        (Plane 3)
  84. Scan line 1:         RRR...
  85.                      GGG...
  86.                      BBB...
  87.                      III...        (etc.)
  88.  
  89. The encoding method is:
  90.     FOR  each  byte,  X,  read from the file
  91.         IF the top two bits of X are  1's then
  92.             count = 6 lowest bits of X
  93.             data = next byte following X
  94.         ELSE
  95.             count = 1
  96.             data = X
  97.  
  98. Since the overhead this technique requires is, on average,  25% of
  99. the non-repeating data and is at least offset whenever bytes are repeated,
  100. the file storage savings are usually considerable.
  101.  
  102. ZSoft .PCX FILE HEADER FORMAT
  103.  
  104. Byte      Item          Size   Description/Comments 
  105.  0         Manufacturer 1      Constant Flag, 10 = ZSoft .pcx 
  106.  1         Version      1      Version information 
  107.                                0 = Version 2.5 of PC Paintbrush 
  108.                                2 = Version 2.8 w/palette information 
  109.                                3 = Version 2.8 w/o palette information 
  110.                                4 = PC Paintbrush for Windows(Plus for
  111.                                   Windows uses Ver 5) 
  112.                                5 = Version 3.0 and > of PC Paintbrush
  113.                                   and PC Paintbrush +, includes
  114.                                   Publisher's Paintbrush . Includes
  115.                                   24-bit .PCX files 
  116.  2         Encoding      1     1 = .PCX run length encoding 
  117.  3         BitsPerPixel  1     Number of bits to represent a pixel
  118.                                   (per Plane) - 1, 2, 4, or 8 
  119.  4         Window        8     Image Dimensions: Xmin,Ymin,Xmax,Ymax 
  120. 12         HDpi          2     Horizontal Resolution of image in DPI* 
  121. 14         VDpi          2     Vertical Resolution of image in DPI* 
  122. 16         Colormap     48     Color palette setting, see text 
  123. 64         Reserved      1     Should be set to 0. 
  124. 65         NPlanes       1     Number of color planes 
  125. 66         BytesPerLine  2     Number of bytes to allocate for a scanline
  126.                                   plane.  MUST be an EVEN number.  Do NOT
  127.                                   calculate from Xmax-Xmin. 
  128. 68         PaletteInfo   2     How to interpret palette- 1 = Color/BW,
  129.                                   2 = Grayscale (ignored in PB IV/ IV +) 
  130. 70         HscreenSize   2     Horizontal screen size in pixels. New field
  131.                                   found only in PB IV/IV Plus 
  132. 72         VscreenSize   2     Vertical screen size in pixels. New field
  133.                                   found only in PB IV/IV Plus 
  134. 74         Filler       54     Blank to fill out 128 byte header.  Set all
  135.                                   bytes to 0 
  136.  
  137. NOTES:
  138.  
  139. All sizes are measured in BYTES. 
  140.  
  141. All variables of SIZE 2 are integers.  
  142.  
  143. *HDpi and VDpi represent the Horizontal and Vertical resolutions which the
  144. image was created (either printer or scanner); i.e. an image which was
  145. scanned might have 300 and 300 in each of these fields.
  146.  
  147. Decoding .PCX Files
  148.  
  149. First, find the pixel dimensions of the image by calculating
  150. [XSIZE = Xmax - Xmin + 1] and [YSIZE = Ymax - Ymin + 1].  Then calculate
  151. how many bytes are required to hold one complete uncompressed scan line:
  152.  
  153. TotalBytes = NPlanes * BytesPerLine
  154.  
  155. Note that since there are always an even number of bytes per scan line,
  156. there will probably be unused data at the end of each scan line.  TotalBytes
  157. shows how much storage must be available to decode each scan line, including
  158. any blank area on the right side of the image.  You can now begin decoding
  159. the first scan line - read the first byte of data from the file.  If the
  160. top two bits are set, the remaining six bits in the byte show how many times
  161. to duplicate the next byte in the file.  If the top two bits are not set,
  162. the first byte is the data itself, with a count of one.
  163.  
  164. Continue decoding the rest of the line.  Keep a running subtotal of how
  165. many bytes are moved and duplicated into the output buffer.  When the
  166. subtotal equals TotalBytes, the scan line is complete.  There should always
  167. be a decoding break at the end of each scan line.  But there will not be a
  168. decoding break at the end of each plane within each scan line.  When the
  169. scan line is completed, there may be extra blank data at the end of each
  170. plane within the scan line.  Use the XSIZE and YSIZE values to find where
  171. the valid image data is.  If the data is multi-plane, BytesPerLine shows
  172. where each plane ends within the scan line.
  173.  
  174. Continue decoding the remainder of the scan lines (do not just read to
  175. end-of-file).  There may be additional data after the end of the image
  176. (palette, etc.)
  177.  
  178. Palette Information Description
  179.  
  180. EGA/VGA 16 Color Palette Information
  181.  
  182. In standard RGB format (IBM EGA, IBM VGA) the data is stored as 16 triples.
  183. Each triple is a 3 byte quantity of Red, Green, Blue values.  The values can
  184. range from 0-255, so some interpretation may be necessary.  On an IBM EGA,
  185. for example, there are 4 possible levels of RGB for each color.  Since
  186. 256/4 = 64, the following is a list of the settings and levels:
  187.  
  188. Setting                Level
  189.    0-63                0
  190.  64-127                1
  191. 128-192                2
  192. 193-254                3
  193.  
  194. VGA 256 Color Palette Information
  195.  
  196. ZSoft has recently added the capability to store palettes containing more
  197. than 16 colors in the .PCX image file.  The 256 color palette is formatted
  198. and treated the same as the 16 color palette, except that it is substantially
  199. longer.  The palette (number of colors x 3 bytes in length) is appended to
  200. the end of the .PCX file, and is preceded by a 12 decimal.  Since the VGA
  201. device expects a palette value to be 0-63 instead of 0-255, you need to
  202. divide the values read in the palette by 4.
  203.  
  204. To access a 256 color palette:
  205.  
  206. First, check the version number in the header; if it contains a 5 there is
  207. a palette.
  208.  
  209. Second, read to the end of the file and count back 769 bytes.  The value
  210. you find should be a 12 decimal, showing the presence of a 256 color palette.
  211.  
  212. 24-Bit .PCX Files
  213.  
  214. 24 bit images are stored as version 5 or above as 8 bit, 3 plane images.
  215.  
  216. 24 bit images do not contain a palette.
  217.  
  218. Bit planes are ordered as lines of red, green, blue in that order.
  219.  
  220. CGA Color Palette Information
  221.  
  222. NOTE: This is no longer supported for PC Paintbrush IV/IV Plus.
  223.  
  224. For a standard IBM CGA board, the palette settings are a bit more complex.
  225. Only the first byte of the triple is used.  The first triple has a valid
  226. first byte which represents the background color.  To find the background,
  227. take the (unsigned) byte value and divide by 16.  This will give a result
  228. between 0-15, hence the background color.  The second triple has a valid
  229. first byte, which represents the foreground palette.  PC Paintbrush supports
  230. 8 possible CGA palettes, so when the foreground setting is encoded between
  231. 0 and 255, there are 8 ranges of numbers and the divisor is 32.
  232.  
  233. CGA Color Map
  234.  
  235. Header Byte #16 
  236.  
  237. Background color is determined in the upper four bits.
  238.  
  239. Header Byte #19
  240.  
  241. Only upper 3 bits are used, lower 5 bits are ignored.  The first three bits
  242. that are used are ordered C, P, I.  These bits are interpreted as follows:
  243.  
  244. c: color burst enable - 0 = color; 1 = monochrome
  245.  
  246. p: palette - 0 = yellow; 1 = white
  247.  
  248. i: intensity - 0 = dim; 1 = bright
  249.  
  250. PC Paintbrush Bitmap Character Format
  251.  
  252. NOTE: This format is for PC Paintbrush (up to Vers 3.7) and PC Paintbrush
  253. Plus (up to Vers 1.65)
  254.  
  255. The bitmap character fonts are stored in a particularly simple format.  The
  256. format of these characters is as follows:
  257.  
  258.  
  259. Header
  260.  
  261. font width         byte                0xA0 + character width  (in pixels)
  262. font height        byte                character height  (in pixels)
  263.  
  264. Character Width Table
  265.  
  266. char widths        (256 bytes)         each char's width + 1 pixel of kerning
  267.  
  268. Character Images
  269.  
  270. (remainder of the file)                starts at char 0  (Null)
  271.  
  272. The characters are stored in ASCII order and as many as 256 may be provided.
  273. Each character is left justified in the character block, all characters take
  274. up the same number of bytes.
  275.  
  276. Bytes are organized as N strings, where each string is one scan line of the
  277. character.
  278.  
  279. For example, each character in a 5x7 font requires 7 bytes.  A 9x14 font
  280. uses 28 bytes per character (stored two bytes per scan line in 14 sets of
  281. 2 byte packets).  Custom fonts may be any size up to the current maximum of
  282. 10K bytes allowed for a font file.  There is a maximum of 4 bytes per scan
  283. line.
  284.  
  285. Sample "C" Routines
  286.  
  287. The following is a simple set of C subroutines to read data from a .PCX file.
  288.  
  289. /* This procedure reads one encoded block from the image file and stores a
  290. count and data byte.
  291.  
  292. Return result:  0 = valid data stored, EOF = out of data in file */
  293.  
  294. encget(pbyt, pcnt, fid)
  295. int *pbyt;        /* where to place data */
  296. int *pcnt;        /* where to place count */
  297. FILE *fid;        /* image file handle */
  298. {
  299. int i;
  300.         *pcnt = 1;        /* assume a "run" length of one */
  301.         if (EOF == (i = getc(fid)))
  302.                 return (EOF);
  303.         if (0xC0 == (0xC0 & i))
  304.                 {
  305.                 *pcnt = 0x3F & i;
  306.                 if (EOF == (i = getc(fid)))
  307.                         return (EOF);
  308.                 }
  309.         *pbyt = i;
  310.         return (0);
  311. }
  312. /* Here's a program fragment using encget.  This reads an entire file and
  313. stores it in a (large) buffer, pointed to by the variable "bufr". "fp" is
  314. the file pointer for the image */
  315.  
  316. int i;
  317. long l, lsize;
  318.      lsize = (long )hdr.BytesPerLine * hdr.Nplanes * (1 + hdr.Ymax - hdr.Ymin);
  319.      for (l = 0; l < lsize; )             /* increment by cnt below */
  320.                 {
  321.                 if (EOF == encget(&chr, &cnt, fp))
  322.                         break;
  323.                 for (i = 0; i < cnt; i++)
  324.                         *bufr++ = chr;
  325.                 l += cnt;
  326.                 }
  327.  
  328. The following is a set of C subroutines to write data to a .PCX file.
  329.  
  330. /* Subroutine for writing an encoded byte pair (or single byte if it
  331. doesn't encode) to a file. It returns the count of bytes written, 0 if error */
  332.  
  333. encput(byt, cnt, fid)
  334. unsigned char byt, cnt;
  335. FILE *fid;
  336. {
  337.   if (cnt) {
  338.         if ((cnt == 1) && (0xC0 != (0xC0 & byt)))
  339.                 {
  340.                 if (EOF == putc((int )byt, fid))
  341.                         return(0);     /* disk write error (probably full) */
  342.                 return(1);
  343.                 }
  344.         else
  345.                 {
  346.                 if (EOF == putc((int )0xC0 | cnt, fid))
  347.                         return (0);      /* disk write error */
  348.                 if (EOF == putc((int )byt, fid))
  349.                         return (0);      /* disk write error */
  350.                 return (2);
  351.                 }
  352.         }
  353.    return (0);
  354. }
  355.  
  356. /* This subroutine encodes one scanline and writes it to a file.
  357. It returns number of bytes written into outBuff, 0 if failed. */
  358.  
  359. encLine(inBuff, inLen, fp)
  360. unsigned char *inBuff;    /* pointer to scanline data */
  361. int inLen;                        /* length of raw scanline in bytes */
  362. FILE *fp;                        /* file to be written to */
  363. {
  364. unsigned char this, last;
  365. int srcIndex, i;
  366. register int total;
  367. register unsigned char runCount;     /* max single runlength is 63 */
  368.   total = 0;
  369.   runCount = 1;
  370.   last = *(inBuff);
  371.  
  372. /* Find the pixel dimensions of the image by calculating 
  373. [XSIZE = Xmax - Xmin + 1] and [YSIZE = Ymax - Ymin + 1].  
  374. Then calculate how many bytes are in a "run" */
  375.  
  376.   for (srcIndex = 1; srcIndex < inLen; srcIndex++)
  377.         {
  378.         this = *(++inBuff);
  379.         if (this == last)     /* There is a "run" in the data, encode it */
  380.                 {
  381.                 runCount++;
  382.                 if (runCount == 63)
  383.                         {
  384.                         if (! (i = encput(last, runCount, fp)))
  385.                                 return (0);
  386.                         total += i;
  387.                         runCount = 0;
  388.                         }
  389.                 }
  390.         else                /* No "run"  -  this != last */
  391.                 {
  392.                 if (runCount)
  393.                         {
  394.                         if (! (i = encput(last, runCount, fp)))
  395.                                 return(0);
  396.                         total += i;
  397.                         }
  398.                 last = this;
  399.                 runCount = 1;
  400.                 }
  401.         }        /* endloop */
  402.   if (runCount)        /* finish up */
  403.         {
  404.         if (! (i = encput(last, runCount, fp)))
  405.                 return (0);
  406.         return (total + i);
  407.         }
  408.   return (total);
  409. }
  410.  
  411. FRIEZE Technical Information
  412.  
  413. General FRIEZE Information
  414.  
  415. FRIEZE is a memory-resident utility that allows you to capture and save
  416. graphic images from other programs.  You can then bring these images into
  417. PC Paintbrush for editing and enhancement.
  418.  
  419. FRIEZE 7.10 and later can be removed from memory (this can return you up
  420. to 90K of DOS RAM, depending on your configuration). To remove FRIEZE from
  421. memory, change directories to your paintbrush directory and type the word
  422. "FRIEZE".
  423.  
  424. 7.00 and Later FRIEZE
  425.  
  426. The FRIEZE command line format is:
  427.  
  428. FRIEZE {PD} {Xn[aarr]} {flags} {video} {hres} {vres} {vnum}
  429. Where:
  430. {PD}        Printer driver filename (without the .PDV extension)
  431. {Xn[aarr]}
  432.                 X=S for Serial Printer, P for Parallel Printer, D for disk file.
  433.                         (file is always named FRIEZE.PRN)
  434.                 n = port number
  435.                 aa = Two digit hex code for which return bits cause
  436.                          an abort (optional)
  437.                 rr = Two digit hex code for which return bits cause
  438.                         a retry (optional)
  439.                 NOTE:  These codes represent return values from serial or
  440.                        parallel port  BIOS calls.  For values see and IBM
  441.                        BIOS reference (such as Ray Duncan's Advanced MS-DOS
  442.                        Programming).
  443. {flags}Four digit hex code
  444.         First Digit controls Length Flag
  445.         Second Digit controls Width Flag
  446.                 Third Digit controls Mode Flag
  447.                 Fourth Digit controls BIOS Flag
  448.                         0 - None
  449.                         1 - Dual Monitor Present
  450.                         2 - Use internal (true) B/W palette for dithering
  451.                                 2 color images
  452.                         4 - Capture palette along with screen IN VGA ONLY
  453.                                 Frieze 8.08 & up ONLY)
  454.  
  455. NOTE: The length, width and mode flags are printer driver specific.
  456. See PRINTERS.DAT on disk 1 (or Setup Disk) for correct use.  In general
  457. width flag of 1 means wide carriage, and 0 means standard width.  Length
  458. flag of 0 and mode flag of 0 means use default printer driver settings.
  459.  
  460. If you need to use more than one BIOS flag option, add the needed flag values
  461. and use the sum as the flag value.
  462.  
  463. {video}       Video driver combination, where the leading digit signifies the
  464.                 high level video driver and the rest signifies the low
  465.                 level video driver
  466.                 Example = 1EGA - uses DRIVE1 and EGA.DEV
  467. {hres}        Horizontal resolution of the desired graphics mode
  468. {vres}        Vertical resolution of the desired graphics mode
  469. {vnum}        Hardware specific parameter (usually number of color planes)
  470.  
  471. Note: The last four parameters can be obtained from the CARDS.DAT file,
  472. in your PC Paintbrush product directory.
  473.  
  474.  
  475. FRIEZE Function Calls
  476.  
  477. FRIEZE is operated using software interrupt number 10h (the video interrupt
  478. call).
  479.  
  480. To make a FRIEZE function call, load 75 (decimal) into the  AH register and
  481. the function number into the CL register, then either load AL with the
  482. function argument or load ES and BX with a segment and offset which point
  483. to the function argument. Do an int 10h. FRIEZE will return a result code
  484. number in AX.  All other registers are preserved.  In general, a result
  485. code of 0 means success and other values indicate errors.  However, function
  486. 20 (get Frieze Version) behaves differently; see below.
  487. No.      Definition         Arguments
  488. 0        Reserved
  489. 1        Load Window
  490.                             ES:BX - string  (filename to read from)
  491. 2        Save Window
  492.                             ES:BX - string  (filename to write to)
  493. 3        Reserved
  494. 4        Reserved        
  495. 6        Reserved        
  496. 7        Set Window Size
  497.                             ES:BX - 4 element word vector of window settings:
  498.                             Xmin, Ymin, Xmax, Ymax
  499. 8        Reserved
  500. 9        Set Patterns        
  501.                             ES:BX - 16 element vector of byte values
  502.                             containing the screen-to-printer color                                          correspondence
  503. 10        Get Patterns
  504.                             ES:BX - room for 16 bytes as above
  505. 11        Set Mode
  506. 12,13,14  Reserved
  507. 15        Get Window
  508.                             ES:BX - room for 4 words of the current window
  509.                             settings
  510. 16         Set Print Options
  511.                             ES:BX - character string of printer options.
  512.                             Same format as for the FRIEZE command.
  513. 17, 18, 19        Reserved
  514. 20        Get FRIEZE Version.
  515.                             AH gets the whole number portion and AL gets the
  516.                             decimal portion of the version number.  (eg. for
  517.                             Freize vesion 7.41, AH will contain 7 and AL will
  518.                             contain 41.  If AH =0, you are calling a pre-7.0
  519.                             version of FRIEZE).
  520. 21        Set Parameters
  521.                             ES:BX points to an 8 word table  (16 bytes) of
  522.                             parameter settings: TopMargin, LeftMargin,
  523.                             HSize,VSize, Quality/Draft Mode, PrintHres,
  524.                             PrintVres, Reserved.
  525.                             Margins and sizes are specified in hundredths
  526.                             of inches.
  527.                                     Q/D mode parameter values:
  528.                                     0 - draft print mode
  529.                                     1 - quality print mode
  530.                                     Print resolutions are specified in DPI.
  531.                             Any parameter which should be left unchanged may
  532.                             be filled with a (-1) (0FFFF hex).  The reserved
  533.                             settings should be filled with a (-1).
  534. 22        Get Parameters
  535.                             ES:BX points to an 8 word table (16 bytes) where
  536.                             parameter settings are held.
  537. 23        Get Printer Res
  538.                             ES:BX points to a 12 word table (24 bytes) that
  539.                             holds six printer resolution pairs.
  540. 24        Reserved (versions 8.00 & up)
  541.  
  542. FRIEZE Error Codes
  543.  
  544. When FRIEZE is called using interrupt 10 hex, it will return an error code
  545. in the AX register.  A value of zero shows that there was no error.  A
  546. nonzero result means there was an error.  These error codes are explained
  547. below.
  548.  
  549.  0        No Error
  550.  1        Printout was stopped by user with the ESC key
  551.  2        Reserved
  552.  3        File read error
  553.  4        File write error
  554.  5        File not found
  555.  6        Invalid Header - not an image, wrong screen mode
  556.  7        File close error
  557.  8        Disk error - usually drive door open
  558.  9        Printer error - printer is off or out of paper
  559. 10        Invalid command - CL was set to call a nonexistent  FRIEZE function
  560. 11        Can't create file - write protect tab or disk is full
  561. 12        Wrong video mode - FRIEZE cannot capture text screens.
  562.  
  563. Technical Reference Manual
  564.  
  565. Including information for:
  566. Publisher's Paintbrushr
  567. PC Paintbrush IVTM
  568. PC Paintbrush IV PlusTM
  569. PC Paintbrush PlusTM
  570. PC Paintbrushr
  571. FRIEZETM Graphics
  572. PaintbrushTM
  573. Revision 5
  574.  
  575. ZSoft Corporation
  576. 450 Franklin Rd. Suite 100
  577. Marietta, GA  30067
  578. (404) 428-0008
  579. (404) 427-1150 Fax
  580. (404) 427-1045 BBS
  581.  
  582. Copyright c 1985, 1987, 1988, 1990, 1991, ZSoft Corporation 
  583. All Rights Reserved
  584.  
  585.  
  586.  
  587.