===========================================================================
                                
                                USER'S GUIDE
                                     to                                
                                PCX KIT 5.0
                             
                             Copyright (c) 1994
                             by Peter Donnelly                                
                              
                              Skookum Software
                              1301 Ryan Street
                                Victoria BC
                               Canada V8T 4Y8

---------------------------------------------------------------------------
                                
CONTENTS
--------
   
   PCX
     Introduction
     Capabilities
     Using the modules
     References
     
   CLIP
     Introduction
     Operation
     Using CLIP images in Pascal and C/C++
     Incorporating palette changes
     Linking data into the EXE file
     
   CLIPSHOW
     Introduction
     Examples
     
---------------------------------------------------------------------------

PCX
---   

Introduction
------------        
   
   This is a set of modules to display .PCX files under DOS. The actual 
   work of decoding the file and moving the data into video memory is done 
   in assembler and is very fast.
   
   Versions are provided for Turbo/Borland Pascal and C++. Both use the 
   same assembler modules (VGA.ASM and, in the registered version, 
   SVGA.ASM). Compiled versions of these have been provided for those
   who do not have TASM. See comments in the files for instructions on how 
   to compile them if you make changes.
                                                   
   PCX.PAS will automatically link in VGAP.OBJ and SVGAP.OBJ when compiled 
   to PCX.TPU. For C++, VGAC.OBJ and SVGAC.OBJ need to be added to the 
   project like any other modules; the supplied versions are for the large 
   memory model. 
   
   Used to create the code were:

      Turbo Pascal for DOS version 6.0
      Turbo C++ for DOS version 3.0
      Turbo Assembler version 2.0

Capabilities
------------

   The following display modes are supported for VGA cards:

              Mode      Resolution  Colors
              ~~~~      ~~~~~~~~~~  ~~~~~~
            0Dh   13d    320 x 200    16
            0Eh   14d    640 x 200    16
            10h   16d    640 x 350    16
            12h   18d    640 x 480    16
            13h   19d    320 x 200   256

   The following modes are supported for Super-VGA cards with VESA BIOS:

         * 100h  256d    640 x 400   256
         * 101h  257d    640 x 480   256
           102h  258d    800 x 600    16
         * 103h  259d    800 x 600   256
         * 105h  261d   1024 x 768   256
         * 107h  263d   1280 x 1024  256

        [* Supported by registered version only.]

   The 256-color modes are not supported for PCX files with no palette
   information, i.e. those produced by versions of Paintbrush earlier
   than 3.0.

   Images wider than the screen cannot be displayed. Images taller than the 
   screen are written to memory without checking to see whether they 
   overrun the space available.

   Note that the video mode is set directly through BIOS, never with the
   BGI. If you want to use any BGI functions after the PCX file is
   displayed, you'll have to rewrite the mode-setting routines (for modes
   supported by the BGI) to use InitGraph and SetGraphMode.

Using the modules
-----------------
    
    The sample implementations and the comments in the source code should 
    make it clear how to use PCX in your own C++ and Pascal programs. 
    Essentially all you have to do is pass the pathname of a PCX file to 
    the C++ read_it() or Pascal ReadIt function along with a video mode and 
    an options word. 
    
    Mode
    ----
      If the mode argument is zero (you can use the constant auto_set or, 
      in Pascal, AutoSet), the program will determine the best mode based 
      on the file's original resolution and the capabilities of the current 
      video display. The image will be displayed at its original resolution 
      unless it is too wide to fit on the screen, in which case the program 
      will try to display it at a higher resolution. 
    
    Options
    -------
      The options argument is set by ORing the supplied constants; see the 
      sample implementations, and the list of constants in the modules. The 
      available options are horizontal and vertical centering, preserving 
      video memory (conceivably of some use for simple animation effects or 
      overlaying images, provided the palette does not change), and hiding 
      the picture until it is completely written to video memory.
    
    In addition to read_it(), there are some other functions that may be of 
    use in direct calls. These are listed in PCX.H and in the interface 
    section of PCX.PAS. 
    
References
----------

   Richard F. Ferraro, "Programmer's Guide to the EGA and VGA Cards"
   (Addison-Wesley, 1988).

   Richard Wilton, "Programmer's Guide to PC Video Systems" Second
   Edition (Microsoft Press, 1994).

   "Technical Reference Manual [for Paintbrush]" (Zsoft, 1988). The
   information in this booklet is also found in a file distributed with
   at least some versions of Microsoft/PC Paintbrush.

   Further information on programming for VESA-compliant Super-VGA cards
   can be obtained from:

          Video Electronics Standards Association
          2150 North First St., Suite 440
          San Jose CA 95131-2029
          Phone (408) 435-0333

---------------------------------------------------------------------------

CLIP
----

