byHeart Software 620 Ballantree Road West Vancouver, B.C. Canada V7S 1W3 Tel. (604) 922-6148 Fax. (604) 987-7621 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. p. 2 3. Disk Contents The disk includes the following files: 3.1. Documentation PCX_LIB.DOC - PCX_LIB documentation (this file) PCX_FMT.DOC - PCX image file format specifications 3.2. ANSI C Source Code PCX_COMM.C - PCX image file common functions PCX_DISP.C - PCX image file display functions PCX_EXAM.C - PCX image file header examination utility PCX_FILE.C - PCX image capture functions RD_DEMO.C - PCX image file display demonstration program WR_DEMO.C - PCX image file capture demonstration program PCX_EXT.H - PCX_LIB external definitions include file PCX_INT.H - PCX_LIB internal definitions include file 3.3. MS-DOS Executables PCX_EXAM.EXE - PCX image file header examination utility RD_DEMO.EXE - PCX image file display demonstration program WR_DEMO.EXE - PCX image file capture demonstration program 3.4. Sample PCX Image Files 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_isvga - determine whether a display adapter supports VGA BIOS calls 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.