path: root/support/bm2ltx/pcx_lib.doc

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.