home *** CD-ROM | disk | FTP | other *** search
/ Resource Library: Graphics / graphics-16000.iso / msdos / animutil / fastgfx / fg303b / manuals.arj / USER01.DOC < prev    next >
Text File  |  1993-10-02  |  67KB  |  1,416 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17. Fastgraph (tm)
  18.  
  19.  
  20.  
  21.  
  22.  
  23. User's Guide
  24. Copyright (c) 1991-1993 by Ted Gruber Software.
  25.  
  26. All rights reserved.  No part of this publication may be reproduced, stored
  27. in a retrieval system, or transmitted by any means, electronic, mechanical,
  28. photocopying, recording, or otherwise, without express written permission
  29. from Ted Gruber Software.  The software described in this publication is
  30. furnished under a license agreement and may be used or copied only in
  31. accordance with the terms of that agreement.
  32.  
  33. This publication and its associated software are sold without warranties,
  34. either expressed or implied, regarding their merchantability or fitness for
  35. any particular application or purpose.  The information in this publication
  36. is subject to change without notice and does not represent a commitment on
  37. the part of Ted Gruber Software.  In no event shall Ted Gruber Software be
  38. liable for any loss of profit or any other commercial damage, including but
  39. not limited to special, incidental, consequential, or other damages resulting
  40. from the use of or the inability to use this product, even if Ted Gruber
  41. Software has been notified of the possibility of such damages.
  42.  
  43.  
  44. First Printing, April 1993
  45.  
  46. Fastgraph version 3.00
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. All brand and product names mentioned in this publication are trademarks or
  59. registered trademarks of their respective holders.
  60.  
  61.  
  62.  
  63.  
  64.  
  65.                       T a b l e   o f   C o n t e n t s
  66.  
  67.  
  68. Chapter 1  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .    1
  69.      What is Fastgraph? . . . . . . . . . . . . . . . . . . . . . . . . .    2
  70.      Fastgraph/Light  . . . . . . . . . . . . . . . . . . . . . . . . . .    2
  71.      Prerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . .    2
  72.      Supported Compilers  . . . . . . . . . . . . . . . . . . . . . . . .    3
  73.      Memory Models  . . . . . . . . . . . . . . . . . . . . . . . . . . .    3
  74.      Installing Fastgraph . . . . . . . . . . . . . . . . . . . . . . . .    4
  75.      The READ.ME File . . . . . . . . . . . . . . . . . . . . . . . . . .    5
  76.      Fastgraph Naming Conventions . . . . . . . . . . . . . . . . . . . .    5
  77.      Compilation and Linking  . . . . . . . . . . . . . . . . . . . . . .    5
  78.           Borland C++ . . . . . . . . . . . . . . . . . . . . . . . . . .    8
  79.           Borland Pascal  . . . . . . . . . . . . . . . . . . . . . . . .   10
  80.           Microsoft BASIC PDS 7 . . . . . . . . . . . . . . . . . . . . .   11
  81.           Microsoft C and C++ . . . . . . . . . . . . . . . . . . . . . .   13
  82.           Microsoft FORTRAN . . . . . . . . . . . . . . . . . . . . . . .   14
  83.           Microsoft QuickBASIC  . . . . . . . . . . . . . . . . . . . . .   16
  84.           Microsoft QuickC  . . . . . . . . . . . . . . . . . . . . . . .   18
  85.           Microsoft Visual Basic for DOS  . . . . . . . . . . . . . . . .   20
  86.           Microsoft Visual C++  . . . . . . . . . . . . . . . . . . . . .   22
  87.           Power C . . . . . . . . . . . . . . . . . . . . . . . . . . . .   23
  88.           Turbo C and Turbo C++ . . . . . . . . . . . . . . . . . . . . .   25
  89.           Turbo Pascal  . . . . . . . . . . . . . . . . . . . . . . . . .   27
  90.           Zortech C++ . . . . . . . . . . . . . . . . . . . . . . . . . .   28
  91.      Fastgraph/Light Video Driver . . . . . . . . . . . . . . . . . . . .   29
  92.  
  93. Chapter 2  PC and PS/2 Video Modes  . . . . . . . . . . . . . . . . . . .   31
  94.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   32
  95.      Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   33
  96.      Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . .   35
  97.           CGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   35
  98.           Tandy 1000 and PCjr Graphics Modes  . . . . . . . . . . . . . .   36
  99.           Hercules Graphics Modes . . . . . . . . . . . . . . . . . . . .   36
  100.           EGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   37
  101.           VGA and MCGA Graphics Modes . . . . . . . . . . . . . . . . . .   38
  102.           Extended VGA (XVGA) Graphics Modes  . . . . . . . . . . . . . .   39
  103.           SuperVGA (SVGA) Graphics Modes  . . . . . . . . . . . . . . . .   40
  104.  
  105. Chapter 3  Initializing the Video Environment . . . . . . . . . . . . . .   43
  106.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   44
  107.      Establishing a Text Mode . . . . . . . . . . . . . . . . . . . . . .   44
  108.      43-line and 50-line Text Modes . . . . . . . . . . . . . . . . . . .   47
  109.      Establishing a Graphics Mode . . . . . . . . . . . . . . . . . . . .   48
  110.      SuperVGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   51
  111.      Summary of Video Initialization Routines . . . . . . . . . . . . . .   56
  112.  
  113. Chapter 4  Coordinate Systems . . . . . . . . . . . . . . . . . . . . . .   59
  114.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   60
  115.      Character Space  . . . . . . . . . . . . . . . . . . . . . . . . . .   60
  116.      Screen Space . . . . . . . . . . . . . . . . . . . . . . . . . . . .   61
  117.  
  118.                                      iii
  119.  
  120.      World Space  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   62
  121.      Conversion Routines  . . . . . . . . . . . . . . . . . . . . . . . .   64
  122.      Summary of Coordinate Routines . . . . . . . . . . . . . . . . . . .   64
  123.  
  124. Chapter 5  The Use of Color . . . . . . . . . . . . . . . . . . . . . . .   67
  125.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   68
  126.      Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   68
  127.           Color Text Modes  . . . . . . . . . . . . . . . . . . . . . . .   68
  128.           Monochrome Text Mode  . . . . . . . . . . . . . . . . . . . . .   69
  129.      Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . .   70
  130.           CGA Color Modes . . . . . . . . . . . . . . . . . . . . . . . .   70
  131.           CGA Two-Color Mode  . . . . . . . . . . . . . . . . . . . . . .   72
  132.           Tandy and PCjr Modes  . . . . . . . . . . . . . . . . . . . . .   73
  133.           Hercules Mode . . . . . . . . . . . . . . . . . . . . . . . . .   74
  134.           Hercules Low-Resolution Mode  . . . . . . . . . . . . . . . . .   75
  135.           EGA 200-Line Modes  . . . . . . . . . . . . . . . . . . . . . .   76
  136.           EGA Monochrome Mode . . . . . . . . . . . . . . . . . . . . . .   78
  137.           EGA Enhanced Mode . . . . . . . . . . . . . . . . . . . . . . .   79
  138.           VGA and MCGA Two-Color Mode . . . . . . . . . . . . . . . . . .   81
  139.           VGA/SVGA 16-Color Modes . . . . . . . . . . . . . . . . . . . .   83
  140.           256-Color Modes . . . . . . . . . . . . . . . . . . . . . . . .   83
  141.      Using Video DAC Registers in EGA Modes . . . . . . . . . . . . . . .   87
  142.      RGB Color Mapping  . . . . . . . . . . . . . . . . . . . . . . . . .   89
  143.      Defining All Palette Registers . . . . . . . . . . . . . . . . . . .   90
  144.      Virtual Colors . . . . . . . . . . . . . . . . . . . . . . . . . . .   90
  145.      A Multiple-Mode Example  . . . . . . . . . . . . . . . . . . . . . .   92
  146.      Summary of Color-Related Routines  . . . . . . . . . . . . . . . . .   94
  147.  
  148. Chapter 6  Graphics Fundamentals  . . . . . . . . . . . . . . . . . . . .   97
  149.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   98
  150.      Clearing the Screen  . . . . . . . . . . . . . . . . . . . . . . . .   98
  151.      Clipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   98
  152.      Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   99
  153.      The Graphics Cursor  . . . . . . . . . . . . . . . . . . . . . . . .  101
  154.      Solid Lines  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  102
  155.      Dashed Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . .  104
  156.      Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  105
  157.      Circles and Ellipses . . . . . . . . . . . . . . . . . . . . . . . .  109
  158.      Solid Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . .  111
  159.      Unfilled Rectangles  . . . . . . . . . . . . . . . . . . . . . . . .  112
  160.      Dithered Rectangles  . . . . . . . . . . . . . . . . . . . . . . . .  114
  161.      Region Fill  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  121
  162.      Summary of Fundamental Graphics Routines . . . . . . . . . . . . . .  122
  163.  
  164. Chapter 7  Character Display Routines . . . . . . . . . . . . . . . . . .  127
  165.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  128
  166.      Character Space  . . . . . . . . . . . . . . . . . . . . . . . . . .  128
  167.      Hardware Characters  . . . . . . . . . . . . . . . . . . . . . . . .  129
  168.      Character Height . . . . . . . . . . . . . . . . . . . . . . . . . .  137
  169.      Conversion Routines  . . . . . . . . . . . . . . . . . . . . . . . .  138
  170.      Software Characters  . . . . . . . . . . . . . . . . . . . . . . . .  139
  171.      Bit-Mapped Characters  . . . . . . . . . . . . . . . . . . . . . . .  145
  172.      Summary of Character Display Routines  . . . . . . . . . . . . . . .  145
  173.  
  174. Chapter 8  Video Page Management  . . . . . . . . . . . . . . . . . . . .  149
  175.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  150
  176.  
  177.                                       iv
  178.  
  179.      Physical Pages and Virtual Pages . . . . . . . . . . . . . . . . . .  150
  180.      Pages With Special Meanings  . . . . . . . . . . . . . . . . . . . .  151
  181.      Some Simple Examples . . . . . . . . . . . . . . . . . . . . . . . .  152
  182.      Text Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . .  159
  183.      Obtaining Video Page Information . . . . . . . . . . . . . . . . . .  160
  184.      Considerations for Virtual Pages . . . . . . . . . . . . . . . . . .  161
  185.      Logical Pages  . . . . . . . . . . . . . . . . . . . . . . . . . . .  162
  186.      Video Page Resizing  . . . . . . . . . . . . . . . . . . . . . . . .  164
  187.      Preserving Video Page Contents Across Mode Switches  . . . . . . . .  166
  188.      Controlling Page Allocation  . . . . . . . . . . . . . . . . . . . .  167
  189.      Summary of Video Page Management Routines  . . . . . . . . . . . . .  169
  190.  
  191. Chapter 9  Image Files  . . . . . . . . . . . . . . . . . . . . . . . . .  171
  192.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  172
  193.      PCX Files  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  172
  194.      GIF Files  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  175
  195.      Pixel Run Files  . . . . . . . . . . . . . . . . . . . . . . . . . .  176
  196.      Display Patterns . . . . . . . . . . . . . . . . . . . . . . . . . .  181
  197.      Controlling the Image Buffer Size  . . . . . . . . . . . . . . . . .  186
  198.      Summary of Image File Routines . . . . . . . . . . . . . . . . . . .  187
  199.  
  200. Chapter 10  Bit-Mapped Images . . . . . . . . . . . . . . . . . . . . . .  189
  201.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  190
  202.      Mode-Independent Bit-Mapped Images . . . . . . . . . . . . . . . . .  190
  203.      Mode-Specific Bit-Mapped Images  . . . . . . . . . . . . . . . . . .  194
  204.           Regular Images  . . . . . . . . . . . . . . . . . . . . . . . .  195
  205.           Clipped Images  . . . . . . . . . . . . . . . . . . . . . . . .  203
  206.           Reversed Images . . . . . . . . . . . . . . . . . . . . . . . .  203
  207.           Reversed Clipped Images . . . . . . . . . . . . . . . . . . . .  203
  208.           Images Without Transparent Pixels . . . . . . . . . . . . . . .  203
  209.           Some Examples . . . . . . . . . . . . . . . . . . . . . . . . .  203
  210.      Retrieving Images  . . . . . . . . . . . . . . . . . . . . . . . . .  207
  211.      Pixel Run Maps . . . . . . . . . . . . . . . . . . . . . . . . . . .  212
  212.      Masking Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . .  215
  213.      Summary of Bit-Mapped Image Display Routines . . . . . . . . . . . .  219
  214.  
  215. Chapter 11  Block Transfer Routines . . . . . . . . . . . . . . . . . . .  221
  216.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  222
  217.      Full Page Transfer . . . . . . . . . . . . . . . . . . . . . . . . .  222
  218.      Byte Boundaries  . . . . . . . . . . . . . . . . . . . . . . . . . .  223
  219.      Dual SVGA Banks  . . . . . . . . . . . . . . . . . . . . . . . . . .  224
  220.      The "Hidden" Video Page  . . . . . . . . . . . . . . . . . . . . . .  225
  221.      Saving and Restoring Blocks  . . . . . . . . . . . . . . . . . . . .  225
  222.      A More General Block Transfer Routine  . . . . . . . . . . . . . . .  228
  223.      Blocks with Transparent Colors . . . . . . . . . . . . . . . . . . .  231
  224.      Transferring Blocks to and from Conventional Memory  . . . . . . . .  233
  225.      Summary of Block Transfer Routines . . . . . . . . . . . . . . . . .  234
  226.  
  227. Chapter 12  Animation Techniques  . . . . . . . . . . . . . . . . . . . .  237
  228.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  238
  229.      Simple Animation . . . . . . . . . . . . . . . . . . . . . . . . . .  238
  230.      XOR Animation  . . . . . . . . . . . . . . . . . . . . . . . . . . .  240
  231.      Static Frame Animation . . . . . . . . . . . . . . . . . . . . . . .  242
  232.      Dynamic Frame Animation  . . . . . . . . . . . . . . . . . . . . . .  244
  233.      Page Flipping  . . . . . . . . . . . . . . . . . . . . . . . . . . .  246
  234.      An Animation Example:  The Fastgraph Fish Tank . . . . . . . . . . .  248
  235.  
  236.                                       v
  237.  
  238.      Summary of Animation Techniques  . . . . . . . . . . . . . . . . . .  248
  239.  
  240. Chapter 13  Special Effects . . . . . . . . . . . . . . . . . . . . . . .  249
  241.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  250
  242.      Screen Dissolving  . . . . . . . . . . . . . . . . . . . . . . . . .  250
  243.      Scrolling  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  252
  244.      Changing the Screen Origin . . . . . . . . . . . . . . . . . . . . .  255
  245.      Summary of Special Effects Routines  . . . . . . . . . . . . . . . .  258
  246.  
  247. Chapter 14  Input Device Support  . . . . . . . . . . . . . . . . . . . .  259
  248.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  260
  249.      Keyboard Support . . . . . . . . . . . . . . . . . . . . . . . . . .  260
  250.           Reading Keystrokes  . . . . . . . . . . . . . . . . . . . . . .  262
  251.           Testing and Setting Key States  . . . . . . . . . . . . . . . .  263
  252.           Low-Level Keyboard Handler  . . . . . . . . . . . . . . . . . .  264
  253.      Mouse Support  . . . . . . . . . . . . . . . . . . . . . . . . . . .  266
  254.           Initializing the Mouse  . . . . . . . . . . . . . . . . . . . .  267
  255.           XVGA and SVGA Mouse Considerations  . . . . . . . . . . . . . .  268
  256.           Controlling the Mouse Cursor  . . . . . . . . . . . . . . . . .  269
  257.           Reporting the Mouse Status  . . . . . . . . . . . . . . . . . .  271
  258.           Defining the Mouse Cursor . . . . . . . . . . . . . . . . . . .  273
  259.      Joystick Support . . . . . . . . . . . . . . . . . . . . . . . . . .  279
  260.           Initializing Joysticks  . . . . . . . . . . . . . . . . . . . .  279
  261.           Reporting Joystick Status . . . . . . . . . . . . . . . . . . .  280
  262.           Keyboard Emulation  . . . . . . . . . . . . . . . . . . . . . .  281
  263.           Special Joystick Considerations . . . . . . . . . . . . . . . .  283
  264.      Summary of Input Routines  . . . . . . . . . . . . . . . . . . . . .  283
  265.  
  266. Chapter 15  Sound Effects . . . . . . . . . . . . . . . . . . . . . . . .  285
  267.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  286
  268.      Sound Sources  . . . . . . . . . . . . . . . . . . . . . . . . . . .  286
  269.      Synchronous Sound  . . . . . . . . . . . . . . . . . . . . . . . . .  286
  270.      Asynchronous Sound . . . . . . . . . . . . . . . . . . . . . . . . .  290
  271.      Summary of Sound Routines  . . . . . . . . . . . . . . . . . . . . .  296
  272.  
  273. Chapter 16  Program Timing  . . . . . . . . . . . . . . . . . . . . . . .  299
  274.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  300
  275.      Real-Time Routines . . . . . . . . . . . . . . . . . . . . . . . . .  300
  276.      Routines Dependent on the System Speed . . . . . . . . . . . . . . .  301
  277.      Summary of Timing Routines . . . . . . . . . . . . . . . . . . . . .  303
  278.  
  279. Chapter 17  Miscellaneous Routines  . . . . . . . . . . . . . . . . . . .  303
  280.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  304
  281.      Determining Available Memory . . . . . . . . . . . . . . . . . . . .  304
  282.      Choosing the Video Memory Update Function  . . . . . . . . . . . . .  305
  283.      Controlling Vertical Retrace Synchronization . . . . . . . . . . . .  306
  284.      Summary of Miscellaneous Routines  . . . . . . . . . . . . . . . . .  307
  285.  
  286. Appendix A  Fastgraph Utilities . . . . . . . . . . . . . . . . . . . . .  309
  287.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  310
  288.      SNAPSHOT Utility . . . . . . . . . . . . . . . . . . . . . . . . . .  310
  289.      CLIP Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . .  311
  290.      CONVERT Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  312
  291.      EDITSPR Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  313
  292.      GrabRGB Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  313
  293.      HERCFIX Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  314
  294.  
  295.                                       vi
  296.  
  297.      PCXHEAD Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  315
  298.  
  299. Appendix B  Using Fastgraph from Assembly Language  . . . . . . . . . . .  317
  300.  
  301. Appendix C  Interrupts and Fastgraph  . . . . . . . . . . . . . . . . . .  321
  302.      Interrupts Used by Fastgraph . . . . . . . . . . . . . . . . . . . .  322
  303.      Extending the Time-of-Day Interrupt  . . . . . . . . . . . . . . . .  322
  304.  
  305. Appendix D  Contents of the Compiler-Specific Libraries . . . . . . . . .  329
  306.  
  307. Appendix E  Contents of the Pascal Unit Files . . . . . . . . . . . . . .  331
  308.  
  309. Appendix F  Integrating Fastgraph With Other Graphics Software  . . . . .  333
  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.                                      vii
  355. Chapter 1
  356.  
  357.  
  358.  
  359.  
  360.  
  361. Introduction
  362. 2   Fastgraph User's Guide
  363.  
  364.  
  365. What is Fastgraph?
  366.  
  367.      Fastgraph is a library of more than 200 highly-optimized routines that
  368. are callable from high-level and assembly language programs running under the
  369. MS-DOS or PC-DOS operating systems.  This collection of routines provides a
  370. programmer with proven, powerful tools to take command of the PC and PS/2
  371. video environment.  In addition to its video support, Fastgraph also includes
  372. routines to perform keyboard, mouse, and joystick control, as well as music
  373. and sound capabilities.  Fastgraph is an ideal development tool for
  374. entertainment and educational software, presentation graphics products,
  375. scientific and engineering applications, CAD/CAM, animation, or any
  376. application that demands robust graphics.
  377.  
  378.      As its name implies, the most notable feature of Fastgraph is its speed.
  379. Virtually all of Fastgraph is written in 8086 assembly language, and each
  380. routine has been optimized by hand to provide maximum performance.
  381.  
  382.      Fastgraph supports all the standard text and graphics video modes used
  383. by the IBM PC (PC, PC/XT, and PC/AT) and PS/2 families and compatible
  384. systems.  In addition, Fastgraph provides support for six SuperVGA (SVGA)
  385. graphics modes, four extended VGA (XVGA) graphics modes, and a 16-color
  386. graphics mode unique to Tandy 1000 series computers and the PCjr.  Even
  387. though the graphics mode of the Hercules Graphics Card is not an IBM
  388. standard, its popularity has made it a de facto standard, and for this reason
  389. Fastgraph also supports it.  In total, Fastgraph supports 23 graphics modes
  390. and 5 text modes.  A complete discussion of these video modes appears in the
  391. next chapter.
  392.  
  393.  
  394. Fastgraph/Light
  395.  
  396.      Fastgraph/Light is a subset of Fastgraph.  It includes all of
  397. Fastgraph's features except the redefinable world space coordinate system and
  398. the routines pertaining to software characters.  Programs created using
  399. Fastgraph/Light are 100% source code compatible with Fastgraph.
  400.  
  401.      The most important difference between Fastgraph/Light and Fastgraph is
  402. the method of running a program created with the two products.  With
  403. Fastgraph, any of its routines used in your program are linked directly into
  404. the resulting .EXE file.  With Fastgraph/Light, however, this is not the
  405. case.  Instead, the Fastgraph/Light routines provide an interface to an
  406. external driver, called the Fastgraph/Light Video Driver, which must be
  407. loaded separately before running programs that call any Fastgraph/Light
  408. routines.  See the last section of this chapter for more information.
  409.  
  410.      In this document, and in the accompanying Fastgraph Reference Manual,
  411. references to Fastgraph also apply to Fastgraph/Light unless stated
  412. otherwise.
  413.  
  414.  
  415. Prerequisite Knowledge
  416.  
  417.      Fastgraph is a programming tool, which means programmers are its
  418. intended audience.  For this reason, the Fastgraph User's Guide and the
  419. accompanying Fastgraph Reference Manual assume you have a knowledge of
  420.                                                   Chapter 1:  Introduction   3
  421.  
  422. programming.  Additionally, a knowledge of converting numbers between binary,
  423. decimal, and hexadecimal is assumed.
  424.  
  425.      Virtually all the examples in this manual are written in the C
  426. programming language, so a knowledge of C would be especially helpful.  The
  427. examples intentionally avoid using any of C's features and idioms that might
  428. not be readily apparent to a programmer unfamiliar with C.  Finally, we'd
  429. like to point out that the examples are intended to be read not by
  430. themselves, but as part of the surrounding text.
  431.  
  432.  
  433. Supported Compilers
  434.  
  435.      You can use Fastgraph with any compilers or assemblers that use the same
  436. calling and naming conventions as the small, medium, or large memory models
  437. of the supported compilers.  Mixed language programming is allowed where
  438. supported by the language translators and linker being used.  Fastgraph
  439. supports the following compilers:
  440.  
  441.        Borland C++ (version 2.0 or later)
  442.        Borland Pascal (version 7.0 or later)
  443.        Microsoft C (version 5.0 or later)
  444.        Microsoft C++ (version 7.0 or later)
  445.        Microsoft BASIC PDS (version 7.1 or later)
  446.        Microsoft FORTRAN (version 4.0 or later)
  447.        Microsoft QuickBASIC (version 4.0 or later)
  448.        Microsoft QuickC (version 2.0 or later)
  449.        Microsoft Visual Basic for DOS (version 1.0 or later)
  450.        Microsoft Visual C++ (version 1.0 or later)
  451.        Power C (version 2.0 or later)
  452.        Turbo C (version 2.0 or later)
  453.        Turbo C++ (version 1.0 or later)
  454.        Turbo Pascal (version 6.0 or later)
  455.        Zortech C++ (version 3.0 or later)
  456.  
  457. The listed version numbers are the compiler versions under which Fastgraph
  458. was developed and tested.  Fastgraph may or may not work with earlier
  459. versions of these compilers.  As we constantly add support for new compilers,
  460. please check the READ.ME file in the \FG directory for additions to the above
  461. list.  The use of Fastgraph from assembly language programs is addressed in
  462. Appendix B.
  463.  
  464.  
  465. Memory Models
  466.  
  467.      All of Fastgraph's supported compilers except QuickBASIC, Visual Basic
  468. for DOS, Borland Pascal, and Turbo Pascal offer several memory models.  A
  469. memory model defines how memory is set up for a program's code and data
  470. segments.  Fastgraph includes libraries for the small, medium, and large
  471. memory models.
  472.  
  473.      The small memory model allows for one code segment and one data segment.
  474. Programs that use the small model can thus have a maximum of 64K bytes of
  475. code and 64K bytes of data.  Because the small model implements call
  476. instructions and data references through near pointers, it produces the most
  477. efficient code of the three supported memory models.
  478. 4   Fastgraph User's Guide
  479.  
  480.      The medium memory model allows for multiple code segments and one data
  481. segment.  Programs that use the medium model thus have no compiler-imposed
  482. limit to the code size (although no one segment can exceed 64K bytes) and a
  483. maximum of 64K bytes of data.  Like the small model, the medium model
  484. implements data references through near pointers, but it implements call
  485. instructions through far pointers.  The use of far pointers adds two bytes of
  486. code and 13 clock cycles for each subprogram call.  The medium model is a
  487. popular choice among programmers.
  488.  
  489.      The large memory model supports multiple code and data segments.
  490. Programs that use the large model do not have any compiler-imposed limits for
  491. code and data sizes.  However, no single code or data segment can exceed 64K
  492. bytes.  Because the large model implements call instructions and data
  493. references through far pointers, it produces the least efficient code of the
  494. three supported memory models.
  495.  
  496.      For more information about memory models, please refer to the user's
  497. guide or reference manual supplied with your compiler.
  498.  
  499.  
  500. Installing Fastgraph
  501.  
  502.      This section explains how to use the INSTALL program to load Fastgraph
  503. (or Fastgraph/Light) and its related files on a hard disk.  The installation
  504. program lets you select the compilers and memory models you wish to use with
  505. Fastgraph.  It also gives you the opportunity to load many example Fastgraph
  506. programs specific to the compilers you choose.
  507.  
  508.      Before you start the installation, we recommend using the DOS commands
  509. COPY or DISKCOPY to make working copies of the Fastgraph distribution disks
  510. (refer to your DOS reference manual if you are unfamiliar with these
  511. commands).  Once you have created the working copies, store the original
  512. disks in a safe place.  Install Fastgraph from the working copies you just
  513. created.
  514.  
  515.      For simplicity, we'll assume you are installing Fastgraph from the
  516. diskette drive A: to the hard drive C:, but you can of course use any
  517. available drives.  The Fastgraph distribution disk labeled Installation and
  518. Utilities contains Fastgraph's INSTALL program.  Place this disk in the A:
  519. drive, make A: your current drive, and enter the command INSTALL, as shown
  520. below.
  521.  
  522.                                   C> A:
  523.                                   A> INSTALL
  524.  
  525. From this point, just follow the directions on each screen.  At any time, you
  526. can press the Esc key to abort the installation.
  527.  
  528.      The INSTALL program will ask you for the compilers and memory models
  529. you'll use with Fastgraph, as well as the directory names for the Fastgraph
  530. utilities, libraries, and include files.  For the utilities, the default
  531. directory is C:\FG.  For the include files and libraries, we recommend using
  532. directories where the compiler you've chosen normally searches for such
  533. files.  INSTALL will automatically try to determine these directories and
  534. propose them as defaults.
  535.                                                   Chapter 1:  Introduction   5
  536.  
  537.      You can install support for additional compilers or memory models at any
  538. time.  If you choose to do this, you should use the command INSTALL /L to
  539. avoid copying the files common to all compilers and memory models.
  540.  
  541.  
  542. The READ.ME File
  543.  
  544.      The READ.ME file contains additions and changes that may have been made
  545. to Fastgraph since the publication of the manuals.  We encourage you to
  546. examine the READ.ME file immediately after installing Fastgraph.  READ.ME is
  547. an ASCII text file, suitable for any printer or text editor.  The INSTALL
  548. program places the READ.ME file in the Fastgraph utilities directory (C:\FG
  549. by default).
  550.  
  551.  
  552. Fastgraph Naming Conventions
  553.  
  554.      The names of all Fastgraph routines begin with the three characters
  555. "fg_".  This prefix helps identify Fastgraph routines within a program, and
  556. it also reduces the chance of name conflicts that might otherwise occur
  557. between Fastgraph and other third party libraries.
  558.  
  559.      Because QuickBASIC and Visual Basic for DOS do not permit underscores in
  560. identifiers, the BASIC versions of Fastgraph routines begin with the two
  561. characters "FG".  For example, the fg_version routine is named FGversion in
  562. the QuickBASIC and Visual Basic for DOS libraries.  All subsequent references
  563. to Fastgraph routines in this manual and the accompanying Fastgraph Reference
  564. Manual will use the fg_ naming convention instead of the BASIC names.
  565.  
  566.  
  567. Compilation and Linking
  568.  
  569.      To build an executable (.EXE) file for a program that uses Fastgraph
  570. routines, first compile or assemble the program using the small, medium, or
  571. large memory model.  This step produces an object file, which is then linked
  572. with Fastgraph and any other object libraries to produce an executable file.
  573.  
  574.      Example 1-1 uses the Fastgraph routine fg_version to display the version
  575. number for your copy of Fastgraph.  Versions of this program are presented
  576. for each high-level language Fastgraph supports:  C/C++, BASIC, FORTRAN, and
  577. Pascal.  If you loaded the example programs when you installed Fastgraph, the
  578. files \FG\EXAMPLES\01-01.C, 01-01.BAS, 01-01.FOR, and 01-01.PAS contain the
  579. source code for these examples.  You can use them to test the compilation and
  580. linking process for the memory models and compilers you'll be using with
  581. Fastgraph.
  582.  
  583.                          Example 1-1 (C/C++ version).
  584.  
  585.       #include <fastgraf.h>
  586.       #include <stdio.h>
  587.       void main(void);
  588.  
  589.       void main()
  590.       {
  591.          int major;
  592.          int minor;
  593. 6   Fastgraph User's Guide
  594.  
  595.          fg_version(&major,&minor);
  596.          printf("This is version %d.%2.2d of Fastgraph.\n",major,minor);
  597.       }
  598.  
  599.  
  600.      The header file FASTGRAF.H contains the C function prototypes for each
  601. Fastgraph routine.  It should reside in a directory where the compiler
  602. normally searches for other header files.  For Microsoft C/C++, QuickC, and
  603. Zortech C++, FASTGRAF.H can reside in any of the directories specified by the
  604. INCLUDE environment variable.  For Power C, it can reside in any of the
  605. directories specified by the /i switch in the PCOPTION environment variable.
  606.  
  607.                          Example 1-1 (BASIC version).
  608.  
  609.           REM $INCLUDE: 'fastgraf.bi'
  610.  
  611.           DEFINT A-Z
  612.  
  613.           FGversion Major, Minor
  614.           Version! = Major + Minor*0.01
  615.  
  616.           PRINT USING "This is version #.## of Fastgraph."; Version!
  617.  
  618.           END
  619.  
  620.  
  621.      You must include the DECLARE commands in the file FASTGRAF.BI at the
  622. beginning of each QuickBASIC or Visual Basic for DOS module.  This file
  623. should reside in the directory where the compiler normally searches for other
  624. .BI files, or in any of the directories specified by the INCLUDE environment
  625. variable.  The DECLARE commands in this file automatically provide the
  626. calling convention and naming convention for each Fastgraph routine.  In
  627. addition, they relieve the programmer of distinguishing arguments passed by
  628. value from those passed by reference.
  629.  
  630.                         Example 1-1 (FORTRAN version).
  631.  
  632.      $INCLUDE: '\FG\INTRFACE.FOR'
  633.  
  634.            PROGRAM MAIN
  635.  
  636.            INTEGER*2 MAJOR
  637.            INTEGER*2 MINOR
  638.  
  639.            CALL FG_VERSION (MAJOR, MINOR)
  640.  
  641.            WRITE (6,10) MAJOR, MINOR
  642.      10    FORMAT (' This is version ', I1, '.', I2.2, ' of Fastgraph.')
  643.  
  644.            STOP ' '
  645.            END
  646.  
  647.      You must include the INTERFACE statements in the file INTRFACE.FOR at
  648. the beginning of FORTRAN programs (this file should reside in the \FG
  649. directory).  The INTERFACE statements in this file automatically provide the
  650. calling convention and naming convention for each Fastgraph routine.  In
  651.                                                   Chapter 1:  Introduction   7
  652.  
  653. addition, they relieve the FORTRAN programmer of distinguishing arguments
  654. passed by value from those passed by reference.
  655.  
  656.                         Example 1-1 (Pascal version).
  657.  
  658.       program main;
  659.       uses fgmain;
  660.  
  661.       var
  662.         Major : integer;
  663.         Minor : integer;
  664.  
  665.       begin
  666.         fg_version(Major,Minor);
  667.         writeln('This is version ',Major,'.',Minor:2,' of Fastgraph.');
  668.       end.
  669.  
  670.  
  671.      Pascal programs that use Fastgraph or Fastgraph/Light must include a
  672. uses statement specifying the names of the unit files (TPU files) needed in
  673. the program.  All unit files must reside in a directory where the compiler
  674. normally searches for units.  Appendix E lists the Fastgraph functions in
  675. each unit.
  676.  
  677.      The following sections show the simplest compilation and linking
  678. procedures for the supported compilers.  In what follows, items enclosed in
  679. angle brackets, such as <filename>, are placeholders for parameters you must
  680. supply (the name of a file in this case).  Items enclosed in square brackets,
  681. such as [/E], are optional.
  682. 8   Fastgraph User's Guide
  683.  
  684.  
  685. Borland C++
  686.  
  687.      Borland C++ allows you to compile and link a program directly from the
  688. DOS command line, or from its integrated development environment (IDE).  To
  689. use Fastgraph from the IDE, you must make sure the compiler options match one
  690. of Fastgraph's available memory models (small, medium, or large) and then
  691. create a project file that links with the corresponding Fastgraph libraries
  692. (as listed below).
  693.  
  694.      You also can compile and link a Borland C++ program from the DOS command
  695. line using the BCC command.  The format of the BCC command for compiling a
  696. program and linking it with Fastgraph is
  697.  
  698.  
  699.              BCC <model> <filename> <fg_library> [<fg_extended>]
  700.  
  701. where:
  702.  
  703.      <model>        specifies the compiler memory model you'll be using.
  704.                     It must be either -ms (for the small model), -mm
  705.                     (for the medium model), or -ml (for the large
  706.                     model).
  707.  
  708.      <filename>     is the name of the file containing your program.  It
  709.                     may include a path specification.
  710.  
  711.      <fg_library>   is the name of a standard Fastgraph or
  712.                     Fastgraph/Light library.  For Fastgraph, the library
  713.                     name is FGS.LIB (for the small model), FGM.LIB (for
  714.                     the medium model), or FGL.LIB (for the large model).
  715.                     For Fastgraph/Light, the library name is FGLS.LIB
  716.                     (for the small model), FGLM.LIB (for the medium
  717.                     model), or FGLL.LIB (for the large model).
  718.  
  719.      <fg_extended>  is the name of an optional compiler-specific
  720.                     extended Fastgraph library.  You need to specify an
  721.                     extended library name only if your program calls any
  722.                     of the Fastgraph routines listed in Appendix D.  The
  723.                     Borland C++ extended library name is FGTCS.LIB (for
  724.                     the small model), FGTCM.LIB (for the medium model),
  725.                     or FGTCL.LIB (for the large model).  Fastgraph/Light
  726.                     does not use extended libraries.
  727.  
  728.      For example, to compile the program 01-01.C under the medium memory
  729. model and then link it with Fastgraph, you could use the following BCC
  730. command:
  731.  
  732.                       BCC -mm 01-01.C FGM.LIB FGTCM.LIB
  733.  
  734. Although we specified the extended library name FGTCM.LIB on the command
  735. line, we didn't need to in this example because the program doesn't call any
  736. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  737. were using Fastgraph/Light instead of Fastgraph, the BCC command would be:
  738.  
  739.                            BCC -mm 01-01.C FGLM.LIB
  740.                                                   Chapter 1:  Introduction   9
  741.  
  742. For more information about project files, memory models, or other compilation
  743. and linking options, please refer to the Borland C++ User's Guide, published
  744. by Borland International.
  745. 10   Fastgraph User's Guide
  746.  
  747.  
  748. Borland Pascal
  749.  
  750.      Borland Pascal allows you to compile and link a program directly from
  751. the DOS command line with the TPC command, or from its integrated development
  752. environment (IDE) with the TURBO command.  To use Fastgraph from the IDE,
  753. just start the IDE as you would for any other Pascal program, making sure the
  754. Fastgraph unit files reside in one of the directories listed in the Unit
  755. Directories option.
  756.  
  757.      You also can compile and link a Borland Pascal program from the DOS
  758. command line using the TPC command.  The format of the TPC command for
  759. compiling a program and linking it with Fastgraph is
  760.  
  761.                                 TPC <filename>
  762.  
  763. where:
  764.  
  765.      <filename>          is the name of the file containing your
  766.                          program.  It may include a path specification.
  767.  
  768.      For example, to compile the program 01-01.PAS and then link it with
  769. Fastgraph, you could use the following command:
  770.  
  771.                                 TPC 01-01.PAS
  772.  
  773. For more information about other compilation and linking options, please
  774. refer to the Borland Pascal With Objects User's Guide, published by Borland
  775. International.
  776.  
  777.      All remaining example programs in the Fastgraph User's Guide are written
  778. in the C programming language.  However, when you install Fastgraph for
  779. Borland Pascal, the installation procedure copies Pascal versions of the
  780. example programs to the \FG\EXAMPLES directory.
  781.                                                  Chapter 1:  Introduction   11
  782.  
  783.  
  784. Microsoft BASIC PDS 7
  785.  
  786.      Microsoft BASIC Professional Development System (PDS) allows you to
  787. compile and link a program directly from the DOS command line, or from its
  788. programming environment.  To use Fastgraph from the BASIC PDS programming
  789. environment, just specify the quick library name FGQBX when starting BASIC
  790. PDS, as shown below.
  791.  
  792.                            QBX /LFGQBX [<filename>]
  793.  
  794. You must use the default "Far Strings" setting within the environment.  There
  795. are no near string Fastgraph libraries available for BASIC PDS.  If you are
  796. using Fastgraph/Light, use the library name FGLQBX instead of FGQBX.
  797.  
  798.      You also can compile and link a BASIC PDS program from the DOS command
  799. line using the BC and LINK commands.  The format of these commands for
  800. compiling a program and linking it with Fastgraph is
  801.  
  802.                   BC /Fs [/O] <filename>;
  803.                   LINK [/E] <object_file>,,NUL,<fg_library>;
  804.  
  805. where:
  806.  
  807.      <filename>     is the name of the file containing your program.  It
  808.                     may include a path specification.
  809.  
  810.      <object_file>  is the name of the object file produced by the BC
  811.                     command.  By default, this will be the same as
  812.                     <filename>, but with an extension of .OBJ rather
  813.                     than .BAS.
  814.  
  815.      <fg_library>   is the name of the standard Fastgraph or
  816.                     Fastgraph/Light library.  For Fastgraph, the library
  817.                     name is FGQBX.  For Fastgraph/Light, the library
  818.                     name is FGLQBX.  QuickBASIC does not use extended
  819.                     Fastgraph libraries.
  820.  
  821. When compiling BASIC PDS programs with the BC command, you must include the
  822. /Fs option to use far strings.  The /O option on the BC command is
  823. recommended because it creates .EXE files that do not require the BASIC PDS
  824. run-time module.  The /E linker option is not required but will produce a
  825. smaller .EXE file if specified.
  826.  
  827.      For example, to compile the program 01-01.BAS and then link it with
  828. Fastgraph, you could use the following commands:
  829.  
  830.                          BC /Fs /O 01-01.BAS;
  831.                          LINK /E 01-01.OBJ,,NUL,FGQBX;
  832.  
  833. If you were using Fastgraph/Light instead of Fastgraph, the commands would
  834. be:
  835.  
  836.                         BC /Fs /O 01-01.BAS;
  837.                         LINK /E 01-01.OBJ,,NUL,FGLQBX;
  838.  
  839. 12   Fastgraph User's Guide
  840.  
  841. For more information about other compilation and linking options, please
  842. refer to the Microsoft BASIC PDS Programmer's Guide, published by Microsoft
  843. Corporation.
  844.  
  845.      All remaining example programs in the Fastgraph User's Guide are written
  846. in the C programming language.  However, when you install Fastgraph for
  847. Microsoft BASIC PDS, the installation procedure copies BASIC versions of the
  848. example programs to the \FG\EXAMPLES directory.
  849.                                                  Chapter 1:  Introduction   13
  850.  
  851.  
  852. Microsoft C and C++
  853.  
  854.      Microsoft C and C++ programs are compiled and linked by entering a CL
  855. command at the DOS command prompt.  The format of the CL command for
  856. compiling a program and linking it with Fastgraph is
  857.  
  858.         CL <model> <filename> /link <fg_library> [<fg_extended>] [/E]
  859.  
  860. where:
  861.  
  862.      <model>        specifies the compiler memory model you'll be using.
  863.                     It must be either /AS (for the small model), /AM
  864.                     (for the medium model), or /AL (for the large
  865.                     model).
  866.  
  867.      <filename>     is the name of the file containing your program.  It
  868.                     must include the file extension (typically .C) and
  869.                     may include a path specification.
  870.  
  871.      <fg_library>   is the name of a standard Fastgraph or
  872.                     Fastgraph/Light library.  For Fastgraph, the library
  873.                     name is FGS (for the small model), FGM (for the
  874.                     medium model), or FGL (for the large model).  For
  875.                     Fastgraph/Light, the library name is FGLS (for the
  876.                     small model), FGLM (for the medium model), or FGLL
  877.                     (for the large model).
  878.  
  879.      <fg_extended>  is the name of an optional compiler-specific
  880.                     extended Fastgraph library.  You need to specify an
  881.                     extended library name only if your program calls any
  882.                     of the Fastgraph routines listed in Appendix D.  The
  883.                     Microsoft C/C++ extended library name is FGMSCS (for
  884.                     the small model), FGMSCM (for the medium model), or
  885.                     FGMSCL (for the large model).  Fastgraph/Light does
  886.                     not use extended libraries.
  887.  
  888. The /E linker option is not required but will produce a smaller .EXE file if
  889. specified.
  890.  
  891.      For example, to compile the program 01-01.C under the medium memory
  892. model and then link it with Fastgraph, you could use the following CL
  893. command:
  894.  
  895.                       CL /AM 01-01.C /link FGM FGMSCM /E
  896.  
  897. Although we specified the extended library name FGMSCM on the command line,
  898. we didn't need to in this example because the program doesn't call any of the
  899. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  900. Fastgraph/Light instead of Fastgraph, the CL command would be:
  901.  
  902.                          CL /AM 01-01.C /link FGLM /E
  903.  
  904. For more information about memory models or other compilation and linking
  905. options, please refer to the Microsoft C Optimizing Compiler User's Guide,
  906. published by Microsoft Corporation.
  907. 14   Fastgraph User's Guide
  908.  
  909.  
  910. Microsoft FORTRAN
  911.  
  912.      Microsoft FORTRAN programs are compiled and linked by entering an FL
  913. command at the DOS command prompt.  The format of the FL command for
  914. compiling a program and linking it with Fastgraph is
  915.  
  916.            FL /FPi /4I2 /4Nt <model> <filename> /link <fg_library>
  917.                [<fg_extended>] [/E]
  918.  
  919. where:
  920.  
  921.      <model>        specifies the compiler memory model you'll be using.
  922.                     It must be either /AM (for the medium model) or /AL
  923.                     (for the large model).  Microsoft FORTRAN does not
  924.                     support the small model.
  925.  
  926.      <filename>     is the name of the file containing your program.  It
  927.                     may include a path specification.
  928.  
  929.      <fg_library>   is the name of a standard Fastgraph or
  930.                     Fastgraph/Light library.  For Fastgraph, the library
  931.                     name is FGM (for the medium model) or FGL (for the
  932.                     large model).  For Fastgraph/Light, the library name
  933.                     is FGLM (for the medium model) or FGLL (for the
  934.                     large model).
  935.  
  936.      <fg_extended>  is the name of an optional compiler-specific
  937.                     extended Fastgraph library.  You need to specify an
  938.                     extended library name only if your program calls any
  939.                     of the Fastgraph routines listed in Appendix D.  The
  940.                     Microsoft FORTRAN extended library name is FGMSFM
  941.                     (for the medium model) or FGMSFL (for the large
  942.                     model).  Fastgraph/Light does not use extended
  943.                     libraries.
  944.  
  945. The /E linker option is not required but will produce a smaller .EXE file if
  946. specified.
  947.  
  948.      For example, to compile the program 01-01.FOR under the medium memory
  949. model and then link it with Fastgraph, you could use the following FL
  950. command:
  951.  
  952.              FL /FPi /4I2 /4Nt /AM 01-01.FOR /link FGM FGMSFM /E
  953.  
  954. Although we specified the extended library name FGMSFM on the command line,
  955. we didn't need to in this example because the program doesn't call any of the
  956. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  957. Fastgraph/Light instead of Fastgraph, the FL command would be:
  958.  
  959.                 FL /FPi /4I2 /4Nt /AM 01-01.FOR /link FGLM /E
  960.  
  961. For more information about memory models or other compilation and linking
  962. options, please refer to the Microsoft FORTRAN Optimizing Compiler User's
  963. Guide, published by Microsoft Corporation.
  964.                                                  Chapter 1:  Introduction   15
  965.  
  966.      All remaining example programs in the Fastgraph User's Guide are written
  967. in the C programming language.  However, when you install Fastgraph for the
  968. Microsoft FORTRAN compiler, the installation procedure copies FORTRAN
  969. versions of the example programs to the \FG\EXAMPLES directory.
  970. 16   Fastgraph User's Guide
  971.  
  972. Microsoft QuickBASIC
  973.  
  974.      Microsoft QuickBASIC allows you to compile and link a program directly
  975. from the DOS command line, or from its programming environment.  To use
  976. Fastgraph from QuickBASIC's programming environment, just specify the quick
  977. library name FGQB when starting QuickBASIC, as shown below.
  978.  
  979.                             QB /LFGQB [<filename>]
  980.  
  981. If you are using Fastgraph/Light, use the library name FGLQB instead of FGQB.
  982.  
  983.      You also can compile and link a QuickBASIC program from the DOS command
  984. line using the BC and LINK commands.  The format of these commands for
  985. compiling a program and linking it with Fastgraph is
  986.  
  987.                   BC [/O] <filename>;
  988.                   LINK [/E] <object_file>,,NUL,<fg_library>;
  989.  
  990. where:
  991.  
  992.      <filename>     is the name of the file containing your program.  It
  993.                     may include a path specification.
  994.  
  995.      <object_file>  is the name of the object file produced by the BC
  996.                     command.  By default, this will be the same as
  997.                     <filename>, but with an extension of .OBJ rather
  998.                     than .BAS.
  999.  
  1000.      <fg_library>   is the name of the standard Fastgraph or
  1001.                     Fastgraph/Light library.  For Fastgraph, the library
  1002.                     name is FGQB.  For Fastgraph/Light, the library name
  1003.                     is FGLQB.  QuickBASIC does not use extended
  1004.                     Fastgraph libraries.
  1005.  
  1006. The /O option on the BC command is recommended because it creates .EXE files
  1007. that do not require the QuickBASIC run-time module.  The /E linker option is
  1008. not required but will produce a smaller .EXE file if specified.
  1009.  
  1010.      For example, to compile the program 01-01.BAS and then link it with
  1011. Fastgraph, you could use the following commands:
  1012.  
  1013.                          BC /O 01-01.BAS;
  1014.                          LINK /E 01-01.OBJ,,NUL,FGQB;
  1015.  
  1016. If you were using Fastgraph/Light instead of Fastgraph, the commands would
  1017. be:
  1018.  
  1019.                          BC /O 01-01.BAS;
  1020.                          LINK /E 01-01.OBJ,,NUL,FGLQB;
  1021.  
  1022. For more information about other compilation and linking options, please
  1023. refer to the Microsoft QuickBASIC: Programming in BASIC manual, published by
  1024. Microsoft Corporation.
  1025.  
  1026.      All remaining example programs in the Fastgraph User's Guide are written
  1027. in the C programming language.  However, when you install Fastgraph for
  1028.                                                  Chapter 1:  Introduction   17
  1029.  
  1030. Microsoft QuickBASIC, the installation procedure copies BASIC versions of the
  1031. example programs to the \FG\EXAMPLES directory.
  1032. 18   Fastgraph User's Guide
  1033.  
  1034. Microsoft QuickC
  1035.  
  1036.      Microsoft QuickC allows you to compile and link a program directly from
  1037. the DOS command line, or from its programming environment.  To use Fastgraph
  1038. from the QuickC programming environment, you must make sure the compiler
  1039. options match one of Fastgraph's available memory models (small, medium, or
  1040. large) and then create a make file that includes one or more of the
  1041. corresponding Fastgraph libraries (as listed below).
  1042.  
  1043.      You also can compile and link a QuickC program from the DOS command line
  1044. using the QCL command.  The format of the QCL command for compiling a program
  1045. and linking it with Fastgraph is
  1046.  
  1047.         QCL <model> <filename> /link <fg_library> [<fg_extended>] [/E]
  1048.  
  1049. where:
  1050.  
  1051.      <model>        specifies the compiler memory model you'll be using.
  1052.                     It must be either /AS (for the small model), /AM
  1053.                     (for the medium model), or /AL (for the large
  1054.                     model).
  1055.  
  1056.      <filename>     is the name of the file containing your program.  It
  1057.                     must include the file extension (typically .C) and
  1058.                     may include a path specification.
  1059.  
  1060.      <fg_library>   is the name of a standard Fastgraph or
  1061.                     Fastgraph/Light library.  For Fastgraph, the library
  1062.                     name is FGS (for the small model), FGM (for the
  1063.                     medium model), or FGL (for the large model).  For
  1064.                     Fastgraph/Light, the library name is FGLS (for the
  1065.                     small model), FGLM (for the medium model), or FGLL
  1066.                     (for the large model).
  1067.  
  1068.      <fg_extended>  is the name of an optional compiler-specific
  1069.                     extended Fastgraph library.  You need to specify an
  1070.                     extended library name only if your program calls any
  1071.                     of the Fastgraph routines listed in Appendix D.  The
  1072.                     QuickC extended library name is FGMSCS (for the
  1073.                     small model), FGMSCM (for the medium model), or
  1074.                     FGMSCL (for the large model).  Fastgraph/Light does
  1075.                     not use extended libraries.
  1076.  
  1077. The /E linker option is not required but will produce a smaller .EXE file if
  1078. specified.
  1079.  
  1080.      For example, to compile the program 01-01.C under the medium memory
  1081. model and then link it with Fastgraph, you could use the following QCL
  1082. command:
  1083.  
  1084.                      QCL /AM 01-01.C /link FGM FGMSCM /E
  1085.  
  1086. Although we specified the extended library name FGMSCM on the command line,
  1087. we didn't need to in this example because the program doesn't call any of the
  1088. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  1089. Fastgraph/Light instead of Fastgraph, the QCL command would be:
  1090.                                                  Chapter 1:  Introduction   19
  1091.  
  1092.  
  1093.                         QCL /AM 01-01.C /link FGLM /E
  1094.  
  1095. For more information about make files, memory models, or other compilation
  1096. and linking options, please refer to the Microsoft QuickC Tool Kit manual,
  1097. published by Microsoft Corporation.
  1098. 20   Fastgraph User's Guide
  1099.  
  1100.  
  1101. Microsoft Visual Basic for DOS
  1102.  
  1103.      Microsoft Visual Basic for DOS allows you to compile and link a program
  1104. directly from the DOS command line, or from its programming environment.  To
  1105. use Fastgraph from the programming environment, just specify the quick
  1106. library name FGVBDOS when starting Visual Basic, as shown below.
  1107.  
  1108.                          VBDOS /LFGVBDOS [<filename>]
  1109.  
  1110. If you are using Fastgraph/Light, use the library name FGLVBDOS instead of
  1111. FGVBDOS.  When using the Visual Basic for DOS programming environment, you
  1112. may get an "Out of Memory" or "Out of String Space" error message when trying
  1113. to build an EXE file or run an application within the environment.  Should
  1114. this occur, you must specify the /S option on the VBDOS command line to
  1115. increase the amount of memory available to your application.
  1116.  
  1117.      You also can compile and link a Visual Basic program from the DOS
  1118. command line using the BC and LINK commands.  The format of these commands
  1119. for compiling a program and linking it with Fastgraph is
  1120.  
  1121.                   BC [/O] <filename>;
  1122.                   LINK [/E] <object_file>,,NUL,<fg_library>;
  1123.  
  1124. where:
  1125.  
  1126.      <filename>     is the name of the file containing your program.  It
  1127.                     may include a path specification.
  1128.  
  1129.      <object_file>  is the name of the object file produced by the BC
  1130.                     command.  By default, this will be the same as
  1131.                     <filename>, but with an extension of .OBJ rather
  1132.                     than .BAS.
  1133.  
  1134.      <fg_library>   is the name of the standard Fastgraph or
  1135.                     Fastgraph/Light library.  For Fastgraph, the library
  1136.                     name is FGVBDOS.  For Fastgraph/Light, the library
  1137.                     name is FGLVBDOS.  Visual Basic does not use
  1138.                     extended Fastgraph libraries.
  1139.  
  1140. The /O option on the BC command is recommended because it creates .EXE files
  1141. that do not require the Visual Basic run-time module.  The /E linker option
  1142. is not required but will produce a smaller .EXE file if specified.
  1143.  
  1144.      For example, to compile the program 01-01.BAS and then link it with
  1145. Fastgraph, you could use the following commands:
  1146.  
  1147.                          BC /O 01-01.BAS;
  1148.                          LINK /E 01-01.OBJ,,NUL,FGVBDOS;
  1149.  
  1150. If you were using Fastgraph/Light instead of Fastgraph, the commands would
  1151. be:
  1152.  
  1153.                          BC /O 01-01.BAS;
  1154.                          LINK /E 01-01.OBJ,,NUL,FGLVBDOS;
  1155.  
  1156.                                                  Chapter 1:  Introduction   21
  1157.  
  1158. When linking Visual Basic for DOS programs that call Fastgraph's world space
  1159. or software character routines (i.e., any of the routines listed in Appendix
  1160. D), you may need to increase the number of segments available to the linker.
  1161. Use the /SEG:n option on the LINK command to do this.  The default value of
  1162. "n" is 128 segments; usually a slightly larger value, such as 144, will be
  1163. sufficient.  For more information about other compilation and linking
  1164. options, please refer to the Microsoft Visual Basic Programmer's Guide,
  1165. published by Microsoft Corporation.
  1166.  
  1167.      All remaining example programs in the Fastgraph User's Guide are written
  1168. in the C programming language.  However, when you install Fastgraph for
  1169. Visual Basic, the installation procedure copies BASIC versions of the example
  1170. programs to the \FG\EXAMPLES directory.
  1171. 22   Fastgraph User's Guide
  1172.  
  1173.  
  1174. Microsoft Visual C++
  1175.  
  1176.      To use Fastgraph with Microsoft Visual C++, use the same compilation
  1177. sequences as for Microsoft C and C++.
  1178.                                                  Chapter 1:  Introduction   23
  1179.  
  1180.  
  1181. Power C
  1182.  
  1183.      Power C programs are compiled and linked from the DOS command line using
  1184. the PC and PCL commands.  The format of these commands for compiling a
  1185. program and linking it with Fastgraph is
  1186.  
  1187.                 PC <model> <filename>
  1188.                 PCL <mix_file> ;<fg_library> [;<fg_extended>]
  1189.  
  1190. where:
  1191.  
  1192.      <model>        specifies the compiler memory model you'll be using.
  1193.                     It must be either /ms (for the small model), /mm
  1194.                     (for the medium model), or /ml (for the large
  1195.                     model).
  1196.  
  1197.      <filename>     is the name of the file containing your program.  It
  1198.                     may include a path specification.
  1199.  
  1200.      <mix_file>     is the name of the object file produced by the PC
  1201.                     command.  By default, this will be the same as
  1202.                     <filename>, but with an extension of .MIX rather
  1203.                     than .C.
  1204.  
  1205.      <fg_library>   is the name of a standard Fastgraph or
  1206.                     Fastgraph/Light library.  For Fastgraph, the library
  1207.                     name is FGS (for the small model), FGM (for the
  1208.                     medium model), or FGL (for the large model).  For
  1209.                     Fastgraph/Light, the library name is FGLS (for the
  1210.                     small model), FGLM (for the medium model), or FGLL
  1211.                     (for the large model).
  1212.  
  1213.      <fg_extended>  is the name of an optional compiler-specific
  1214.                     extended Fastgraph library.  You need to specify an
  1215.                     extended library name only if your program calls any
  1216.                     of the Fastgraph routines listed in Appendix D.  The
  1217.                     Power C extended library name is FGPCS (for the
  1218.                     small model), FGPCM (for the medium model), or FGPCL
  1219.                     (for the large model).  Fastgraph/Light does not use
  1220.                     extended libraries.
  1221.  
  1222.      For example, to compile the program 01-01.C under the medium memory
  1223. model and then link it with Fastgraph, you could use the following commands:
  1224.  
  1225.                           PC /mm 01-01.C
  1226.                           PCL 01-01.MIX ;FGM ;FGPCM
  1227.  
  1228. Although we specified the extended library name FGPCM on the command line, we
  1229. didn't need to in this example because the program doesn't call any of the
  1230. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  1231. Fastgraph/Light instead of Fastgraph, the commands would be:
  1232.  
  1233.                              PC /mm 01-01.C
  1234.                              PCL 01-01.MIX ;FGPCM
  1235. 24   Fastgraph User's Guide
  1236.  
  1237. For more information about memory models or other compilation and linking
  1238. options, please refer to the Power C manual, published by Mix Software, Inc.
  1239.                                                  Chapter 1:  Introduction   25
  1240.  
  1241.  
  1242. Turbo C and Turbo C++
  1243.  
  1244.      Turbo C and Turbo C++ allow you to compile and link a program directly
  1245. from the DOS command line, or from their integrated development environment
  1246. (IDE).  To use Fastgraph from the IDE, you must make sure the compiler
  1247. options match one of Fastgraph's available memory models (small, medium, or
  1248. large) and then create a project file that links with the corresponding
  1249. Fastgraph libraries (as listed below).
  1250.  
  1251.      You also can compile and link a Turbo C or Turbo C++ program from the
  1252. DOS command line using the TCC command.  The format of the TCC command for
  1253. compiling a program and linking it with Fastgraph is
  1254.  
  1255.              TCC <model> <filename> <fg_library> [<fg_extended>]
  1256.  
  1257. where:
  1258.  
  1259.      <model>        specifies the compiler memory model you'll be using.
  1260.                     It must be either -ms (for the small model), -mm
  1261.                     (for the medium model), or -ml (for the large
  1262.                     model).
  1263.  
  1264.      <filename>     is the name of the file containing your program.  It
  1265.                     may include a path specification.
  1266.  
  1267.      <fg_library>   is the name of a standard Fastgraph or
  1268.                     Fastgraph/Light library.  For Fastgraph, the library
  1269.                     name is FGS.LIB (for the small model), FGM.LIB (for
  1270.                     the medium model), or FGL.LIB (for the large model).
  1271.                     For Fastgraph/Light, the library name is FGLS.LIB
  1272.                     (for the small model), FGLM.LIB (for the medium
  1273.                     model), or FGLL.LIB (for the large model).
  1274.  
  1275.      <fg_extended>  is the name of an optional compiler-specific
  1276.                     extended Fastgraph library.  You need to specify an
  1277.                     extended library name only if your program calls any
  1278.                     of the Fastgraph routines listed in Appendix D.  The
  1279.                     Turbo C/C++ extended library name is FGTCS.LIB (for
  1280.                     the small model), FGTCM.LIB (for the medium model),
  1281.                     or FGTCL.LIB (for the large model).  Fastgraph/Light
  1282.                     does not use extended libraries.
  1283.  
  1284.      For example, to compile the program 01-01.C under the medium memory
  1285. model and then link it with Fastgraph, you could use the following TCC
  1286. command:
  1287.  
  1288.                       TCC -mm 01-01.C FGM.LIB FGTCM.LIB
  1289.  
  1290. Although we specified the extended library name FGTCM.LIB on the command
  1291. line, we didn't need to in this example because the program doesn't call any
  1292. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  1293. were using Fastgraph/Light instead of Fastgraph, the TCC command would be:
  1294.  
  1295.                            TCC -mm 01-01.C FGLM.LIB
  1296. 26   Fastgraph User's Guide
  1297.  
  1298. For more information about project files, memory models, or other compilation
  1299. and linking options, please refer to the Turbo C User's Guide and the Turbo C
  1300. Reference Guide, both published by Borland International.
  1301.                                                  Chapter 1:  Introduction   27
  1302.  
  1303.  
  1304. Turbo Pascal
  1305.  
  1306.      Turbo Pascal allows you to compile and link a program directly from the
  1307. DOS command line with the TPC command, or from its integrated development
  1308. environment (IDE) with the TURBO command.  To use Fastgraph from the IDE,
  1309. just start the IDE as you would for any other Pascal program, making sure the
  1310. Fastgraph unit files reside in one of the directories listed in the Unit
  1311. Directories option.
  1312.  
  1313.      You also can compile and link a Turbo Pascal program from the DOS
  1314. command line using the TPC command.  The format of the TPC command for
  1315. compiling a program and linking it with Fastgraph is
  1316.  
  1317.                                 TPC <filename>
  1318.  
  1319. where:
  1320.  
  1321.      <filename>          is the name of the file containing your
  1322.                          program.  It may include a path specification.
  1323.  
  1324.      For example, to compile the program 01-01.PAS and then link it with
  1325. Fastgraph, you could use the following command:
  1326.  
  1327.                                 TPC 01-01.PAS
  1328.  
  1329. For more information about other compilation and linking options, please
  1330. refer to the Turbo Pascal User's Guide, published by Borland International.
  1331.  
  1332.      All remaining example programs in the Fastgraph User's Guide are written
  1333. in the C programming language.  However, when you install Fastgraph for Turbo
  1334. Pascal, the installation procedure copies Pascal versions of the example
  1335. programs to the \FG\EXAMPLES directory.
  1336. 28   Fastgraph User's Guide
  1337.  
  1338.  
  1339. Zortech C++
  1340.  
  1341.      Zortech C++ programs are compiled and linked from the DOS command line
  1342. using the ZTC command.  The format of this command for compiling a program
  1343. and linking it with Fastgraph is
  1344.  
  1345.              ZTC <model> <filename> <fg_library> [<fg_extended>]
  1346.  
  1347. where:
  1348.  
  1349.      <model>        specifies the compiler memory model you'll be using.
  1350.                     It must be either -ms (for the small model), -mm
  1351.                     (for the medium model), or -ml (for the large
  1352.                     model).
  1353.  
  1354.      <filename>     is the name of the file containing your program.  It
  1355.                     may include a path specification.
  1356.  
  1357.      <fg_library>   is the name of a standard Fastgraph or
  1358.                     Fastgraph/Light library.  For Fastgraph, the library
  1359.                     name is FGS.LIB (for the small model), FGM.LIB (for
  1360.                     the medium model), or FGL.LIB (for the large model).
  1361.                     For Fastgraph/Light, the library name is FGLS.LIB
  1362.                     (for the small model), FGLM.LIB (for the medium
  1363.                     model), or FGLL.LIB (for the large model).
  1364.  
  1365.      <fg_extended>  is the name of an optional compiler-specific
  1366.                     extended Fastgraph library.  You need to specify an
  1367.                     extended library name only if your program calls any
  1368.                     of the Fastgraph routines listed in Appendix D.  The
  1369.                     Zortech C++ extended library name is FGZCS.LIB (for
  1370.                     the small model), FGZCM.LIB (for the medium model),
  1371.                     or FGZCL.LIB (for the large model).  Fastgraph/Light
  1372.                     does not use extended libraries.
  1373.  
  1374.      For example, to compile the program 01-01.C under the medium memory
  1375. model and then link it with Fastgraph, you could use the following ZTC
  1376. command:
  1377.  
  1378.                       ZTC -mm 01-01.C FGM.LIB FGZCM.LIB
  1379.  
  1380. Although we specified the extended library name FGZCM.LIB on the command
  1381. line, we didn't need to in this example because the program doesn't call any
  1382. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  1383. were using Fastgraph/Light instead of Fastgraph, the TCC command would be:
  1384.  
  1385.                            ZTC -mm 01-01.C FGLM.LIB
  1386.  
  1387. For more information about memory models or other compilation and linking
  1388. options, please refer to the manuals supplied with your Zortech C++ compiler.
  1389.                                                  Chapter 1:  Introduction   29
  1390.  
  1391.  
  1392. Fastgraph/Light Video Driver
  1393.  
  1394.      As mentioned earlier, running any program created with Fastgraph/Light
  1395. requires an external program called the Fastgraph/Light Video Driver.  The
  1396. video driver is a terminate and stay resident program (TSR) that provides an
  1397. interface between your program and Fastgraph.  Once loaded, the video driver
  1398. uses over 100,000 bytes of conventional memory.
  1399.  
  1400.      To load the video driver, enter the command FGDRIVER at the DOS command
  1401. prompt (assuming FGDRIVER.EXE is in the current directory, or the \FG
  1402. directory is in your DOS path specification).  The driver will display a
  1403. message indicating whether or not it loaded successfully.  After you load the
  1404. driver, just run a program created with Fastgraph/Light as you would any
  1405. other program.  If you try running a program that uses Fastgraph/Light
  1406. without first loading the video driver, the message "Fastgraph/Light video
  1407. driver not installed" will appear.
  1408.  
  1409.      You don't need to load the driver before running each program, just once
  1410. per system boot (in fact, the driver will display an "already loaded" message
  1411. if you try to load it more than once).  If you want to unload the video
  1412. driver, just enter FGDRIVER /U at the DOS command prompt.  The unload
  1413. operation will work completely only if the video driver was the last TSR
  1414. loaded.  If it wasn't the last TSR, the driver will still unload, but the
  1415. memory it uses will not be released back to DOS.
  1416. 30   Fastgraph User's Guide