home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 350_01 / pcx_lib.doc < prev    next >
Text File  |  1991-12-01  |  10KB  |  464 lines
  1. byHeart Software
  2. 620 Ballantree Road
  3. West Vancouver, B.C.
  4. Canada V7S 1W3
  5.  
  6. Tel. (604) 922-6148
  7. Fax. (604) 987-7621
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                           PCX_LIB Documentation
  21.                           ---------------------
  22.                               Version 1.00C
  23.  
  24.  
  25.                           by Ian Ashdown, P.Eng.
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.                  Released into the Public Domain 91/04/01
  50.  
  51. 1.  Introduction
  52.  
  53.     PCX_LIB is a library of functions for displaying and storing ZSoft's 
  54.     Paintbrush (R) PCX-format image files.  It was developed expressly 
  55.     for release into the Public Domain.  Fully commented ANSI C source 
  56.     code is provided for all functions, along with complete technical 
  57.     specifications for ZSoft's PCX image file format.
  58.  
  59.     Version 1.00B supports the display and storage of images on MS-DOS 
  60.     systems equipped with the following display adapters:
  61.  
  62.       Hercules  - monochrome
  63.       CGA       - Color Graphics Adapter
  64.       EGA       - Enhanced Graphics Adapter
  65.       MCGA      - MultiColor Graphics Adapter
  66.       VGA       - Video Graphics Adapter
  67.  
  68.     All valid MS-DOS graphic modes are supported.
  69.  
  70.     SuperVGA and XGA display adapters are not supported in this release.
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.                                                                      p. 1
  107.  
  108. 2.  DISCLAIMER:
  109.  
  110.     IN NO EVENT SHALL BYHEART SOFTWARE BE LIABLE FOR ANY DAMAGES 
  111.     WHATSOEVER INCLUDING, WITHOUT LIMITATION, PERSONAL DAMAGES, DAMAGES 
  112.     FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS 
  113.     INFORMATION, OR OTHER PECUNIARY LOSS, ARISING OUT OF THE USE OR 
  114.     INABILITY TO USE THIS PRODUCT, EVEN IF BYHEART SOFTWARE HAS BEEN 
  115.     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.                                                                      p. 2
  163.  
  164. 3.  Disk Contents
  165.  
  166.     The disk includes the following files:
  167.  
  168.  
  169. 3.1.  Documentation
  170.  
  171.     PCX_LIB.DOC         - PCX_LIB documentation (this file)
  172.     PCX_FMT.DOC         - PCX image file format specifications
  173.  
  174.  
  175. 3.2.  ANSI C Source Code
  176.  
  177.     PCX_COMM.C          - PCX image file common functions
  178.     PCX_DISP.C          - PCX image file display functions
  179.     PCX_EXAM.C          - PCX image file header examination utility
  180.     PCX_FILE.C          - PCX image capture functions
  181.     RD_DEMO.C           - PCX image file display demonstration program
  182.     WR_DEMO.C           - PCX image file capture demonstration program
  183.  
  184.     PCX_EXT.H           - PCX_LIB external definitions include file
  185.     PCX_INT.H           - PCX_LIB internal definitions include file
  186.  
  187.  
  188. 3.3.  MS-DOS Executables
  189.  
  190.     PCX_EXAM.EXE        - PCX image file header examination utility
  191.     RD_DEMO.EXE         - PCX image file display demonstration program
  192.     WR_DEMO.EXE         - PCX image file capture demonstration program
  193.  
  194.  
  195. 3.4.  Sample PCX Image Files
  196.  
  197.     TEST_04.PCX         - 320 x 200 4-color CGA test image (mode 4)
  198.     TEST_06.PCX         - 640 x 200 2-color CGA test image (mode 6)
  199.     TEST_16.PCX         - 640 x 350 16-color EGA test image (mode 16)
  200.     TEST_19.PCX         - 320 x 200 256-color VGA test image (mode 19)
  201.  
  202.  
  203. 3.5.  Miscellaneous
  204.  
  205.     PCX_LIB.BAT         - Microsoft C V6.0 program build batch file
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.                                                                      p. 3
  219.  
  220. 4.  Trying It Out
  221.  
  222.     Four test images are included on the disk, one each for MS-DOS video 
  223.     modes 4, 6, 16 and 19. 
  224.  
  225.  
  226. 4.1.  PCX_EXAM
  227.  
  228.       PCX_EXAM reads a PCX-format image file and displays a summary of 
  229.       the information contained in the file header.  A full explanation
  230.       of this information is presented in PCX_FMT.DOC.
  231.  
  232.       To run PCX_EXAM with a file (e.g. - "MY_PICT.PCX"), enter:
  233.  
  234.         PCX_EXAM my_pict.pcx
  235.  
  236.  
  237. 4.2.  RD_DEMO
  238.  
  239.       To display any of these images, enter:
  240.  
  241.         RD_DEMO test_xx.pcx xx
  242.  
  243.       where "xx" is the video mode (e.g. - "RD_DEMO test_06.pcx 6").  
  244.       Your display adapter must be capable of emulating the specified 
  245.       video mode in order to display the image.
  246.  
  247.       Once the image is displayed, press any key to clear the screen and 
  248.       return to DOS.
  249.  
  250.       RD_DEMO will also display a PCX-format image if your display 
  251.       adapter supports its appropriate video mode.  For example, to 
  252.       display a PCX-format image file "MY_PICT.PCX" that was created for 
  253.       display on 320 x 200 256-color VGA displays, enter: 
  254.  
  255.         RD_DEMO my_pict.pcx 19
  256.  
  257.  
  258. 4.3.  WR_DEMO
  259.  
  260.       The demonstration program WR_DEMO will first display a PCX-format 
  261.       image file, then capture the image directly from the display 
  262.       adapter's memory and create a PCX-format image file called 
  263.       "PCX_DEMO.PCX".
  264.  
  265.       To run WR_DEMO, enter:
  266.  
  267.         WR_DEMO test_xx.pcx xx
  268.   
  269.       where "xx" is the video mode (e.g. - "WR_DEMO test_06.pcx 6").  
  270.       Your display adapter must be capable of emulating the specified 
  271.       video mode in order to display and capture the image.
  272.  
  273.  
  274.                                                                      p. 4
  275.  
  276.       Once the image is displayed, WR_DEMO will automatically capture 
  277.       it and create the file "PCX_DEMO.PCX" before clearing the screen 
  278.       and returning to DOS.
  279.  
  280.       WR_DEMO will also display and capture a PCX-format image if your
  281.       display adapter supports its appropriate video mode.  For example, 
  282.       to capture a PCX-format image file "MY_PICT.PCX" that was created 
  283.       for display on 320 x 200 256-color VGA displays, enter: 
  284.  
  285.         WR_DEMO my_pict.pcx 19
  286.  
  287.       WR_DEMO captures the entire screen and all color planes, so the
  288.       size of the resultant PCX_DEMO.PCX file may be different than the
  289.       file it displayed.
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.                                                                      p. 5
  331.  
  332. 5.  Using The Library
  333.  
  334.     The public functions in PCX_LIB (i.e. - those meant to be called by 
  335.     application programs) are:
  336.  
  337.       pcx_read          - display a PCX-format image file
  338.       pcx_write         - capture a displayed image to a PCX-format file
  339.  
  340.       pcx_isvga         - determine whether a display adapter supports
  341.                           VGA BIOS calls
  342.  
  343.       pcx_init_dsa      - set up BIOS to capture EGA color palette
  344.                           register updates
  345.       pcx_free_dsa      - reset BIOS to state before call to 
  346.                           "pcx_inst_dsa"
  347.  
  348.     All functions are fully and exhaustively documented in the source 
  349.     code files.  Example calls to the public functions may be found in 
  350.     the source code files RD_DEMO.C and WR_DEMO.C.
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.                                                                      p. 6
  387.  
  388. 6.  Why Public Domain ?
  389.  
  390.     PCX_LIB was written expressly for the public domain.  What that means
  391.     is you may do whatever you wish with the executables, source code and
  392.     documentation, including:
  393.  
  394.       1.  Modifying it to meet your requirements.
  395.  
  396.       2.  Including it in commmercial software products.
  397.  
  398.       3.  Marketing it as a commercial product.
  399.  
  400.  
  401.     No royalties are payable to byHeart Software under any circumstances.
  402.  
  403.     byHeart Software does not offer official technical support for 
  404.     PCX_LIB.  However, if you are having problems with the product 
  405.     (including questions relating to other compilers and modifying the 
  406.     source code), you are welcome to write, call or fax any questions to: 
  407.  
  408.         Ian Ashdown, P.Eng.
  409.         byHeart Software
  410.         620 Ballantree Road
  411.         West Vancouver, B.C.
  412.         Canada V7S 1W3
  413.  
  414.         Tel: (604) 922-6148
  415.         Fax: (604) 987-7621
  416.  
  417.  
  418.     AUTHOR'S MESSAGE:
  419.  
  420.     byHeart Software took approximately 250 man-hours to research, 
  421.     design, code, test and document PCX_LIB.  It was conceived as a 
  422.     public domain offering, yet written to the most stringent of 
  423.     professional engineering standards.  Developing PCX_LIB was a 
  424.     challenging and rewarding task.
  425.  
  426.     PCX_LIB was written for all programmers, from the individual hobbyist 
  427.     to the seasoned and harried professional working for a Fortune 100 
  428.     company.  It was written to save you the time and effort of 
  429.     reinventing the stone tools needed to build the wheel, and without 
  430.     the hassles of royalties and copyrights.
  431.  
  432.     If you find PCX_LIB useful, consider exactly how useful it is.  Would 
  433.     you have spent 250 hours of your time to develop the PCX graphics 
  434.     drivers yourself?  Would you have otherwise spent $500 or so to 
  435.     purchase the source code version of a commercial PCX graphics 
  436.     library? 
  437.  
  438.     The oft-quoted Jerry Pournelle, BYTE columnist, once related a story 
  439.     about somebody who was very helpful.  When Jerry had a chance to 
  440.     thank the person at a meeting, he used the rhetorical phrase "How can 
  441.     I every repay you?".  The answer was quite unexpected:
  442.  
  443.         "You don't. You pass the favor on to someone else."
  444.  
  445.  
  446.     Once again, did you find PCX_LIB useful, and if so how useful?  We
  447.     have likely never met, and yet I wrote PCX_LIB as a favor for you.  
  448.     Like Jerry Pournelle's benefactor, I ask only that you pass the favor 
  449.     on to someone else.
  450.  
  451.     The possibilties are many.  As an individual, you could write your 
  452.     own public domain software.  You could contribute time or money to a 
  453.     worthy charity.  You could simply remember me when a friend or 
  454.     stranger needs help and act accordingly.
  455.  
  456.     As a corporation using PCX_LIB in a commercial product, either 
  457.     directly or indirectly, you could make a corporate (and tax-
  458.     deductible) donation to a charity - or give the employee who brought 
  459.     PCX_LIB to your attention a day off with pay.
  460.  
  461.     As for PCX_LIB, it is simply another favor being passed on within 
  462.     our worldwide community.  Pass it on, please.
  463.  
  464.