16/PCX_LIB/PCX_LIB.DOC

   1 byHeart Software\r
   2 620 Ballantree Road\r
   3 West Vancouver, B.C.\r
   4 Canada V7S 1W3\r
   5 \r
   6 Tel. (604) 922-6148\r
   7 Fax. (604) 987-7621\r
   8 \r
   9 \r
  10 \r
  11 \r
  12 \r
  13 \r
  14 \r
  15 \r
  16 \r
  17 \r
  18 \r
  19 \r
  20                           PCX_LIB Documentation\r
  21                           ---------------------\r
  22                               Version 1.00B\r
  23 \r
  24 \r
  25                           by Ian Ashdown, P.Eng.\r
  26 \r
  27 \r
  28 \r
  29 \r
  30 \r
  31 \r
  32 \r
  33 \r
  34 \r
  35 \r
  36 \r
  37 \r
  38 \r
  39 \r
  40 \r
  41 \r
  42 \r
  43 \r
  44 \r
  45 \r
  46 \r
  47 \r
  48 \r
  49                  Released into the Public Domain 91/04/01\r
  50 \f\r
  51 1.  Introduction\r
  52 \r
  53     PCX_LIB is a library of functions for displaying and storing ZSoft's \r
  54     Paintbrush (R) PCX-format image files.  It was developed expressly \r
  55     for release into the Public Domain.  Fully commented ANSI C source \r
  56     code is provided for all functions, along with complete technical \r
  57     specifications for ZSoft's PCX image file format.\r
  58 \r
  59     Version 1.00B supports the display and storage of images on MS-DOS \r
  60     systems equipped with the following display adapters:\r
  61 \r
  62       Hercules  - monochrome\r
  63       CGA       - Color Graphics Adapter\r
  64       EGA       - Enhanced Graphics Adapter\r
  65       MCGA      - MultiColor Graphics Adapter\r
  66       VGA       - Video Graphics Adapter\r
  67 \r
  68     All valid MS-DOS graphic modes are supported.\r
  69 \r
  70     SuperVGA and XGA display adapters are not supported in this release.\r
  71 \r
  72 \r
  73 \r
  74 \r
  75 \r
  76 \r
  77 \r
  78 \r
  79 \r
  80 \r
  81 \r
  82 \r
  83 \r
  84 \r
  85 \r
  86 \r
  87 \r
  88 \r
  89 \r
  90 \r
  91 \r
  92 \r
  93 \r
  94 \r
  95 \r
  96 \r
  97 \r
  98 \r
  99 \r
 100 \r
 101 \r
 102 \r
 103 \r
 104 \r
 105 \r
 106                                                                      p. 1\r
 107 \f\r
 108 2.  DISCLAIMER:\r
 109 \r
 110     IN NO EVENT SHALL BYHEART SOFTWARE BE LIABLE FOR ANY DAMAGES \r
 111     WHATSOEVER INCLUDING, WITHOUT LIMITATION, PERSONAL DAMAGES, DAMAGES \r
 112     FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS \r
 113     INFORMATION, OR OTHER PECUNIARY LOSS, ARISING OUT OF THE USE OR \r
 114     INABILITY TO USE THIS PRODUCT, EVEN IF BYHEART SOFTWARE HAS BEEN \r
 115     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\r
 116 \r
 117 \r
 118 \r
 119 \r
 120 \r
 121 \r
 122 \r
 123 \r
 124 \r
 125 \r
 126 \r
 127 \r
 128 \r
 129 \r
 130 \r
 131 \r
 132 \r
 133 \r
 134 \r
 135 \r
 136 \r
 137 \r
 138 \r
 139 \r
 140 \r
 141 \r
 142 \r
 143 \r
 144 \r
 145 \r
 146 \r
 147 \r
 148 \r
 149 \r
 150 \r
 151 \r
 152 \r
 153 \r
 154 \r
 155 \r
 156 \r
 157 \r
 158 \r
 159 \r
 160 \r
 161 \r
 162                                                                      p. 2\r
 163 \f\r
 164 3.  Disk Contents\r
 165 \r
 166     The disk includes the following files:\r
 167 \r
 168 \r
 169 3.1.  Documentation\r
 170 \r
 171     PCX_LIB.DOC         - PCX_LIB documentation (this file)\r
 172     PCX_FMT.DOC         - PCX image file format specifications\r
 173 \r
 174 \r
 175 3.2.  ANSI C Source Code\r
 176 \r
 177     PCX_COMM.C          - PCX image file common functions\r
 178     PCX_DISP.C          - PCX image file display functions\r
 179     PCX_EXAM.C          - PCX image file header examination utility\r
 180     PCX_FILE.C          - PCX image capture functions\r
 181     RD_DEMO.C           - PCX image file display demonstration program\r
 182     WR_DEMO.C           - PCX image file capture demonstration program\r
 183 \r
 184     PCX_EXT.H           - PCX_LIB external definitions include file\r
 185     PCX_INT.H           - PCX_LIB internal definitions include file\r
 186 \r
 187 \r
 188 3.3.  MS-DOS Executables\r
 189 \r
 190     PCX_EXAM.EXE        - PCX image file header examination utility\r
 191     RD_DEMO.EXE         - PCX image file display demonstration program\r
 192     WR_DEMO.EXE         - PCX image file capture demonstration program\r
 193 \r
 194 \r
 195 3.4.  Sample PCX Image Files\r
 196 \r
 197     TEST_04.PCX         - 320 x 200 4-color CGA test image (mode 4)\r
 198     TEST_06.PCX         - 640 x 200 2-color CGA test image (mode 6)\r
 199     TEST_16.PCX         - 640 x 350 16-color EGA test image (mode 16)\r
 200     TEST_19.PCX         - 320 x 200 256-color VGA test image (mode 19)\r
 201 \r
 202 \r
 203 3.5.  Miscellaneous\r
 204 \r
 205     PCX_LIB.BAT         - Microsoft C V6.0 program build batch file\r
 206 \r
 207 \r
 208 \r
 209 \r
 210 \r
 211 \r
 212 \r
 213 \r
 214 \r
 215 \r
 216 \r
 217 \r
 218                                                                      p. 3\r
 219 \f\r
 220 4.  Trying It Out\r
 221 \r
 222     Four test images are included on the disk, one each for MS-DOS video \r
 223     modes 4, 6, 16 and 19. \r
 224 \r
 225 \r
 226 4.1.  PCX_EXAM\r
 227 \r
 228       PCX_EXAM reads a PCX-format image file and displays a summary of \r
 229       the information contained in the file header.  A full explanation\r
 230       of this information is presented in PCX_FMT.DOC.\r
 231 \r
 232       To run PCX_EXAM with a file (e.g. - "MY_PICT.PCX"), enter:\r
 233 \r
 234         PCX_EXAM my_pict.pcx\r
 235 \r
 236 \r
 237 4.2.  RD_DEMO\r
 238 \r
 239       To display any of these images, enter:\r
 240 \r
 241         RD_DEMO test_xx.pcx xx\r
 242 \r
 243       where "xx" is the video mode (e.g. - "RD_DEMO test_06.pcx 6").  \r
 244       Your display adapter must be capable of emulating the specified \r
 245       video mode in order to display the image.\r
 246 \r
 247       Once the image is displayed, press any key to clear the screen and \r
 248       return to DOS.\r
 249 \r
 250       RD_DEMO will also display a PCX-format image if your display \r
 251       adapter supports its appropriate video mode.  For example, to \r
 252       display a PCX-format image file "MY_PICT.PCX" that was created for \r
 253       display on 320 x 200 256-color VGA displays, enter: \r
 254 \r
 255         RD_DEMO my_pict.pcx 19\r
 256 \r
 257 \r
 258 4.3.  WR_DEMO\r
 259 \r
 260       The demonstration program WR_DEMO will first display a PCX-format \r
 261       image file, then capture the image directly from the display \r
 262       adapter's memory and create a PCX-format image file called \r
 263       "PCX_DEMO.PCX".\r
 264 \r
 265       To run WR_DEMO, enter:\r
 266 \r
 267         WR_DEMO test_xx.pcx xx\r
 268   \r
 269       where "xx" is the video mode (e.g. - "WR_DEMO test_06.pcx 6").  \r
 270       Your display adapter must be capable of emulating the specified \r
 271       video mode in order to display and capture the image.\r
 272 \r
 273 \r
 274                                                                      p. 4\r
 275 \f\r
 276       Once the image is displayed, WR_DEMO will automatically capture \r
 277       it and create the file "PCX_DEMO.PCX" before clearing the screen \r
 278       and returning to DOS.\r
 279 \r
 280       WR_DEMO will also display and capture a PCX-format image if your\r
 281       display adapter supports its appropriate video mode.  For example, \r
 282       to capture a PCX-format image file "MY_PICT.PCX" that was created \r
 283       for display on 320 x 200 256-color VGA displays, enter: \r
 284 \r
 285         WR_DEMO my_pict.pcx 19\r
 286 \r
 287       WR_DEMO captures the entire screen and all color planes, so the\r
 288       size of the resultant PCX_DEMO.PCX file may be different than the\r
 289       file it displayed.\r
 290 \r
 291 \r
 292 \r
 293 \r
 294 \r
 295 \r
 296 \r
 297 \r
 298 \r
 299 \r
 300 \r
 301 \r
 302 \r
 303 \r
 304 \r
 305 \r
 306 \r
 307 \r
 308 \r
 309 \r
 310 \r
 311 \r
 312 \r
 313 \r
 314 \r
 315 \r
 316 \r
 317 \r
 318 \r
 319 \r
 320 \r
 321 \r
 322 \r
 323 \r
 324 \r
 325 \r
 326 \r
 327 \r
 328 \r
 329 \r
 330                                                                      p. 5\r
 331 \f\r
 332 5.  Using The Library\r
 333 \r
 334     The public functions in PCX_LIB (i.e. - those meant to be called by \r
 335     application programs) are:\r
 336 \r
 337       pcx_read          - display a PCX-format image file\r
 338       pcx_write         - capture a displayed image to a PCX-format file\r
 339 \r
 340       pcx_isvga         - determine whether a display adapter supports\r
 341                           VGA BIOS calls\r
 342 \r
 343       pcx_init_dsa      - set up BIOS to capture EGA color palette\r
 344                           register updates\r
 345       pcx_free_dsa      - reset BIOS to state before call to \r
 346                           "pcx_inst_dsa"\r
 347 \r
 348     All functions are fully and exhaustively documented in the source \r
 349     code files.  Example calls to the public functions may be found in \r
 350     the source code files RD_DEMO.C and WR_DEMO.C.\r
 351 \r
 352 \r
 353 \r
 354 \r
 355 \r
 356 \r
 357 \r
 358 \r
 359 \r
 360 \r
 361 \r
 362 \r
 363 \r
 364 \r
 365 \r
 366 \r
 367 \r
 368 \r
 369 \r
 370 \r
 371 \r
 372 \r
 373 \r
 374 \r
 375 \r
 376 \r
 377 \r
 378 \r
 379 \r
 380 \r
 381 \r
 382 \r
 383 \r
 384 \r
 385 \r
 386                                                                      p. 6\r
 387 \r