home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
C!T ROM 5
/
ctrom5b.zip
/
ctrom5b
/
PROGRAM
/
DIVERSEN
/
PCXK53
/
PCXKIT.TXT
< prev
next >
Wrap
Text File
|
1995-01-17
|
18KB
|
432 lines
===========================================================================
USER'S GUIDE
to
PCX KIT
Copyright (c) 1994, 1995
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 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 6.0
Turbo C++ for DOS 3.0, and Borland C++ 4.5
Turbo Assembler 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, hiding the
picture until it is completely written to video memory, and
preserving video memory (conceivably of some use for simple animation
effects or overlaying images, provided the palette does not change).
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, VGA, and Super VGA
Cards" Third Edition (Addison-Wesley, 1994).
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>.
===========================================================================