Introduction
------------

   The Borland Graphical Interface contains an easy-to-use procedure, 
   PutImage (the PUTIMAGE function in C/C++), for displaying complex images 
   on a portion of the screen. However, the Turbo/Borland C/C++ or Pascal 
   programmer faces the difficulty of getting the image into a usable form 
   in the first place - that is, of drawing it and then converting it into 
   the format that PutImage requires.

   CLIP is a bridge between powerful commercial painting programs and the 
   BGI. It lets you "clip" images of any size (up to the 64K limit imposed 
   by PutImage) from PCX files in EGA and VGA medium or high resolution, 
   and puts these images in files that can be used in your C or Pascal 
   routines with a minimum of effort.

Operation
---------

   The program is very simple to use. First create a screen-wide PCX 
   graphics file in 16-color 640x350 or 640x480 resolution, using a 
   painting or screen-capture program. (If your software doesn't directly 
   support the PCX format, it may include a conversion program that does.) 
   Then run CLIP with the pathname of the graphics file on the command 
   line; don't include the ".PCX" part.

   By default the program will come up in 640x480 resolution if your system 
   supports it, but you can override this default by entering "/e" on the 
   command line after the PCX file name, in which case the display mode 
   will be 640x350 and only EGA palette information will be produced (more 
   on this below).

   Now, with the mouse, point to one corner of the image you wish to save. 
   Hold down the left button and drag the mouse to create a frame around 
   the image. The area you are defining includes the pixels covered by the 
   frame lines, so that you can work right to the edge of the screen.

   When you release the button, you are prompted to enter a name for the 
   image file. Type the file name and press <Enter>, or abort with <Esc>. 
   You may use any file name except one with the extension ".PAL".

   If the image is too large for the BGI PutImage procedure, a bell sounds 
   and you are not allowed to save. The size limit is about 58 percent of 
   the screen in EGA mode or about 42 percent in VGA. If you want to save 
   the entire screen, you can of course do so in chunks; but a better way 
   is to use PCX.PAS or PCX.CPP to display the original PCX image in your 
   program.

   By default the co-ordinates of the mouse are shown at the upper right 
   corner of the screen. This information can be useful for cutting images 
   exactly to size, especially if you have made a note of the desired 
   boundaries while working in the magnified mode of your painting program. 
   CLIP will ignore the display of co-ordinates when saving an image 
   clipped from this part of the screen; however, you can toggle off the 
   display with <F1> if you wish to see what lies beneath.

   Continue saving images from the screen until you're done; then press 
   <Alt-X> or <F10> to exit.

Using CLIP images in Pascal and C/C++
-------------------------------------

   The data structure used by Borland's image-manipulating procedures and 
   functions is the same in both Pascal and C/C++, and CLIP's output files 
   are equally usable with either language. The examples in this section 
   will be in Pascal.

   The disk file created by CLIP to store an image takes exactly the same 
   form as the data structure created by the GetImage procedure and used by 
   PutImage. It is an untyped file.

   The first two words in the file store the width and height respectively 
   of the image (counting from zero: an image of "1 by 1" is actually 2 by 
   2). The PutImage procedure uses these figures to set up the image 
   properly, and they are also used by ImageSize to calculate the storage 
   needed for the image. The BGI does not use data compression; a blank 
   image occupies as much storage space as a complex image of the same 
   dimensions.

   Here is a simple routine to import an image from a file and display it 
   at the current pointer.

     var    BitMap: Pointer;
         f: file;

     Begin
       Assign(f, 'MYIMAGE.IM');
       Reset(f, 1);
       GetMem(BitMap, FileSize(f));
       BlockRead(f, BitMap^, FileSize(f));
       PutImage(GetX, GetY, BitMap^, CopyPut);
     End;

   For a program that uses multiple images, it may be convenient to group 
   all the images together in a single data file. It is easy to do so with 
   the DOS Copy command. For example, to create a file "CHESSMEN" 
   containing all the pieces:

     COPY KING/B + QUEEN + BISHOP + KNIGHT + ROOK + PAWN CHESSMEN

   Note the "/B" argument after the first filename. Do not omit this; it is 
   essential so that DOS treats all the files as binary and does not 
   truncate any on encountering a Control-Z.

   Obviously it is up to the programmer to ensure that the file-reading 
   routines take into account the number of bytes occupied by each image. 
   If the file contains images of different sizes that are to be stored 
   dynamically as they are imported, you can use the ImageSize function to 
   determine how much memory to allocate for each image:

     var   Width, Height, Size: word;
           BitMap: pointer;
           f: file;

     Begin
       Assign(f, 'IMAGES.DTA');
       Reset(f, 1);
       Repeat
         BlockRead(f, Width, 2);            { Get dimensions from header }
         BlockRead(f, Height, 2);
         Size:= ImageSize(0, 0, Width, Height);
         GetMem(BitMap, Size);
         Seek(f, FilePos(f) - 4);           { Back up }
         BlockRead(f, Bitmap^, Size);       { Get whole image }
       Until Eof(f);
     End;    

   This routine has the great advantage that you can alter the size of any 
   of the component images in the file without having to change program 
   code.

