=========================================================================== CLIP by Peter Donnelly 1301 Ryan Street Victoria BC Canada V8T 4Y8 =========================================================================== INTRODUCTION ------------ The Borland Graphical Interface contains an easy-to-use procedure, PutImage, 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 640x200, 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 , or abort with . 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 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 if you wish to see what lies beneath. Continue saving images from the screen until you're done; then press or to exit. USING CLIP IMAGES IN PASCAL AND C --------------------------------- The data structure used by Borland's image-manipulating procedures and functions is the same in both Pascal and 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. Files of 640x200 resolution are a special case. If you want to display images in the BGI "EGALo" format, only the 16 default colors are available, so it is unlikely you will want any palette information; in any case, the .PAL file produced by CLIP in its EGA mode will be of no use since the palette system is completely different in 200-line and 350-line modes. If you want the full VGA palette data for "VGALo" format, you must create the image in CLIP's 480-line mode. Again, the distortion will make no difference in the final product. 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. ===========================================================================