home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 21 / CD_ASCQ_21_040595.iso / dos / prg / pas / pcxkit53 / pcxkit.txt < prev    next >
Text File  |  1995-01-17  |  18KB  |  432 lines
  1. ===========================================================================
  2.                                 
  3.                                 USER'S GUIDE
  4.  
  5.                                      to
  6.  
  7.                                   PCX KIT
  8.  
  9.  
  10.                           Copyright (c) 1994, 1995
  11.                              by Peter Donnelly                                
  12.                               
  13.                               Skookum Software
  14.                               1301 Ryan Street
  15.                                 Victoria BC
  16.                                Canada V8T 4Y8
  17.  
  18. ---------------------------------------------------------------------------
  19.                                 
  20. CONTENTS
  21. --------
  22.    
  23.    PCX
  24.      Introduction
  25.      Capabilities
  26.      Using the modules
  27.      References
  28.      
  29.    CLIP
  30.      Introduction
  31.      Operation
  32.      Using CLIP images in Pascal and C/C++
  33.      Incorporating palette changes
  34.      Linking data into the EXE file
  35.      
  36.    CLIPSHOW
  37.      Introduction
  38.      Examples
  39.      
  40. ---------------------------------------------------------------------------
  41.  
  42. PCX
  43. ---   
  44.  
  45. Introduction
  46. ------------        
  47.    
  48.    This is a set of modules to display .PCX files under DOS. The actual 
  49.    work of decoding the file and moving the data into video memory is done 
  50.    in assembler and is very fast.
  51.    
  52.    Versions are provided for Borland Pascal and C++. Both use the same
  53.    assembler modules (VGA.ASM and, in the registered version, SVGA.ASM).
  54.    Compiled versions of these have been provided for those who do not have
  55.    TASM. See comments in the files for instructions on how to compile them
  56.    if you make changes.
  57.                                                    
  58.    PCX.PAS will automatically link in VGAP.OBJ and SVGAP.OBJ when compiled 
  59.    to PCX.TPU. For C++, VGAC.OBJ and SVGAC.OBJ need to be added to the 
  60.    project like any other modules; the supplied versions are for the large 
  61.    memory model. 
  62.    
  63.    Used to create the code were:
  64.  
  65.       Turbo Pascal for DOS 6.0
  66.       Turbo C++ for DOS 3.0, and Borland C++ 4.5
  67.       Turbo Assembler 2.0
  68.  
  69. Capabilities
  70. ------------
  71.  
  72.    The following display modes are supported for VGA cards:
  73.  
  74.               Mode      Resolution  Colors
  75.               ~~~~      ~~~~~~~~~~  ~~~~~~
  76.             0Dh   13d    320 x 200    16
  77.             0Eh   14d    640 x 200    16
  78.             10h   16d    640 x 350    16
  79.             12h   18d    640 x 480    16
  80.             13h   19d    320 x 200   256
  81.  
  82.    The following modes are supported for Super-VGA cards with VESA BIOS:
  83.  
  84.          * 100h  256d    640 x 400   256
  85.          * 101h  257d    640 x 480   256
  86.            102h  258d    800 x 600    16
  87.          * 103h  259d    800 x 600   256
  88.          * 105h  261d   1024 x 768   256
  89.          * 107h  263d   1280 x 1024  256
  90.  
  91.         [* Supported by registered version only.]
  92.  
  93.    The 256-color modes are not supported for PCX files with no palette
  94.    information, i.e. those produced by versions of Paintbrush earlier
  95.    than 3.0.
  96.  
  97.    Images wider than the screen cannot be displayed. Images taller than the 
  98.    screen are written to memory without checking to see whether they 
  99.    overrun the space available.
  100.  
  101.    Note that the video mode is set directly through BIOS, never with the
  102.    BGI. If you want to use any BGI functions after the PCX file is
  103.    displayed, you'll have to rewrite the mode-setting routines (for modes
  104.    supported by the BGI) to use InitGraph and SetGraphMode.
  105.  
  106. Using the modules
  107. -----------------
  108.     
  109.    The sample implementations and the comments in the source code should
  110.    make it clear how to use PCX in your own C++ and Pascal programs.
  111.    Essentially all you have to do is pass the pathname of a PCX file to the
  112.    C++ read_it() or Pascal ReadIt function along with a video mode and an
  113.    options word.
  114.     
  115.    Mode
  116.    ----
  117.       If the mode argument is zero (you can use the constant auto_set or, 
  118.       in Pascal, AutoSet), the program will determine the best mode based 
  119.       on the file's original resolution and the capabilities of the current 
  120.       video display. The image will be displayed at its original resolution 
  121.       unless it is too wide to fit on the screen, in which case the program 
  122.       will try to display it at a higher resolution. 
  123.     
  124.    Options
  125.    -------
  126.       The options argument is set by ORing the supplied constants; see the
  127.       sample implementations, and the list of constants in the modules. The
  128.       available options are horizontal and vertical centering, hiding the
  129.       picture until it is completely written to video memory, and
  130.       preserving video memory (conceivably of some use for simple animation
  131.       effects or overlaying images, provided the palette does not change).
  132.     
  133.    In addition to read_it(), there are some other functions that may be of
  134.    use in direct calls. These are listed in PCX.H and in the interface
  135.    section of PCX.PAS.
  136.     
  137. References
  138. ----------
  139.  
  140.    Richard F. Ferraro, "Programmer's Guide to the EGA, VGA, and Super VGA 
  141.    Cards" Third Edition (Addison-Wesley, 1994).
  142.  
  143.    Richard Wilton, "Programmer's Guide to PC Video Systems" Second
  144.    Edition (Microsoft Press, 1994).
  145.  
  146.    "Technical Reference Manual [for Paintbrush]" (Zsoft, 1988). The
  147.    information in this booklet is also found in a file distributed with
  148.    at least some versions of Microsoft/PC Paintbrush.
  149.  
  150.    Further information on programming for VESA-compliant Super-VGA cards
  151.    can be obtained from:
  152.  
  153.           Video Electronics Standards Association
  154.           2150 North First St., Suite 440
  155.           San Jose CA 95131-2029
  156.           Phone (408) 435-0333
  157.  
  158. ---------------------------------------------------------------------------
  159.  
  160. CLIP
  161. ----
  162.  
  163. Introduction
  164. ------------
  165.  
  166.    The Borland Graphical Interface contains an easy-to-use procedure, 
  167.    PutImage (the PUTIMAGE function in C/C++), for displaying complex images 
  168.    on a portion of the screen. However, the Turbo/Borland C/C++ or Pascal 
  169.    programmer faces the difficulty of getting the image into a usable form 
  170.    in the first place - that is, of drawing it and then converting it into 
  171.    the format that PutImage requires.
  172.  
  173.    CLIP is a bridge between powerful commercial painting programs and the 
  174.    BGI. It lets you "clip" images of any size (up to the 64K limit imposed 
  175.    by PutImage) from PCX files in EGA and VGA medium or high resolution, 
  176.    and puts these images in files that can be used in your C or Pascal 
  177.    routines with a minimum of effort.
  178.  
  179. Operation
  180. ---------
  181.  
  182.    The program is very simple to use. First create a screen-wide PCX 
  183.    graphics file in 16-color 640x350 or 640x480 resolution, using a 
  184.    painting or screen-capture program. (If your software doesn't directly 
  185.    support the PCX format, it may include a conversion program that does.) 
  186.    Then run CLIP with the pathname of the graphics file on the command 
  187.    line; don't include the ".PCX" part.
  188.  
  189.    By default the program will come up in 640x480 resolution if your system 
  190.    supports it, but you can override this default by entering "/e" on the 
  191.    command line after the PCX file name, in which case the display mode 
  192.    will be 640x350 and only EGA palette information will be produced (more 
  193.    on this below).
  194.  
  195.    Now, with the mouse, point to one corner of the image you wish to save. 
  196.    Hold down the left button and drag the mouse to create a frame around 
  197.    the image. The area you are defining includes the pixels covered by the 
  198.    frame lines, so that you can work right to the edge of the screen.
  199.  
  200.    When you release the button, you are prompted to enter a name for the 
  201.    image file. Type the file name and press <Enter>, or abort with <Esc>. 
  202.    You may use any file name except one with the extension ".PAL".
  203.  
  204.    If the image is too large for the BGI PutImage procedure, a bell sounds 
  205.    and you are not allowed to save. The size limit is about 58 percent of 
  206.    the screen in EGA mode or about 42 percent in VGA. If you want to save 
  207.    the entire screen, you can of course do so in chunks; but a better way 
  208.    is to use PCX.PAS or PCX.CPP to display the original PCX image in your 
  209.    program.
  210.  
  211.    By default the co-ordinates of the mouse are shown at the upper right 
  212.    corner of the screen. This information can be useful for cutting images 
  213.    exactly to size, especially if you have made a note of the desired 
  214.    boundaries while working in the magnified mode of your painting program. 
  215.    CLIP will ignore the display of co-ordinates when saving an image 
  216.    clipped from this part of the screen; however, you can toggle off the 
  217.    display with <F1> if you wish to see what lies beneath.
  218.  
  219.    Continue saving images from the screen until you're done; then press 
  220.    <Alt-X> or <F10> to exit.
  221.  
  222. Using CLIP images in Pascal and C/C++
  223. -------------------------------------
  224.  
  225.    The data structure used by Borland's image-manipulating procedures and 
  226.    functions is the same in both Pascal and C/C++, and CLIP's output files 
  227.    are equally usable with either language. The examples in this section 
  228.    will be in Pascal.
  229.  
  230.    The disk file created by CLIP to store an image takes exactly the same 
  231.    form as the data structure created by the GetImage procedure and used by 
  232.    PutImage. It is an untyped file.
  233.  
  234.    The first two words in the file store the width and height respectively 
  235.    of the image (counting from zero: an image of "1 by 1" is actually 2 by 
  236.    2). The PutImage procedure uses these figures to set up the image 
  237.    properly, and they are also used by ImageSize to calculate the storage 
  238.    needed for the image. The BGI does not use data compression; a blank 
  239.    image occupies as much storage space as a complex image of the same 
  240.    dimensions.
  241.  
  242.    Here is a simple routine to import an image from a file and display it 
  243.    at the current pointer.
  244.  
  245.      var    BitMap: Pointer;
  246.          f: file;
  247.  
  248.      Begin
  249.        Assign(f, 'MYIMAGE.IM');
  250.        Reset(f, 1);
  251.        GetMem(BitMap, FileSize(f));
  252.        BlockRead(f, BitMap^, FileSize(f));
  253.        PutImage(GetX, GetY, BitMap^, CopyPut);
  254.      End;
  255.  
  256.    For a program that uses multiple images, it may be convenient to group 
  257.    all the images together in a single data file. It is easy to do so with 
  258.    the DOS Copy command. For example, to create a file "CHESSMEN" 
  259.    containing all the pieces:
  260.  
  261.      COPY KING/B + QUEEN + BISHOP + KNIGHT + ROOK + PAWN CHESSMEN
  262.  
  263.    Note the "/B" argument after the first filename. Do not omit this; it is 
  264.    essential so that DOS treats all the files as binary and does not 
  265.    truncate any on encountering a Control-Z.
  266.  
  267.    Obviously it is up to the programmer to ensure that the file-reading 
  268.    routines take into account the number of bytes occupied by each image. 
  269.    If the file contains images of different sizes that are to be stored 
  270.    dynamically as they are imported, you can use the ImageSize function to 
  271.    determine how much memory to allocate for each image:
  272.  
  273.      var   Width, Height, Size: word;
  274.            BitMap: pointer;
  275.            f: file;
  276.  
  277.      Begin
  278.        Assign(f, 'IMAGES.DTA');
  279.        Reset(f, 1);
  280.        Repeat
  281.          BlockRead(f, Width, 2);            { Get dimensions from header }
  282.          BlockRead(f, Height, 2);
  283.          Size:= ImageSize(0, 0, Width, Height);
  284.          GetMem(BitMap, Size);
  285.          Seek(f, FilePos(f) - 4);           { Back up }
  286.          BlockRead(f, Bitmap^, Size);       { Get whole image }
  287.        Until Eof(f);
  288.      End;    
  289.  
  290.    This routine has the great advantage that you can alter the size of any 
  291.    of the component images in the file without having to change program 
  292.    code.
  293.  
  294. Incorporating palette changes
  295. -----------------------------
  296.  
  297.    Whenever you save an image file, CLIP automatically creates a palette 
  298.    file with the same name and the extension ".PAL". If CLIP is running in 
  299.    EGA (350-line) mode, this is simply an untyped 17-byte file containing a 
  300.    PaletteType record. For the VGA, it is an array of the RGB values for 
  301.    each of the 16 palette entries, or 48 bytes in all.
  302.  
  303.    If you are working in 350-line mode on the VGA, the program presumes 
  304.    that you want only EGA palette data. If you want the full VGA 
  305.    information, you can load the file in 480-line mode; the resulting 
  306.    distortion will make no difference if the clipped images are ultimately 
  307.    to be displayed in their original 350-line format.
  308.  
  309.    For the EGA, you can easily import saved palette values into your own 
  310.    program by BlockReading the palette file into a PaletteType variable. It 
  311.    is then simply a matter of passing that variable into SetAllPalette. (Of 
  312.    course, in many cases it may be preferable to hard-code the palette 
  313.    values, which can be examined with DEBUG.)
  314.  
  315.    For the VGA, things are a bit more complicated. Here you have to make 
  316.    these declarations:
  317.  
  318.        type    RGBrec = record
  319.                           redval, greenval, blueval: byte;
  320.                         end;
  321.     
  322.        var     RGBpalette: array[0..15] of RGBrec;
  323.     
  324.    Now BlockRead the palette file into RGBpalette. From here the data can 
  325.    be passed into the BGI's SetRGBPalette procedure; but first you have to 
  326.    make sure that the palette entries are pointing to the registers you are 
  327.    modifying. (In the VGA, the 16 palette entries don't contain color 
  328.    values; they contain the numbers of color registers, which in turn hold 
  329.    the actual colors.) By default the palette points to registers 0-5, 20, 
  330.    7, and 56-63, which contain the standard EGA colors. You can either 
  331.    modify these registers or else use SetPalette to put the numbers 0-15 in 
  332.    the palette, then modify registers 0-15 with SetRGBPalette.
  333.    
  334. Linking data into the .EXE file
  335. -------------------------------
  336.  
  337.    For the sake of tidiness you may want to incorporate image and palette 
  338.    data in the executable file itself rather than keeping it in separate 
  339.    files. Turbo/Borland Pascal makes this easy.
  340.  
  341.    Suppose you have an image of an apple in the file MYAPPLE.IM. First 
  342.    convert this to an object file with Borland's BINOBJ program thus:
  343.  
  344.      BINOBJ MYAPPLE.IM APPLE GETAPPLE
  345.  
  346.    There are three arguments on the command line. The first is the source 
  347.    file, the second is the destination file (.OBJ is assumed), and the 
  348.    third is the public declaration or interface of the object file. You are 
  349.    creating APPLE.OBJ, which contains the public declaration GetApple.
  350.  
  351.    Now, in your Pascal program, you declare a dummy "procedure" using the 
  352.    public name of the data, and link in the object file:
  353.  
  354.     procedure GetApple; external;
  355.     {$L APPLE.OBJ}
  356.  
  357.    Finally, you declare a pointer variable and assign it the address of the 
  358.    dummy procedure:
  359.  
  360.       var   AppleImage: pointer;
  361.     
  362.       AppleImage:= @GetApple;
  363.     
  364.    And when you want to display the image:
  365.  
  366.      PutImage(X, Y, AppleImage^, CopyPut);
  367.   
  368.    X and Y are the desired screen coordinates for the upper left corner of 
  369.    the image.
  370.  
  371.    Although linked data is convenient, remember that it takes up memory 
  372.    space for the life of the program, whereas data from files can be read 
  373.    into dynamic memory and discarded when no longer needed. If memory is in 
  374.    short supply and an image only has to be written to the screen once (for 
  375.    example, as part of a "title page"), a separate data file is probably 
  376.    the best choice.
  377.  
  378. ---------------------------------------------------------------------------
  379.  
  380. CLIPSHOW
  381. --------
  382.  
  383. Introduction
  384. ------------
  385.    
  386.    This little program is for reviewing your collection of BGI clip art; 
  387.    that is, image files created with CLIP or a similar program and suited 
  388.    for use with the PutImage procedure/function in Turbo/Borland Pascal or 
  389.    C/C++.
  390.  
  391.    To run the program, enter a filespec on the command line. A directory 
  392.    path and the usual wildcards are accepted.
  393.  
  394.    Optionally you may specify a palette file as the second argument. It is 
  395.    assumed that this file is in the same directory as the image file(s); if 
  396.    you don't specify an extension, ".PAL" is appended. If you don't specify 
  397.    a palette at all, the program will attempt to match each image file with 
  398.    a ".PAL" file; for example, it will try to display "ROSE.IM" with the 
  399.    color data from a file called "ROSE.PAL". If there is no matching 
  400.    palette file, or if it is the wrong type for the present display mode, 
  401.    the default colors are used. (See CLIP.DOC for more information on 
  402.    palette files.)
  403.  
  404.    By default the program will run in VGA 640x480 resolution if your system 
  405.    supports it, or in EGA 640x350 otherwise. You can force it into EGA mode 
  406.    by entering "/e" on the command line as the last argument.
  407.  
  408. Examples
  409. --------
  410.  
  411.       C:>clipshow daisy
  412.  
  413.    The program will display "DAISY" from the current directory and will set 
  414.    the colors from "DAISY.PAL" if that palette file exists and is the right 
  415.    type for the default display mode.
  416.  
  417.       C:>clipshow \images\*.im blossoms /e
  418.  
  419.    The program will display all files in C:\IMAGES that have the extension 
  420.    ".IM", using the palette file "BLOSSOMS.PAL" from the same directory, 
  421.    and will run in EGA mode.
  422.  
  423.    The program looks for any BGI-format image files that match the 
  424.    filespec. To weed out non-image files, CLIPSHOW checks the file size 
  425.    against the image size calculated from the first two words in the file; 
  426.    so it will not read a file that has been appended to.
  427.  
  428.    To proceed to the next image, strike <PgDn> or <Enter>. To quit the 
  429.    program, strike <Esc>, <Alt-X>, or <F10>.
  430.  
  431. =========================================================================== 
  432.