Incorporating palette changes
-----------------------------

   Whenever you save an image file, CLIP automatically creates a palette 
   file with the same name and the extension ".PAL". If CLIP is running in 
   EGA (350-line) mode, this is simply an untyped 17-byte file containing a 
   PaletteType record. For the VGA, it is an array of the RGB values for 
   each of the 16 palette entries, or 48 bytes in all.

   If you are working in 350-line mode on the VGA, the program presumes 
   that you want only EGA palette data. If you want the full VGA 
   information, you can load the file in 480-line mode; the resulting 
   distortion will make no difference if the clipped images are ultimately 
   to be displayed in their original 350-line format.

   For the EGA, you can easily import saved palette values into your own 
   program by BlockReading the palette file into a PaletteType variable. It 
   is then simply a matter of passing that variable into SetAllPalette. (Of 
   course, in many cases it may be preferable to hard-code the palette 
   values, which can be examined with DEBUG.)

   For the VGA, things are a bit more complicated. Here you have to make 
   these declarations:

       type    RGBrec = record
                          redval, greenval, blueval: byte;
                        end;
    
       var     RGBpalette: array[0..15] of RGBrec;
    
   Now BlockRead the palette file into RGBpalette. From here the data can 
   be passed into the BGI's SetRGBPalette procedure; but first you have to 
   make sure that the palette entries are pointing to the registers you are 
   modifying. (In the VGA, the 16 palette entries don't contain color 
   values; they contain the numbers of color registers, which in turn hold 
   the actual colors.) By default the palette points to registers 0-5, 20, 
   7, and 56-63, which contain the standard EGA colors. You can either 
   modify these registers or else use SetPalette to put the numbers 0-15 in 
   the palette, then modify registers 0-15 with SetRGBPalette.
   
Linking data into the .EXE file
-------------------------------

   For the sake of tidiness you may want to incorporate image and palette 
   data in the executable file itself rather than keeping it in separate 
   files. Turbo/Borland Pascal makes this easy.
 
   Suppose you have an image of an apple in the file MYAPPLE.IM. First 
   convert this to an object file with Borland's BINOBJ program thus:

     BINOBJ MYAPPLE.IM APPLE GETAPPLE

   There are three arguments on the command line. The first is the source 
   file, the second is the destination file (.OBJ is assumed), and the 
   third is the public declaration or interface of the object file. You are 
   creating APPLE.OBJ, which contains the public declaration GetApple.

   Now, in your Pascal program, you declare a dummy "procedure" using the 
   public name of the data, and link in the object file:

    procedure GetApple; external;
    {$L APPLE.OBJ}

   Finally, you declare a pointer variable and assign it the address of the 
   dummy procedure:

      var   AppleImage: pointer;
    
      AppleImage:= @GetApple;
    
   And when you want to display the image:

     PutImage(X, Y, AppleImage^, CopyPut);
  
   X and Y are the desired screen coordinates for the upper left corner of 
   the image.

   Although linked data is convenient, remember that it takes up memory 
   space for the life of the program, whereas data from files can be read 
   into dynamic memory and discarded when no longer needed. If memory is in 
   short supply and an image only has to be written to the screen once (for 
   example, as part of a "title page"), a separate data file is probably 
   the best choice.

---------------------------------------------------------------------------

CLIPSHOW
--------

Introduction
------------
   
   This little program is for reviewing your collection of BGI clip art; 
   that is, image files created with CLIP or a similar program and suited 
   for use with the PutImage procedure/function in Turbo/Borland Pascal or 
   C/C++.

   To run the program, enter a filespec on the command line. A directory 
   path and the usual wildcards are accepted.

   Optionally you may specify a palette file as the second argument. It is 
   assumed that this file is in the same directory as the image file(s); if 
   you don't specify an extension, ".PAL" is appended. If you don't specify 
   a palette at all, the program will attempt to match each image file with 
   a ".PAL" file; for example, it will try to display "ROSE.IM" with the 
   color data from a file called "ROSE.PAL". If there is no matching 
   palette file, or if it is the wrong type for the present display mode, 
   the default colors are used. (See CLIP.DOC for more information on 
   palette files.)

   By default the program will run in VGA 640x480 resolution if your system 
   supports it, or in EGA 640x350 otherwise. You can force it into EGA mode 
   by entering "/e" on the command line as the last argument.

Examples
--------

      C:>clipshow daisy

   The program will display "DAISY" from the current directory and will set 
   the colors from "DAISY.PAL" if that palette file exists and is the right 
   type for the default display mode.

      C:>clipshow \images\*.im blossoms /e

   The program will display all files in C:\IMAGES that have the extension 
   ".IM", using the palette file "BLOSSOMS.PAL" from the same directory, 
   and will run in EGA mode.

   The program looks for any BGI-format image files that match the 
   filespec. To weed out non-image files, CLIPSHOW checks the file size 
   against the image size calculated from the first two words in the file; 
   so it will not read a file that has been appended to.

   To proceed to the next image, strike <PgDn> or <Enter>. To quit the 
   program, strike <Esc>, <Alt-X>, or <F10>.

=========================================================================== 
