home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
C++ Games Programming
/
CPPGAMES.ISO
/
fgl
/
fglight
/
manuals.arj
/
USER01.DOC
< prev
next >
Wrap
Text File
|
1995-02-06
|
77KB
|
1,587 lines
Fastgraph (tm)
User's Guide
Copyright (c) 1991-1995 by Ted Gruber Software, Inc.
All rights reserved. No part of this publication may be reproduced, stored in
a retrieval system, or transmitted by any means, electronic, mechanical,
photocopying, recording, or otherwise, without express written permission from
Ted Gruber Software. The software described in this publication is furnished
under a license agreement and may be used or copied only in accordance with
the terms of that agreement.
This publication and its associated software are sold without warranties,
either expressed or implied, regarding their merchantability or fitness for
any particular application or purpose. The information in this publication is
subject to change without notice and does not represent a commitment on the
part of Ted Gruber Software. In no event shall Ted Gruber Software be liable
for any loss of profit or any other commercial damage, including but not
limited to special, incidental, consequential, or other damages resulting from
the use of or the inability to use this product, even if Ted Gruber Software
has been notified of the possibility of such damages.
First Printing, August 1994
Fastgraph version 4.0
All brand and product names mentioned in this publication are trademarks or
registered trademarks of their respective holders.
T a b l e o f C o n t e n t s
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 1
What is Fastgraph? . . . . . . . . . . . . . . . . . . . . . . . . . 2
Fastgraph/Light . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Prerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . . 3
Supported Compilers . . . . . . . . . . . . . . . . . . . . . . . . 3
Real Mode, Protected Mode, and DOS Extenders . . . . . . . . . . . . 4
Memory Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Installing Fastgraph . . . . . . . . . . . . . . . . . . . . . . . . 6
The READ.ME File . . . . . . . . . . . . . . . . . . . . . . . . . . 7
The WHATS.NEW File . . . . . . . . . . . . . . . . . . . . . . . . . 7
Fastgraph Naming Conventions . . . . . . . . . . . . . . . . . . . . 7
Compilation and Linking . . . . . . . . . . . . . . . . . . . . . . 7
Borland C++ . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Borland Pascal . . . . . . . . . . . . . . . . . . . . . . . . 12
MetaWare High C/C++ . . . . . . . . . . . . . . . . . . . . . . 13
Microsoft BASIC Professional Development System . . . . . . . . 14
Microsoft C/C++ . . . . . . . . . . . . . . . . . . . . . . . . 15
Microsoft FORTRAN . . . . . . . . . . . . . . . . . . . . . . . 16
Microsoft FORTRAN PowerStation . . . . . . . . . . . . . . . . 17
Microsoft QuickBASIC . . . . . . . . . . . . . . . . . . . . . 18
Microsoft QuickC . . . . . . . . . . . . . . . . . . . . . . . 19
Microsoft Visual Basic for DOS . . . . . . . . . . . . . . . . 20
Microsoft Visual C++ . . . . . . . . . . . . . . . . . . . . . 21
Microsoft Visual C++ 32-bit Edition . . . . . . . . . . . . . . 22
Power C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Turbo C and Turbo C++ . . . . . . . . . . . . . . . . . . . . . 24
Turbo Pascal . . . . . . . . . . . . . . . . . . . . . . . . . 25
WATCOM C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . 26
WATCOM C32 for DOS . . . . . . . . . . . . . . . . . . . . . . 26
Zortech C++ . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Fastgraph/Light Video Driver . . . . . . . . . . . . . . . . . . . . 28
Chapter 2 PC and PS/2 Video Modes . . . . . . . . . . . . . . . . . . . 29
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
CGA Graphics Modes . . . . . . . . . . . . . . . . . . . . . . 33
Tandy 1000 and PCjr Graphics Modes . . . . . . . . . . . . . . 34
Hercules Graphics Modes . . . . . . . . . . . . . . . . . . . . 34
EGA Graphics Modes . . . . . . . . . . . . . . . . . . . . . . 35
VGA and MCGA Graphics Modes . . . . . . . . . . . . . . . . . . 36
Extended VGA (XVGA) Graphics Modes . . . . . . . . . . . . . . 37
SuperVGA (SVGA) Graphics Modes . . . . . . . . . . . . . . . . 38
Chapter 3 Initializing the Video Environment . . . . . . . . . . . . . . 41
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Establishing a Text Mode . . . . . . . . . . . . . . . . . . . . . . 42
43-line and 50-line Text Modes . . . . . . . . . . . . . . . . . . . 45
Establishing a Graphics Mode . . . . . . . . . . . . . . . . . . . . 46
SuperVGA Graphics Modes . . . . . . . . . . . . . . . . . . . . . . 50
Summary of Video Initialization Routines . . . . . . . . . . . . . . 55
iii
Chapter 4 Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . 57
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Character Space . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Screen Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Viewports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
World Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Conversion Routines . . . . . . . . . . . . . . . . . . . . . . . . 64
Summary of Coordinate Routines . . . . . . . . . . . . . . . . . . . 64
Chapter 5 The Use of Color . . . . . . . . . . . . . . . . . . . . . . . 67
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Color Text Modes . . . . . . . . . . . . . . . . . . . . . . . 68
Monochrome Text Mode . . . . . . . . . . . . . . . . . . . . . 69
Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
CGA Color Modes . . . . . . . . . . . . . . . . . . . . . . . . 70
CGA Two-Color Mode . . . . . . . . . . . . . . . . . . . . . . 72
Tandy and PCjr Modes . . . . . . . . . . . . . . . . . . . . . 73
Hercules Mode . . . . . . . . . . . . . . . . . . . . . . . . . 74
Hercules Low-Resolution Mode . . . . . . . . . . . . . . . . . 75
EGA 200-Line Modes . . . . . . . . . . . . . . . . . . . . . . 76
EGA Monochrome Mode . . . . . . . . . . . . . . . . . . . . . . 78
EGA Enhanced Mode . . . . . . . . . . . . . . . . . . . . . . . 79
VGA and MCGA Two-Color Mode . . . . . . . . . . . . . . . . . . 81
VGA/SVGA 16-Color Modes . . . . . . . . . . . . . . . . . . . . 83
256-Color Modes . . . . . . . . . . . . . . . . . . . . . . . . 83
Using Video DAC Registers in EGA Modes . . . . . . . . . . . . . . . 87
RGB Color Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 89
Defining All Palette Registers . . . . . . . . . . . . . . . . . . . 90
Virtual Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
A Multiple-Mode Example . . . . . . . . . . . . . . . . . . . . . . 92
Summary of Color-Related Routines . . . . . . . . . . . . . . . . . 94
Chapter 6 Graphics Fundamentals . . . . . . . . . . . . . . . . . . . . 97
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Clearing the Screen . . . . . . . . . . . . . . . . . . . . . . . . 98
Clipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
The Graphics Cursor . . . . . . . . . . . . . . . . . . . . . . . . 100
Solid Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Dashed Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Circles and Ellipses . . . . . . . . . . . . . . . . . . . . . . . . 107
Solid Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Unfilled Rectangles . . . . . . . . . . . . . . . . . . . . . . . . 110
Dithered Rectangles . . . . . . . . . . . . . . . . . . . . . . . . 112
Region Fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Summary of Fundamental Graphics Routines . . . . . . . . . . . . . . 121
Chapter 7 Character Display Routines . . . . . . . . . . . . . . . . . . 125
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Character Space . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Hardware Characters . . . . . . . . . . . . . . . . . . . . . . . . 127
Character Height . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Conversion Routines . . . . . . . . . . . . . . . . . . . . . . . . 137
Software Characters . . . . . . . . . . . . . . . . . . . . . . . . 138
iv
Bitmapped Characters . . . . . . . . . . . . . . . . . . . . . . . . 143
Summary of Character Display Routines . . . . . . . . . . . . . . . 144
Chapter 8 Video Pages and Virtual Buffers . . . . . . . . . . . . . . . 147
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Physical Pages and Virtual Pages . . . . . . . . . . . . . . . . . . 148
Pages With Special Meanings . . . . . . . . . . . . . . . . . . . . 150
Some Simple Examples . . . . . . . . . . . . . . . . . . . . . . . . 150
Text Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Obtaining Video Page Information . . . . . . . . . . . . . . . . . . 158
Considerations for Virtual Pages . . . . . . . . . . . . . . . . . . 159
Considerations for SuperVGA Pages . . . . . . . . . . . . . . . . . 160
Logical Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Extended Video Pages . . . . . . . . . . . . . . . . . . . . . . . . 163
Video Page Resizing . . . . . . . . . . . . . . . . . . . . . . . . 166
Preserving Video Page Contents Across Mode Switches . . . . . . . . 167
Controlling Page Allocation . . . . . . . . . . . . . . . . . . . . 169
Virtual Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Summary of Video Page and Virtual Buffer Routines . . . . . . . . . 180
Chapter 9 Image Files . . . . . . . . . . . . . . . . . . . . . . . . . 183
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
PCX Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
GIF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
FLI and FLC files . . . . . . . . . . . . . . . . . . . . . . . . . 192
Pixel Run Files . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Display Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Controlling the Image Buffer Size . . . . . . . . . . . . . . . . . 206
Summary of Image File Routines . . . . . . . . . . . . . . . . . . . 208
Chapter 10 Bitmapped Images . . . . . . . . . . . . . . . . . . . . . . 211
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Mode-Independent Bitmapped Images . . . . . . . . . . . . . . . . . 212
Mode-Specific Bitmapped Images . . . . . . . . . . . . . . . . . . . 217
Regular Images . . . . . . . . . . . . . . . . . . . . . . . . 217
Clipped Images . . . . . . . . . . . . . . . . . . . . . . . . 225
Reversed Images . . . . . . . . . . . . . . . . . . . . . . . . 225
Reversed Clipped Images . . . . . . . . . . . . . . . . . . . . 226
Images Without Transparent Pixels . . . . . . . . . . . . . . . 226
Some Examples . . . . . . . . . . . . . . . . . . . . . . . . . 226
Retrieving Images . . . . . . . . . . . . . . . . . . . . . . . . . 229
Inverting Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . 234
Converting Mode-Specific Bitmaps . . . . . . . . . . . . . . . . . . 236
Bitmap Scaling and Shearing . . . . . . . . . . . . . . . . . . . . 239
Pixel Run Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Masking Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Summary of Bitmapped Image Display Routines . . . . . . . . . . . . 251
Chapter 11 Block Transfer Routines . . . . . . . . . . . . . . . . . . . 255
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Full Page Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 256
Byte Boundaries . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Dual SVGA Banks . . . . . . . . . . . . . . . . . . . . . . . . . . 259
The "Hidden" Video Page . . . . . . . . . . . . . . . . . . . . . . 259
Saving and Restoring Blocks . . . . . . . . . . . . . . . . . . . . 259
A More General Block Transfer Routine . . . . . . . . . . . . . . . 262
v
Block Transfer Routines for Virtual Buffers . . . . . . . . . . . . 266
Blocks with Transparent Colors . . . . . . . . . . . . . . . . . . . 267
Transparent Block Transfers for Virtual Buffers . . . . . . . . . . 269
Transferring Blocks to and from Conventional Memory . . . . . . . . 270
Summary of Block Transfer Routines . . . . . . . . . . . . . . . . . 271
Chapter 12 Animation Techniques . . . . . . . . . . . . . . . . . . . . 273
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Simple Animation . . . . . . . . . . . . . . . . . . . . . . . . . . 274
XOR Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Static Frame Animation . . . . . . . . . . . . . . . . . . . . . . . 278
Dynamic Frame Animation . . . . . . . . . . . . . . . . . . . . . . 280
Page Flipping . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
An Animation Example: The Fastgraph Fish Tank . . . . . . . . . . . 284
Summary of Animation Techniques . . . . . . . . . . . . . . . . . . 284
Chapter 13 Special Effects . . . . . . . . . . . . . . . . . . . . . . . 287
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Screen Dissolving . . . . . . . . . . . . . . . . . . . . . . . . . 288
Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Changing the Screen Origin . . . . . . . . . . . . . . . . . . . . . 293
Panning With Virtual Buffers . . . . . . . . . . . . . . . . . . . . 296
Split Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Summary of Special Effects Routines . . . . . . . . . . . . . . . . 300
Chapter 14 Input Device Support . . . . . . . . . . . . . . . . . . . . 301
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Keyboard Support . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Reading Keystrokes . . . . . . . . . . . . . . . . . . . . . . 304
Testing and Setting Key States . . . . . . . . . . . . . . . . 305
Low-Level Keyboard Handler . . . . . . . . . . . . . . . . . . 307
Mouse Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Initializing the Mouse . . . . . . . . . . . . . . . . . . . . 309
XVGA and SVGA Mouse Considerations . . . . . . . . . . . . . . 310
Controlling the Mouse Cursor . . . . . . . . . . . . . . . . . 311
Reporting the Mouse Status . . . . . . . . . . . . . . . . . . 313
Defining the Mouse Cursor . . . . . . . . . . . . . . . . . . . 315
Joystick Support . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Initializing Joysticks . . . . . . . . . . . . . . . . . . . . 323
Reporting Joystick Status . . . . . . . . . . . . . . . . . . . 324
Keyboard Emulation . . . . . . . . . . . . . . . . . . . . . . 325
Special Joystick Considerations . . . . . . . . . . . . . . . . 326
Summary of Input Routines . . . . . . . . . . . . . . . . . . . . . 326
Chapter 15 Sound Effects . . . . . . . . . . . . . . . . . . . . . . . . 329
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Sound Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Synchronous Sound . . . . . . . . . . . . . . . . . . . . . . . . . 330
Asynchronous Sound . . . . . . . . . . . . . . . . . . . . . . . . . 335
Summary of Sound Routines . . . . . . . . . . . . . . . . . . . . . 340
Chapter 16 Program Timing . . . . . . . . . . . . . . . . . . . . . . . 343
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Real-Time Routines . . . . . . . . . . . . . . . . . . . . . . . . . 344
Routines Dependent on the System Speed . . . . . . . . . . . . . . . 345
Summary of Timing Routines . . . . . . . . . . . . . . . . . . . . . 347
vi
Chapter 17 Miscellaneous Routines . . . . . . . . . . . . . . . . . . . 349
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Determining Available Memory . . . . . . . . . . . . . . . . . . . . 350
Choosing the Video Memory Update Function . . . . . . . . . . . . . 351
Controlling Vertical Retrace Synchronization . . . . . . . . . . . . 352
External SVGA Bank Switching . . . . . . . . . . . . . . . . . . . . 353
Saving and Restoring the Video State . . . . . . . . . . . . . . . . 353
Summary of Miscellaneous Routines . . . . . . . . . . . . . . . . . 354
Appendix A Fastgraph Utilities . . . . . . . . . . . . . . . . . . . . . 355
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
SNAPSHOT Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 356
CLIP Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
CONVERT Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 358
EDITSPR Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 359
GrabRGB Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 359
HERCFIX Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 360
PCXHEAD Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Appendix B Using Fastgraph from Assembly Language . . . . . . . . . . . 363
Appendix C Interrupts and Fastgraph . . . . . . . . . . . . . . . . . . 367
Interrupts Used by Fastgraph . . . . . . . . . . . . . . . . . . . . 368
Extending the Time-of-Day Interrupt . . . . . . . . . . . . . . . . 368
Appendix D Contents of the Compiler-Specific Libraries . . . . . . . . . 373
Appendix E Contents of the Pascal Unit Files . . . . . . . . . . . . . . 375
Appendix F Integrating Fastgraph With Other Graphics Software . . . . . 379
Appendix G Converting Programs to Protected Mode . . . . . . . . . . . . 381
Protected Mode Initialization . . . . . . . . . . . . . . . . . . . 382
Considerations for Logical Pages . . . . . . . . . . . . . . . . . . 382
Considerations for Virtual Buffers . . . . . . . . . . . . . . . . . 382
Mouse Cursor Definition . . . . . . . . . . . . . . . . . . . . . . 382
FORTRAN Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 383
Incompatible Real Mode Behavior . . . . . . . . . . . . . . . . . . 383
Appendix H Image File Header Formats . . . . . . . . . . . . . . . . . . 385
vii
viii
Chapter 1
Introduction
2 Fastgraph User's Guide
What is Fastgraph?
Fastgraph is a library of more than 275 highly-optimized routines that
are callable from high-level and assembly language programs running under the
MS-DOS or PC-DOS operating systems. This collection of routines provides a
programmer with proven, powerful tools to take command of the PC and PS/2
video environment. In addition to its video support, Fastgraph also includes
routines to perform keyboard, mouse, and joystick control, as well as music
and sound capabilities. Fastgraph is an ideal development tool for
entertainment and educational software, presentation graphics products,
scientific and engineering applications, CAD/CAM, animation, or any
application that demands robust graphics.
As its name implies, the most notable feature of Fastgraph is its speed.
Virtually all of Fastgraph is written in assembly language, and each routine
has been optimized by hand to provide maximum performance. Fastgraph's
protected mode libraries take advantage of the features offered by the 80286
and 80386 instruction sets.
Fastgraph supports all the standard text and graphics video modes used by
the IBM PC and compatible systems (PC, PC/XT, and PC/AT, 80386, 80486, and
Pentium) and IBM PS/2 family. In addition, Fastgraph provides support for six
SuperVGA (SVGA) graphics modes, four extended VGA (XVGA) graphics modes, and a
16-color graphics mode unique to Tandy 1000 series computers and the PCjr.
Even though the graphics mode of the Hercules Graphics Card is not an IBM
standard, its one-time popularity has made it a de facto standard, and for
this reason Fastgraph also supports it. In total, Fastgraph supports 23
graphics modes and 5 text modes. A complete discussion of these video modes
appears in the next chapter.
Fastgraph/Light
Fastgraph/Light is a subset of Fastgraph. It includes all of Fastgraph's
features except the GIF file support routines, redefinable world space
coordinate system, and the routines pertaining to software characters.
Programs created using Fastgraph/Light are 100% source code compatible with
Fastgraph.
The most important difference between Fastgraph/Light and Fastgraph is
the method of running a program created with the two products. With Fastgraph,
any of its routines used in your program are linked directly into the
resulting EXE file. With Fastgraph/Light, however, this is not the case.
Instead, the Fastgraph/Light routines provide an interface to an external
driver, called the Fastgraph/Light Video Driver, which must be loaded
separately before running programs that call any Fastgraph/Light routines. See
the last section of this chapter for more information.
Another important difference between Fastgraph and Fastgraph/Light is the
name of the library (LIB) files. All Fastgraph libraries begin with the two
characters FG, while the equivalent Fastgraph/Light libraries begin with the
three characters FGL. For example, FGS.LIB is the small model Fastgraph
library used with most C compilers, but FGLS.LIB is the equivalent
Fastgraph/Light library name. Note that the Pascal unit files always begin
with FG, whether you're using Fastgraph or Fastgraph/Light.
Chapter 1: Introduction 3
In the Fastgraph User's Guide and the accompanying Fastgraph Reference
Manual, references to Fastgraph also apply to Fastgraph/Light unless stated
otherwise.
Prerequisite Knowledge
Fastgraph is a programming tool, which means programmers are its intended
audience. For this reason, the Fastgraph User's Guide and Fastgraph Reference
Manual assume you have a knowledge of programming. Additionally, a knowledge
of converting numbers between binary, decimal, and hexadecimal is assumed.
Virtually all the examples in this manual are written in the C
programming language, so a knowledge of C would be especially helpful. The
examples intentionally avoid using any of C's features and idioms that might
not be readily apparent to a programmer unfamiliar with C. If you're
programming in real mode, don't be confused by the fact that all the examples
call Fastgraph's fg_initpm routine for protected mode initialization -- in
real mode, fg_initpm simply returns to the caller. Finally, we'd like to point
out that the examples should be read not by themselves, but as part of the
surrounding text.
Supported Compilers
You can use Fastgraph with any compilers or assemblers that use the same
calling and naming conventions as the small, medium, large, or flat memory
models of the supported compilers. Mixed language programming is allowed where
supported by the language translators, linker, and DOS extender being used.
Fastgraph supports the following compilers:
* Borland C++ (version 2.0 or later)
* Borland Pascal (version 7.0 or later)
* MetaWare High C/C++ (version 3.0 or later)
* Microsoft BASIC Professional Development System (version 7.0 or 7.1)
* Microsoft C/C++ (version 5.1 or later)
* Microsoft FORTRAN (version 4.0 or later)
* Microsoft FORTRAN PowerStation (version 1.0 or later)
* Microsoft QuickBASIC (version 4.0 or later)
* Microsoft QuickC (version 2.0 or later)
* Microsoft Visual Basic for DOS (version 1.0 or later)
* Microsoft Visual C++ (version 1.0 or later)
* Microsoft Visual C++ 32-bit Edition (version 1.0 or later)
* Power C (version 2.0 or later)
* Turbo C (version 2.0 or later)
* Turbo C++ (version 1.0 or later)
* Turbo Pascal (version 6.0 or later)
* WATCOM C/C++ (version 9.5 or later)
* WATCOM C32 for DOS (version 9.5 or later)
* Zortech C++ (version 3.0 or later)
The listed version numbers are the compiler versions under which Fastgraph was
developed and tested. Fastgraph may or may not work with earlier versions of
these compilers. As we constantly add support for new compilers, please check
the READ.ME file in the \FG directory for possible additions to the above
4 Fastgraph User's Guide
list. The use of Fastgraph from assembly language programs is addressed in
Appendix B.
Real Mode, Protected Mode, and DOS Extenders
DOS is inherently a real mode operating system. Real mode is the native
(and only) operating mode of the 8086 and 8088 microprocessors, upon which the
original IBM PC and PC/XT systems were based. While these processors provided
the ability to address one megabyte of memory, IBM reserved the upper 384K of
this one megabyte address space for such things as video memory and the ROM
BIOS. This left a maximum of 640K for DOS applications.
Intel's later microprocessors (80286, 80386, 80486, and Pentium) provide
a second operating mode called protected mode. Perhaps the most important
aspect of protected mode is its ability to use much more memory. When running
in protected mode, the 16-bit 80286 processor has a 16 megabyte
addressability, while the 32-bit 80386 and later processors can address four
gigabytes. Expanded and extended memory services provide limited access to
this larger address space, but a program must run in protected mode if it
wants to treat this memory like conventional DOS memory. Because DOS is a real
mode operating system, DOS applications running on 80286 and later processors
are still restricted to DOS's ubiquitous 640K barrier. In this case, these
systems function merely as faster 8086 or 8088 systems.
When a DOS-compatible protected mode operating system did not appear, DOS
extenders arrived instead. A DOS extender is a product, a "mini-operating
system" if you will, that can run protected mode applications under DOS. The
DOS extender accomplishes this by executing a real mode stub program that
switches the processor to protected mode and passes control to your program.
Your program continues to run in protected mode until it issues a DOS service
such as a file I/O request. The extender then switches back to real mode to
satisfy the request, and upon completion reverts to protected mode. When your
program terminates, the DOS extender switches back to real mode and returns
control to DOS. This is of course an oversimplification of how a DOS extender
works, but these behind the scenes tasks are transparent to your program's end
users. From their perspective, an extended DOS application executes just like
any ordinary DOS application.
DOS extenders come in two flavors: 16-bit and 32-bit. Programs written
for 16-bit DOS extenders require at least an 80286-based system, while those
written for 32-bit extenders require an 80386 or better. Many real mode
compilers can create 16-bit extended DOS applications, but you'll need special
32-bit compilers to create 32-bit extended DOS applications. Fastgraph
supports the following 16-bit DOS extenders:
* Borland Pascal 7 (built in DPMI extender)
* Borland PowerPack for DOS
* Phar Lap 286|Dos-Extender SDK
* Phar Lap 286|Dos-Extender Lite
* Rational Systems DOS/16M
Fastgraph supports the following 32-bit DOS extenders:
* Borland PowerPack for DOS
* DOSXMSF (supplied with Microsoft FORTRAN PowerStation)
Chapter 1: Introduction 5
* Phar Lap TNT Dos-Extender SDK (formerly 386|Dos-Extender SDK)
* Phar Lap TNT Dos-Extender Lite
* Rational Systems DOS/4G
* Rational Systems DOS/4GW (supplied with 32-bit WATCOM compilers)
* Rational Systems DOS/4GW Professional
Please check the READ.ME file in the \FG directory for possible additions to
the above lists.
Note that some DOS extenders require licensing fees or royalty payments
before you can include or bind their components with applications you
distribute. We recommend checking your DOS extender manuals or license
agreement for details, or if you're not sure, contacting the DOS extender
manufacturer directly.
Memory Models
Fastgraph's supported real mode C, C++, and FORTRAN compilers offer
several memory models. A memory model defines how memory is set up for a
program's code and data segments. Fastgraph includes real mode libraries for
the small, medium, and large memory models and protected mode libraries for
16-bit and 32-bit environments. The 16-bit protected mode libraries use an
extension of the large memory model, while the 32-bit libraries use a special
flat memory model.
The small memory model allows for one code segment and one data segment.
Programs that use the small model can thus have a maximum of 64K bytes of code
and 64K bytes of data. Because the small model implements call instructions
and data references through near pointers, it produces the most efficient code
of the three supported real mode memory models. The small memory model is
specific to real mode compilers.
The medium memory model allows for multiple code segments and one data
segment. Programs that use the medium model thus have no compiler-imposed
limit to the code size (although no one segment can exceed 64K bytes) and a
maximum of 64K bytes of data. Like the small model, the medium model
implements data references through near pointers, but it implements call
instructions through far pointers. The use of far pointers adds two bytes of
code and 13 clock cycles for each subprogram call. The medium model is a
popular choice for real mode programs and is specific to real mode compilers.
The large memory model supports multiple code and data segments. Programs
that use the large model do not have any compiler-imposed limits for code and
data sizes. However, no single code or data segment can exceed 64K bytes.
Because the large model implements call instructions and data references
through far pointers, it produces the least efficient code of the three
supported memory models. In real mode, the total size of all code and data
segments is limited by the DOS 640K barrier, though in reality the true limit
will be somewhat less depending on the target system's configuration and
resident programs. In 16-bit protected mode, the total size of all code and
data segments can reach 16 megabytes, although no one segment can exceed 64K
bytes.
The flat memory model allows for one code segment and one data segment,
just like the small memory model. The flat model differs in that the segment
6 Fastgraph User's Guide
sizes can be up to four gigabytes instead of 64K. By default, the flat model
implements call instructions and data references through 32-bit near pointers,
virtually eliminating the need for segments. The flat memory model is specific
to 32-bit protected mode compilers.
For more information about memory models, please refer to the user's
guide or reference manual supplied with your compiler.
Installing Fastgraph
This section explains how to use the INSTALL program to load Fastgraph
(or Fastgraph/Light) and its related files on a hard disk. The installation
program lets you select the compilers, memory models, and DOS extenders you
wish to use with Fastgraph. It also gives you the opportunity to load many
example Fastgraph programs specific to the compilers you choose.
Before you start the installation, we recommend using the DOS commands
COPY or DISKCOPY to make working copies of the Fastgraph distribution disks
(refer to your DOS reference manual if you are unfamiliar with these
commands). Once you have created the working copies, store the original disks
in a safe place. Install Fastgraph from the working copies you just created.
For simplicity, we'll assume you are installing Fastgraph from the
diskette drive A: to the hard drive C:, but you of course can use any
available drives. The Fastgraph distribution disk labeled Installation and
Utilities contains Fastgraph's INSTALL program. Place this disk in the A:
drive, make A: your current drive, and enter the command INSTALL, as shown
here:
C> A:
A> INSTALL
From this point, just follow the directions on each screen. At any time, you
can press the Escape key to abort the installation.
The INSTALL program will ask you for the compilers, memory models, and
DOS extenders you'll use with Fastgraph, as well as the directory names for
the Fastgraph utilities, libraries, and include files. For the utilities, the
default directory is C:\FG. For the include files and libraries, we recommend
using directories where the compiler you've chosen normally searches for such
files. INSTALL will automatically try to determine these directories and
propose them as defaults.
You can install support for additional compilers, memory models, or DOS
extenders at any time. If you choose to do this, you should use the command
INSTALL /L to avoid copying the files common to all environments.
The READ.ME File
The READ.ME file contains additions and changes that may have been made
to Fastgraph since the publication of the manuals. We encourage you to examine
the READ.ME file immediately after installing Fastgraph. READ.ME is an ASCII
text file, suitable for any printer or text editor. The INSTALL program places
the READ.ME file in the Fastgraph utilities directory (C:\FG by default).
Chapter 1: Introduction 7
The WHATS.NEW File
The WHATS.NEW file contains information about new features added in
Fastgraph version 4.0. Programmers who've used earlier versions of Fastgraph
may want to examine the WHATS.NEW file to learn about Fastgraph's new
functionality and possible changes needed when converting applications to
version 4.0. WHATS.NEW is an ASCII text file, suitable for any printer or text
editor. The INSTALL program places the WHATS.NEW file in the Fastgraph
utilities directory (C:\FG by default).
Fastgraph Naming Conventions
The names of all Fastgraph routines begin with the three characters
"fg_". This prefix helps identify Fastgraph routines within a program, and it
also reduces the chance of name conflicts that might otherwise occur between
Fastgraph and other third party libraries.
Because BASIC does not permit underscores in identifiers, the BASIC
versions of Fastgraph routines begin with the two characters "FG". For
example, the fg_version routine is named FGversion in the BASIC libraries. All
future references to Fastgraph routines in the Fastgraph User's Guide and the
Fastgraph Reference Manual will use the fg_ naming convention instead of the
BASIC names.
Compilation and Linking
To build an executable (EXE) file for a program that uses Fastgraph
routines, first compile or assemble the program using one of the supported
memory models. This step produces an object file, which you then link with one
or more Fastgraph libraries (or Pascal unit files) and possibly other
libraries to produce an executable file. When creating protected mode
executables, additional binding steps may be needed as described in your
compiler or DOS extender manuals. The Fastgraph libraries or Pascal unit files
must reside in a directory where the linker normally searches for such files.
Example 1-1 uses the Fastgraph routine fg_version to display the version
number for your copy of Fastgraph. It also uses one other Fastgraph routine,
fg_initpm, to set up Fastgraph's protected mode kernel for the selected DOS
extender (when using the real mode Fastgraph libraries, fg_initpm does
nothing). Versions of this program are presented for each high-level language
Fastgraph supports: C/C++, BASIC, FORTRAN, and Pascal. If you loaded the
example programs when you installed Fastgraph, the files \FG\EXAMPLES\01-01.C,
01-01.BAS, 01-01.FOR, and 01-01.PAS contain the source code for these
examples. You can use them to test the compilation and linking process for the
compilers you'll be using with Fastgraph.
Example 1-1 (C/C++ version).
#include <fastgraf.h>
#include <stdio.h>
void main(void);
8 Fastgraph User's Guide
void main()
{
int major;
int minor;
fg_initpm();
fg_version(&major,&minor);
printf("This is version %d.%2.2d of Fastgraph.\n",major,minor);
}
The header file FASTGRAF.H contains the C and C++ function prototypes for
each Fastgraph routine. It must reside in a directory where the compiler
normally searches for other header files. When creating 32-bit protected mode
applications, FASTGRAF.H will define the symbol FG32. This symbol is useful
for controlling conditional compilation when creating applications that run in
both 16-bit and 32-bit environments.
Example 1-1 (BASIC version).
REM $INCLUDE: 'fastgraf.bi'
DEFINT A-Z
FGversion Major, Minor
Version! = Major + Minor*0.01
PRINT USING "This is version #.## of Fastgraph."; Version!
END
You must include the DECLARE commands in the file FASTGRAF.BI at the
beginning of each BASIC module. This file should reside in a directory where
the compiler normally searches for BI files, or in any of the directories
specified by the INCLUDE environment variable. The DECLARE commands in this
file automatically provide the calling convention and naming convention for
each Fastgraph routine. In addition, they relieve the BASIC programmer of
distinguishing arguments passed by value from those passed by reference.
Example 1-1 (FORTRAN version).
$INCLUDE: '\FG\FASTGRAF.FI'
PROGRAM MAIN
INTEGER MAJOR
INTEGER MINOR
CALL FG_INITPM
CALL FG_VERSION (MAJOR, MINOR)
WRITE (6,10) MAJOR, MINOR
10 FORMAT (' This is version ', I1, '.', I2.2, ' of Fastgraph.')
STOP ' '
Chapter 1: Introduction 9
END
You must include the INTERFACE statements in the file FASTGRAF.FI at the
beginning of FORTRAN programs (this file should reside in the \FG directory).
The INTERFACE statements in this file automatically provide the calling
convention and naming convention for each Fastgraph routine. In addition, they
relieve the FORTRAN programmer of distinguishing arguments passed by value
from those passed by reference.
Example 1-1 (Pascal version).
program main;
uses fgmain;
var
Major : integer;
Minor : integer;
begin
fg_initpm;
fg_version(Major,Minor);
writeln('This is version ',Major,'.',Minor:2,' of Fastgraph.');
end.
Pascal programs that use Fastgraph or Fastgraph/Light must include a uses
statement specifying the names of the unit files (TPU or TPP files) needed in
the program. This list must always include the fgmain unit; for protected mode
programs that call GlobalAllocPtr, GlobalFreePtr, or other functions in
WinAPI, it also must include the WinAPI unit. All unit files must reside in a
directory where the compiler normally searches for such files. Appendix E
lists the Fastgraph functions in each unit.
The following sections show the simplest procedures for compiling a
program and linking it with Fastgraph. Information is presented for each
supported compiler, listed alphabetically by the compiler name. In what
follows, items enclosed in angle brackets, such as <source_file>, are
placeholders for parameters you must supply (the name of a file in this case).
Items enclosed in square brackets, such as [/E], are optional. For simplicity,
we'll only show the Fastgraph library names. If you're using Fastgraph/Light,
the library names will begin with "FGL" instead of "FG". For example, FGS.LIB
is the real mode small model Fastgraph for most C compilers, while FGLS.LIB is
the equivalent library for Fastgraph/Light. Note that Fastgraph/Light does not
support protected mode environments.
10 Fastgraph User's Guide
Borland C++
Borland C++ can create real mode, 16-bit protected mode, and 32-bit
protected mode applications (Borland C++ 4.0 or later is required for 32-bit
protected mode). You can compile and link programs directly from the DOS
command line or from the Borland C++ integrated development environment (IDE).
The following Fastgraph libraries are compatible with Borland C++:
FGS.LIB Real mode small model general library
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGTCS.LIB Real mode small model auxiliary library
FGTCM.LIB Real mode medium model auxiliary library
FGTCL.LIB Real mode large model auxiliary library
FG16.LIB 16-bit protected mode general library
FG16BC.LIB 16-bit protected mode auxiliary library
FG16DPMI.LIB 16-bit DPMI-compliant DOS extender support library
FG16PHAR.LIB Phar Lap 286|Dos-Extender support library
FG32.LIB 32-bit protected mode general library
FG32BC.LIB 32-bit protected mode auxiliary library
FG32DPMI.LIB 32-bit DPMI-compliant DOS extender support library
FG32PHAR.LIB Phar Lap TNT|Dos-Extender support library
To build real mode Fastgraph applications in the Borland C++ IDE, the
compiler options must match one of Fastgraph's available memory models (small,
medium, or large). 16-bit protected mode programs must use the large memory
model, while 32-bit protected mode programs must be compiled as console
applications. In any case, you also must create a project file that includes
the name of each C, CPP, and LIB file required by your application (refer to
your Borland C++ manuals for information about project files). For Borland C++
4.0 and above, the project file also specifies the platform: DOS for real mode
applications, DOS (16-bit DPMI) for 16-bit protected mode applications, or
DOS (32-bit DPMI) for 32-bit protected mode applications. Project files are
only needed when using the IDE.
You can also compile and link programs from the DOS command line using
the BCC or BCC32 commands. Here are example BCC and BCC32 commands for
compiling a Borland C++ program and linking it with Fastgraph. The compiler-
specific auxiliary library names only need to be included when your program
uses any of the Fastgraph routines listed in Appendix D.
Real mode, small memory model:
BCC -ms <source_file> FGS.LIB [FGTCS.LIB]
Real mode, medium memory model:
BCC -mm <source_file> FGM.LIB [FGTCM.LIB]
Real mode, large memory model:
BCC -ml <source_file> FGL.LIB [FGTCL.LIB]
16-bit protected mode, Borland PowerPack DOS extender:
BCC -ml -WX <source_file> FG16.LIB FG16DPMI.LIB [FG16BC.LIB]
16-bit protected mode, Phar Lap 286|Dos-Extender:
BCC286 <source_file> FG16.LIB FG16PHAR.LIB [FG16BC.LIB]
Chapter 1: Introduction 11
32-bit protected mode, Borland PowerPack DOS extender:
BCC32 -WX <source_file> FG32.LIB FG32DPMI.LIB [FG32BC.LIB]
To create Borland C++ 16-bit protected mode programs using the Rational
Systems DOS/16M extender, please refer to the DOS/16M User's Guide. To create
Borland C++ 32-bit protected mode programs using the Phar Lap
TNT|Dos-Extender, please refer to Phar Lap's C/C++ User's Guide to TNT
Dos-Extender.
For more information about memory models or other compilation and linking
options, please refer to the Borland C++ User's Guide, Borland PowerPack for
DOS User's Guide, Phar Lap's Borland C++ User's Guide to 286 Dos-Extender, or
the DOS/16M User's Guide.
12 Fastgraph User's Guide
Borland Pascal
Borland Pascal can create real mode and 16-bit protected mode
applications. Protected mode applications can be built without a third party
DOS extender, as the necessary protected mode extensions are implemented
through a DOS Protected Mode Interface (DPMI) server and a run-time manager.
You can compile real mode and protected mode programs directly from the DOS
command line or from the Borland Pascal integrated development environment
(IDE).
To build Fastgraph applications in the Borland Pascal IDE, just start the
IDE as you would for any other Pascal program, making sure the Fastgraph unit
files reside in one of the directories listed in the IDE's "Unit Directories"
option. If you're creating a protected mode application from the IDE, choose
Compile|Target and select "Protected-mode Application" from the Target
Platform dialog box.
You can also compile Borland Pascal programs from the DOS command line
using the BPC or TPC commands, as shown here. Real mode programs can use
either BPC or TPC, while protected mode programs must use BPC.
Real mode:
BPC <source_file>
TPC <source_file>
16-bit protected mode:
BPC /CP <source_file>
For more information about other compilation and linking options, please
refer to the Borland Pascal With Objects User's Guide.
All remaining example programs in the Fastgraph User's Guide are written
in the C programming language. However, when you install Fastgraph for Borland
Pascal, the installation procedure copies Pascal versions of the example
programs to the \FG\EXAMPLES directory.
Chapter 1: Introduction 13
MetaWare High C/C++
MetaWare High C/C++ is strictly a 32-bit protected mode compiler. It
supports the Phar Lap TNT|Dos-Extender SDK and the Rational Systems DOS/4G
extender. The following Fastgraph libraries are compatible with MetaWare High
C/C++:
FG32.LIB 32-bit protected mode general library
FG32HC.LIB 32-bit protected mode auxiliary library
FG32DPMI.LIB 32-bit DPMI-compliant DOS extender support library
FG32PHAR.LIB Phar Lap TNT|Dos-Extender support library
Programs are compiled and linked from the DOS command line using the
HC386 command. Here are example HC386 commands for compiling a MetaWare High
C/C++ program and linking it with Fastgraph. The compiler-specific auxiliary
library (FG32HC) only needs to be included when your program uses any of the
Fastgraph routines listed in Appendix D.
32-bit protected mode, Phar Lap TNT|Dos-Extender:
HC386 <source_file> -lFG32 -lFG32PHAR [-lFG32HC] -nomap -onecase
32-bit protected mode, Rational Systems DOS/4G extender:
HC386 <source_file> -Hdos4g -lFG32 -lFG32DPMI [-lFG32HC]
For more information about other compilation and linking options, please
refer to the MetaWare High C/C++ Programmer's Guide, Phar Lap's C/C++ User's
Guide to TNT Dos-Extender, or the DOS/4G User's Manual.
14 Fastgraph User's Guide
Microsoft BASIC Professional Development System
You can compile and link Microsoft BASIC Professional Development System
(PDS) programs directly from the DOS command line or from the PDS programming
environment. In either case, BASIC PDS always creates real mode programs. The
following Fastgraph libraries are compatible with BASIC PDS:
FGQBX.LIB Stand-alone library for BASIC PDS
FGQBX.QLB Quick library for BASIC PDS
To build Fastgraph applications in the PDS programming environment, just
specify the quick library name FGQBX when starting BASIC PDS:
QBX /LFGQBX [<source_file>]
You must use the default "Far Strings" setting within the PDS environment.
There are no near string Fastgraph libraries available for BASIC PDS.
To compile a BASIC PDS program from the DOS command line and link it with
Fastgraph, use the BC and LINK commands:
BC /Fs [/O] <source_file>;
LINK [/E] <object_file>,,NUL,FGQBX;
The /O option on the BC command is recommended because it creates EXE files
that do not require the BASIC PDS run-time module. The /E linker option is not
required but will produce a smaller EXE file if specified. For more
information about other compilation and linking options, please refer to the
Microsoft BASIC Professional Development System Programmer's Guide.
All remaining example programs in the Fastgraph User's Guide are written
in the C programming language. However, when you install Fastgraph for
Microsoft BASIC PDS, the installation procedure copies BASIC versions of the
example programs to the \FG\EXAMPLES directory.
Chapter 1: Introduction 15
Microsoft C/C++
Microsoft C/C++ can create real mode and 16-bit protected mode
applications. For protected mode, it supports the Phar Lap 286|Dos-Extender
(both SDK and Lite versions) and the Rational Systems DOS/16M extender. The
following Fastgraph libraries are compatible with Microsoft C/C++:
FGS.LIB Real mode small model general library
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGMSCS.LIB Real mode small model auxiliary library
FGMSCM.LIB Real mode medium model auxiliary library
FGMSCL.LIB Real mode large model auxiliary library
FG16.LIB 16-bit protected mode general library
FG16MSC.LIB 16-bit protected mode auxiliary library
FG16DPMI.LIB 16-bit DPMI-compliant DOS extender support library
FG16PHAR.LIB Phar Lap 286|Dos-Extender support library
Programs are compiled and linked from the DOS command line using the CL
command. Here are example CL commands for compiling a Microsoft C/C++ program
and linking it with Fastgraph. The compiler-specific auxiliary library names
only need to be included when your program uses any of the Fastgraph routines
listed in Appendix D. In the real mode examples, the /E linker option is not
required but will produce a smaller EXE file if specified.
Real mode, small memory model:
CL /AS <source_file> /link FGS.LIB [FGMSCS.LIB] [/E]
Real mode, medium memory model:
CL /AM <source_file> /link FGM.LIB [FGMSCM.LIB] [/E]
Real mode, large memory model:
CL /AL <source_file> /link FGL.LIB [FGMSCL.LIB] [/E]
16-bit protected mode, Phar Lap 286 SDK or Lite extender:
CL /AL /Lp <source_file> /link FG16.LIB FG16PHAR.LIB [FG16MSC.LIB]
To create Microsoft C/C++ protected mode programs using the Rational Systems
DOS/16M extender, please refer to the DOS/16M User's Guide.
For more information about memory models or other compilation and linking
options, please refer to the Microsoft C Optimizing Compiler User's Guide,
Phar Lap's Microsoft C & C++ User's Guide to 286|Dos-Extender, or the DOS/16M
User's Guide.
16 Fastgraph User's Guide
Microsoft FORTRAN
Microsoft FORTRAN creates real mode applications. The following Fastgraph
libraries are compatible with Microsoft FORTRAN:
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGMSFM.LIB Real mode medium model auxiliary library
FGMSFL.LIB Real mode large model auxiliary library
Programs are compiled and linked from the DOS command line using the FL
command. Here are example FL commands for compiling a Microsoft FORTRAN
program and linking it with Fastgraph. The compiler-specific auxiliary library
names only need to be included when your program uses any of the Fastgraph
routines listed in Appendix D. The /E linker option is not required but will
produce a smaller EXE file if specified.
Medium memory model:
FL /AM /FPi /4I2 /4Nt <source_file> /link FGM.LIB [FGMSFM.LIB] [/E]
Large memory model:
FL /AL /FPi /4I2 /4Nt <source_file> /link FGL.LIB [FGMSFL.LIB] [/E]
For more information about memory models or other compilation and linking
options, please refer to the Microsoft FORTRAN Optimizing Compiler User's
Guide.
All remaining example programs in the Fastgraph User's Guide are written
in the C programming language. However, when you install Fastgraph for the
Microsoft FORTRAN compiler, the installation procedure copies FORTRAN versions
of the example programs to the \FG\EXAMPLES directory.
Chapter 1: Introduction 17
Microsoft FORTRAN PowerStation
Microsoft FORTRAN PowerStation is strictly a 32-bit protected mode
compiler. It supports the DOSXMSF DOS extender included with the compiler and
the Phar Lap TNT|Dos-Extender SDK (DOSXMSF is a subset of the
TNT|Dos-Extender). The following Fastgraph library is compatible with
Microsoft FORTRAN PowerStation:
FG32MSF.LIB 32-bit PM library for Microsoft FORTRAN PowerStation
FG32MSF.LIB includes Fastgraph's Phar Lap support functions normally found in
the FG32PHAR.LIB library.
Programs are compiled and linked from the DOS command line using the FL32
command:
FL32 <source_file> FG32MSF.LIB
This command invokes the PowerStation compiler and Microsoft Portable
Executable Linker (LINK32) to create a 32-bit protected mode executable.
For more information about other compilation and linking options, please
refer to the Microsoft FORTRAN PowerStation User's Guide or Phar Lap's FORTRAN
User's Guide to TNT Dos-Extender.
18 Fastgraph User's Guide
Microsoft QuickBASIC
You can compile and link Microsoft QuickBASIC programs directly from the
DOS command line or from the QuickBASIC programming environment. In either
case, QuickBASIC always creates real mode programs. The following Fastgraph
libraries are compatible with QuickBASIC:
FGQB.LIB Stand-alone library for QuickBASIC
FGQB.QLB Quick library for QuickBASIC
To build Fastgraph applications in QuickBASIC's programming environment,
just specify the quick library name FGQB when starting QuickBASIC:
QB /LFGQB [<source_file>]
To compile a QuickBASIC program from the DOS command line and link it with
Fastgraph, use the BC and LINK commands:
BC [/O] <source_file>;
LINK [/E] <object_file>,,NUL,FGQB;
The /O option on the BC command is recommended because it creates EXE files
that do not require the QuickBASIC run-time module. The /E linker option is
not required but will produce a smaller EXE file if specified. For more
information about other compilation and linking options, please refer to the
Microsoft QuickBASIC: Programming in BASIC manual.
All remaining example programs in the Fastgraph User's Guide are written
in the C programming language. However, when you install Fastgraph for
Microsoft QuickBASIC, the installation procedure copies BASIC versions of the
example programs to the \FG\EXAMPLES directory.
Chapter 1: Introduction 19
Microsoft QuickC
You can compile and link Microsoft QuickC programs directly from the DOS
command line or from the QuickC programming environment. In either case,
QuickC always creates real mode programs. The following Fastgraph libraries
are compatible with QuickC:
FGS.LIB Real mode small model general library
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGMSCS.LIB Real mode small model auxiliary library
FGMSCM.LIB Real mode medium model auxiliary library
FGMSCL.LIB Real mode large model auxiliary library
To build Fastgraph applications in the QuickC programming environment,
you must make sure the compiler options match one of Fastgraph's available
memory models (small, medium, or large) and then create a make file that
includes the corresponding Fastgraph library names.
To compile a QuickC program from the DOS command line and link it with
Fastgraph, use the QCL command. Here are example QCL commands for compiling a
QuickC program and linking it with Fastgraph. The compiler-specific auxiliary
library names only need to be included when your program uses any of the
Fastgraph routines listed in Appendix D. The /E linker option is not required
but will produce a smaller EXE file if specified.
Small memory model:
QCL /AS <source_file> /link FGS.LIB [FGMSCS.LIB] [/E]
Medium memory model:
QCL /AM <source_file> /link FGM.LIB [FGMSCM.LIB] [/E]
Large memory model:
QCL /AL <source_file> /link FGL.LIB [FGMSCL.LIB] [/E]
For more information about make files, memory models, or other
compilation and linking options, please refer to the Microsoft QuickC Tool Kit
manual.
20 Fastgraph User's Guide
Microsoft Visual Basic for DOS
You can compile and link Microsoft Visual Basic for DOS programs directly
from the DOS command line or from the Visual Basic programming environment. In
either case, Visual Basic always creates real mode programs. The following
Fastgraph libraries are compatible with Visual Basic:
FGVBDOS.LIB Stand-alone library for Visual Basic
FGVBDOS.QLB Quick library for Visual Basic
To build Fastgraph applications in Visual Basic's programming
environment, just specify the quick library name FGVBDOS when starting Visual
Basic:
VBDOS /LFGVBDOS [<source_file>]
When using the programming environment, you may get an "Out of Memory" or "Out
of String Space" error message when trying to build an EXE file or run an
application within the environment. Should this occur, you must specify the /S
option on the VBDOS command line to increase the amount of memory available to
your application. If you have EMS or XMS memory installed on your system, it's
also useful to specify the /E or /X options to make portions of the
programming environment resident in EMS or XMS. For more information about
these options, refer to Appendix B of the Microsoft Visual Basic Programmer's
Guide.
To compile a Visual Basic program from the DOS command line and link it
with Fastgraph, use the BC and LINK commands:
BC [/O] <source_file>;
LINK [/E] <object_file>,,NUL,FGVBDOS;
The /O option on the BC command is recommended because it creates EXE files
that do not require the Visual Basic run-time module. The /E linker option is
not required but will produce a smaller EXE file if specified. For more
information about other compilation and linking options, please refer to the
Microsoft Visual Basic Programmer's Guide.
When linking Visual Basic for DOS programs that call Fastgraph's world
space or software character routines (that is, any of the routines listed in
Appendix D), you may need to increase the number of segments available to the
linker. Use the /SEG:n option on the LINK command to do this. The default
value of n is 128 segments; usually a slightly larger value, such as 144, will
be enough.
All remaining example programs in the Fastgraph User's Guide are written
in the C programming language. However, when you install Fastgraph for Visual
Basic, the installation procedure copies BASIC versions of the example
programs to the \FG\EXAMPLES directory.
Chapter 1: Introduction 21
Microsoft Visual C++
Microsoft Visual C++ can create real mode and 16-bit protected mode
applications. For protected mode, it supports the Phar Lap 286|Dos-Extender
(both SDK and Lite versions) and the Rational Systems DOS/16M extender. The
following Fastgraph libraries are compatible with Visual C++:
FGS.LIB Real mode small model general library
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGMSCS.LIB Real mode small model auxiliary library
FGMSCM.LIB Real mode medium model auxiliary library
FGMSCL.LIB Real mode large model auxiliary library
FG16.LIB 16-bit protected mode general library
FG16MSC.LIB 16-bit protected mode auxiliary library
FG16DPMI.LIB 16-bit DPMI-compliant DOS extender support library
FG16PHAR.LIB Phar Lap 286|Dos-Extender support library
Programs are compiled and linked from the DOS command line using the CL
command. Here are example CL commands for compiling a Visual C++ program and
linking it with Fastgraph. The compiler-specific auxiliary library names only
need to be included when your program uses any of the Fastgraph routines
listed in Appendix D. In the real mode examples, the /E linker option is not
required but will produce a smaller EXE file if specified.
Real mode, small memory model:
CL /AS <source_file> /link FGS.LIB [FGMSCS.LIB] [/E]
Real mode, medium memory model:
CL /AM <source_file> /link FGM.LIB [FGMSCM.LIB] [/E]
Real mode, large memory model:
CL /AL <source_file> /link FGL.LIB [FGMSCL.LIB] [/E]
16-bit protected mode, Phar Lap 286 SDK or Lite extender:
CL /AL /Lp <source_file> /link FG16.LIB FG16PHAR.LIB [FG16MSC.LIB]
To create Visual C++ protected mode programs using the Rational Systems
DOS/16M extender, please refer to the DOS/16M User's Guide.
For more information about memory models or other compilation and linking
options, please refer to the Visual C++ Command-Line Utilities User's Guide,
Phar Lap's Microsoft C & C++ User's Guide to 286|Dos-Extender, or the DOS/16M
User's Guide.
22 Fastgraph User's Guide
Microsoft Visual C++ 32-bit Edition
As its name suggests, Microsoft Visual C++ 32-bit Edition is strictly a
32-bit protected mode compiler. It supports the Phar Lap TNT|Dos-Extender SDK
and the Phar Lap TNT|Dos-Extender Lite. The following Fastgraph library is
compatible with the 32-bit Edition of Visual C++:
FG32VC.LIB 32-bit PM library for Microsoft Visual C++ 32-bit Edition
FG32VC.LIB includes Fastgraph's Phar Lap support functions normally found in
the FG32PHAR.LIB library.
There are two basic methods of creating 32-bit protected mode executables
with Visual C++ 32-bit Edition. The first method compiles and links the
program in a single command and uses the Microsoft 32-bit linker:
CL <source_file> /link /stub:\TNT\BIN\GOTNT.EXE FG32VC.LIB
The second method compiles and links the program in separate commands and uses
Phar Lap's 386|Link utility:
CL /c <source_file>
386LINK <obj_file> @MSVC32.DOS -lib FG32VC -nomap -onecase
The Phar Lap linker has problems with Fastgraph's world space routines. If
your program uses any of the Fastgraph routines listed in Appendix D, you
should use the Microsoft 32-bit linker.
For more information about other compilation and linking options, please
refer to Phar Lap's C/C++ User's Guide to TNT Dos-Extender.
Chapter 1: Introduction 23
Power C
Power C is an inexpensive real mode command-line compiler. The following
Fastgraph libraries are compatible with Power C:
FGS.MIX Small model general library
FGM.MIX Medium model general library
FGL.MIX Large model general library
FGPCS.MIX Small model auxiliary library
FGPCM.MIX Medium model auxiliary library
FGPCL.MIX Large model auxiliary library
To compile a Power C program from the DOS command line and link it with
Fastgraph, use the PC and PCL commands. Here are example command sequences for
compiling a Power C program and linking it with Fastgraph. The compiler-
specific auxiliary library names only need to be included when your program
uses any of the Fastgraph routines listed in Appendix D.
Small memory model:
PC /ms <source_file>
PCL <mix_file> ;FGS [;FGPCS]
Medium memory model:
PC /mm <source_file>
PCL <mix_file> ;FGM [;FGPCM]
Large memory model:
PC /ml <source_file>
PCL <mix_file> ;FGL [;FGPCL]
For more information about memory models or other compilation and linking
options, please refer to the Power C manual, published by Mix Software, Inc.
24 Fastgraph User's Guide
Turbo C and Turbo C++
Turbo C and Turbo C++ can create real mode and 16-bit protected mode
applications. For protected mode, only the Rational Systems DOS/16M extender
is supported. You can compile and link programs directly from the DOS command
line or from the Turbo C/C++ integrated development environment (IDE). The
following Fastgraph libraries are compatible with Turbo C/C++:
FGS.LIB Real mode small model general library
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGTCS.LIB Real mode small model auxiliary library
FGTCM.LIB Real mode medium model auxiliary library
FGTCL.LIB Real mode large model auxiliary library
FG16.LIB 16-bit protected mode general library
FG16BC.LIB 16-bit protected mode auxiliary library
FG16DPMI.LIB 16-bit DPMI-compliant DOS extender support library
To build Fastgraph applications in the Turbo C/C++ IDE, the compiler
options must match one of Fastgraph's available memory models (small, medium,
or large). You also must create a project file that includes the name of each
C, CPP, and LIB file required by your application (refer to your Turbo C or
Turbo C++ manuals for information about project files). Project files are only
needed when using the IDE.
You can also compile and link programs from the DOS command line using
the TCC command. Here are example TCC commands for compiling a Turbo C or
Turbo C++ program and linking it with Fastgraph. The compiler-specific
auxiliary library names only need to be included when your program uses any of
the Fastgraph routines listed in Appendix D.
Real mode, small memory model:
TCC -ms <source_file> FGS.LIB [FGTCS.LIB]
Real mode, medium memory model:
TCC -mm <source_file> FGM.LIB [FGTCM.LIB]
Real mode, large memory model:
TCC -ml <source_file> FGL.LIB [FGTCL.LIB]
To create Turbo C/C++ protected mode programs using the Rational Systems
DOS/16M extender, please refer to the DOS/16M User's Guide.
For more information about memory models or other compilation and linking
options, please refer to the Turbo C User's Guide, Turbo C Reference Guide, or
the DOS/16M User's Guide.
Chapter 1: Introduction 25
Turbo Pascal
Turbo Pascal can build real mode programs directly from the DOS command
line or from the Turbo Pascal integrated development environment (IDE).
To build Fastgraph applications in the Turbo Pascal IDE, just start the
IDE as you would for any other Pascal program, making sure the Fastgraph unit
files reside in one of the directories listed in the IDE's "Unit Directories"
option.
You also can compile Turbo Pascal programs from the DOS command line
using the TPC command, as shown here:
TPC <source_file>
For more information about other compilation and linking options, please refer
to the Turbo Pascal User's Guide.
All remaining example programs in the Fastgraph User's Guide are written
in the C programming language. However, when you install Fastgraph for Turbo
Pascal, the installation procedure copies Pascal versions of the example
programs to the \FG\EXAMPLES directory.
26 Fastgraph User's Guide
WATCOM C/C++
WATCOM C32 for DOS
WATCOM C/C++ and WATCOM C32 for DOS both are 16-bit real mode and 32-bit
protected mode compilers (for simplicity, we'll use the term WATCOM C/C++ to
refer to either compiler). Both compilers support the DOS/4G, DOS/4GW, and
DOS/4GW Professional DOS extenders from Rational Systems (DOS/4GW is supplied
with both compilers), as well as the Phar Lap TNT|Dos-Extender SDK. The
following Fastgraph libraries are compatible with the WATCOM compilers:
FGS.LIB Real mode small model general library
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGWCS.LIB Real mode small model auxiliary library
FGWCM.LIB Real mode medium model auxiliary library
FGWCL.LIB Real mode large model auxiliary library
FG32.LIB 32-bit protected mode general library
FG32WC.LIB 32-bit protected mode auxiliary library
FG32DPMI.LIB 32-bit DPMI-compliant DOS extender support library
FG32PHAR.LIB Phar Lap TNT|Dos-Extender support library
Programs are compiled and linked from the DOS command line using the WCL
or WCL386 commands. Here are example commands for compiling a WATCOM C/C++
program and linking it with Fastgraph. The compiler-specific auxiliary
libraries (FGWCS, FGWCM, FGWCL, and FG32WC) only need to be included when your
program uses any of the Fastgraph routines listed in Appendix D.
Real mode, small memory model:
WCL /ms <source_file> FGS.LIB [FGWCS.LIB]
Real mode, medium memory model:
WCL /mm <source_file> FGM.LIB [FGWCM.LIB]
Real mode, large memory model:
WCL /ml <source_file> FGL.LIB [FGWCL.LIB]
32-bit protected mode, any Rational Systems DOS/4G extender:
WCL386 /l=dos4g <source_file> FG32.LIB FG32DPMI.LIB [FG32WC.LIB]
32-bit protected mode, Phar Lap TNT|Dos-Extender:
WCL386 /l=pharlap <source_file> FG32.LIB FG32PHAR.LIB [FG32WC.LIB]
For more information about other compilation and linking options, please
refer to the WATCOM C/C++ User's Guide, Phar Lap's C/C++ User's Guide to TNT
Dos-Extender, or the DOS/4G User's Manual.
Chapter 1: Introduction 27
Zortech C++
Zortech C++ creates real mode applications. The following Fastgraph
libraries are compatible with Zortech C++:
FGS.LIB Real mode small model general library
FGM.LIB Real mode medium model general library
FGL.LIB Real mode large model general library
FGZCS.LIB Real mode small model auxiliary library
FGZCM.LIB Real mode medium model auxiliary library
FGZCL.LIB Real mode large model auxiliary library
Programs are compiled and linked from the DOS command line using the ZTC
command. Here are example ZTC commands for compiling a Zortech C++ program and
linking it with Fastgraph. The compiler-specific auxiliary library names only
need to be included when your program uses any of the Fastgraph routines
listed in Appendix D.
Small memory model:
ZTC -ms <source_file> FGS.LIB [FGZCS.LIB]
Medium memory model:
ZTC -mm <source_file> FGM.LIB [FGZCM.LIB]
Large memory model:
ZTC -ml <source_file> FGL.LIB [FGZCL.LIB]
For more information about memory models or other compilation and linking
options, please refer to the manuals supplied with your Zortech C++ compiler.
28 Fastgraph User's Guide
Fastgraph/Light Video Driver
As mentioned earlier, running any program created with Fastgraph/Light
requires an external program called the Fastgraph/Light Video Driver. The
video driver is a terminate and stay resident program (TSR) that provides an
interface between your program and Fastgraph.
To load the video driver, enter the command FGDRIVER at the DOS command
prompt (assuming FGDRIVER.EXE is in the current directory, or the \FG
directory is in your DOS path specification). The driver will display a
message indicating whether or not it loaded successfully. After you load the
driver, just run a program created with Fastgraph/Light as you would any other
program. If you try running a program that uses Fastgraph/Light without first
loading the video driver, the message "Fastgraph/Light video driver not
installed" will appear.
You don't need to load the driver before running each program, just once
per system boot (in fact, the driver will display an "already loaded" message
if you try to load it more than once). If you want to unload the video driver,
just enter FGDRIVER /U at the DOS command prompt. The unload operation will
work completely only if the video driver was the last TSR loaded. If it wasn't
the last TSR, the driver will still unload, but the memory it uses will not be
released back to DOS.