summaryrefslogtreecommitdiff
path: root/support/bm2ltx/pcx_lib.doc
blob: 24599542c42d29ae09f661e16a4280c5df08cbb2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
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
107
108
109
110
111
112
113
114
115
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
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
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
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
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
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.