PCX_LIB Documentation
---------------------
Version 1.00C
by Ian Ashdown, P.Eng.
Released into the Public Domain 91/04/01
1. Introduction
PCX_LIB is a library of functions for displaying and storing ZSoft's
Paintbrush (R) PCX-format image files. It was developed expressly
for release into the Public Domain. Fully commented ANSI C source
code is provided for all functions, along with complete technical
specifications for ZSoft's PCX image file format.
Version 1.00B supports the display and storage of images on MS-DOS
systems equipped with the following display adapters:
Hercules - monochrome
CGA - Color Graphics Adapter
EGA - Enhanced Graphics Adapter
MCGA - MultiColor Graphics Adapter
VGA - Video Graphics Adapter
All valid MS-DOS graphic modes are supported.
SuperVGA and XGA display adapters are not supported in this release.
p. 1
2. DISCLAIMER:
IN NO EVENT SHALL BYHEART SOFTWARE BE LIABLE FOR ANY DAMAGES
WHATSOEVER INCLUDING, WITHOUT LIMITATION, PERSONAL DAMAGES, DAMAGES
FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR OTHER PECUNIARY LOSS, ARISING OUT OF THE USE OR
INABILITY TO USE THIS PRODUCT, EVEN IF BYHEART SOFTWARE HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
TEST_04.PCX - 320 x 200 4-color CGA test image (mode 4)
TEST_06.PCX - 640 x 200 2-color CGA test image (mode 6)
TEST_16.PCX - 640 x 350 16-color EGA test image (mode 16)
TEST_19.PCX - 320 x 200 256-color VGA test image (mode 19)
3.5. Miscellaneous
PCX_LIB.BAT - Microsoft C V6.0 program build batch file
p. 3
4. Trying It Out
Four test images are included on the disk, one each for MS-DOS video
modes 4, 6, 16 and 19.
4.1. PCX_EXAM
PCX_EXAM reads a PCX-format image file and displays a summary of
the information contained in the file header. A full explanation
of this information is presented in PCX_FMT.DOC.
To run PCX_EXAM with a file (e.g. - "MY_PICT.PCX"), enter:
PCX_EXAM my_pict.pcx
4.2. RD_DEMO
To display any of these images, enter:
RD_DEMO test_xx.pcx xx
where "xx" is the video mode (e.g. - "RD_DEMO test_06.pcx 6").
Your display adapter must be capable of emulating the specified
video mode in order to display the image.
Once the image is displayed, press any key to clear the screen and
return to DOS.
RD_DEMO will also display a PCX-format image if your display
adapter supports its appropriate video mode. For example, to
display a PCX-format image file "MY_PICT.PCX" that was created for
display on 320 x 200 256-color VGA displays, enter:
RD_DEMO my_pict.pcx 19
4.3. WR_DEMO
The demonstration program WR_DEMO will first display a PCX-format
image file, then capture the image directly from the display
adapter's memory and create a PCX-format image file called
"PCX_DEMO.PCX".
To run WR_DEMO, enter:
WR_DEMO test_xx.pcx xx
where "xx" is the video mode (e.g. - "WR_DEMO test_06.pcx 6").
Your display adapter must be capable of emulating the specified
video mode in order to display and capture the image.
p. 4
Once the image is displayed, WR_DEMO will automatically capture
it and create the file "PCX_DEMO.PCX" before clearing the screen
and returning to DOS.
WR_DEMO will also display and capture a PCX-format image if your
display adapter supports its appropriate video mode. For example,
to capture a PCX-format image file "MY_PICT.PCX" that was created
for display on 320 x 200 256-color VGA displays, enter:
WR_DEMO my_pict.pcx 19
WR_DEMO captures the entire screen and all color planes, so the
size of the resultant PCX_DEMO.PCX file may be different than the
file it displayed.
p. 5
5. Using The Library
The public functions in PCX_LIB (i.e. - those meant to be called by
application programs) are:
pcx_read - display a PCX-format image file
pcx_write - capture a displayed image to a PCX-format file
pcx_init_dsa - set up BIOS to capture EGA color palette
register updates
pcx_free_dsa - reset BIOS to state before call to
"pcx_inst_dsa"
All functions are fully and exhaustively documented in the source
code files. Example calls to the public functions may be found in
the source code files RD_DEMO.C and WR_DEMO.C.
p. 6
6. Why Public Domain ?
PCX_LIB was written expressly for the public domain. What that means
is you may do whatever you wish with the executables, source code and
documentation, including:
1. Modifying it to meet your requirements.
2. Including it in commmercial software products.
3. Marketing it as a commercial product.
No royalties are payable to byHeart Software under any circumstances.
byHeart Software does not offer official technical support for
PCX_LIB. However, if you are having problems with the product
(including questions relating to other compilers and modifying the
source code), you are welcome to write, call or fax any questions to:
Ian Ashdown, P.Eng.
byHeart Software
620 Ballantree Road
West Vancouver, B.C.
Canada V7S 1W3
Tel: (604) 922-6148
Fax: (604) 987-7621
AUTHOR'S MESSAGE:
byHeart Software took approximately 250 man-hours to research,
design, code, test and document PCX_LIB. It was conceived as a
public domain offering, yet written to the most stringent of
professional engineering standards. Developing PCX_LIB was a
challenging and rewarding task.
PCX_LIB was written for all programmers, from the individual hobbyist
to the seasoned and harried professional working for a Fortune 100
company. It was written to save you the time and effort of
reinventing the stone tools needed to build the wheel, and without
the hassles of royalties and copyrights.
If you find PCX_LIB useful, consider exactly how useful it is. Would
you have spent 250 hours of your time to develop the PCX graphics
drivers yourself? Would you have otherwise spent $500 or so to
purchase the source code version of a commercial PCX graphics
library?
The oft-quoted Jerry Pournelle, BYTE columnist, once related a story
about somebody who was very helpful. When Jerry had a chance to
thank the person at a meeting, he used the rhetorical phrase "How can
I every repay you?". The answer was quite unexpected:
"You don't. You pass the favor on to someone else."
Once again, did you find PCX_LIB useful, and if so how useful? We
have likely never met, and yet I wrote PCX_LIB as a favor for you.
Like Jerry Pournelle's benefactor, I ask only that you pass the favor
on to someone else.
The possibilties are many. As an individual, you could write your
own public domain software. You could contribute time or money to a
worthy charity. You could simply remember me when a friend or
stranger needs help and act accordingly.
As a corporation using PCX_LIB in a commercial product, either
directly or indirectly, you could make a corporate (and tax-
deductible) donation to a charity - or give the employee who brought
PCX_LIB to your attention a day off with pay.
As for PCX_LIB, it is simply another favor being passed on within
our worldwide community. Pass it on, please.
