Category : C Source Code
Archive   : DBPCXL18.ZIP
Filename : PCXLIB.DOC

------------------------------------------------------------------------------
pcxlib v1.8 Copyright (c) 1992, 1993 by Dave Boynton

------------------------------------------------------------------------------
This library is shareware. You are authorized to use it for personal
use without registration. If you use it for business, or in programs that
you distribute and expect to profit from, you are required to register.
Registration is only $10 and includes registration to my video library.
However, for $20, I'll send you the library source (both pcx.lib and
videof.lib) and the next update. To register, send your name, address
and registration fee to:

David Boynton
7117H DeFranzo Loop
Fort Meade MD 20755

1-410-674-6408 (evenings only)
CIS: 71043,317
internet: [email protected].
------------------------------------------------------------------------------
Limitations
This library currently supports 16 and 256 color pcx files. There
are routines here for monochrome files, but none have been tested.
Writing to pcx files is now implemented and tested, although there is no
read/modify/write setup. I suspect it would be much better to convert the
file to BMP, or some other uncompressed format, for doing modifies.
The examples support up to 1024x768 256 colors, and up to X
in 16 colors.
However, the video library has routines for up to 1280x1024 VESA modes,
so you're welcome to modify the examples to use those modes.

------------------------------------------------------------------------------
Reading PCX files:

Using the library is simple. Follow these steps and you can't go
wrong (famous last words):

1. Insert '#include "pcxlib.h"' in your source code, and 'pcx.lib'
in your project or makefile.

