PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/pascal/pcxkit.exe/CLIP.DOC

Text File | 1992-01-11 | 16.7 KB | 370 lines

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

                                    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 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 <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 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 TURBO PASCAL AND TURBO C
---------------------------------------------

The data structure used by Borland's image-manipulating procedures and
functions is the same in both Turbo Pascal and Turbo 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 Turbo 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 Turbo'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 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 (distributed with
Turbo Pascal) 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.


A FEW WORDS ABOUT ANIMATION
---------------------------

As you will see from the enclosed HOEDOWN demonstration, simple animated
effects are very easy to achieve. The demo uses just two repeating images
to give the illusion of movement, but you can use as many as you like,
writing them alternately to the two EGA video pages.

If you look closely at the dancer, you will notice that some of the colors
in his costume change as he moves across various parts of the backdrop. To
understand why, and how to avoid this problem, you need to understand the
concept of logical operations on pixel values.

Each of the palette entries may be represented by a pattern of four bits,
as in the following table.

                Entry  Bit Pattern  Default Color

                  0      0 0 0 0      black
                  1      0 0 0 1      blue
                  2      0 0 1 0      green
                  3      0 0 1 1      cyan
                  4      0 1 0 0      red
                  5      0 1 0 1      magenta
                  6      0 1 1 0      brown
                  7      0 1 1 1      lightgray
                  8      1 0 0 0      darkgray
                  9      1 0 0 1      lightblue
                 10      1 0 1 0      lightgreen
                 11      1 0 1 1      lightcyan
                 12      1 1 0 0      lightred
                 13      1 1 0 1      lightmagenta
                 14      1 1 1 0      yellow
                 15      1 1 1 1      white

There are five different ways that PutImage can write a pixel to the
screen, three of which are most likely to be of use to the animator:
CopyPut, OrPut, and XorPut.

In the first of these, CopyPut, the procedure simply copies the new color
over top of the old one, regardless of the value of either.

HOEDOWN does not use CopyPut because if it did, the background color around
the dancing figure would overwrite the scenic backdrop. (Try it and see.)
Since we do not want the figure to be dancing inside a blank rectangle,
instead we use the OrPut operator. This operator says to PutImage: "For
each pixel, set all bits `on' that are `on' in either the new color or the
old color." For example, using the default palette, if you put a blue pixel
on top of a green one, the result will be cyan.

Because the background color, whatever it is, is always taken from entry 0
of the palette, it will never alter the color of a pixel where it is
printed - it has no bits set, so the product of an OR operation with any
other number will be that number (0 or 6 = 6).

On the other hand, white (or whatever absolute color is in palette entry
15) will always be unchanged by an OR operation, since no more bits can
be set by the operation. In the demo, the figure's blue jeans are drawn
from palette entry 15, so they can safely pass in front of any other color.

Obviously if you wish to use the OrPut operator in PutImage you have to do
some planning. Certain palette entries can be used safely on top of certain
others; other combinations will lead to unwelcome changes. For instance, a
glance at the table above shows that in the default palette, yellow can
safely be superimposed on lightgreen but not on lightblue.

Another approach to the problems inherent in the use of OrPut is to create
a "hole" in the backdrop before placing the image there. To create such a
hole, you could draw a silhouette copy of the image in which all
"transparent" pixels were white and all others black, then put this image on
the screen with AndPut, which would leave the backdrop unaltered where the
silhouette image was white but would erase it elsewhere. The original image
could then be OrPut into this hole with no danger of color changes.

The other logical operator you may find yourself using is XorPut. XORing an
image onto a blank background has the same effect as ORing it. If you
XOR an image onto itself, the image is erased, leaving nothing but
background color. (All bits that the old and new pixels have in common are
set to 0.) This technique is not used in the demo, since we wish to restore
the backdrop scenery, and this is done by copying it over the old dancing
figure.

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

         ----------------end-of-author's-documentation---------------

                         Software Library Information:

                    This disk copy provided as a service of

                           Public (software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  PsL cannot debug pro-
         programs over the telephone, though we can answer questions.

         Disks in the PsL are updated  monthly,  so if you did not get
         this disk directly from the PsL, you should be aware that the
         files in this set may no longer be the current versions. Also,
         if you got this disk from another vendor and are having prob-
         lems,  be aware that  some files may have become corrupted or
         lost by that vendor. Get a current, working disk from PsL.

         For a copy of the latest monthly software library newsletter
         and a list of the 4,000+ disks in the library, call or write

                           Public (software) Library
                                 P.O.Box 35705
                            Houston, TX 77235-5705

                                 Orders only:
                                1-800-2424-PSL
                              MC/Visa/AmEx/Discover

                          Outside of U.S. or in Texas
                          or for general information,
                              Call 1-713-524-6394

                          PsL also has an outstanding
                          catalog for the Macintosh.