2. Insert '#include "vidlib.h"' in your source code, and 'videof.lib'
in your project or makefile, if you'll be using my video library
(required if you're using any 'fdisp' routines). Add a call to
Vinit() or VESAinit() before calling functions from 'videof.lib'
(other than isVGA() or isVESA(), which can be called anytime).

3. Declare pointers to PCXF, a structure that holds key information
about open pcx files. I'll use 'pfile' in this walk-through, so
that would be:

PCXF *pfile;

4. Choose a debug filename and insert 'Start_pcxdebug(filename);'
in an early part of your program, IFF you want the library to
output debugging information. For example:

Start_pcxdebug("pcx.dbg");

Remember, this is optional; nothing bad will happen if you don't
do this. For speed, the low-level routines don't check for this
but the high-level functions will dump their arguments to the
specified file.

5. Open pcx files with something like:

pfile=fopenPCXr("blast256.pcx");

6. Set the video mode and "realize" the palette, if needed.
"realize" means to make the VGA card use a specified palette
instead of the default.

When using my video library, this is

VGAmode(0x13, pfile->palette);
or VGAmode(0x13, NULL); /* if you want to set the palette later */

for VGA mode 0x13 320x200 256 colors, or

VESAmode(0x100, pfile->palette);

for VESA mode 0x100 640x400 256 colors. (To leave the screen
palette unchanged, replace pfile->palette with NULL.)

7. To change the palette at any other time use:

PCXrealizepalette(pfile,6); /* use 8 if your adapter supports
24bit entries */

or another way for 256 color files:

WriteDACs((void *)palette);

where 'palette' points to a 768 byte buffer containing 256 3-byte
palette entries (remember, the vga only uses the lower 6 bits), or:

WriteDACsn((void *)palette, first, last);

where first & last are in units of 3 bytes, starting with 0.
For 16 color files it would be much better to use the
PCXrealizepalette, since it also ensures that the EGA palette
registers are pointing to the right color registers.

8. Read from the pcx file with either fread8PCX() or fdisp8PCX().
The latter assumes the use of my vidlib library to set the video
mode.
It is also possible to use _read_pcx_line, especially if
line-by-line conversions, or other processing is planned. See
the program testpcx.c for an example of _read_pcx_line.

(I lied before, use of my video library isn't necessary for
the fdisp routines, all you need do is ensure that _screen_start,
_screen_width, and _screen_length are properly updated prior to
calling fdisp8PCX(). For mode 13h (320x200 by 256 colors), these
values should be 0xA0000000L, 320, and 200, respectively. These
variables are declared as externs in vidlib.h. If you won't be
linking with videof.lib, you'll need to declare them in order
to link with pcx.lib.)

9. When done, close the file with fclosePCX(pfile), which not only
closes the file, but frees the memory allocated to hold the
structures.

10. If you opened the pcxdebug file, close it with 'Close_pcxdebug();'.

11. If you called Vinit(), call Vclose() to reset the video to text mode.

See showpcx.c for a working example.


------------------------------------------------------------------------------
Reading partial files & specifying where on the screen to load:

The video library & the fdisp functions have always supported loading
partial files and controlling there placement on the screen. We'll do an
example using the fdisp4PCX() function for loading part of a file on the
screen.
First, the file must have been opened with fopenPCXr(). We'll assume
the pointer returned is "pfile", and that we're already in a 16 color EGA/VGA
mode. Let's say this file is 128 pixels wide by 32 pixels tall. The image has
four "icons" in it, each 32x32. Let's say that we want to load icon #2 onto
the screen at pixel (not byte) x=80,y=40. Here's what we do:

/* int rc; */
rc=fdisp4PCX( 80/8, 40, 32/8, 0, 63/8, 31, pfile);

Notice that the x values had to be divided by eight. The fdisp4PCX expects
byte values, so cannot be used to load pcx files directly into unaligned
display memory.
It can, however, be used to load into offscreen display memory just
by using a valid (but offscreen) y pixel value. For example, let's say the
adapter is a 640x350 VGA mode. There's room in memory for 819 scan lines in
that mode, so you could've easily loaded the file with:

rc=fdisp4PCX( 80/8, 700, 32/8, 0, 63/8, 31, pfile);

------------------------------------------------------------------------------
Using a different video library

The 16 color display functions need to manipulate the VGA registers
to operate properly. The following are used in fdisp4PCX():

What_Wmode(); /* find out what write mode we're in */
SQread_reg(2); /* find out which planes are writable */
Select_Wmode(); /* select EGA/VGA write mode */
Select_WPlane(); /* select which plane(s) are writable */
_screen_width /* variable contains current modes width in bytes */
_screen_start /* far pointer to the begining of video memory */

The 256 color display function simply needs the last two _screen_*
variables. Note that the screen length isn't checked by these functions so
be careful not to pass in a huge number for a y pixel value.

------------------------------------------------------------------------------
Writing PCX files:

Writing is more complex, but still easy.

1. Insert '#include "pcxlib.h"' in your source code, and 'pcx.lib'
in your project or makefile.

2. Declare pointers to PCXF, a structure that holds key information
about open pcx files. I'll use 'pfile' in this walk-through, so
that would be:

PCXF *pfile;

3. Allocate a PCXH structure and fill in the required values.

PCXH *h=(PCXH *)malloc(sizeof(PCXH));

h->Xmin=0; h->Ymin=0;
h->Xmax=639; h->Ymax=479;

/* for 256 color files: */
h->BitsPixel=8;
h->Planes=1;

/* or for 16 color files: */
h->BitsPixel=1;
h->Planes=4;

4. Open a pcx file for writing with:

pfile=fopenPCXw("blast256.pcx",h,(char *)palette);

The PCXH you created can be free'd now, fopenPCXw just copied it
into it's own buffer.

5. Write to the pcx file with _write_pcx_line(). See the example
in testpcx.c

6. Write the palette, if it's a 256 color file.

_write_pcx_file(pfile);

7. When done, close the file with fclosePCX(pfile), which not only
closes the file, but frees the memory allocated to hold the
structures.


See testpcx.c for a working example.

---------------------------------
Update history:
1.8 - Added flashPCX(), which makes a "best guess" of the mode to
use, based on the size of the image and the file type.
It stays on the screen until a key is hit (which is returned
to the caller).
- The showpcx example now uses flashPCX(), so is much simpler.
It can now be compiled with Borland's "wildargs.obj" to make
it cycle through large numbers of files. This is optional, though,
see the makefile.
- Adapters with high-color support usually also support using
the full 8 bits in the palette, thus PCXrealizepalette() now
has a second parameter.
- 16 color support is much better, though VESA 16 color modes
(namely 800x600) is still not there yet.

1.6 - Fixed some ANSI problems, hopefully MSC users can compile now.
- Tested & fixed 16 color functions including writing.
- Added a command line option '-h' to showpcx which forces it to
use the highest resolution mode available.

1.5 - Implemented functions for writing to pcx files.
- Implemented VESA support.
- Added 16 color and monochrome functions (but didn't test them).
- Added a palette display demo program, 'showpal'.

1.1 - Fixed debugging to be useful. The Start_pcxdebug() and
Close_pcxdebug() functions can be called several times during a
given program now; the start function will append if the file
was previously opened and closed.
- Fixed memory allocation problem.