home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Devil's Doorknob BBS Capture (1996-2003)
/
devilsdoorknobbbscapture1996-2003.iso
/
Dloads
/
PROGRAMM
/
FGL112B.ZIP
/
REF.DOC
< prev
next >
Wrap
Text File
|
1992-10-05
|
213KB
|
11,504 lines
Fastgraph (tm)
Reference Manual
Ted Gruber Software
PO Box 13408
Las Vegas, NV 89112
(702) 735-1980
Copyright (c) 1991,1992 by Ted Gruber Software.
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.
Second Printing, January 1992
Fastgraph version 2.10
Fastgraph/Light version 1.10
Fastgraph and Fastgraph/Light are trademarks of Ted Gruber Software.
Hercules is a trademark of Hercules Computer Technology.
IBM, IBM PC, IBM PC/XT, IBM PC/AT, PS/2, PCjr, and PC-DOS are registered
trademarks of International Business Machines, Inc.
Intel is a registered trademark of Intel Corporation.
Microsoft and MS-DOS are registered trademarks of Microsoft Corporation.
QuickBASIC is a trademark of Microsoft Corporation.
Tandy is a registered trademark of Tandy Corporation.
Turbo Pascal is a registered trademark of Borland International, Inc.
All other 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
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Fastgraph Routines by Category . . . . . . . . . . . . . . . . . . . . . 1
Alphabetical List of Fastgraph Routines . . . . . . . . . . . . . . . . . 2
fg_allocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
fg_alloccms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
fg_allocems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
fg_allocxms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
fg_automode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
fg_bestmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
fg_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
fg_boxdepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
fg_button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
fg_capslock . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
fg_chgattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
fg_chgtext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
fg_circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
fg_circlew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
fg_clipmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
fg_clpimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
fg_clprect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
fg_clprectw . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
fg_copypage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
fg_cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
fg_dash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
fg_dashrel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
fg_dashrw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
fg_dashw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
fg_defcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
fg_dispfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
fg_display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
fg_displayp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
fg_disppcx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
fg_draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
fg_drawmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
fg_drawmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
fg_drawrel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
fg_drawrw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
fg_draww . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
fg_drect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
fg_drectw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
fg_drwimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
fg_egacheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
fg_ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
fg_ellipsew . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
fg_erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
fg_fadein . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
fg_fadeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
fg_flipmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
fg_flpimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
fg_freepage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
fg_getaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
fg_getattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
iii
fg_getchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
fg_getclock . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
fg_getcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
fg_getdacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
fg_gethpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
fg_getimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
fg_getindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
fg_getkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
fg_getlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
fg_getmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
fg_getmaxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
fg_getmaxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
fg_getmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
fg_getpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
fg_getpixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
fg_getrgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
fg_getvpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
fg_getworld . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
fg_getxjoy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
fg_getxpos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
fg_getyjoy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
fg_getypos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
fg_hush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
fg_hushnext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
fg_imagesiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
fg_initems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
fg_initjoy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
fg_initw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
fg_initxms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
fg_intjoy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
fg_intkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
fg_locate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
fg_makepcx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
fg_maprgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
fg_measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
fg_memavail . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
fg_mousebut . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
fg_mousecur . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
fg_mouseini . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
fg_mouselim . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
fg_mousemov . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
fg_mousepos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
fg_mouseptr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
fg_mousespd . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
fg_mousevis . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
fg_move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
fg_moverel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
fg_moverw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
fg_movew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
fg_music . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
fg_musicb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
fg_numlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
fg_paint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
fg_paintw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
fg_palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
fg_palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
fg_pan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
iv
fg_panw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
fg_pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
fg_playing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
fg_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
fg_pointw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
fg_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
fg_polygonw . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
fg_quiet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
fg_rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
fg_rectw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
fg_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
fg_resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
fg_restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
fg_restorew . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
fg_resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
fg_revimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
fg_revmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
fg_save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
fg_savew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
fg_scrlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
fg_scroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
fg_setangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
fg_setattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
fg_setcaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
fg_setclip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
fg_setclipw . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
fg_setcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
fg_setdacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
fg_setfunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
fg_sethpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
fg_setlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
fg_setmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
fg_setnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
fg_setpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
fg_setratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
fg_setrgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
fg_setsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
fg_setsizew . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
fg_setvpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
fg_setworld . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
fg_sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
fg_sounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
fg_stall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
fg_suspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
fg_swchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
fg_swlength . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
fg_swtext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
fg_tcmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
fg_tcxfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
fg_testmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
fg_text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
fg_transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
fg_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
fg_voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
fg_voices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
fg_waitfor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
fg_waitkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
v
fg_where . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
fg_xalpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
fg_xconvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
fg_xscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
fg_xworld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
fg_yalpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
fg_yconvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
fg_yscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
fg_yworld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
vi
Introduction
The Fastgraph Reference Manual is a companion publication to the
Fastgraph User's Guide. Whereas the latter publication is essentially a
detailed tutorial about Fastgraph, the Fastgraph Reference Manual is intended
as a reference for programmers familiar with the product.
This manual has two major parts. The first part lists the Fastgraph
routines by category; each category corresponds to a chapter in the Fastgraph
User's Guide. The second part, which occupies the larger portion of this
manual, gives descriptions of each Fastgraph routine in alphabetical order.
Fastgraph Routines by Category
This section lists the Fastgraph routines by category. These categories
parallel the chapters in the Fastgraph User's Guide. The lists in this
section are provided as a general overview of Fastgraph's capabilities. You
can find detailed information about each Fastgraph routine in the next
section of this manual, and of course in the Fastgraph User's Guide.
Video Initialization Routines: fg_automode, fg_bestmode, fg_cursor,
fg_egacheck, fg_getlines, fg_getmode, fg_reset, fg_setlines, fg_setmode,
fg_testmode.
Coordinate Routines: fg_getmaxx, fg_getmaxy, fg_getworld, fg_initw,
fg_setworld, fg_xalpha, fg_xconvert, fg_xscreen, fg_xworld, fg_yalpha,
fg_yconvert, fg_yscreen, fg_yworld.
Color-Related Routines: fg_defcolor, fg_getcolor, fg_getdacs, fg_getindex,
fg_getrgb, fg_maprgb, fg_palette, fg_palettes, fg_setattr, fg_setcolor,
fg_setdacs, fg_setrgb.
Fundamental Graphics Routines: fg_box, fg_boxdepth, fg_circle, fg_circlew,
fg_clprect, fg_clprectw, fg_dash, fg_dashrel, fg_dashrw, fg_dashw, fg_draw,
fg_drawrel, fg_drawrw, fg_draww, fg_drect, fg_drectw, fg_ellipse,
fg_ellipsew, fg_erase, fg_getpixel, fg_getxpos, fg_getypos, fg_move,
fg_moverel, fg_moverw, fg_movew, fg_paint, fg_paintw, fg_point, fg_pointw,
fg_polygon, fg_polygonw, fg_rect, fg_rectw, fg_setclip, fg_setclipw.
Character Display Routines: fg_chgattr, fg_chgtext, fg_getattr, fg_getchar,
fg_locate, fg_setangle, fg_setattr, fg_setcolor, fg_setratio, fg_setsize,
fg_setsizew, fg_swchar, fg_swlength, fg_swtext, fg_text, fg_where, fg_xalpha,
fg_xconvert, fg_yalpha, fg_yconvert.
Video Page Management Routines: fg_allocate, fg_alloccms, fg_allocems,
fg_allocxms, fg_copypage, fg_freepage, fg_getaddr, fg_gethpage, fg_getpage,
fg_getvpage, fg_initems, fg_initxms, fg_resize, fg_sethpage, fg_setpage,
fg_setvpage.
Image Management Routines: fg_clipmask, fg_clpimage, fg_copypage,
fg_dispfile, fg_display, fg_displayp, fg_disppcx, fg_drawmap, fg_drawmask,
fg_drwimage, fg_flipmask, fg_flpimage, fg_getimage, fg_getmap, fg_imagesiz,
fg_makepcx, fg_pattern, fg_restore, fg_restorew, fg_revimage, fg_revmask,
fg_save, fg_savew, fg_tcmask, fg_tcxfer, fg_transfer.
1
Special Effects Routines: fg_fadein, fg_fadeout, fg_pan, fg_panw, fg_resize,
fg_scroll.
Input Routines: fg_button, fg_capslock, fg_getkey, fg_getxjoy, fg_getyjoy,
fg_initjoy, fg_intjoy, fg_intkey, fg_mousebut, fg_mousecur, fg_mouseini,
fg_mouselim, fg_mousemov, fg_mousepos, fg_mouseptr, fg_mousespd, fg_mousevis,
fg_numlock, fg_scrlock, fg_setcaps, fg_setnum, fg_waitkey.
Sound Routines: fg_hush, fg_hushnext, fg_music, fg_musicb, fg_playing,
fg_quiet, fg_resume, fg_sound, fg_sounds, fg_suspend, fg_voice, fg_voices.
Timing Routines: fg_getclock, fg_measure, fg_stall, fg_waitfor.
Miscellaneous Routines: fg_memavail, fg_setfunc, fg_version.
Alphabetical List of Fastgraph Routines
This section presents a detailed description of each Fastgraph routine.
Once you're familiar with Fastgraph, you'll probably refer to these
descriptions more often than any other section of the two Fastgraph
publications.
The information presented for each routine includes the following:
function prototypes or declarations for each supported language
a description of the routine itself
the number of parameters, their purpose, and their data types
the meaning and data type of the routine's return value (if any)
information about important restrictions pertaining to the routine
references to similar routines, or other routines that affect the
routine
example programs in the Fastgraph User's Guide that use the routine
A prototype specifies the data types of a routine's parameters and
return value. The description of each Fastgraph routine includes prototypes
for C, QuickBASIC, FORTRAN, and Turbo Pascal (in that order). For example,
the prototypes for the fg_allocate routine are:
int fg_allocate (int page_number);
function FGallocate% (page_number%)
integer*2 function fg_allocate (integer*2 page_number)
function fg_allocate (page_number : integer) : integer;
The C, QuickBASIC, and Turbo Pascal prototypes use the declaration syntax for
those languages. FORTRAN does not use function prototypes, so we've created
our own prototype syntax for FORTRAN. In the FORTRAN prototypes, each
parameter is preceded by its data type. Furthermore, if the routine has a
return value, the prototype begins with the return value's data type and the
word function. If the routine has no return value, the prototype begins with
the word subroutine.
2
fg_allocate
Prototype
int fg_allocate (int page_number);
function FGallocate% (page_number%)
integer*2 function fg_allocate (integer*2 page_number)
function fg_allocate (page_number : integer) : integer;
Description
The fg_allocate routine creates a virtual video page. The amount of memory
required depends on the current video mode.
Parameters
page_number is the number by which the virtual page will be referenced. It
must be between 0 and 63.
Return value
A status code indicating the success or failure of the virtual page
creation, as shown below.
0 = virtual page created
1 = specified page is a physical or logical page
7 = virtual page created, but memory control blocks were destroyed
8 = insufficient memory to create the virtual page
Restrictions
This routine has no effect if page_number references a physical video page,
a logical video page, or if used in a video mode that does not support
virtual video pages.
See also
fg_freepage
Examples
8-3, 8-4, 8-5, 8-6, 8-8, 9-23, 9-24, 9-25, 10-4, 10-5, 11-2, 11-5, 15-1
3
fg_alloccms
Prototype
int fg_alloccms (int page_number);
function FGalloccms% (page_number%)
integer*2 function fg_alloccms (integer*2 page_number)
function fg_alloccms (page_number : integer) : integer;
Description
The fg_alloccms routine creates a logical page in conventional memory. The
amount of memory required depends on the current video mode and video
buffer dimensions.
Parameters
page_number is the number by which the logical page will be referenced. It
must be between 1 and 63.
Return value
0 = logical page created in conventional memory
-2 = invalid page number
-3 = page already created, or page exists as a physical or virtual page
-4 = insufficient expanded memory to create the page
Restrictions
This routine has no effect if page_number references a physical or virtual
video page.
The only function you can perform with logical pages is copying one entire
page to another (with fg_copypage).
See also
fg_allocems, fg_allocxms, fg_copypage, fg_freepage
Examples
8-9
4
fg_allocems
Prototype
int fg_allocems (int page_number);
function FGallocems% (page_number%)
integer*2 function fg_allocems (integer*2 page_number)
function fg_allocems (page_number : integer) : integer;
Description
The fg_allocems routine creates a logical page in expanded memory (EMS).
The amount of memory required depends on the current video mode and video
buffer dimensions.
Parameters
page_number is the number by which the logical page will be referenced. It
must be between 1 and 63.
Return value
0 = logical page created in expanded memory
-1 = Expanded Memory Manager not initialized
-2 = invalid page number
-3 = page already created, or page exists as a physical or virtual page
-4 = insufficient expanded memory to create the page
Restrictions
This routine has no effect if page_number references a physical or virtual
video page.
Before using this routine, you must use the fg_initems routine to
initialize the Expanded Memory Manager.
The only function you can perform with EMS logical pages is copying one
entire page to another (with fg_copypage).
See also
fg_alloccms, fg_allocxms, fg_copypage, fg_freepage, fg_initems
Examples
8-9
5
fg_allocxms
Prototype
int fg_allocxms (int page_number);
function FGallocxms% (page_number%)
integer*2 function fg_allocxms (integer*2 page_number)
function fg_allocxms (page_number : integer) : integer;
Description
The fg_allocxms routine creates a logical page in extended memory (XMS).
The amount of memory required depends on the current video mode and video
buffer dimensions.
Parameters
page_number is the number by which the logical page will be referenced. It
must be between 1 and 63.
Return value
0 = logical page created in extended memory
-1 = XMS driver not present
-2 = invalid page number
-3 = page already created, or page exists as a physical or virtual page
-4 = insufficient extended memory to create the page
Restrictions
This routine has no effect if page_number references a physical or virtual
video page.
Before using this routine, you must use the fg_initxms routine to
initialize the XMS driver.
The only function you can perform with XMS logical pages is copying one
entire page to another (with fg_copypage).
See also
fg_alloccms, fg_allocems, fg_copypage, fg_freepage, fg_initxms
Examples
8-9
6
fg_automode
Prototype
int fg_automode (void);
function FGautomode% ()
integer*2 function fg_automode ()
function fg_automode : integer;
Description
The fg_automode routine determines the graphics video mode that offers the
most features for the user's display and adapter configuration.
Parameters
none
Return value
The return value is the proposed video mode number. The current display
and adapter configuration determine the mode number, as illustrated in the
following table.
display
adapter mono RGB ECD VGA
MDA 7 0 7 7
HGC 11 0 0 11
CGA 0 4 0 0
EGA 15 13 16 0
VGA 17 17 17 18
MCGA 17 17 17 19
Tandy 7 9 0 0
PCjr 7 9 0 0
The return value can either be passed directly to the fg_setmode routine,
or it can help determine suitable video modes for your program.
Restrictions
none
See also
fg_bestmode, fg_setmode, fg_testmode
Examples
3-7, 4-3
7
fg_bestmode
Prototype
int fg_bestmode (int horizontal, int vertical, int pages);
function FGbestmode% (horizontal%, vertical%, pages%)
integer*2 function fg_bestmode (integer*2 horizontal, integer*2 vertical,
integer*2 pages)
function fg_bestmode (horizontal, vertical, pages : integer) : integer;
Description
The fg_bestmode routine determines the video mode having the requested
resolution and the most features for the user's display and adapter
configuration. It is similar to fg_automode, but it excludes video modes
that do not offer the specified resolution and video page requirements.
The video pages can include physical pages, virtual pages, or both.
Parameters
horizontal specifies the required horizontal resolution.
vertical specifies the required vertical resolution.
pages specifies the required number of video pages.
Return value
If fg_bestmode finds a video mode that offers the specified resolution and
video page requirements, it returns the corresponding video mode number.
If not, it returns -1.
Restrictions
none
See also
fg_automode, fg_setmode, fg_testmode
Examples
3-4, 3-8
8
fg_box
Prototype
void fg_box (int minx, int maxx, int miny, int maxy);
sub FGbox (minx%, maxx%, miny%, maxy%)
subroutine fg_box (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy)
procedure fg_box (minx, maxx, miny, maxy : integer);
Description
The fg_box routine draws an unfilled rectangle in screen space, with
respect to the clipping region. The width of the rectangle's edges is one
pixel unless changed with the fg_boxdepth routine.
Parameters
minx is the x coordinate of the rectangle's left edge.
maxx is the x coordinate of the rectangle's right edge. It must be greater
than or equal to the value of minx.
miny is the y coordinate of the rectangle's top edge.
maxy is the y coordinate of the rectangle's bottom edge. It must be
greater than or equal to the value of miny.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_boxdepth, fg_rect
Examples
6-11, 11-7
9
fg_boxdepth
Prototype
void fg_boxdepth (int xdepth, int ydepth);
sub FGboxdepth (xdepth%, ydepth%)
subroutine fg_boxdepth (integer*2 xdepth, integer*2 ydepth)
procedure fg_boxdepth (xdepth, ydepth : integer);
Description
The fg_boxdepth routine defines the depth of rectangles drawn with the
fg_box routine. The fg_setmode routine initializes the box depth to one
pixel in each direction.
Parameters
xdepth is the width in pixels of the rectangle's left and right sides. It
must be greater than zero.
ydepth is the height in pixels of the rectangle's top and bottom sides. It
must be greater than zero.
Return value
none
Restrictions
none
See also
fg_box
Examples
6-11
10
fg_button
Prototype
int fg_button (int n);
function FGbutton% (n%)
integer*2 function fg_button (integer*2 n)
function fg_button (n : integer) : integer;
Description
The fg_button routine returns information about the state of either
joystick's button status.
Parameters
n specifies the joystick number, either 1 or 2.
Return value
A status code indicating the current button status for the requested
joystick, as shown below.
0 = neither button pressed
1 = top button pressed
2 = bottom button pressed
3 = top and bottom buttons pressed
Restrictions
none
See also
fg_getxjoy, fg_getyjoy, fg_initjoy, fg_intjoy
Examples
12-11
11
fg_capslock
Prototype
int fg_capslock (void);
function FGcapslock% ()
integer*2 function fg_capslock ()
function fg_capslock : integer;
Description
The fg_capslock routine determines the state of the CapsLock key.
Parameters
none
Return value
If the return value is 0, it means the CapsLock key is off. If it is 1, it
means the CapsLock key is on.
Restrictions
none
See also
fg_numlock, fg_scrlock, fg_setcaps, fg_setnum
Examples
12-3
12
fg_chgattr
Prototype
void fg_chgattr (int n);
sub FGchgattr (n%)
subroutine fg_chgattr (integer*2 n)
procedure fg_chgattr (n: integer);
Description
The fg_chgattr routine applies the current text attribute to a given number
of characters, starting at the text cursor position. This routine leaves
the text cursor one column to the right of the last character changed (or
the first column of the next row if the last character is at the end of a
row).
Parameters
n is the number of characters for which to change the text attribute.
Return value
none
Restrictions
This routine has no effect in graphics video modes.
See also
fg_chgtext, fg_text
Examples
7-3
13
fg_chgtext
Prototype
void fg_chgtext (char *string, int n);
sub FGchgtext (string$, n%)
subroutine fg_chgtext (character*(*) string, integer*2 n)
procedure fg_chgtext (string : string; n : integer);
Description
The fg_chgtext routine displays a string of hardware characters, starting
at the text cursor position, using the existing text attributes. This
routine leaves the text cursor one column to the right of the last
character changed (or the first column of the next row if the last
character is at the end of a row).
Parameters
string is the arbitrary-length sequence of characters to display.
n is the number of characters in string.
Return value
none
Restrictions
This routine has no effect in graphics video modes.
See also
fg_chgattr, fg_text
Examples
7-3
14
fg_circle
Prototype
void fg_circle (int radius);
sub FGcircle (radius%)
subroutine fg_circle (integer*2 radius)
procedure fg_circle (radius : integer);
Description
The fg_circle routine draws an unfilled circle in screen space. The circle
is centered at the current graphics cursor position.
Parameters
radius defines the circle's radius in horizontal screen space units. Its
value must be greater than zero.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_circlew, fg_ellipse, fg_ellipsew
Examples
6-9
15
fg_circlew
Prototype
void fg_circlew (double radius);
sub FGcirclew (radius#)
subroutine fg_circlew (real*8 radius)
procedure fg_circlew (radius : real);
Description
The fg_circlew routine draws an unfilled circle in world space. The circle
is centered at the current graphics cursor position.
Parameters
radius defines the circle's radius in horizontal world space units. Its
value must be greater than zero.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_circle, fg_ellipse, fg_ellipsew
Examples
6-8
16
fg_clipmask
Prototype
void fg_clipmask (char *map_array, int runs, int width);
sub FGclipmask (map_array$, runs%, width%)
subroutine fg_clipmask (integer*1 map_array, integer*2 runs, integer*2
width)
procedure fg_clipmask (var map_array : byte; runs, width : integer);
Description
The fg_clipmask routine displays a clipped image stored as a masking map.
The image will be positioned so that its lower left corner is at the
graphics cursor position. Refer to the description of the fg_drawmask
routine for more information about masking maps.
Parameters
map_array is the arbitrary-length array containing the masking map.
runs is the number of pixel runs in the masking map.
width is the width in pixels of the masking map.
Return value
none
Restrictions
This routine has no effect in text video modes, or in the native EGA and
VGA graphics video modes.
See also
fg_drawmask, fg_flipmask, fg_revmask, fg_setclip
Examples
9-16
17
fg_clpimage
Prototype
void fg_clpimage (char *map_array, int width, int height);
sub FGclpimage (map_array$, width%, height%)
subroutine fg_clpimage (integer*1 map_array, integer*2 width, integer*2
height)
procedure fg_clpimage (var map_array : byte; width, height : integer);
Description
The fg_clpimage routine displays a clipped image stored as a mode-specific
bit map. The image will be positioned so that its lower left corner is at
the graphics cursor position. Only that part of the image that falls
within the current clipping limits will be displayed, but the clipping
limits will be extended to a byte boundary if necessary. Refer to the
Fastgraph User's Guide for complete information about mode-specific bit
maps.
Parameters
map_array is the arbitrary-length array containing the bit map.
width is the width in bytes of the bit map.
height is the height in bytes (pixel rows) of the bit map.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_drwimage, fg_flpimage, fg_getimage, fg_revimage, fg_setclip
Examples
9-8, 9-9
18
fg_clprect
Prototype
void fg_clprect (int minx, int maxx, int miny, int maxy);
sub FGclprect (minx%, maxx%, miny%, maxy%)
subroutine fg_clprect (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy)
procedure fg_clprect (minx, maxx, miny, maxy : integer);
Description
The fg_clprect routine draws a solid (filled) rectangle in screen space,
with respect to the clipping region.
Parameters
minx is the screen space x coordinate of the rectangle's left edge.
maxx is the screen space x coordinate of the rectangle's right edge. It
must be greater than or equal to the value of minx.
miny is the screen space y coordinate of the rectangle's top edge.
maxy is the screen space y coordinate of the rectangle's bottom edge. It
must be greater than or equal to the value of miny.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_clprectw, fg_rect, fg_rectw, fg_setclip
Examples
10-1, 10-2, 10-3, 10-4
19
fg_clprectw
Prototype
void fg_clprectw (double xmin, double xmax, double ymin, double ymax);
sub FGclprectw (xmin#, xmax#, ymin#, ymax#)
subroutine fg_clprectw (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax)
procedure fg_clprectw (xmin, xmax, ymin, ymax : real);
Description
The fg_clprectw routine draws a solid (filled) rectangle in world space,
with respect to the clipping region.
Parameters
xmin is the world space x coordinate of the rectangle's left edge.
xmax is the world space x coordinate of the rectangle's right edge. It
must be greater than or equal to the value of xmin.
ymin is the world space y coordinate of the rectangle's bottom edge.
ymax is the world space y coordinate of the rectangle's top edge. It must
be greater than or equal to the value of ymin.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_clprect, fg_rect, fg_rectw, fg_setclipw
20
fg_copypage
Prototype
void fg_copypage (int source_page, int dest_page);
sub FGcopypage (source_page%, dest_page%)
subroutine fg_copypage (integer*2 source_page, integer*2 dest_page)
procedure fg_copypage (source_page, dest_page : integer);
Description
The fg_copypage routine transfers the contents of one video page to
another. The pages may be physical, virtual, or logical video pages. The
call
fg_copypage(source,dest);
is equivalent to
fg_transfer(0,fg_getmaxx(),0,fg_getmaxy(),0,fg_getmaxx(),source,dest);
Parameters
source_page is the source video page number. It must be between 0 and 63.
dest_page is the destination video page number. It must be between 0 and
63.
Return value
none
Restrictions
If source_page and dest_page both reference logical pages, the pages must
exist in the same type of memory. For example, you cannot copy a logical
page in extended memory to a logical page in conventional memory.
See also
fg_alloccms, fg_allocems, fg_allocxms, fg_initems, fg_initxms, fg_transfer
Examples
8-9, 9-22
21
fg_cursor
Prototype
void fg_cursor (int state);
sub FGcursor (state%)
subroutine fg_cursor (integer*2 state)
procedure fg_cursor (state : integer);
Description
The fg_cursor routine determines the ROM BIOS cursor visibility in text
video modes. After calling fg_setmode, the cursor is made visible by
default.
Parameters
The state parameter defines the cursor visibility. If it is 0, the cursor
becomes invisible; if it is 1, the cursor becomes visible.
Return value
none
Restrictions
This routine has no effect in graphics video modes.
Examples
3-1, 3-2, 3-3, 3-4, 3-5, 5-16, 7-1, 7-2, 7-3, 8-3, 8-5, 8-7, 9-7, 9-21,
9-23, 9-25, 11-4
22
fg_dash
Prototype
void fg_dash (int ix, int iy, int pattern);
sub FGdash (ix%, iy%, pattern%)
subroutine fg_dash (integer*2 ix, integer*2 iy, integer*2 pattern)
procedure fg_dash (ix, iy, pattern : integer);
Description
The fg_dash routine draws a dashed line from the graphics cursor position
to an absolute screen space position. It also makes the destination
position the new graphics cursor position.
Parameters
ix is the screen space x coordinate of the destination position.
iy is the screen space y coordinate of the destination position.
pattern is a 16-bit value representing a cyclic dash pattern. Bits that
are 1 will result in a pixel being drawn; bits that are 0 will result in a
pixel being skipped.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_dashrel, fg_dashrw, fg_dashw, fg_move
Examples
6-6
23
fg_dashrel
Prototype
void fg_dashrel (int ix, int iy, int pattern);
sub FGdashrel (ix%, iy%, pattern%)
subroutine fg_dashrel (integer*2 ix, integer*2 iy, integer*2 pattern)
procedure fg_dashrel (ix, iy, pattern : integer);
Description
The fg_dash routine draws a dashed line from the graphics cursor position
to a screen space position relative to it. It also makes the destination
position the new graphics cursor position.
Parameters
ix is the screen space x offset of the destination position.
iy is the screen space y offset of the destination position.
pattern is a 16-bit value representing a cyclic dash pattern. Bits that
are 1 will result in a pixel being drawn; bits that are 0 will result in a
pixel being skipped.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_dash, fg_dashrw, fg_dashw, fg_moverel
24
fg_dashrw
Prototype
void fg_dashrw (double x, double y, int pattern);
sub FGdashrw (x#, y#, pattern%)
subroutine fg_dashrw (real*8 x, real*8 y, integer*2 pattern)
procedure fg_dashrw (x, y : real; pattern : integer);
Description
The fg_dashrw routine draws a dashed line from the graphics cursor position
to a world space position relative to it. It also makes the destination
position the new graphics cursor position.
Parameters
x is the world space x offset of the destination position.
y is the world space y offset of the destination position.
pattern is a 16-bit value representing a cyclic dash pattern. Bits that
are 1 will result in a pixel being drawn; bits that are 0 will result in a
pixel being skipped.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_dash, fg_dashrel, fg_dashw, fg_moverw
25
fg_dashw
Prototype
void fg_dashw (double x, double y, int pattern);
sub FGdashw (x#, y#, pattern%)
subroutine fg_dashw (real*8 x, real*8 y, integer*2 pattern)
procedure fg_dashw (x, y : real; pattern : integer);
Description
The fg_dashw routine draws a dashed line from the graphics cursor position
to an absolute world space position. It also makes the destination
position the new graphics cursor position.
Parameters
x is the world space x coordinate of the destination position.
y is the world space y coordinate of the destination position.
pattern is a 16-bit value representing a cyclic dash pattern. Bits that
are 1 will result in a pixel being drawn; bits that are 0 will result in a
pixel being skipped.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_dash, fg_dashrel, fg_dashrw, fg_movew
26
fg_defcolor
Prototype
void fg_defcolor (int index, int value);
sub FGdefcolor (index%, value%)
subroutine fg_defcolor (integer*2 index, integer*2 value)
procedure fg_defcolor (index, value : integer);
Description
The fg_defcolor routine assigns a color value to a virtual color index.
Parameters
index is the virtual color index to define, between 0 and 255.
value is the color value to assign to the specified color index. It must
be between 0 and the maximum color value for the current video mode.
Return value
none
Restrictions
This routine has no effect in text video modes or in 256-color graphics
video modes.
See also
fg_getindex, fg_palette, fg_setcolor
Examples
5-15, 5-16
27
fg_dispfile
Prototype
void fg_dispfile (char *filename, int width, int format);
sub FGdispfile (filename$, width%, format%)
subroutine fg_dispfile (character*(*) filename, integer*2 width, integer*2
format)
procedure fg_dispfile (filename : string; width, format : integer);
Description
The fg_dispfile routine displays an image stored in Fastgraph's standard or
packed pixel run format, where the image resides in an external file. The
image will be positioned so that its lower left corner is at the graphics
cursor position. Refer to the descriptions of the fg_display and
fg_displayp routines for more information about the two pixel run formats.
Parameters
filename is the name of the file that contains the image. A device and
path name may be included as part of the file name. The file name must be
terminated by a null character (that is, a zero byte).
width is the width of the image in pixels. It must be greater than zero.
format specifies the image format. The value of format must be 0 if the
image is in standard pixel run format, and 1 if the image is in packed
pixel run format.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_display, fg_displayp, fg_disppcx, fg_pattern
Examples
9-13, 9-14
28
fg_display
Prototype
void fg_display (char *map_array, int runs, int width);
sub FGdisplay (map_array$, runs%, width%)
subroutine fg_display (integer*1 map_array, integer*2 runs, integer*2
width)
procedure fg_display (var map_array : byte; runs, width : integer);
Description
The fg_display routine displays an image stored in Fastgraph's standard
pixel run format, where the image resides in an array. The image will be
positioned so that its lower left corner is at the graphics cursor
position.
Parameters
map_array is the arbitrary-length array containing the pixel run map. The
pixel runs are represented by (color,count) pairs, as shown below.
[0] color for run 1
[1] count for run 1
[2] color for run 2
[3] count for run 2
.
.
.
[2n-2] color for run n
[2n-1] count for run n
Each "color" element is a value between 0 and 255 specifying the color
index for that pixel run. Each "count" element is a value between 0 and
255 specifying the length in pixels of that pixel run.
runs is the number of pixel runs to display from the pixel run map. It is
normally 1/2 the size of the map_array array.
width is the width of the image in pixels. It must be greater than zero.
Return value
none
Restrictions
This routine has no effect in text video modes.
29
fg_display (continued)
See also
fg_dispfile, fg_displayp, fg_pattern
Examples
9-10, 9-12
30
fg_displayp
Prototype
void fg_displayp (char *map_array, int runs, int width);
sub FGdisplayp (map_array$, runs%, width%)
subroutine fg_displayp (integer*1 map_array, integer*2 runs, integer*2
width)
procedure fg_displayp (var map_array : byte; runs, width : integer);
Description
The fg_displayp routine displays an image stored in Fastgraph's packed
pixel run format, where the image resides in an array. The image will be
positioned so that its lower left corner is at the graphics cursor
position.
Parameters
map_array is the arbitrary-length array containing the pixel run map. The
pixel runs are represented by (color,count) pairs, as shown below.
7 4 3 0
[0] color for run 1 color for run 2
[1] count for run 1
[2] count for run 2
[3] color for run 3 color for run 4
[4] count for run 3
[5] count for run 4
.
.
.
[3n/2-3] color for run n-1 color for run n
[3n/2-2] count for run n-1
[3n/2-1] count for run n
Each "color" element is a value between 0 and 15 specifying the color index
for that pixel run. Each "count" element is a value between 0 and 255
specifying the length in pixels of that pixel run.
runs is the number of pixel runs to display from the pixel run map. It is
normally 2/3 the size of the map_array array.
width is the width of the image in pixels. It must be greater than zero.
31
fg_displayp (continued)
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_dispfile, fg_display, fg_pattern
Examples
9-11, 9-12
32
fg_disppcx
Prototype
int fg_disppcx (char *filename, int flags);
function FGdisppcx% (filename$, flags%)
integer*2 function fg_disppcx (character*(*) filename, integer*2 flags)
function fg_disppcx (filename : string; flags : integer) : integer;
Description
The fg_disppcx routine displays an image stored in a PCX file. The image
will be positioned so that its upper left corner is at the graphics cursor
position of the active video page.
Parameters
filename is the name of the PCX file. A device and path name may be
included as part of the file name. The file name must be terminated by a
null character (that is, a zero byte).
flags is a bit mask that controls how the image is displayed.
Bit 0
0 = use palette values stored in the PCX file
1 = use the current palette settings
Bits 1-15 are reserved for future use and should be zero.
Return value
0 = success
1 = file not found
2 = file is not a PCX file
Restrictions
PCX files are specific to certain video modes. The table below summarizes
the compatible video modes for PCX files.
If PCX file was You can display
created in mode it in these modes
4 or 5 4 or 5
6 or 11 6, 11, 13 to 18
9 9
13 to 18 13 to 18
19 19 to 23
Displaying a PCX file at a lower resolution (for example, a 640x480 PCX
file at 320x200) will truncate the display on the right and on the bottom.
This effectively displays the upper left corner of the PCX file. If you
attempt to display a PCX file in an incompatible video mode, fg_disppcx
will still display something, but it will be garbled.
The fg_disppcx routine has no effect in text video modes or in the Hercules
low-resolution graphics mode.
33
fg_disppcx (continued)
See also
fg_dispfile, fg_makepcx
Examples
9-15
34
fg_draw
Prototype
void fg_draw (int ix, int iy);
sub FGdraw (ix%, iy%)
subroutine fg_draw (integer*2 ix, integer*2 iy)
procedure fg_draw (ix, iy : integer);
Description
The fg_draw routine draws a solid line from the graphics cursor position to
an absolute screen space position. It also makes the destination position
the new graphics cursor position.
Parameters
ix is the screen space x coordinate of the destination position.
iy is the screen space y coordinate of the destination position.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_drawrel, fg_drawrw, fg_draww, fg_move
Examples
6-2, 6-5, 11-5, 11-6
35
fg_drawmap
Prototype
void fg_drawmap (char *map_array, int width, int height);
sub FGdrawmap (map_array$, width%, height%)
subroutine fg_drawmap (integer*1 map_array, integer*2 width, integer*2
height)
procedure fg_drawmap (var map_array : byte; width, height : integer);
Description
The fg_drawmap routine displays an image stored as a mode-independent bit
map. The image will be positioned so that its lower left corner is at the
graphics cursor position. Refer to the Fastgraph User's Guide for complete
information about mode-independent bit maps.
Parameters
map_array is the arbitrary-length array containing the bit map. Each byte
of map_array represents eight pixels. Bits that are set (1) result in the
corresponding pixel being displayed in the current color. Bits that are
reset (0) leave the corresponding pixel unchanged.
width is the width in bytes of the bit map.
height is the height in bytes (pixel rows) of the bit map.
Return value
none
Restrictions
none
See also
fg_drwimage, fg_getmap
Examples
9-1, 9-2, 9-18, 9-19
36
fg_drawmask
Prototype
void fg_drawmask (char *map_array, int runs, int width);
sub FGdrawmask (map_array$, runs%, width%)
subroutine fg_drawmask (integer*1 map_array, integer*2 runs, integer*2
width)
procedure fg_drawmask (var map_array : byte; runs, width : integer);
Description
The fg_drawmask routine displays an image stored as a masking map. The
image will be positioned so that its lower left corner is at the graphics
cursor position. Refer to the Fastgraph User's Guide for a complete
discussion of masking maps.
Parameters
map_array is the arbitrary-length array containing the masking map. The
masking map is a series of alternating "protect" and "zero" pixel runs, as
shown below.
[1] length of 1st protect run
[2] length of 1st zero run
[3] length of 2nd protect run
[4] length of 2nd zero run
.
.
.
[n-2] length of final protect run
[n-1] length of final zero run
The "protect" runs protect video memory, while the "zero" runs zero video
memory (that is, set the pixels to the background color). The length of
each run must be between 0 and 255.
runs is the number of pixel runs in the masking map.
width is the width in pixels of the masking map.
Return value
none
Restrictions
This routine has no effect in text video modes, or in the native EGA and
VGA graphics video modes.
37
fg_drawmask (continued)
See also
fg_clipmask, fg_flipmask, fg_revmask
Examples
9-16, 9-17
38
fg_drawrel
Prototype
void fg_drawrel (int ix, int iy);
sub FGdrawrel (ix%, iy%)
subroutine fg_drawrel (integer*2 ix, integer*2 iy)
procedure fg_drawrel (ix, iy : integer);
Description
The fg_drawrel routine draws a solid line from the graphics cursor position
to a screen space position relative to it. It also makes the destination
position the new graphics cursor position.
Parameters
ix is the screen space x offset of the destination position.
iy is the screen space y offset of the destination position.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_draw, fg_drawrw, fg_draww, fg_moverel
Examples
6-3, 6-15
39
fg_drawrw
Prototype
void fg_drawrw (double x, double y);
sub FGdrawrw (x#, y#)
subroutine fg_drawrw (real*8 x, real*8 y)
procedure fg_drawrw (x, y : real);
Description
The fg_drawrw routine draws a solid line from the graphics cursor position
to a world space position relative to it. It also makes the destination
position the new graphics cursor position.
Parameters
x is the world space x offset of the destination position.
y is the world space y offset of the destination position.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_draw, fg_drawrel, fg_draww, fg_moverw
40
fg_draww
Prototype
void fg_draww (double x, double y);
sub FGdraww (x#, y#)
subroutine fg_draww (real*8 x, real*8 y)
procedure fg_draww (x, y : real);
Description
The fg_draww routine draws a dashed line from the graphics cursor position
to an absolute world space position. It also makes the destination
position the new graphics cursor position.
Parameters
x is the world space x coordinate of the destination position.
y is the world space y coordinate of the destination position.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_draw, fg_drawrel, fg_drawrw, fg_movew
Examples
6-4
41
fg_drect
Prototype
void fg_drect (int minx, int maxx, int miny, int maxy, char *matrix);
sub FGdrect (minx%, maxx%, miny%, maxy%, matrix$)
subroutine fg_drect (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy,
integer*1 matrix)
procedure FGdrect (minx, maxx, miny, maxy : integer; var matrix : byte);
Description
The fg_drect routine draws a dithered rectangle in screen space, without
regard to the clipping region.
Parameters
minx is the screen space x coordinate of the rectangle's left edge.
maxx is the screen space x coordinate of the rectangle's right edge. It
must be greater than or equal to the value of minx.
miny is the screen space y coordinate of the rectangle's top edge.
maxy is the screen space y coordinate of the rectangle's bottom edge. It
must be greater than or equal to the value of miny.
matrix is a four-element array (an eight-element array in 256-color
graphics modes) that defines the dithering matrix. The format of the
dithering matrix is dependent on the video mode; refer to the Fastgraph
User's Guide for more information.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_drectw, fg_rect, fg_rectw
Examples
6-12, 6-13, 6-14
42
fg_drectw
Prototype
void fg_drectw (double xmin, double xmax, double ymin, double ymax, char
*matrix);
sub FGdrectw (xmin#, xmax#, ymin#, ymax#, matrix$)
subroutine fg_drectw (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax,
integer*1 matrix)
procedure fg_drectw (xmin, xmax, ymin, ymax : real; var matrix : byte);
Description
The fg_drectw routine draws a dithered rectangle in world space, without
regard to the clipping region.
Parameters
xmin is the world space x coordinate of the rectangle's left edge.
xmax is the world space x coordinate of the rectangle's right edge. It
must be greater than or equal to the value of xmin.
ymin is the world space y coordinate of the rectangle's bottom edge.
ymax is the world space y coordinate of the rectangle's top edge. It must
be greater than or equal to the value of ymin.
matrix is a four-element array (an eight-element array in 256-color
graphics modes) that defines the dithering matrix. The format of the
dithering matrix is dependent on the video mode; refer to the Fastgraph
User's Guide for more information.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_drect, fg_rect, fg_rectw
43
fg_drwimage
Prototype
void fg_drwimage (char *map_array, int width, int height);
sub FGdrwimage (map_array$, width%, height%)
subroutine fg_drwimage (integer*1 map_array, integer*2 width, integer*2
height)
procedure fg_drwimage (var map_array : byte; width, height : integer);
Description
The fg_drwimage routine displays an image stored as a mode-specific bit
map. The image will be positioned so that its lower left corner is at the
graphics cursor position (or the text cursor position in text video modes).
Refer to the Fastgraph User's Guide for complete information about mode-
specific bit maps.
Parameters
map_array is the arbitrary-length array containing the bit map.
width is the width in bytes of the bit map.
height is the height in bytes (pixel rows) of the bit map.
Return value
none
Restrictions
none
See also
fg_clpimage, fg_flpimage, fg_getimage, fg_revimage
Examples
9-3, 9-4, 9-5, 9-6, 9-7, 9-8, 9-9, 9-17, 9-20, 9-21
44
fg_egacheck
Prototype
int fg_egacheck (void);
function FGegacheck% ()
integer*2 function fg_egacheck ()
function fg_egacheck : integer;
Description
The fg_egacheck routine returns information about the active EGA adapter
and display (or the EGA emulation capabilities of a VGA). It is useful in
checking if the adapter has enough memory to run a program.
Parameters
none
Return value
The fg_egacheck routine returns a value of 0 if an EGA is not found, or if
an EGA without an Enhanced Color Display (ECD) is detected. Otherwise,
fg_egacheck returns a positive integer indicating the number of 64K-byte
increments of video memory on the EGA, as summarized below.
1 = EGA with 64K video memory
2 = EGA with 128K video memory
3 = EGA with 192K video memory
4 = EGA with 256K video memory
Restrictions
none
See also
fg_testmode
Examples
3-6, 15-2
45
fg_ellipse
Prototype
void fg_ellipse (int horiz, int vert);
sub FGellipse (horiz%, vert%)
subroutine fg_ellipse (integer*2 horiz, integer*2 vert)
procedure fg_ellipse (horiz, vert : integer);
Description
The fg_ellipse routine draws an unfilled ellipse in screen space. The
ellipse is centered at the current graphics cursor position, and its size
is determined by the specified lengths of its semi-axes.
Parameters
horiz defines the horizontal semi-axis of the ellipse (the absolute screen
space distance from the center of the ellipse to its horizontal extremity).
vert defines the vertical semi-axis of the ellipse (the absolute screen
space distance from the center of the ellipse to its vertical extremity).
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_circle, fg_circlew, fg_ellipsew
Examples
6-9, 10-4, 10-5
46
fg_ellipsew
Prototype
void fg_ellipsew (double horiz, double vert);
sub FGellipsew (horiz#, vert#)
subroutine fg_ellipsew (real*8 horiz, real*8 vert)
procedure fg_ellipsew (horiz, vert : real);
Description
The fg_ellipsew routine draws an unfilled ellipse in world space. The
ellipse is centered at the current graphics cursor position, and its size
is determined by the specified lengths of its semi-axes.
Parameters
horiz defines the horizontal semi-axis of the ellipse (the absolute world
space distance from the center of the ellipse to its horizontal extremity).
vert defines the vertical semi-axis of the ellipse (the absolute world
space distance from the center of the ellipse to its vertical extremity).
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_circle, fg_circlew, fg_ellipse
Examples
6-8
47
fg_erase
Prototype
void fg_erase (void);
sub FGerase ()
subroutine fg_erase ()
procedure fg_erase;
Description
The fg_erase routine clears the active video page. In text modes, fg_erase
stores a space character (ASCII 32) with a gray foreground attribute in
each character cell. In graphics modes, fg_erase sets each pixel to zero.
Parameters
none
Return value
none
Restrictions
none
See also
fg_reset
Examples
8-9, 8-10, 9-12, 9-13, 9-22
48
fg_fadein
Prototype
void fg_fadein (int delay);
sub FGfadein (delay%)
subroutine fg_fadein (integer*2 delay)
procedure fg_fadein (delay : integer);
Description
The fg_fadein routine replaces the visual page contents with the hidden
page contents. The replacement is done randomly in small sections, thus
giving a "fade in" effect.
Parameters
delay controls the speed at which the replacement takes place. A value of
zero means to perform the replacement as quickly as possible, while 1 is
slightly slower, 2 is slower yet, and so forth.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_fadeout, fg_sethpage
Examples
11-2
49
fg_fadeout
Prototype
void fg_fadeout (int delay);
sub FGfadeout (delay%)
subroutine fg_fadeout (integer*2 delay)
procedure fg_fadeout (delay : integer);
Description
The fg_fadeout routine replaces the visual page contents with pixels of the
current color. The replacement is done randomly in small sections, thus
giving a "fade out" effect.
Parameters
delay controls the speed at which the replacement takes place. A value of
zero means to perform the replacement as quickly as possible, while 1 is
slightly slower, 2 is slower yet, and so forth.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_fadein, fg_setcolor
Examples
11-1
50
fg_flipmask
Prototype
void fg_flipmask (char *map_array, int runs, int width);
sub FGflipmask (map_array$, runs%, width%)
subroutine fg_flipmask (integer*1 map_array, integer*2 runs, integer*2
width)
procedure fg_flipmask (var map_array : byte; runs, width : integer);
Description
The fg_flipmask routine displays a reversed clipped image stored as a
masking map. The image will be positioned so that its lower left corner is
at the graphics cursor position. Refer to the description of the
fg_drawmask routine for more information about masking maps.
Parameters
map_array is the arbitrary-length array containing the masking map.
runs is the number of pixel runs in the masking map.
width is the width in pixels of the masking map.
Return value
none
Restrictions
This routine has no effect in text video modes, or in the native EGA and
VGA graphics video modes.
See also
fg_clipmask, fg_drawmask, fg_revmask, fg_setclip
Examples
9-16
51
fg_flpimage
Prototype
void fg_flpimage (char *map_array, int width, int height);
sub FGflpimage (map_array$, width%, height%)
subroutine fg_flpimage (integer*1 map_array, integer*2 width, integer*2
height)
procedure fg_flpimage (var map_array : byte; width, height : integer);
Description
The fg_flpimage routine displays a reversed clipped image stored as a mode-
specific bit map. The image will be positioned so that its lower left
corner is at the graphics cursor position. Only that part of the image
that falls within the current clipping limits will be displayed, but the
clipping limits will be extended to a byte boundary if necessary. Refer to
the Fastgraph User's Guide for complete information about mode-specific bit
maps.
Parameters
map_array is the arbitrary-length array containing the bit map.
width is the width in bytes of the bit map.
height is the height in bytes (pixel rows) of the bit map.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_clpimage, fg_drwimage, fg_getimage, fg_revimage, fg_setclip
Examples
9-8, 9-9
52
fg_freepage
Prototype
int fg_freepage (int page_number);
function FGfreepage% (page_number%)
integer*2 function fg_freepage (integer*2 page_number)
function fg_freepage (page_number : integer) : integer;
Description
The fg_freepage routine releases a virtual or logical video page created
with the fg_allocate, fg_alloccms, fg_allocems, or fg_allocxms routines.
Parameters
page_number is the number of the virtual page to release. It must be
between 0 and 63.
Return value
A status code indicating the success or failure of the virtual page
release, as shown below.
0 = virtual page released
1 = specified page is a physical page
7 = virtual page released, but memory control blocks were destroyed
9 = attempt to use fg_freepage on a virtual or logical page that was
never created
Restrictions
This routine has no effect if page_number references a physical video page,
or a virtual page that was never created.
See also
fg_allocate, fg_alloccms, fg_allocems, fg_allocxms
Examples
8-3, 8-4, 8-5, 8-6, 8-8, 8-9, 9-22, 9-23, 9-24, 9-25, 10-4, 10-5, 11-2,
11-5, 15-1
53
fg_getaddr
Prototype
int fg_getaddr (void);
function FGgetaddr% ()
integer*2 function fg_getaddr ()
function fg_getaddr : integer;
Description
The fg_getaddr routine returns the segment address of the active video
page.
Parameters
none
Return value
The segment address of the active video page.
Restrictions
none
See also
fg_setpage
Examples
8-8
54
fg_getattr
Prototype
int fg_getattr (int row, int column);
function FGgetattr% (row%, column%)
integer*2 function fg_getattr (integer*2 row, integer*2 column)
function fg_getattr (row, column : integer) : integer;
Description
The fg_getattr routine returns the character attribute stored at the
specified position on the active video page.
Parameters
row is the row number of the character cell to examine, between 0 and 24
(unless you've called fg_setlines to increase the number of lines per
page).
column is the column number of the character cell to examine, between 0 and
39 for 40-column modes, or between 0 and 79 for 80-column modes.
Return value
The character attribute stored at the specified position.
Restrictions
This routine has no effect in graphics video modes.
See also
fg_getchar, fg_getimage
Examples
7-4
55
fg_getchar
Prototype
int fg_getchar (int row, int column);
function FGgetchar% (row%, column%)
integer*2 function fg_getchar (integer*2 row, integer*2 column)
function fg_getchar (row, column : integer) : integer;
Description
The fg_getchar routine returns the character value stored at the specified
position on the active video page.
Parameters
row is the row number of the character cell to examine, between 0 and 24
(unless you've called fg_setlines to increase the number of lines per
page).
column is the column number of the character cell to examine, between 0 and
39 for 40-column modes, or between 0 and 79 for 80-column modes.
Return value
The character value stored at the specified position.
Restrictions
This routine has no effect in graphics video modes.
See also
fg_getattr, fg_getimage
Examples
7-4
56
fg_getclock
Prototype
long fg_getclock (void);
function FGgetclock& ()
integer*4 function fg_getclock ()
function fg_getclock : longint;
Description
The fg_getclock routine returns the number of clock ticks since midnight.
Parameters
none
Return value
The number of clock ticks since midnight. There are approximately 18.2
clock ticks per second.
Restrictions
none
Examples
14-2
57
fg_getcolor
Prototype
int fg_getcolor (void);
function FGgetcolor% ()
integer*2 function fg_getcolor ()
function fg_getcolor : integer;
Description
The fg_getcolor routine returns the current text attribute (in text modes)
or color index (in graphics modes), as defined by the most recent call to
fg_setattr or fg_setcolor.
Parameters
none
Return value
In graphics video modes, the return value is the current color index. In
text modes, it is the current text attribute.
Restrictions
none
See also
fg_setattr, fg_setcolor
58
fg_getdacs
Prototype
void fg_getdacs (int start, int count, char *values);
sub FGgetdacs (start%, count%, values$)
subroutine fg_getdacs (integer*2 start, integer*2 count, integer*1 values)
procedure fg_getdacs (start, count : integer; var values : shortint);
Description
The fg_getdacs routine retrieves the red, green, and blue color components
of a contiguous block of video DAC registers. Each color component is a
value between 0 and 63; increasing values produce more intense colors.
Reading many DAC registers with fg_getdacs is considerably faster than
doing so individually with fg_getrgb.
Parameters
start is the starting video DAC register number, between 0 and 255.
count is the number of contiguous DAC registers to retrieve, between 1 and
256. If the sum of start and count exceeds 255, the register numbers wrap
around and resume with register number 0.
values is the array that will receive the color components. The first
three bytes of this array receive the red, green, and blue components for
DAC register start, the next three bytes receive the components for
register start+1, and so forth. The size of the values array must be at
least 3*count bytes.
Return value
none
Restrictions
This routine has no effect in text video modes, or in any graphics video
mode numbered 16 or below (because these video modes do not use DAC
registers).
See also
fg_getrgb, fg_setdacs, fg_setrgb
Examples
5-12
59
fg_gethpage
Prototype
int fg_gethpage (void);
function FGgethpage% ()
integer*2 function fg_gethpage ()
function fg_gethpage : integer;
Description
The fg_gethpage routine returns the hidden video page number (as set in the
most recent call to fg_sethpage).
Parameters
none
Return value
The number of the hidden video page, between 0 and 63.
Restrictions
none
See also
fg_sethpage
60
fg_getimage
Prototype
void fg_getimage (char *map_array, int width, int height);
sub FGgetimage (map_array$, width%, height%)
subroutine fg_getimage (integer*1 map_array, integer*2 width, integer*2
height)
procedure fg_getimage (var map_array : byte; width, height : integer);
Description
The fg_getimage routine retrieves an image as a mode-specific bit map. The
graphics cursor position (the text cursor position in text video modes)
defines the lower left corner of the image to retrieve. Refer to the
Fastgraph User's Guide for complete information about mode-specific bit
maps.
Parameters
map_array is the arbitrary-length array in which to retrieve the bit map.
width is the width in bytes of the bit map.
height is the height in bytes (pixel rows) of the bit map.
Return value
none
Restrictions
none
See also
fg_clpimage, fg_drwimage, fg_flpimage, fg_getmap, fg_revimage
Examples
9-20, 9-21
61
fg_getindex
Prototype
int fg_getindex (int index);
function FGgetindex% (index%)
integer*2 function fg_getindex (integer*2 index)
function fg_getindex (index : integer) : integer;
Description
The fg_getindex routine returns the color value assigned to a specified
virtual color index.
Parameters
index is the virtual color index to retrieve, between 0 and 255.
Return value
In graphics video modes with fewer than 256 available colors, the return
value is the color value assigned to the specified virtual index. In text
modes and 256-color graphics modes, the fg_getindex routine returns the
value passed to it.
Restrictions
none
See also
fg_defcolor, fg_palette, fg_setcolor
62
fg_getkey
Prototype
void fg_getkey (unsigned char *key, unsigned char *aux);
sub FGgetkey (key$, aux$)
subroutine fg_getkey (integer*1 key, integer*1 aux)
procedure fg_getkey (var key, aux : byte);
Description
The fg_getkey routine waits for a keystroke, or reads the next entry from
the BIOS keyboard buffer (without echo). It returns the keystroke's
standard or extended keyboard code (a list of these appears in Chapter 12
of the Fastgraph User's Guide).
Parameters
key receives the keystroke's standard keyboard code if it represents a
standard character. If the keystroke represents an extended character, key
will be set to zero. In QuickBASIC, you must explicitly declare key as a
fixed-length string variable of length 1.
aux receives the keystroke's extended keyboard code if it represents an
extended character. If the keystroke represents a standard character, aux
will be set to zero. In QuickBASIC, you must explicitly declare aux as a
fixed-length string variable of length 1.
Return value
none
Restrictions
none
See also
fg_intkey, fg_waitkey
Examples
12-1, 14-2
63
fg_getlines
Prototype
int fg_getlines (void);
function FGgetlines% ()
integer*2 function fg_getlines ()
function fg_getlines : integer;
Description
The fg_getlines routine returns the number of text rows per video page for
the current video mode.
Parameters
none
Return value
The number of text rows per video page for the current video mode.
Restrictions
none
See also
fg_setlines
Examples
3-5
64
fg_getmap
Prototype
void fg_getmap (char *map_array, int width, int height);
sub FGgetmap (map_array$, width%, height%)
subroutine fg_getmap (integer*1 map_array, integer*2 width, integer*2
height)
procedure fg_getmap (var map_array : byte; width, height : integer);
Description
The fg_getmap routine retrieves an image as a mode-independent bit map.
The graphics cursor position defines the lower left corner of the image to
retrieve. Refer to the Fastgraph User's Guide for complete information
about mode-independent bit maps.
Parameters
map_array is the arbitrary-length array in which to retrieve the bit map.
Each byte of map_array represents eight pixels. Pixels of the current
color set the corresponding bits in map_array. Pixels of other colors make
the corresponding map_array bits zero. In QuickBASIC, you must explicitly
declare map_array as a fixed-length string variable of length width*height.
width is the width in bytes of the bit map.
height is the height in bytes (pixel rows) of the bit map.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_drawmap, fg_getimage
Examples
9-18, 9-19
65
fg_getmaxx
Prototype
int fg_getmaxx (void);
function FGgetmaxx% ()
integer*2 function fg_getmaxx ()
function fg_getmaxx : integer;
Description
The fg_getmaxx routine returns the maximum x coordinate in screen space
when used in a graphics video mode. It returns the maximum column number
in character space when used in a text mode. In either case, the maximum x
coordinate is one less than the horizontal screen resolution.
Parameters
none
Return value
The maximum x coordinate.
Restrictions
none
See also
fg_getmaxy
Examples
4-1, 4-2
66
fg_getmaxy
Prototype
int fg_getmaxy (void);
function FGgetmaxy% ()
integer*2 function fg_getmaxy ()
function fg_getmaxy : integer;
Description
The fg_getmaxy routine returns the maximum y coordinate in screen space
when used in a graphics video mode. It returns the maximum row number in
character space when used in a text mode. In either case, the maximum y
coordinate is one less than the vertical screen resolution.
Parameters
none
Return value
The maximum y coordinate.
Restrictions
none
See also
fg_getmaxx
Examples
4-1, 4-2
67
fg_getmode
Prototype
int fg_getmode (void);
function FGgetmode% ()
integer*2 function fg_getmode ()
function fg_getmode : integer;
Description
The fg_getmode routine returns the current video mode number. It is
typically one of the first Fastgraph routines called in a program. The
value returned by fg_getmode can be retained to restore the original video
mode when a program transfers control back to DOS.
Parameters
none
Return value
The current video mode number, between 0 and 23. Refer to the description
of the fg_setmode routine for descriptions of each video mode.
Restrictions
none
See also
fg_setmode
Examples
3-3, 3-4, 3-5, 3-6, 3-7, 3-8, 3-9
68
fg_getpage
Prototype
int fg_getpage (void);
function FGgetpage% ()
integer*2 function fg_getpage ()
function fg_getpage : integer;
Description
The fg_getpage routine returns the active video page number (as set in the
most recent call to fg_setpage).
Parameters
none
Return value
The number of the active video page, between 0 and 63.
Restrictions
none
See also
fg_setpage
Examples
8-8
69
fg_getpixel
Prototype
int fg_getpixel (int ix, int iy);
function FGgetpixel% (ix%, iy%)
integer*2 function fg_getpixel (integer*2 ix, integer*2 iy)
function fg_getpixel (ix, iy : integer) : integer;
Description
The fg_getpixel routine returns the color value of a specified pixel.
Parameters
ix is the pixel's screen space x coordinate.
iy is the pixel's screen space y coordinate.
Return value
The color value of the pixel, between 0 and one less than the number of
colors available in the current video mode. In text modes, fg_getpixel
always returns zero.
Restrictions
none
See also
fg_point, fg_pointw
Examples
6-1
70
fg_getrgb
Prototype
void fg_getrgb (int number, int *red, int *green, int *blue);
sub FGgetrgb (number%, red%, green%, blue%)
subroutine fg_getrgb (integer*2 number, integer*2 red, integer*2 green,
integer*2 blue)
procedure fg_getrgb (number : integer; var red, green, blue : integer);
Description
The fg_getrgb routine returns the red, green, and blue color components for
a specified video DAC register. Each color component is a value between 0
and 63; increasing values produce more intense colors.
Parameters
number is the video DAC register number. It must be between 0 and 15 in
video modes 17 and 18, or between 0 and 255 in modes 19 through 23.
red, green, and blue respectively receive the red, green, and blue
components of the specified video DAC register.
Return value
none
Restrictions
This routine has no effect in text video modes, or in any graphics video
mode numbered 16 or below (because these video modes do not use DAC
registers).
See also
fg_getdacs, fg_palette, fg_setdacs, fg_setrgb
Examples
5-11
71
fg_getvpage
Prototype
int fg_getvpage (void);
function FGgetvpage% ()
integer*2 function fg_getvpage ()
function fg_getvpage : integer;
Description
The fg_getvpage routine returns the visual video page number (as set in the
most recent call to fg_setvpage).
Parameters
none
Return value
The number of the visual video page, between 0 and 63.
Restrictions
none
See also
fg_setvpage
Examples
8-8
72
fg_getworld
Prototype
void fg_getworld (double *xmin, double *xmax, double *ymin, double *ymax);
sub FGgetworld (xmin#, xmax#, ymin#, ymax#)
subroutine fg_getworld (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax)
procedure fg_getworld (var xmin, xmax, ymin, ymax : real);
Description
The fg_getworld routine returns the current world space limits, as defined
in the most recent call to fg_setworld.
Parameters
xmin receives the world space coordinate of the screen's left edge.
xmax receives the world space coordinate of the screen's right edge.
ymin receives the world space coordinate of the screen's top edge.
ymax receives the world space coordinate of the screen's bottom edge.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_setworld
Examples
4-3
73
fg_getxjoy
Prototype
int fg_getxjoy (int n);
function FGgetxjoy% (n%)
integer*2 function fg_getxjoy (integer*2 n)
function fg_getxjoy (n : integer) : integer;
Description
The fg_getxjoy routine returns the horizontal coordinate position of the
specified joystick. The actual coordinates depend on the processor speed
and brand of joystick used.
Parameters
n specifies the joystick number, either 1 or 2.
Return value
If the return value is positive, it represents the current horizontal
coordinate position of the requested joystick. If the return value is -1,
it means the requested joystick has not been initialized or is not present.
Restrictions
Before using this routine, you must use the fg_initjoy routine to
initialize the requested joystick.
See also
fg_button, fg_getyjoy, fg_initjoy, fg_intjoy
Examples
12-11
74
fg_getxpos
Prototype
int fg_getxpos (void);
function FGgetxpos% ()
integer*2 function fg_getxpos ()
function fg_getxpos : integer;
Description
The fg_getxpos routine returns the screen space x coordinate of the
graphics cursor position.
Parameters
none
Return value
The x coordinate of graphics cursor position.
Restrictions
none
See also
fg_getypos
75
fg_getyjoy
Prototype
int fg_getyjoy (int n);
function FGgetyjoy% (n%)
integer*2 function fg_getyjoy (integer*2 n)
function fg_getyjoy (n : integer) : integer;
Description
The fg_getyjoy routine returns the vertical coordinate position of the
specified joystick. The actual coordinates depend on the processor speed
and brand of joystick used.
Parameters
n specifies the joystick number, either 1 or 2.
Return value
If the return value is positive, it represents the current vertical
coordinate position of the requested joystick. If the return value is -1,
it means the requested joystick has not been initialized or is not present.
Restrictions
Before using this routine, you must use the fg_initjoy routine to
initialize the requested joystick.
See also
fg_button, fg_getxjoy, fg_initjoy, fg_intjoy
Examples
12-11
76
fg_getypos
Prototype
int fg_getypos (void);
function FGgetypos% ()
integer*2 function fg_getypos ()
function fg_getypos : integer;
Description
The fg_getypos routine returns the screen space y coordinate of the
graphics cursor position.
Parameters
none
Return value
The y coordinate of graphics cursor position.
Restrictions
none
See also
fg_getxpos
77
fg_hush
Prototype
void fg_hush (void);
sub FGhush ()
subroutine fg_hush ()
procedure fg_hush;
Description
The fg_hush routine immediately stops asynchronous sound started with the
fg_musicb, fg_sounds, or fg_voices routines. It has no effect if there is
no asynchronous sound in progress.
Parameters
none
Return value
none
Restrictions
none
See also
fg_hushnext, fg_musicb, fg_sounds, fg_suspend, fg_voices
Examples
13-7
78
fg_hushnext
Prototype
void fg_hushnext (void);
sub FGhushnext ()
subroutine fg_hushnext ()
procedure fg_hushnext;
Description
The fg_hushnext routine stops asynchronous sound started with the
fg_musicb, fg_sounds, or fg_voices routines, but not until the current
repetition finishes. It has no effect if there is no asynchronous sound in
progress.
Parameters
none
Return value
none
Restrictions
This routine has no effect unless the asynchronous sound is continuous.
See also
fg_hush, fg_musicb, fg_sounds, fg_suspend, fg_voices
Examples
13-7
79
fg_imagesiz
Prototype
long fg_imagesiz (int width, int height);
function FGimagesiz& (width%, height%)
integer*4 function fg_imagesiz (integer*2 width, integer*2 height)
function fg_imagesiz (width, height : integer) : longint;
Description
The fg_imagesiz routine determines the number of bytes required to store a
mode-specific bit-mapped image of specified dimensions.
Parameters
width specifies the image width in pixels.
height specifies the image height in pixels.
Return value
The number of bytes required to store a mode-specific bit-mapped image of
the specified size in the current video mode.
Restrictions
none
See also
fg_clpimage, fg_drwimage, fg_flpimage, fg_getimage, fg_revimage
Examples
9-20
80
fg_initems
Prototype
int fg_initems (void);
function FGinitems% ()
integer*2 function fg_initems ()
function fg_initems : integer;
Description
The fg_initems routine initializes expanded memory (EMS) for use with
Fastgraph.
Parameters
none
Return value
0 = success
-1 = Expanded Memory Manager not installed or not accessible
Restrictions
This routine requires an Expanded Memory Manager (EMM) that conforms to the
Lotus/Intel/Microsoft Expanded Memory Specification (LIM-EMS) version 3.2
or later. On 80386 and 80486 systems, the EMM386.EXE device driver
supplied with DOS 5.0 can be used to treat some or all of extended memory
as expanded memory.
The Expanded Memory Manager uses interrupt 67h. As a result, this vector
is not available for application programs.
See also
fg_allocems, fg_initxms
Examples
8-9
81
fg_initjoy
Prototype
int fg_initjoy (int n);
function FGinitjoy% (n%)
integer*2 function fg_initjoy (integer*2 n)
function fg_initjoy (n : integer) : integer;
Description
The fg_initjoy routine initializes either joystick and must be called
before using fg_getxjoy, fg_getyjoy, or fg_intjoy.
Parameters
n specifies the joystick number, either 1 or 2.
Return value
If the return value is 0, it means the joystick initialization was
successful. If it is -1, it means the machine has no game port, or the
requested joystick is not connected to the game port.
Restrictions
When you call fg_initjoy, Fastgraph assumes the requested joystick is
centered.
See also
fg_button, fg_getxjoy, fg_getyjoy, fg_intjoy
Examples
12-10, 12-11, 12-12
82
fg_initw
Prototype
void fg_initw (void);
sub FGinitw ()
subroutine fg_initw ()
procedure fg_initw;
Description
The fg_initw routine initializes Fastgraph's internal parameters for world
space. This routine must be called once, before any other routine that
uses world space coordinates.
Parameters
none
Return value
none
Restrictions
This routine is not available in Fastgraph/Light.
Examples
4-3, 6-4, 6-8, 7-8, 7-9, 7-10, 7-11
83
fg_initxms
Prototype
int fg_initxms (void);
function FGinitxms% ()
integer*2 function fg_initxms ()
function fg_initxms : integer;
Description
The fg_initxms routine initializes extended memory (XMS) for use with
Fastgraph.
Parameters
none
Return value
0 = success
-1 = XMS driver not installed or not accessible
Restrictions
This routine requires an external driver that conforms to the
Lotus/Intel/Microsoft/AST eXtended Memory Specification (XMS) version 2.0,
such as HIMEM.SYS. XMS drivers require an 80286, 80386, or 80486 system.
See also
fg_allocxms, fg_initems
Examples
8-9
84
fg_intjoy
Prototype
void fg_intjoy (int n, char *key, char *aux);
sub FGintjoy (n%, key$, aux$)
subroutine fg_intjoy (integer*2 n, integer*1 key, integer*1 aux)
procedure fg_intjoy (n : integer; var key, aux : byte);
Description
The fg_intjoy routine returns the standard and extended keyboard codes
analogous to the current position and button status of the specified
joystick.
Parameters
n specifies the joystick number, either 1 or 2.
key receives the joystick's button status. If any button on the requested
joystick is pressed, key is set to 13, the standard keyboard code for the
Enter key. If no buttons are pressed, key is set to zero. In QuickBASIC,
you must explicitly declare key as a fixed-length string variable of length
1.
aux receives the joystick's analog position, as listed below. In
QuickBASIC, you must explicitly declare aux as a fixed-length string
variable of length 1.
If the requested joystick has not been initialized, both key and aux will
be set to zero.
Return value
none
Restrictions
Before using this routine, you must use the fg_initjoy routine to
initialize the requested joystick.
See also
fg_button, fg_getxjoy, fg_getyjoy, fg_initjoy, fg_intkey
85
fg_intjoy (continued)
Examples
12-12
86
fg_intkey
Prototype
void fg_intkey (unsigned char *key, unsigned char *aux);
sub FGintkey (key$, aux$)
subroutine fg_intkey (integer*1 key, integer*1 aux)
procedure fg_intkey (var key, aux : byte);
Description
The fg_intkey routine reads the next entry from the BIOS keyboard buffer
(without echo) and returns the keystroke's standard or extended keyboard
code (a list of these appears in Chapter 12 of the Fastgraph User's Guide).
It is similar to fg_getkey, but it does not wait for a keystroke if the
keyboard buffer is empty.
Parameters
key receives the keystroke's standard keyboard code if it represents a
standard character. If the keystroke represents an extended character, key
will be set to zero. In QuickBASIC, you must explicitly declare key as a
fixed-length string variable of length 1.
aux receives the keystroke's extended keyboard code if it represents an
extended character. If the keystroke represents a standard character, aux
will be set to zero. In QuickBASIC, you must explicitly declare aux as a
fixed-length string variable of length 1.
If the BIOS keyboard buffer is empty, both key and aux will be set to zero.
Return value
none
Restrictions
none
See also
fg_getkey, fg_intjoy, fg_waitkey
Examples
12-2, 13-7, 14-1, 14-3
87
fg_locate
Prototype
void fg_locate (int row, int column);
sub FGlocate (row%, column%)
subroutine fg_locate (integer*2 row, integer*2 column)
procedure fg_locate (row, column : integer);
Description
The fg_locate routine changes the text cursor position for the active
display page. The fg_setmode routine sets each page's text cursor position
to (0,0).
Parameters
row is the text cursor's destination row number, between 0 and one less
than the number of character rows available.
column is text cursor's destination column number, between 0 and one less
than the number of character columns available.
Return value
none
Restrictions
The first eight video pages (0 to 7) each have their own text cursor. Each
subsequent group of 8 video pages (pages 8 through 15, pages 16 to 23, and
so forth) respectively share the same text cursor positions as the first 8
pages. For example, changing the text cursor position on video page 9 also
changes its position on video page 1.
See also
fg_where
Examples
7-1 to 7-8
88
fg_makepcx
Prototype
int fg_makepcx (int minx, int maxx, int miny, int maxy, char *filename);
function FGmakepcx% (minx%, maxx%, miny%, maxy%, filename$)
integer*2 function fg_makepcx (integer*2 minx, integer*2 maxx, integer*2
miny, integer*2 maxy,
character*(*) filename)
function fg_makepcx (minx, maxx, miny, maxy : integer; filename : string) :
integer;
Description
The fg_makepcx routine creates a PCX file from the specified rectangular
region of the active video page. The region's extremes are expressed in
screen space units.
Parameters
minx is the x coordinate of the region's left edge. Its value is reduced
to a byte boundary if necessary.
maxx is the x coordinate of the region's right edge. It must be greater
than or equal to minx.
miny is the y coordinate of the region's top edge.
maxy is the y coordinate of the region's bottom edge. It must be greater
than or equal to miny.
filename is the name of the PCX file to create. A device and path name may
be included as part of the file name. The file name must be terminated by
a null character (that is, a zero byte). If an identically named file
already exists, it is overwritten.
Return value
0 = success
1 = file not created
Restrictions
The fg_makepcx routine has no effect in text video modes or in the Hercules
low-resolution graphics mode. Refer to the description of the fg_disppcx
routine for information about PCX file compatibility between different
video modes.
In the Tandy/PCjr 16-color graphics mode (mode 9) and the native EGA
graphics modes (modes 13 through 16), the palette registers are not
readable. Hence, fg_makepcx will use the default palette settings when
used in these video modes.
See also
fg_disppcx
89
fg_makepcx (continued)
Examples
9-15
90
fg_maprgb
Prototype
int fg_maprgb (int red, int green, int blue);
function FGmaprgb% (red%, green%, blue%)
integer*2 function fg_maprgb (integer*2 red, integer*2 green, integer*2
blue)
function fg_maprgb (red, green, blue : integer) : integer;
Description
The fg_maprgb routine maps six-bit red, green, and blue color components
into a suitable palette value for the current video mode. You can then
pass this value to the fg_palette routine.
Parameters
red, green, and blue respectively specify the color's red, green, and blue
components. These values must be between 0 and 63; increasing values
produce more intense colors.
Return value
The mode-specific palette value for the specified color components.
Restrictions
This routine is meaningful only in 16-color graphics video modes.
See also
fg_palette, fg_palettes, fg_setrgb
Examples
5-13
91
fg_measure
Prototype
int fg_measure (void);
function FGmeasure% ()
integer*2 function fg_measure ()
function fg_measure : integer;
Description
The fg_measure routine returns the approximate number of delay units per
clock tick. This quantity is proportional to the system's processor speed.
Delay units are used by the fg_stall routine.
Parameters
none
Return value
The approximate number of delay units per clock tick. Typical values for
some common systems are:
system delay units
type per clock tick
Tandy 1000 HX 675
10 MHz 80286 3,000
25 MHz 80386 11,000
Restrictions
none
See also
fg_stall
Examples
14-3
92
fg_memavail
Prototype
long fg_memavail (void);
function FGmemavail& ()
integer*4 function fg_memavail ()
function fg_memavail : longint;
Description
The fg_memavail routine determines the amount of conventional memory
available to DOS.
Parameters
none
Return value
The amount of conventional memory (in bytes) available to DOS.
Restrictions
none
Examples
15-1
93
fg_mousebut
Prototype
void fg_mousebut (int number, int *count, int *lastx, int *lasty);
sub FGmousebut (number%, count%, lastx%, lasty%)
subroutine fg_mousebut (integer*2 number, integer*2 count, integer*2 lastx,
integer*2 lasty)
procedure fg_mousebut (number : integer; var count, lastx, lasty :
integer);
Description
The fg_mousebut routine returns information about mouse button press or
release counts, as well as the mouse cursor position at the time of the
last button press or release.
Parameters
number is the mouse button for which to report information (1 means the
left button, 2 the right button, and 3 the middle button). If number is
positive, button press counts will be reported. If it is negative, release
counts will be reported.
count receives the number of press or release counts for the requested
button since the last check, or since calling the fg_mouseini routine.
lastx receives the x coordinate (in screen space) of the mouse cursor
position at the time of the last press or release of the requested button.
If count is zero, lastx is also set to zero.
lasty receives the y coordinate (in screen space) of the mouse cursor
position at the time of the last press or release of the requested button.
If count is zero, lasty is also set to zero.
Return value
none
Restrictions
none
See also
fg_mousepos
Examples
12-7
94
fg_mousecur
Prototype
void fg_mousecur (int screen_mask, int cursor_mask);
sub FGmousecur (screen_mask%, cursor_mask%)
subroutine fg_mousecur (integer*2 screen_mask, integer*2 cursor_mask)
procedure fg_mousecur (screen_mask, cursor_mask : integer);
Description
The fg_mousecur routine defines the appearance of the mouse cursor in text
video modes. Refer to Chapter 12 of the Fastgraph User's Guide for
complete information about defining the mouse cursor in text modes.
Parameters
screen_mask defines the screen mask. When you position the mouse over a
specific character cell, the mouse driver logically ANDs the screen mask
with the existing contents of that cell.
cursor_mask defines the cursor mask. After logically ANDing the screen
mask with the contents of a character cell, the mouse driver XORs the
cursor mask with the result to produce the mouse cursor.
The binary structure of screen_mask and cursor_mask is:
bits meaning
0 to 7 ASCII character value
8 to 11 foreground color
12 to 14 background color
15 blink
Return value
none
Restrictions
This routine has no effect in graphics video modes.
See also
fg_mouseini, fg_mouseptr, fg_mousevis
Examples
12-8
95
fg_mouseini
Prototype
int fg_mouseini (void);
function FGmouseini% ()
integer*2 function fg_mouseini ()
function fg_mouseini : integer;
Description
The fg_mouseini routine initializes the mouse and must be called before any
of Fastgraph's other mouse support routines.
Parameters
none
Return value
If the return value is positive, it indicates the number of buttons on the
mouse being used (2 or 3). If the return value is -1, it means the
initialization failed because the mouse driver has not been loaded or the
mouse is not physically connected.
Restrictions
There is no mouse support available in video modes 20 through 23. The
fg_mouseini routine will always return -1 when used in these video modes.
See also
fg_mousebut, fg_mousecur, fg_mouselim, fg_mousemov, fg_mousepos,
fg_mouseptr, fg_mousespd, fg_mousevis, fg_resize
Examples
12-5, 12-6, 12-7, 12-8, 12-9
96
fg_mouselim
Prototype
void fg_mouselim (int minx, int maxx, int miny, int maxy);
sub FGmouselim (minx%, maxx%, miny%, maxy%)
subroutine fg_mouselim (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy)
procedure fg_mouselim (minx, maxx, miny, maxy : integer);
Description
The fg_mouselim routine defines the rectangular area in which the mouse
cursor may move. In graphics modes, the area is defined in screen space
coordinates. In text modes, it is defined in rows and columns.
Parameters
minx is the x coordinate of the area's left edge.
maxx is the x coordinate of the area's right edge. It must be greater than
or equal to the value of minx.
miny is the y coordinate of the area's top edge.
maxy is the y coordinate of the area's bottom edge. It must be greater
than or equal to the value of miny.
Return value
none
Restrictions
none
See also
fg_mouseini, fg_mousemov
Examples
12-6
97
fg_mousemov
Prototype
void fg_mousemov (int ix, int iy);
sub FGmousemov (ix%, iy%)
subroutine fg_mousemov (integer*2 ix, integer*2 iy)
procedure fg_mousemov (ix, iy : integer);
Description
The fg_mousemov routine moves the mouse cursor to the specified character
cell (in text modes) or screen space position (in graphics modes). The
mouse cursor is moved whether or not it is currently visible.
Parameters
ix is the x coordinate of the mouse cursor position.
iy is the y coordinate of the mouse cursor position.
Return value
none
Restrictions
If you attempt to move the mouse cursor outside the area defined by
fg_mouselim, the fg_mousemov routine just positions the cursor at the
nearest point possible within that area.
See also
fg_mouseini, fg_mouselim
Examples
12-6
98
fg_mousepos
Prototype
void fg_mousepos (int *ix, int *iy, int *buttons);
sub FGmousepos (ix%, iy%, buttons%)
subroutine fg_mousepos (integer*2 ix, integer*2 iy, integer*2 buttons)
procedure fg_mousepos (var ix, iy, buttons : integer);
Description
The fg_mousepos routine returns the current mouse position and button
status. In graphics modes, the position is defined in screen space
coordinates. In text modes, it is defined in rows and columns.
Parameters
ix receives the x coordinate of the mouse cursor position.
iy receives the y coordinate of the mouse cursor position.
buttons receives a bit mask representing the button status, where each bit
is set if the corresponding button is pressed. Bit 0 corresponds to the
left button, bit 1 to the right button, and bit 2 to the middle button.
Return value
none
Restrictions
none
See also
fg_mousebut, fg_mouseini
Examples
12-7
99
fg_mouseptr
Prototype
void fg_mouseptr (int *masks, int xoffset, int yoffset);
sub FGmouseptr (masks%(), xoffset%, yoffset%)
subroutine fg_mouseptr (integer*2 masks, integer*2 xoffset, integer*2
yoffset)
procedure fg_mouseptr (var masks : integer; xoffset, yoffset : integer);
Description
The fg_mouseptr routine defines the shape and appearance of the mouse
cursor in graphics video modes. Refer to Chapter 12 of the Fastgraph
User's Guide for complete information about defining the mouse cursor in
graphics modes.
Parameters
masks is a 32-element array containing the 16-element screen mask followed
by the 16-element cursor mask. The mouse driver displays the mouse cursor
by logically ANDing video memory with the screen mask, and then XORing that
result with the cursor mask. The first item of each mask corresponds to
the top row of the mouse cursor. The following table summarizes the cursor
appearance for all possible combinations of mask bits.
screen mask bit cursor mask bit resulting cursor pixel
0 0 black
0 1 white
1 0 unchanged
1 1 inverted
xoffset is the x coordinate of the "hot spot" relative to the upper left
corner of the mouse cursor.
yoffset is the y coordinate of the "hot spot" relative to the upper left
corner of the mouse cursor.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_mousecur, fg_mouseini, fg_mousevis
Examples
12-9
100
fg_mousespd
Prototype
void fg_mousespd (int xmickeys, int ymickeys);
sub FGmousespd (xmickeys%, ymickeys%)
subroutine fg_mousespd (integer*2 xmickeys, integer*2 ymickeys)
procedure fg_mousespd (xmickeys, ymickeys : integer);
Description
The fg_mousespd routine defines the number of mickey units per eight pixels
of cursor movement (one mickey unit equals 1/200 of an inch). This
effectively controls the speed at which the mouse cursor moves relative to
the movement of the mouse itself.
Parameters
xmickeys is the number of mickey units per eight pixels of horizontal mouse
cursor movement (the default is 8).
ymickeys is the number of mickey units per eight pixels of vertical mouse
cursor movement (the default is 16).
Return value
none
Restrictions
none
See also
fg_mouseini
Examples
12-6
101
fg_mousevis
Prototype
void fg_mousevis (int state);
sub FGmousevis (state%)
subroutine fg_mousevis (integer*2 state)
procedure fg_mousevis (state : integer);
Description
The fg_mousevis routine makes the mouse cursor visible or invisible. After
calling fg_mouseini, the mouse cursor is invisible.
Parameters
state defines the mouse cursor visibility. If state is 0, the mouse cursor
is made invisible. If it is 1, the mouse cursor is made visible.
Return value
none
Restrictions
none
See also
fg_mouseini
Examples
12-6, 12-7, 12-8, 12-9
102
fg_move
Prototype
void fg_move (int ix, int iy);
sub FGmove (ix%, iy%)
subroutine fg_move (integer*2 ix, integer*2 iy)
procedure fg_move (ix, iy : integer);
Description
The fg_move routine establishes the graphics cursor position at an absolute
screen space point. The fg_setmode routine sets the graphics cursor
position to (0,0).
Parameters
ix is the screen space x coordinate of the graphics cursor's new position.
iy is the screen space y coordinate of the graphics cursor's new position.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_moverel, fg_moverw, fg_movew
Examples
6-2, 6-3, 6-5, 6-6, 6-9, 6-15, 9-1
103
fg_moverel
Prototype
void fg_moverel (int ix, int iy);
sub FGmoverel (ix%, iy%)
subroutine fg_moverel (integer*2 ix, integer*2 iy)
procedure fg_moverel (ix, iy : integer);
Description
The fg_moverel routine establishes the graphics cursor position at a screen
space point relative to the current position.
Parameters
ix is the screen space x offset of the graphics cursor's new position.
iy is the screen space y offset of the graphics cursor's new position.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_move, fg_moverw, fg_movew
Examples
6-3
104
fg_moverw
Prototype
void fg_moverw (double x, double y);
sub FGmoverw (x#, y#)
subroutine fg_moverw (real*8 x, real*8 y)
procedure fg_moverw (x, y : real);
Description
The fg_moverw routine establishes the graphics cursor position at a world
space point relative to the current position.
Parameters
x is the world space x offset of the graphics cursor's new position.
y is the world space y offset of the graphics cursor's new position.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_move, fg_moverel, fg_movew
105
fg_movew
Prototype
void fg_movew (double x, double y);
sub FGmovew (x#, y#)
subroutine fg_movew (real*8 x, real*8 y)
procedure fg_movew (x, y : real);
Description
The fg_movew routine establishes the graphics cursor position at an
absolute world space point. The fg_initw routine sets the graphics cursor
position to (0.0,0.0).
Parameters
x is the world space x coordinate of the graphics cursor's new position.
y is the world space y coordinate of the graphics cursor's new position.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_move, fg_moverel, fg_moverw
Examples
6-4, 6-8, 7-8, 7-9, 7-10, 7-11
106
fg_music
Prototype
void fg_music (char *music_string);
sub FGmusic (music_string$)
subroutine fg_music (character*(*) music_string)
procedure fg_music (music_string : string);
Description
The fg_music routine uses the programmable timer to play a sequence of
musical tones.
Parameters
music_string is an arbitrary-length sequence of music commands, followed by
a dollar-sign ($) terminator. Music commands are summarized in the
following table:
commandmeaning
A thru G Play the specified note in the current octave.
# May be appended to a note character (A through G) to make that note
sharp.
. May be appended to a note character (A through G) or a sharp (#) to
extend that note by half its normal length. Multiple dots may be
used, and each will again extend the note by half as much as the
previous extension.
Ln Set the length of subsequent notes and pauses. The value of n is
an integer between 1 and 64, where 1 indicates a whole note, 2 a
half note, 4 a quarter note, and so forth. If no L command is
present, L4 is assumed.
On Set the octave for subsequent notes. The value of n may be an
integer between 0 and 6 to set a specific octave. It also can be a
plus (+) or minus (-) character to increment or decrement the
current octave number. Octave 4 contains middle C, and if no O
command is present, O4 is assumed.
P Pause (rest) for the duration specified by the most recent L
command.
Sn Set the amount of silence between notes. The value of n is an
integer between 0 and 2. If n is 0, each note plays for the full
period set by the L command (music legato). If n is 1, each note
plays for 7/8 the period set by the L command (music normal). If n
is 2, each note plays for 3/4 the period set by the L command
(music staccato). If no S command is present, S1 is assumed.
Tn Set the tempo of the music (the number of quarter notes per
minute). The value of n is an integer between 32 and 255. If no T
command is present, T120 is assumed.
107
fg_music (continued)
Parameters (continued)
The fg_music routine ignores any other characters in music_string. It also
ignores command values outside the allowable range, such as T20 or O8.
Return value
none
Restrictions
This routine has no effect if there is asynchronous sound in progress.
See also
fg_musicb
Examples
13-3
108
fg_musicb
Prototype
void fg_musicb (char *music_string, int ntimes);
sub FGmusicb (music_string$, ntimes%)
subroutine fg_musicb (character*(*) music_string, integer*2 ntimes)
procedure fg_musicb (music_string : string; ntimes : integer);
Description
The fg_musicb routine uses the programmable timer to play a sequence of
musical tones, concurrent with other activity.
Parameters
music_string is an arbitrary-length sequence of music commands, followed by
a dollar-sign ($) terminator. Refer to the description of the fg_music
routine for a complete list of music commands.
ntimes specifies the number of times to cycle through the music commands in
music_string. If ntimes is negative, the music will play repetitively
until you stop it with the fg_hush or fg_hushnext routine.
Return value
none
Restrictions
This routine has no effect if there is asynchronous sound already in
progress. To allow for fast-tempo music, Fastgraph temporarily quadruples
the clock tick interrupt rate from 18.2 to 72.8 ticks per second while
producing asynchronous sound. Because many disk controllers rely on the
18.2 tick per second clock rate to synchronize disk accesses, your programs
should not perform any disk operations when asynchronous sound is in
progress.
See also
fg_hush, fg_hushnext, fg_music, fg_playing, fg_resume, fg_suspend
Examples
13-6, 13-7, 13-8
109
fg_numlock
Prototype
int fg_numlock (void);
function FGnumlock% ()
integer*2 function fg_numlock ()
function fg_numlock : integer;
Description
The fg_numlock routine determines the state of the NumLock key.
Parameters
none
Return value
If the return value is 0, it means the NumLock key is off. If it is 1, it
means the NumLock key is on.
Restrictions
none
See also
fg_capslock, fg_scrlock, fg_setcaps, fg_setnum
Examples
12-3
110
fg_paint
Prototype
void fg_paint (int ix, int iy);
sub FGpaint (ix%, iy%)
subroutine fg_paint (integer*2 ix, integer*2 iy)
procedure fg_paint (ix, iy : integer);
Description
The fg_paint routine fills an arbitrary closed region with the current
color value. The region is defined by specifying a screen space point
within its interior.
Parameters
ix is the screen space x coordinate of the interior point.
iy is the screen space y coordinate of the interior point.
Return value
none
Restrictions
This routine has no effect in text video modes. The screen edges are not
considered region boundaries, and filling an open region will cause
fg_paint to behave unpredictably.
See also
fg_paintw
Examples
6-15, 11-5
111
fg_paintw
Prototype
void fg_paintw (double x, double y);
sub FGpaintw (x#, y#)
subroutine fg_paintw (real*8 x, real*8 y)
procedure fg_paintw (x, y : real);
Description
The fg_paintw routine fills an arbitrary closed region with the current
color value. The region is defined by specifying a world space point
within its interior.
Parameters
x is the world space x coordinate of the interior point.
y is the world space y coordinate of the interior point.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes. The screen edges are not considered region boundaries, and
filling an open region will cause fg_paintw to behave unpredictably.
See also
fg_paint
112
fg_palette
Prototype
void fg_palette (int number, int color);
sub FGpalette (number%, color%)
subroutine fg_palette (integer*2 number, integer*2 color)
procedure fg_palette (number, color : integer);
Description
The fg_palette routine has different functions depending on the current
graphics video mode. For CGA four-color modes (modes 4 and 5), it
establishes the current palette and defines the background color for that
palette. In the CGA two-color mode (mode 6), it defines the foreground
color. For Tandy/PCjr, EGA, and VGA graphics modes (modes 9, 13, 14, 15,
16, 17, and 18), it defines the value of a palette register. For 256-color
MCGA and VGA graphics modes (modes 19 through 23), it defines the value of
a video DAC register.
Parameters
The meanings of the number and color parameters depend on the current video
mode. The following table summarizes the parameter meanings and legal
values for each video mode.
mode number parameter (range) color parameter (range)
4,5 CGA palette number (0-5) background color (0-15)
6 ignored foreground color (0-15)
9 palette register number (0-15) palette value (0-15)
13,14 palette register number (0-15) palette value (0-23)
15 palette register number (0,1,4,5) palette value (0,8,24)
16 palette register number (0-15) palette value (0-63)
17 palette register number (0-1) video DAC register number (0-15)
18 palette register number (0-15) video DAC register number (0-15)
19-23 video DAC register number (0-255) DAC value (0-63)
Refer to Chapter 5 of the Fastgraph User's Guide for more specific
information about the number and color parameters.
Return value
none
Restrictions
This routine has no effect in text video modes or Hercules graphics modes.
Changing the foreground color (in mode 6) always works on true CGA
adapters, but there are very few EGA and VGA adapters that correctly
implement this capability in their mode 6 emulation.
See also
fg_defcolor, fg_maprgb, fg_palettes, fg_setcolor, fg_setdacs, fg_setrgb
113
fg_palette (continued)
Examples
5-1, 5-2, 5-3, 5-6, 5-7, 5-8, 5-9, 5-13, 5-16, 9-14
114
fg_palettes
Prototype
void fg_palettes (int *color_array);
sub FGpalettes (color_array%())
subroutine fg_palettes (integer*2 color_array)
procedure fg_palettes (var color_array : integer);
Description
The fg_palettes routine defines all 16 palette registers (in Tandy/PCjr,
EGA, and VGA graphics modes), or the first 16 video DAC registers (in 256-
color MCGA and VGA graphics modes).
Parameters
color_array is a 16-element array that contains the values to assign to the
palette registers or video DAC registers.
Return value
none
Restrictions
This routine has no effect in text video modes, CGA graphics modes, or
Hercules graphics modes.
See also
fg_maprgb, fg_palette, fg_setdacs
Examples
5-14
115
fg_pan
Prototype
void fg_pan (int ix, int iy);
sub FGpan (ix%, iy%)
subroutine fg_pan (integer*2 ix, integer*2 iy)
procedure fg_pan (ix, iy : integer);
Description
The fg_pan routine changes the screen origin (the upper left corner of the
screen) to the specified screen space coordinates.
Parameters
ix is the new screen space x coordinate for the screen origin.
iy is the new screen space y coordinate for the screen origin.
Return value
none
Restrictions
This routine has no effect in text video odes. Because of hardware
limitations, only certain coordinate positions can be used as the screen
origin. Fastgraph compensates for these restrictions by reducing ix and iy
to values that are acceptable to the current video mode, as shown in the
following table.
x will be reduced y will be reduced
video mode to a multiple of: to a multiple of:
4, 5 8 2
6 16 2
9 4 4
11 8 4
12 4 2 or 3
19 to 23 4 1
See also
fg_panw
Examples
11-6, 11-7
116
fg_panw
Prototype
void fg_panw (double x, double y);
sub FGpanw (x#, y#)
subroutine fg_panw (real*8 x, real*8 y)
procedure fg_panw (x, y : real);
Description
The fg_panw routine changes the screen origin (the upper left corner of the
screen) to the specified world space coordinates.
Parameters
x is the new world space x coordinate for the screen origin.
y is the new world space y coordinate for the screen origin.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes. To compensate for the hardware limitations that restrict the
screen origin coordinates (see the description of the fg_pan routine),
Fastgraph reduces x and y to an acceptable screen space equivalent.
See also
fg_pan
117
fg_pattern
Prototype
void fg_pattern (int index, int display_pattern);
sub FGpattern (index%, display_pattern%)
subroutine fg_pattern (integer*2 index, integer*2 display_pattern)
procedure fg_pattern (index, display_pattern : integer);
Description
The fg_pattern routine defines one of Fastgraph's 256 display patterns used
with the fg_dispfile, fg_display, or fg_displayp routines. When using
these routines to display a pixel run map, Fastgraph will use the pattern
associated with that color index instead of displaying the color itself.
Refer to the Fastgraph User's Guide for more information about display
patterns and their default values for each graphics video mode.
Parameters
index is the number of the display pattern to define, between 0 and 255.
display_pattern is a 16-bit value representing the actual display pattern.
Its structure depends on the video mode, as summarized in the following
table.
video modes pattern structure
4, 5, 12 shift count (8 bits), four pixels (2 bits each)
6, 11 shift count (8 bits), eight pixels (1 bit each)
9 shift count (8 bits), two pixels (4 bits each)
13, 14, 15, 16, 18 unused (8 bits), two pixels (4 bits each)
17unused (14 bits), two pixels (1 bit each)
The shift count defines the number of bits that display_pattern is rotated
left when applied to odd-numbered pixel rows, while the pixels are the
actual color values replicated through the pixel run. For the EGA and VGA
graphics modes, an implied one pixel shift count is used.
Return value
none
Restrictions
This routine has no effect in text video modes or in 256-color graphics
modes.
See also
fg_dispfile, fg_display, fg_displayp
Examples
9-14
118
fg_playing
Prototype
int fg_playing (void);
function FGplaying% ()
integer*2 function fg_playing ()
function fg_playing : integer;
Description
The fg_playing routine determines whether or not there is any asynchronous
sound in progress.
Parameters
none
Return value
If the return value is 0, it means there is no asynchronous sound in
progress. If it is 1, then there is asynchronous sound in progress.
Restrictions
none
See also
fg_musicb, fg_sounds, fg_voices
Examples
13-4, 13-5, 13-6, 13-7, 13-8
119
fg_point
Prototype
void fg_point (int ix, int iy);
sub FGpoint (ix%, iy%)
subroutine fg_point (integer*2 ix, integer*2 iy)
procedure fg_point (ix, iy : integer);
Description
The fg_point routine draws a point (displays a pixel) in screen space.
Parameters
ix is the point's screen space x coordinate.
iy is the point's screen space y coordinate.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_pointw
Examples
6-1
120
fg_pointw
Prototype
void fg_pointw (double x, double y);
sub FGpointw (x#, y#)
subroutine fg_pointw (real*8 x, real*8 y)
procedure fg_pointw (x, y : real);
Description
The fg_pointw routine draws a point (displays a pixel) in world space.
Parameters
x is the point's world space x coordinate.
y is the point's world space y coordinate.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_point
121
fg_polygon
Prototype
void fg_polygon (int *ix_array, int *iy_array, int n);
sub FGpolygon (ix_array%(), iy_array%(), n%)
subroutine fg_polygon (integer*2 ix_array, integer*2 iy_array, integer*2 n)
procedure fg_polygon (var ix_array, iy_array : integer; n : integer);
Description
The fg_polygon routine draws an unfilled polygon in screen space, using two
coordinate arrays to define the polygon vertices. The drawing of the
polygon begins at the graphics cursor position, through the vertices
defined by the coordinate arrays, and finally back to the original graphics
cursor position if necessary.
Parameters
ix_array is an arbitrary-length array containing the screen space x
coordinates of the polygon vertices.
iy_array is an arbitrary-length array containing the screen space y
coordinates of the polygon vertices.
n is the number of vertices in the polygon.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_polygonw
Examples
6-7
122
fg_polygonw
Prototype
void fg_polygonw (double *x_array, double *y_array, int n);
sub FGpolygonw (x_array#(), y_array#(), n%)
subroutine fg_polygonw (real*8 x_array, real*8 y_array, integer*2 n)
procedure fg_polygonw (var x_array, y_array : real; n : integer);
Description
The fg_polygonw routine draws an unfilled polygon in world space, using two
coordinate arrays to define the polygon vertices. The drawing of the
polygon begins at the graphics cursor position, through the vertices
defined by the coordinate arrays, and finally back to the original graphics
cursor position if necessary.
Parameters
x_array is an arbitrary-length array containing the world space x
coordinates of the polygon vertices.
y_array is an arbitrary-length array containing the world space y
coordinates of the polygon vertices.
n is the number of vertices in the polygon.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_polygon
123
fg_quiet
Prototype
void fg_quiet (void);
sub FGquiet ()
subroutine fg_quiet ()
procedure fg_quiet;
Description
The fg_quiet routine stops continuous synchronous sound started with the
fg_sound or fg_voice routines. It has no effect if there is no continuous
sound in progress.
Parameters
none
Return value
none
Restrictions
none
See also
fg_sound, fg_voice
Examples
13-2
124
fg_rect
Prototype
void fg_rect (int minx, int maxx, int miny, int maxy);
sub FGrect (minx%, maxx%, miny%, maxy%)
subroutine fg_rect (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy)
procedure fg_rect (minx, maxx, miny, maxy : integer);
Description
The fg_rect routine draws a solid (filled) rectangle in screen space or
character space, without regard to the clipping region.
Parameters
minx is the x coordinate of the rectangle's left edge.
maxx is the x coordinate of the rectangle's right edge. It must be greater
than or equal to the value of minx.
miny is the y coordinate of the rectangle's top edge.
maxy is the y coordinate of the rectangle's bottom edge. It must be
greater than or equal to the value of miny.
Return value
none
Restrictions
none
See also
fg_clprect, fg_clprectw, fg_drect, fg_drectw, fg_rectw
Examples
6-10, 7-5, 7-7
125
fg_rectw
Prototype
void fg_rectw (double xmin, double xmax, double ymin, double ymax);
sub FGrectw (xmin#, xmax#, ymin#, ymax#)
subroutine fg_rectw (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax)
procedure fg_rectw (xmin, xmax, ymin, ymax : real);
Description
The fg_rectw routine draws a solid (filled) rectangle in world space,
without regard to the clipping region.
Parameters
xmin is the world space x coordinate of the rectangle's left edge.
xmax is the world space x coordinate of the rectangle's right edge. It
must be greater than or equal to the value of xmin.
ymin is the world space y coordinate of the rectangle's bottom edge.
ymax is the world space y coordinate of the rectangle's top edge. It must
be greater than or equal to the value of ymin.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_clprect, fg_clprectw, fg_drect, fg_drectw, fg_rect
Examples
7-11
126
fg_reset
Prototype
void fg_reset (void);
sub FGreset ()
subroutine fg_reset ()
procedure fg_reset;
Description
When the ANSI.SYS driver is not loaded, the fg_reset routine erases the
screen. When ANSI.SYS is loaded, fg_reset also restores any previously set
screen attributes. It is generally the last Fastgraph routine called in a
program.
Parameters
none
Return value
none
Restrictions
This routine has no effect in graphics video modes.
See also
fg_erase
Examples
3-2
127
fg_resize
Prototype
void fg_resize (int width, int height);
sub FGresize (width%, height%)
subroutine fg_resize (integer*2 width, integer*2 height)
procedure fg_resize (width, height : integer);
Description
The fg_resize routine changes the dimensions of a video page in EGA and VGA
graphics modes.
Parameters
width specifies the new video page width in pixels.
height specifies the new video page height in pixels.
Return value
none
Restrictions
The size of a video page is constrained only by the amount of video memory
available. Increasing the video page size reduces the number of physical
pages available proportionally. In mode 13, for example, increasing the
page size from 320x200 to 640x400 reduces the number of video pages from 8
to 2.
When you call fg_resize, the visual page must be page 0.
If you have created any logical video pages, you must release them with
fg_freepage before calling fg_resize, and then create them again afterward.
If you have initialized the mouse (with fg_mouseini), joysticks (with
fg_initjoy), expanded memory (with fg_initems), or extended memory (with
fg_initxms), you should re-initialize these resources after calling
fg_resize. Most mouse drivers expect a fixed video page width, so the
mouse cursor may become distorted after resizing video pages.
The fg_setmode routine re-establishes the dimensions of a video page to the
default screen resolution for the selected video mode.
This routine is meaningful only in the native EGA graphics modes (13 to
16), native VGA graphics modes (17 and 18), and extended VGA graphics modes
(20 to 23). It has no effect in other video modes.
See also
fg_pan
Examples
8-10, 11-7
128
fg_restore
Prototype
void fg_restore (int minx, int maxx, int miny, int maxy);
sub FGrestore (minx%, maxx%, miny%, maxy%)
subroutine fg_restore (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy)
procedure fg_restore (minx, maxx, miny, maxy : integer);
Description
The fg_restore routine copies a rectangular region from the hidden video
page to the same position on the active video page. In text modes, the
region is defined in character space; in graphics modes, it is defined in
screen space.
Parameters
minx is the x coordinate of the region's left edge. In graphics modes, its
value is reduced to a byte boundary if necessary.
maxx is the x coordinate of the region's right edge. It must be greater
than or equal to the value of minx. In graphics modes, its value is
extended to a byte boundary if necessary.
miny is the y coordinate of the region's top edge.
maxy is the y coordinate of the region's bottom edge. It must be greater
than or equal to the value of miny.
Return value
none
Restrictions
none
See also
fg_restorew, fg_save, fg_savew, fg_sethpage, fg_transfer
Examples
9-23, 9-24
129
fg_restorew
Prototype
void fg_restorew (double xmin, double xmax, double ymin, double ymax);
sub FGrestorew (xmin#, xmax#, ymin#, ymax#)
subroutine fg_restorew (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax)
procedure fg_restorew (xmin, xmax, ymin, ymax : real);
Description
The fg_restorew routine copies a rectangular region, defined in world
space, from the hidden video page to the same position on the active video
page.
Parameters
xmin is the world space x coordinate of the region's left edge. In
graphics modes, its value is reduced to a byte boundary if necessary.
xmax is the world space x coordinate of the region's right edge. It must
be greater than or equal to the value of xmin. In graphics modes, its
value is extended to a byte boundary if necessary.
ymin is the world space y coordinate of the region's bottom edge.
ymax is the world space y coordinate of the region's top edge. It must be
greater than or equal to the value of ymin.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_restore, fg_save, fg_savew, fg_sethpage, fg_transfer
130
fg_resume
Prototype
void fg_resume (void);
sub FGresume ()
subroutine fg_resume ()
procedure fg_resume;
Description
The fg_resume routine restarts asynchronous music previously suspended by
the fg_suspend routine. It has no effect if there is no suspended music.
Parameters
none
Return value
none
Restrictions
none
See also
fg_musicb, fg_suspend
Examples
13-8
131
fg_revimage
Prototype
void fg_revimage (char *map_array, int width, int height);
sub FGrevimage (map_array$, width%, height%)
subroutine fg_revimage (integer*1 map_array, integer*2 width, integer*2
height)
procedure fg_revimage (var map_array : byte; width, height : integer);
Description
The fg_revimage routine displays a reversed image stored as a mode-specific
bit map. The image will be positioned so that its lower left corner is at
the graphics cursor position. Refer to the Fastgraph User's Guide for
complete information about mode-specific bit maps.
Parameters
map_array is the arbitrary-length array containing the bit map.
width is the width in bytes of the bit map.
height is the height in bytes (pixel rows) of the bit map.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_clpimage, fg_drwimage, fg_flpimage, fg_getimage
Examples
9-8, 9-9
132
fg_revmask
Prototype
void fg_revmask (char *map_array, int runs, int width);
sub FGrevmask (map_array$, runs%, width%)
subroutine fg_revmask (integer*1 map_array, integer*2 runs, integer*2
width)
procedure fg_revmask (var map_array : byte; runs, width : integer);
Description
The fg_revmask routine displays a reversed image stored as a masking map.
The image will be positioned so that its lower left corner is at the
graphics cursor position. Refer to the description of the fg_drawmask
routine for more information about masking maps.
Parameters
map_array is the arbitrary-length array containing the masking map.
runs is the number of pixel runs in the masking map.
width is the width in pixels of the masking map.
Return value
none
Restrictions
This routine has no effect in text video modes, or in the native EGA and
VGA graphics video modes.
See also
fg_clipmask, fg_drawmask, fg_flipmask
Examples
9-16
133
fg_save
Prototype
void fg_save (int minx, int maxx, int miny, int maxy);
sub FGsave (minx%, maxx%, miny%, maxy%)
subroutine fg_save (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy)
procedure fg_save (minx, maxx, miny, maxy : integer);
Description
The fg_save routine copies a rectangular region from the active video page
to the same position on the hidden video page. In text modes, the region
is defined in character space; in graphics modes, it is defined in screen
space.
Parameters
minx is the x coordinate of the region's left edge. In graphics modes, its
value is reduced to a byte boundary if necessary.
maxx is the x coordinate of the region's right edge. It must be greater
than or equal to the value of minx. In graphics modes, its value is
extended to a byte boundary if necessary.
miny is the y coordinate of the region's top edge.
maxy is the y coordinate of the region's bottom edge. It must be greater
than or equal to the value of miny.
Return value
none
Restrictions
none
See also
fg_restore, fg_restorew, fg_savew, fg_sethpage, fg_transfer
Examples
9-23, 9-24
134
fg_savew
Prototype
void fg_savew (double xmin, double xmax, double ymin, double ymax);
sub FGsavew (xmin#, xmax#, ymin#, ymax#)
subroutine fg_savew (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax)
procedure fg_savew (xmin, xmax, ymin, ymax : real);
Description
The fg_savew routine copies a rectangular region, defined in world space,
from the active video page to the same position on the hidden video page.
Parameters
xmin is the world space x coordinate of the region's left edge. In
graphics modes, its value is reduced to a byte boundary if necessary.
xmax is the world space x coordinate of the region's right edge. It must
be greater than or equal to the value of xmin. In graphics modes, its
value is extended to a byte boundary if necessary.
ymin is the world space y coordinate of the region's bottom edge.
ymax is the world space y coordinate of the region's top edge. It must be
greater than or equal to the value of ymin.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_restore, fg_restorew, fg_save, fg_sethpage, fg_transfer
135
fg_scrlock
Prototype
int fg_scrlock (void);
function FGscrlock% ()
integer*2 function fg_scrlock ()
function fg_scrlock : integer;
Description
The fg_scrlock routine determines the state of the ScrollLock key.
Parameters
none
Return value
If the return value is 0, it means the ScrollLock key is off. If it is 1,
it means the ScrollLock key is on.
Restrictions
Not all PC keyboards have a ScrollLock key. For such systems, fg_scrlock
will return a value of zero.
See also
fg_capslock, fg_numlock, fg_setcaps, fg_setnum
Examples
12-3
136
fg_scroll
Prototype
void fg_scroll (int minx, int maxx, int miny, int maxy, int jump, int
type);
sub FGscroll (minx%, maxx%, miny%, maxy%, jump%, type%)
subroutine fg_scroll (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy,
integer*2 jump, integer*2 type)
procedure fg_scroll (minx, maxx, miny, maxy, jump, type : integer);
Description
The fg_scroll routine vertically scrolls a region of the active video page.
The scrolling may be done either up or down, using either an end-off or
circular method. In text modes, the region is defined in character space;
in graphics modes, it is defined in screen space.
Parameters
minx is the x coordinate of the scrolling region's left edge. In graphics
modes, its value is reduced to a byte boundary if necessary.
maxx is the x coordinate of the scrolling region's right edge. It must be
greater than or equal to the value of minx. In graphics modes, its value
is extended to a byte boundary if necessary.
miny is the y coordinate of the scrolling region's top edge.
maxy is the y coordinate of the scrolling region's bottom edge. It must be
greater than or equal to the value of miny.
jump is the number of pixels to jump between each scrolling iteration. If
jump is negative, the region will scroll toward the top of the screen. If
jump is positive, the region will scroll toward the bottom of the screen.
type specifies the type of scroll. If type is zero, rows that scroll off
one edge appear at the opposite edge, thus producing a circular scrolling
effect. If type is any other value, rows that scroll off one edge will be
replaced at the opposite edge by lines of the current color.
Return value
none
Restrictions
Circular scrolling uses part of the hidden page (as defined in the most
recent call to fg_sethpage) as a temporary workspace.
See also
fg_setcolor, fg_sethpage
137
fg_scroll (continued)
Examples
11-3, 11-4, 11-5
138
fg_setangle
Prototype
void fg_setangle (double angle);
sub FGsetangle (angle#)
subroutine fg_setangle (real*8 angle)
procedure fg_setangle (angle : real);
Description
The fg_setangle routine defines the angle or orientation at which software
characters are displayed. If a program draws software characters before
calling fg_setangle, Fastgraph will use its default angle of zero degrees
(that is, horizontal).
Parameters
angle is the angle of rotation, expressed in degrees and measured
counterclockwise from the positive x axis.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light. Before using this
routine, you must use the fg_initw and fg_setworld routines to establish a
world space coordinate system.
See also
fg_initw, fg_setratio, fg_setsize, fg_setsizew, fg_setworld, fg_swchar,
fg_swlength, fg_swtext
Examples
7-10
139
fg_setattr
Prototype
void fg_setattr (int foreground, int background, int blink);
sub FGsetattr (foreground%, background%, blink%)
subroutine fg_setattr (integer*2 foreground, integer*2 background,
integer*2 blink)
procedure fg_setattr (foreground, background, blink : integer);
Description
The fg_setattr routine establishes the current text attribute in text video
modes.
Parameters
foreground is attribute's foreground component, between 0 and 15.
background is the attribute's background component, between 0 and 7.
blink is the attribute's blink component, between 0 and 1.
Return value
none
Restrictions
This routine has no effect in graphics video modes.
See also
fg_setcolor
Examples
7-1, 7-2, 7-3, 7-4, 8-1, 8-3, 8-5, 8-7, 9-21, 9-23, 9-25, 11-4, 12-8
140
fg_setcaps
Prototype
void fg_setcaps (int state);
sub FGsetcaps (state%)
subroutine fg_setcaps (integer*2 state)
procedure fg_setcaps (state : integer);
Description
The fg_setcaps routine controls the state of the CapsLock key.
Parameters
state defines the CapsLock key state. If state is 0, the CapsLock key is
turned off. If it is 1, the CapsLock key is turned on.
Return value
none
Restrictions
On most keyboards, changing the CapsLock key state will also change the
keyboard state light to reflect the new key state. However, some older
keyboards, especially when used on PC, PC/XT, or Tandy 1000 systems, do not
update the state light. This makes the state light inconsistent with the
true key state.
See also
fg_capslock, fg_numlock, fg_scrlock, fg_setnum
Examples
12-4
141
fg_setclip
Prototype
void fg_setclip (int minx, int maxx, int miny, int maxy);
sub FGsetclip (minx%, maxx%, miny%, maxy%)
subroutine fg_setclip (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy)
procedure fg_setclip (minx, maxx, miny, maxy : integer);
Description
The fg_setclip routine defines the clipping region in screen space. The
clipping region is a rectangular area outside of which graphics are
suppressed.
Parameters
minx is the screen space x coordinate of the clipping region's left edge.
maxx is the screen space x coordinate of the clipping region's right edge.
It must be greater than or equal to the value of minx.
miny is the screen space y coordinate of the clipping region's top edge.
maxy is the screen space y coordinate of the clipping region's bottom edge.
It must be greater than or equal to the value of miny.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_setclipw
Examples
6-5, 9-8, 9-9, 9-16, 10-4
142
fg_setclipw
Prototype
void fg_setclipw (double xmin, double xmax, double ymin, double ymax);
sub FGsetclipw (xmin#, xmax#, ymin#, ymax#)
subroutine fg_setclipw (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax)
procedure fg_setclipw (xmin, xmax, ymin, ymax : real);
Description
The fg_setclipw routine defines the clipping region in world space. The
clipping region is a rectangular area outside of which graphics are
suppressed.
Parameters
xmin is the world space x coordinate of the clipping region's left edge.
xmax is the world space x coordinate of the clipping region's right edge.
It must be greater than or equal to the value of xmin.
ymin is the world space y coordinate of the clipping region's bottom edge.
ymax is the world space y coordinate of the clipping region's top edge. It
must be greater than or equal to the value of ymin.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light and has no effect in text
video modes.
See also
fg_setclip
143
fg_setcolor
Prototype
void fg_setcolor (int color);
sub FGsetcolor (color%)
subroutine fg_setcolor (integer*2 color)
procedure fg_setcolor (color : integer);
Description
The fg_setcolor routine establishes the current color index (which may be a
virtual color index) in graphics modes. In text modes, fg_setcolor
provides an alternate method of defining the current text attribute.
Parameters
color defines the current color index (in graphics modes) or text attribute
(in text modes). Its value must be between 0 and 255.
Return value
none
Restrictions
none
See also
fg_defcolor, fg_getcolor, fg_palette
Examples
3-1 to 3-9
144
fg_setdacs
Prototype
void fg_setdacs (int start, int count, char *values);
sub FGsetdacs (start%, count%, values$)
subroutine fg_setdacs (integer*2 start, integer*2 count, integer*1 values)
procedure fg_setdacs (start, count : integer; var values : shortint);
Description
The fg_setdacs routine defines the values of a block of contiguous video
DAC registers by specifying their red, green, and blue color components.
Defining many DAC registers with fg_setdacs is considerably faster than
doing so individually with fg_setrgb.
Parameters
start is the starting video DAC register number, between 0 and 255.
count is the number of contiguous DAC registers to define, between 1 and
256. If the sum of start and count exceeds 255, the register numbers wrap
around and resume with register number 0.
values is the array containing the color components. The first three bytes
of this array must contain the red, green, and blue components for DAC
register start, the next three bytes contain the components for register
start+1, and so forth. The size of the values array must be at least
3*count bytes.
Return value
none
Restrictions
This routine has no effect in text video modes, or in any graphics video
mode numbered 16 or below (because these video modes do not use DAC
registers).
See also
fg_getdacs, fg_getrgb, fg_setrgb
Examples
5-12
145
fg_setfunc
Prototype
void fg_setfunc (int mode);
sub FGsetfunc (mode%)
subroutine fg_setfunc (integer*2 mode)
procedure fg_setfunc (mode : integer);
Description
The fg_setfunc routine specifies the logical operation applied when video
memory changes in the native EGA and VGA graphics modes. Replacement mode
is selected after you use the fg_setmode routine to establish a video mode.
Parameters
mode defines the logical operation, as shown below.
value of logical
mode operation
0 replacement
1 and
2 or
3 exclusive or
Return value
none
Restrictions
This routine only functions in the native EGA and VGA graphics video modes
(modes 13 through 18).
Examples
10-3, 15-2
146
fg_sethpage
Prototype
void fg_sethpage (int page_number);
sub FGsethpage (page_number%)
subroutine fg_sethpage (integer*2 page_number)
procedure fg_sethpage (page_number : integer);
Description
The fg_sethpage routine establishes the hidden video page. It may be a
physical or virtual video page. The fg_setmode routine designates video
page 0 as the hidden page.
Parameters
page_number is the hidden video page number, between 0 and 63.
Return value
none
Restrictions
This routine has no effect if page_number references a physical video page
that does not exist, or a virtual video page that has not been created.
See also
fg_gethpage, fg_setpage, fg_setvpage
Examples
9-23, 9-24, 11-2, 11-5
147
fg_setlines
Prototype
void fg_setlines (int lines);
sub FGsetlines (lines%)
subroutine fg_setlines (integer*2 lines)
procedure fg_setlines (lines : integer);
Description
The fg_setlines routine extends an 80-column text mode to 25, 43, or 50
lines per screen. The fg_setmode routine sets the number of lines to 25
when establishing an 80-column text mode.
Parameters
lines is the number of text rows per screen. On EGA systems, the value of
lines must be 25 or 43. On MCGA systems, it must be 25 or 50. On VGA
systems, it must be 25, 43, or 50. Any other value is ignored. Before
calling fg_setlines, you should call fg_testmode with pages=0 to see if the
user's system supports the number of rows needed.
Return value
none
Restrictions
This routine is only meaningful when running in 80-column text modes on
EGA, VGA, or MCGA systems (in other cases it does nothing).
When you call fg_setlines, the visual page must be page 0.
Calling fg_setlines makes the text cursor visible.
If you have initialized the mouse (with fg_mouseini), joysticks (with
fg_initjoy), expanded memory (with fg_initems), or extended memory (with
fg_initxms), you should call re-initialize these resources after calling
fg_setlines.
See also
fg_getlines, fg_testmode
Examples
3-5
148
fg_setmode
Prototype
void fg_setmode (int mode_number);
sub FGsetmode (mode_number%)
subroutine fg_setmode (integer*2 mode_number)
procedure fg_setmode (mode_number : integer);
Description
The fg_setmode routine establishes a video mode and initializes Fastgraph's
internal parameters for that video mode. It must be called before any
Fastgraph routine that performs video output. A program can call
fg_setmode as many times as needed to switch between different video modes.
Parameters
mode_number is the video mode number, between 0 and 23. The following
table lists Fastgraph's supported video modes.
Mode No. of Supported Supported
Number Type Resolution Colors Adapters Displays
0 Text 40 x 25 16/8 CGA,EGA,VGA,MCGA RGB,ECD,VGA
1 Text 40 x 25 16/8 CGA,EGA,VGA,MCGA RGB,ECD,VGA
2 Text 80 x 25 16/8 CGA,EGA,VGA,MCGA RGB,ECD,VGA
3 Text 80 x 25 16/8 CGA,EGA,VGA,MCGA RGB,ECD,VGA
4 Graphics 320 x 200 4 CGA,EGA,VGA,MCGA RGB,ECD,VGA
5 Graphics 320 x 200 4 CGA,EGA,VGA,MCGA RGB,ECD,VGA
6 Graphics 640 x 200 2/16 CGA,EGA,VGA,MCGA RGB,ECD,VGA
7 Text 80 x 25 b/w MDA,HGC,EGA,VGA Mono,ECD,VGA
9 Graphics 320 x 200 16 Tandy 1000,PCjr RGB
11 Graphics 720 x 348 b/w HGC Monochrome
12 Graphics 320 x 200 b/w HGC Monochrome
13 Graphics 320 x 200 16 EGA,VGA RGB,ECD,VGA
14 Graphics 640 x 200 16 EGA,VGA RGB,ECD,VGA
15 Graphics 640 x 350 b/w EGA,VGA Mono,VGA
16 Graphics 640 x 350 16/64 EGA,VGA ECD,VGA
17 Graphics 640 x 480 2/256K VGA,MCGA VGA
18 Graphics 640 x 480 16/256K VGA VGA
19 Graphics 320 x 200 256/256K VGA,MCGA VGA
20 Graphics 320 x 200 256/256K VGA VGA
21 Graphics 320 x 400 256/256K VGA VGA
22 Graphics 320 x 240 256/256K VGA VGA
23 Graphics 320 x 480 256/256K VGA VGA
For more information about each video mode, including their required
display adapters (graphics cards) and monitors, please refer to the
Fastgraph User's Guide.
The value of the mode_number parameter also can be -1, which tells
Fastgraph to use the current video mode. This feature is often useful in
programs that use only text video modes, programs executed from another
program, or terminate and stay resident (TSR) programs.
149
fg_setmode (continued)
Return value
none
Restrictions
The fg_setmode routine does not check if the specified video mode is
available on the user's system. If necessary, you should first use the
fg_testmode routine to do this.
See also
fg_automode, fg_bestmode, fg_testmode
Examples
3-1
150
fg_setnum
Prototype
void fg_setnum (int state);
sub FGsetnum (state%)
subroutine fg_setnum (integer*2 state)
procedure fg_setnum (state : integer);
Description
The fg_setnum routine controls the state of the NumLock key.
Parameters
state defines the NumLock key state. If state is 0, the NumLock key is
turned off. If it is 1, the NumLock key is turned on.
Return value
none
Restrictions
On most keyboards, changing the NumLock key state will also change the
keyboard state light to reflect the new key state. However, some older
keyboards, especially when used on PC, PC/XT, or Tandy 1000 systems, do not
update the state light. This makes the state light inconsistent with the
true key state.
See also
fg_capslock, fg_numlock, fg_scrlock, fg_setcaps
Examples
12-4
151
fg_setpage
Prototype
void fg_setpage (int page_number);
sub FGsetpage (page_number%)
subroutine fg_setpage (integer*2 page_number)
procedure fg_setpage (page_number : integer);
Description
The fg_setpage routine establishes the active video page. It may be a
physical or virtual video page. The fg_setmode routine designates video
page 0 as the active page.
Parameters
page_number is the active video page number, between 0 and 63.
Return value
none
Restrictions
This routine has no effect if page_number references a physical video page
that does not exist, or a virtual video page that has not been created.
See also
fg_getpage, fg_sethpage, fg_setvpage
Examples
8-1 to 8-8, 10-4, 10-5, 11-2
152
fg_setratio
Prototype
void fg_setratio (double ratio);
sub FGsetratio (ratio#)
subroutine fg_setratio (real*8 ratio)
procedure fg_setratio (ratio : real);
Description
The fg_setratio routine defines the aspect ratio for software characters.
The aspect ratio is the ratio of character width to character height. If a
program draws software characters before calling fg_setratio, Fastgraph
will use its default aspect ratio of 1.
Parameters
ratio is the aspect ratio. It must be greater than zero.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light. Before using this
routine, you must use the fg_initw and fg_setworld routines to establish a
world space coordinate system.
See also
fg_initw, fg_setangle, fg_setsize, fg_setsizew, fg_setworld, fg_swchar,
fg_swlength, fg_swtext
Examples
7-9
153
fg_setrgb
Prototype
void fg_setrgb (int number, int red, int green, int blue);
sub FGsetrgb (number%, red%, green%, blue%)
subroutine fg_setrgb (integer*2 number, integer*2 red, integer*2 green,
integer*2 blue)
procedure fg_setrgb (number, red, green, blue : integer);
Description
The fg_setrgb defines the value of a palette register (in Tandy/PCjr and
EGA graphics modes) or video DAC register (in VGA and MCGA graphics modes)
by specifying its red, green, and blue color components.
Parameters
number is the palette or video DAC register number. If it references a
palette register, it must be between 0 and 15 (0 and 1 in mode 17). If it
references a video DAC register, it must be between 0 and 255. The value
of number may be negative to specify an intense color for that palette
register in Tandy/PCjr and 200-line EGA graphics modes.
red, green, and blue respectively specify the red, green, and blue
components of the specified palette or video DAC register. These values
must be 0 or 1 for Tandy/PCjr and 200-line EGA graphics modes, between 0
and 3 for 350-line EGA modes, and between 0 and 63 for VGA and MCGA modes.
Return value
none
Restrictions
This routine has no effect in text video modes, CGA graphics modes, or
Hercules graphics modes.
See also
fg_getrgb, fg_palette, fg_setcolor, fg_setdacs
Examples
5-9, 5-11, 5-13, 5-16, 9-14
154
fg_setsize
Prototype
void fg_setsize (int isize);
sub FGsetsize (isize%)
subroutine fg_setsize (integer*2 isize)
procedure fg_setsize (isize : integer);
Description
The fg_setsize routine defines the height of software characters in screen
space units. If neither fg_setsize nor fg_setsizew is called, Fastgraph
will use its default character height of one world space unit.
Parameters
isize is the character height in screen space units.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light. Before using this
routine, you must use the fg_initw and fg_setworld routines to establish a
world space coordinate system.
See also
fg_initw, fg_setangle, fg_setratio, fg_setsizew, fg_setworld, fg_swchar,
fg_swlength, fg_swtext
155
fg_setsizew
Prototype
void fg_setsizew (double size);
sub FGsetsizew (size#)
subroutine fg_setsizew (real*8 size)
procedure fg_setsizew (size : real);
Description
The fg_setsizew routine defines the height of software characters in world
space units. If neither fg_setsize nor fg_setsizew is called, Fastgraph
will use its default character height of one world space unit.
Parameters
size is the character height in world space units.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light. Before using this
routine, you must use the fg_initw and fg_setworld routines to establish a
world space coordinate system.
See also
fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setworld, fg_swchar,
fg_swlength, fg_swtext
Examples
7-8, 7-9, 7-10, 7-11
156
fg_setvpage
Prototype
void fg_setvpage (int page_number);
sub FGsetvpage (page_number%)
subroutine fg_setvpage (integer*2 page_number)
procedure fg_setvpage (page_number : integer);
Description
The fg_setvpage routine establishes the visual video page. It may be a
physical or virtual video page. The fg_setmode routine designates video
page 0 as the visual page.
Parameters
page_number is the visual video page number, between 0 and 63.
Return value
none
Restrictions
This routine has no effect if page_number references a physical video page
that does not exist, or a virtual video page that has not been created.
See also
fg_getpage, fg_sethpage, fg_setpage
Examples
8-1 to 8-7
157
fg_setworld
Prototype
void fg_setworld (double xmin, double xmax, double ymin, double ymax);
sub FGsetworld (xmin#, xmax#, ymin#, ymax#)
subroutine fg_setworld (real*8 xmin, real*8 xmax, real*8 ymin, real*8 ymax)
procedure fg_setworld (xmin, xmax, ymin, ymax : real);
Description
The fg_setworld routine defines the world space coordinates that correspond
to the physical edges of the screen.
Parameters
xmin is the world space coordinate of the screen's left edge.
xmax is the world space coordinate of the screen's right edge. It must be
greater than the value of xmin.
ymin is the world space coordinate of the screen's top edge.
ymax is the world space coordinate of the screen's bottom edge. It must be
greater than the value of ymin.
Return value
none
Restrictions
This routine is not available in Fastgraph/Light. Before using this
routine, you must call the fg_initw routine to initialize Fastgraph's world
space parameters.
See also
fg_getworld, fg_initw
Examples
4-3, 6-4, 6-8, 7-8, 7-9, 7-10, 7-11
158
fg_sound
Prototype
void fg_sound (int frequency, int duration);
sub FGsound (frequency%, duration%)
subroutine fg_sound (integer*2 frequency, integer*2 duration)
procedure fg_sound (frequency, duration : integer);
Description
The fg_sound routine produces a tone of a specified frequency and duration
using the programmable timer.
Parameters
frequency is tone's frequency in Hertz, between 18 and 32,767.
duration is the tone's length in clock ticks (there are approximately 18.2
clock ticks per second). If duration is zero or negative, the tone is said
to be continuous and will play until you stop it with the fg_quiet routine.
Return value
none
Restrictions
This routine has no effect if there is asynchronous sound already in
progress.
See also
fg_music, fg_quiet, fg_sounds, fg_voice
Examples
13-1
159
fg_sounds
Prototype
void fg_sounds (int *sound_array, int ntimes);
sub FGsounds (sound_array%(), ntimes%)
subroutine fg_sounds (integer*2 sound_array, integer*2 ntimes)
procedure fg_sounds (var sound_array : integer; ntimes : integer);
Description
The fg_sounds routine uses the programmable timer to play a series of tones
of specified frequencies and durations, concurrent with other activity. It
is the asynchronous version of the fg_sound routine.
Parameters
sound_array is an arbitrary-length array containing a series of
(frequency,duration) sound definitions. The format of this array is:
[0] frequency of sound 1
[1] duration of sound 1
[2] frequency of sound 2
[3] duration of sound 2
.
.
.
[2n-2] frequency of sound n
[2n-1] duration of sound n
[2n] terminator (0)
Each frequency value is measured in Hertz and must be between 18 and
32,767. The durations are measured in clock ticks (there are approximately
72.8 clock ticks per second). A null character (that is, a zero byte)
terminates the array.
ntimes specifies the number of times to cycle through the sounds defined in
sound_array. If ntimes is negative, the sounds will play repetitively
until stopped with the fg_hush or fg_hushnext routine.
Return value
none
160
fg_sounds (continued)
Restrictions
This routine has no effect if there is asynchronous sound already in
progress. To expand the range of sound effects, Fastgraph temporarily
quadruples the clock tick interrupt rate from 18.2 to 72.8 ticks per second
while producing asynchronous sound. Because many disk controllers rely on
the 18.2 tick per second clock rate to synchronize disk accesses, your
programs should not perform any disk operations when asynchronous sound is
in progress.
See also
fg_hush, fg_hushnext, fg_musicb, fg_playing, fg_sound, fg_voice, fg_voices
Examples
13-4
161
fg_stall
Prototype
void fg_stall (int delay);
sub FGstall (delay%)
subroutine fg_stall (integer*2 delay)
procedure fg_stall (delay : integer);
Description
The fg_stall routine delays a program's execution for a given number of
processor-specific delay units. You can use the fg_measure routine to
obtain the number of delay units per clock tick for the system being used.
Parameters
delay is the number of delay units to wait.
Return value
none
Restrictions
none
See also
fg_measure, fg_waitfor
Examples
14-3
162
fg_suspend
Prototype
void fg_suspend (void);
sub FGsuspend ()
subroutine fg_suspend ()
procedure fg_suspend;
Description
The fg_suspend routine suspends asynchronous music previously started by
the fg_musicb routine. It has no effect if there is no asynchronous music
in progress.
Parameters
none
Return value
none
Restrictions
A program must not exit to DOS with music suspended. You must call fg_hush
to cancel the music first.
See also
fg_hush, fg_musicb, fg_resume
Examples
13-8
163
fg_swchar
Prototype
void fg_swchar (char *string, int n, int justify);
sub FGswchar (string$, n%, justify%)
subroutine fg_swchar (character*(*) string, integer*2 n, integer*2 justify)
procedure fg_swchar (string : string; n, justify : integer);
Description
The fg_swchar routine displays a string of software characters in the
current color index. The string may be left justified, centered, or right
justified relative to the graphics cursor.
Parameters
string is the arbitrary-length sequence of characters to display. It may
contain special operators, as summarized in the following table.
operator meaning
\ switch to other font
\^ superscript the next character
\v subscript the next character
_ begin underlining characters until another
underscore character is encountered
n is the number of characters in string, including any special operator
characters.
justify determines how string is positioned relative to the current
position. If justify is negative, string is left justified; if it is zero,
string is centered; if it is positive, string is right justified.
Return value
none
Restrictions
Before using this routine, you must use the fg_initw and fg_setworld
routines to establish a world space coordinate system. This routine is not
available in Fastgraph/Light and has no effect in text video modes.
See also
fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setsizew, fg_setworld,
fg_swlength, fg_swtext
Examples
7-8, 7-9
164
fg_swlength
Prototype
double fg_swlength (char *string, int n);
function FGswlength# (string$, n%)
real*8 function fg_swlength (character*(*) string, integer*2 n)
function fg_swlength (string : string; n : integer) : real;
Description
The fg_swlength routine computes the length of a string of software
characters.
Parameters
string is the arbitrary-length sequence of characters for which to compute
the length. It may contain special operators used by the fg_swchar and
fg_swtext routines.
n is the number of characters in string, including any special operator
characters.
justify determines how string is positioned relative to the current
position. If justify is negative, string is left justified; if it is zero,
string is centered; if it is positive, string is right justified.
Return value
The length of string, in world space units.
Restrictions
Before using this routine, you must use the fg_initw and fg_setworld
routines to establish a world space coordinate system. This routine is not
available in Fastgraph/Light and has no effect in text video modes.
See also
fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setsizew, fg_setworld,
fg_swchar, fg_swtext
Examples
7-11
165
fg_swtext
Prototype
void fg_swtext (char *string, int n, int justify);
sub FGswtext (string$, n%, justify%)
subroutine fg_swtext (character*(*) string, integer*2 n, integer*2 justify)
procedure fg_swtext (string : string; n, justify : integer);
Description
The fg_swtext routine is a scaled down version of the fg_swchar routine.
It does not include the alternate font character definitions and thus
requires less memory than fg_swchar.
Parameters
string is the arbitrary-length sequence of characters to display. It may
contain special operators, as summarized in the following table.
operator meaning
\^ superscript the next character
\v subscript the next character
_ begin underlining characters until another
underscore character is encountered
n is the number of characters in string, including any special operator
characters.
justify determines how string is positioned relative to the current
position. If justify is negative, string is left justified; if it is zero,
string is centered; if it is positive, string is right justified.
Return value
none
Restrictions
Before using this routine, you must use the fg_initw and fg_setworld
routines to establish a world space coordinate system. This routine is not
available in Fastgraph/Light and has no effect in text video modes.
See also
fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setsizew, fg_setworld,
fg_swchar, fg_swlength
Examples
7-10, 7-11
166
fg_tcmask
Prototype
void fg_tcmask (int mask);
sub FGtcmask (mask%)
subroutine fg_tcmask (integer*2 mask)
procedure fg_tcmask (mask : integer);
Description
The fg_tcmask routine defines which color values the fg_tcxfer routine will
consider transparent.
Parameters
mask is a 16-bit mask, where each bit indicates whether or not the
corresponding color value is transparent. For example, if bit 0 (the
rightmost bit) is 1, then color 0 will be transparent. If bit 0 is 0,
color 0 will not be transparent. Because the mask size is 16 bits, only
the first 16 color values may be defined as transparent.
Return value
none
Restrictions
This routine has no effect in text video modes.
See also
fg_tcxfer
Examples
9-28
167
fg_tcxfer
Prototype
void fg_tcxfer (int minx, int maxx, int miny, int maxy, int newx, int newy,
int source_page, int dest_page);
sub FGtcxfer (minx%, maxx%, miny%, maxy%, newx%, newy%, source_page%,
dest_page%)
subroutine fg_tcxfer (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy, integer*2 newx, integer*2 newy, integer*2 source_page,
integer*2 dest_page);
procedure fg_tcxfer (minx, maxx, miny, maxy, newx, newy, source_page,
dest_page : integer);
Description
The fg_tcxfer routine copies a rectangular region from any position on any
video page to any position on any video page, excluding any pixels whose
color is transparent. The transparent colors are defined by the fg_tcmask
routine.
Parameters
minx is the x coordinate of the source region's left edge. Its value is
reduced to a byte boundary if necessary.
maxx is the x coordinate of the source region's right edge. It must be
greater than or equal to the value of minx. Its value is extended to a
byte boundary if necessary.
miny is the y coordinate of the source region's top edge.
maxy is the y coordinate of the source region's bottom edge. It must be
greater than or equal to the value of miny.
newx is the x coordinate of the destination region's left edge.
newy is the y coordinate of the destination region's bottom edge.
source_page is the video page number containing the source region.
dest_page is the video page number for the destination region.
Return value
none
Restrictions
If source_page and dest_page reference the same video page, the source
region and destination region must not overlap. This routine has no effect
in text video modes.
See also
fg_tcmask, fg_transfer
168
fg_tcxfer (continued)
Examples
9-28
169
fg_testmode
Prototype
int fg_testmode (int mode, int pages);
function FGtestmode% (mode%, pages%)
integer*2 function fg_testmode (integer*2 mode, integer*2 pages)
function fg_testmode (mode, pages : integer) : integer;
Description
The fg_testmode routine determines whether or not a specified video mode is
available on the user's system. Additionally, fg_testmode can check if
there is enough video memory (for physical pages) or random-access memory
(for virtual pages) to support the number of video pages needed.
Parameters
mode is the video mode number to test, between 0 and 23. Refer to the
description of the fg_setmode routine for a list of available video modes.
pages is the number of video pages required (either physical pages, virtual
pages, or both). If the pages parameter is zero or negative, fg_testmode
checks for availability of the video mode but does not consider video
memory requirements.
Return value
If the requested video mode is available (with the requested number of
video pages), fg_testmode returns 1. If not, it returns 0.
Restrictions
none
See also
fg_automode, fg_bestmode, fg_egacheck, fg_setmode
Examples
3-3, 3-5, 3-9, 5-16, 6-7
170
fg_text
Prototype
void fg_text (char *string, int n);
sub FGtext (string$, n%)
subroutine fg_text (character*(*) string, integer*2 n)
procedure fg_text (string : string; n : integer);
Description
The fg_text routine displays a string of hardware characters, starting at
the text cursor position, using the current text attribute (for text modes)
or color index (for graphics modes). This routine leaves the text cursor
one column to the right of the last character changed (or the first column
of the next row if the last character is at the end of a row).
Parameters
string is the arbitrary-length sequence of characters to display.
n is the number of characters to display from string.
Return value
none
Restrictions
none
See also
fg_locate
Examples
7-1 to 7-8, 7-10, 7-11
171
fg_transfer
Prototype
void fg_transfer (int minx, int maxx, int miny, int maxy, int newx,
int newy, int source_page, int dest_page);
sub FGtransfer (minx%, maxx%, miny%, maxy%, newx%, newy%, source_page%,
dest_page%)
subroutine fg_transfer (integer*2 minx, integer*2 maxx, integer*2 miny,
integer*2 maxy, integer*2 newx, integer*2 newy, integer*2 source_page,
integer*2 dest_page);
procedure fg_transfer (minx, maxx, miny, maxy, newx, newy, source_page,
dest_page : integer);
Description
The fg_transfer routine copies a rectangular region from any position on
any video page to any position on any video page. In text modes, the
region is defined in character space; in graphics modes, it is defined in
screen space. It is Fastgraph's most general image transfer routine.
Parameters
minx is the x coordinate of the source region's left edge. In graphics
modes, its value is reduced to a byte boundary if necessary.
maxx is the x coordinate of the source region's right edge. It must be
greater than or equal to the value of minx. In graphics modes, its value
is extended to a byte boundary if necessary.
miny is the y coordinate of the source region's top edge.
maxy is the y coordinate of the source region's bottom edge. It must be
greater than or equal to the value of miny.
newx is the x coordinate of the destination region's left edge.
newy is the y coordinate of the destination region's bottom edge.
source_page is the video page number containing the source region.
dest_page is the video page number for the destination region.
Return value
none
Restrictions
If source_page and dest_page reference the same video page, the source
region and destination region must not overlap.
See also
fg_copypage, fg_restore, fg_restorew, fg_save, fg_savew, fg_tcxfer
172
fg_transfer (continued)
Examples
9-25, 9-26, 9-27, 10-4, 10-5
173
fg_version
Prototype
void fg_version (int *major, int *minor);
sub FGversion (major%, minor%)
subroutine fg_version (integer*2 major, integer*2 minor)
procedure fg_version (var major, minor : integer);
Description
The fg_version routine returns the major and minor version numbers for your
copy of Fastgraph or Fastgraph/Light. For example, if you are using
Fastgraph version 2.10, the major version number is 2 and the minor version
number is 10.
Parameters
major receives the major version number.
minor receives the minor version number, expressed in hundredths.
Return value
none
Restrictions
none
Examples
1-1, 1-2, 1-3
174
fg_voice
Prototype
void fg_voice (int channel, int frequency, int volume, int duration);
sub FGvoice (channel%, frequency%, volume%, duration%)
subroutine fg_voice (integer*2 channel, integer*2 frequency, integer*2
volume, integer*2 duration)
procedure fg_voice (channel, frequency, volume, duration : integer);
Description
The fg_voice routine produces a tone of a specified frequency, duration,
and volume using one of the TI sound chip's four independent voice
channels.
Parameters
channel defines the voice channel or type of noise, as shown below.
value meaning
1 voice channel #1
2 voice channel #2
3 voice channel #3
4 voice channel #4, periodic noise
5 voice channel #4, white noise
frequency defines the tone's frequency in Hertz. If channel is 1, 2, or 3,
then frequency represents the actual frequency, between 18 and 32,767. If
channel is 4 or 5, frequency is instead a value that represents a specific
frequency, as shown below.
value frequency
0 512 Hertz
1 1024 Hertz
2 2048 Hertz
volume is the tone's volume, between 0 (silent) and 15 (loudest).
duration is the tone's length in clock ticks (there are approximately 18.2
clock ticks per second). If duration is zero or negative, the tone is said
to be continuous and will play until you stop it with the fg_quiet routine.
Return value
none
175
fg_voice (continued)
Restrictions
This routine should only be used on systems equipped with the TI sound chip
(namely, the PCjr and Tandy 1000 systems). It has no effect if there is
asynchronous sound already in progress.
See also
fg_music, fg_quiet, fg_sound, fg_voices
Examples
13-2
176
fg_voices
Prototype
void fg_voices (int *sound_array, int ntimes);
sub FGvoices (sound_array%(), ntimes%)
subroutine fg_voices (integer*2 sound_array, integer*2 ntimes)
procedure fg_voices (var sound_array : integer; ntimes : integer);
Description
The fg_voices routine uses the TI sound chip to play a series of tones of
specified frequencies, durations, and volumes, concurrent with other
activity. It is the asynchronous version of the fg_voice routine.
Parameters
sound_array is an arbitrary-length array containing a series of
(channel,frequency,volume,duration) sound definitions. The format of this
array is:
[0] channel # of sound 1
[1] frequency of sound 1
[2] volume of sound 1
[3] duration of sound 1
.
.
.
[4n-4] channel # of sound n
[4n-3] frequency of sound n
[4n-2] volume of sound n
[4n-1] duration of sound n
[4n] terminator (0)
The channel numbers, frequencies, volumes, and durations must be in the
same ranges as discussed in the description of the fg_voice routine, except
the durations are quadrupled because of the accelerated clock tick
interrupt rate (there are 72.8 instead of 18.2 clock ticks per second). A
null character (that is, a zero byte) terminates the array.
ntimes specifies the number of times to cycle through the sounds defined in
sound_array. If ntimes is negative, the sounds will play repetitively
until stopped with the fg_hush or fg_hushnext routine.
177
fg_voices (continued)
Return value
none
Restrictions
This routine should only be used on systems equipped with the TI sound chip
(namely, the PCjr and Tandy 1000 systems). It has no effect if there is
asynchronous sound already in progress. To expand the range of sound
effects, Fastgraph temporarily quadruples the clock tick interrupt rate
from 18.2 to 72.8 ticks per second while producing asynchronous sound.
Because many disk controllers rely on the 18.2 tick per second clock rate
to synchronize disk accesses, your programs should not perform any disk
operations when asynchronous sound is in progress.
See also
fg_hush, fg_hushnext, fg_musicb, fg_playing, fg_sounds, fg_voice
Examples
13-5
178
fg_waitfor
Prototype
void fg_waitfor (int ticks);
sub FGwaitfor (ticks%)
subroutine fg_waitfor (integer*2 ticks)
procedure fg_waitfor (ticks : integer);
Description
The fg_waitfor routine delays a program's execution for a given number of
clock ticks. There are 18.2 clock ticks per second, regardless of the
system's processor speed.
Parameters
ticks is the number of clock ticks to wait.
Return value
none
Restrictions
none
See also
fg_stall
Examples
5-11, 10-1 to 10-5, 11-5, 11-6, 12-2, 12-6, 12-7, 12-11, 12-12, 13-1, 13-2,
13-3, 13-6, 13-7, 14-1
179
fg_waitkey
Prototype
void fg_waitkey (void);
sub FGwaitkey ()
subroutine fg_waitkey ()
procedure fg_waitkey;
Description
The fg_waitkey routine flushes the BIOS keyboard buffer (that is, removes
any type-ahead characters) and then waits for another keystroke. It is
most useful in "press any key to continue" situations.
Parameters
none
Return value
none
Restrictions
none
See also
fg_getkey, fg_intkey
Examples
3-2 to 3-8
180
fg_where
Prototype
void fg_where (int *row, int *column);
sub FGwhere (row%, column%)
subroutine fg_where (integer*2 row, integer*2 column)
procedure fg_where (row, column : integer);
Description
The fg_where routine retrieves the text cursor position for the active
display page.
Parameters
row receives the text cursor's current row number, between 0 and one less
than the number of character rows available.
column receives text cursor's current column number, between 0 and one less
than the number of character columns available.
Return value
none
Restrictions
none
See also
fg_locate
Examples
7-2
181
fg_xalpha
Prototype
int fg_xalpha (int ix);
function FGxalpha% (ix%)
integer*2 function fg_xalpha (integer*2 ix)
function fg_xalpha (ix : integer) : integer;
Description
The fg_xalpha routine translates a screen space x coordinate to the
character space column containing that coordinate.
Parameters
ix is the screen space coordinate to translate.
Return value
The character space column containing the screen space coordinate ix. In
text modes, the return value is equal to the value of ix.
Restrictions
none
See also
fg_xconvert, fg_yalpha, fg_yconvert
Examples
12-9
182
fg_xconvert
Prototype
int fg_xconvert (int column);
function FGxconvert% (column%)
integer*2 function fg_xconvert (integer*2 column)
function fg_xconvert (column : integer) : integer;
Description
The fg_xconvert routine translates a character space column to the screen
space coordinate of its leftmost pixel. In graphics video modes,
fg_xconvert(1) is an easy way to determine the width in pixels of a
character cell.
Parameters
column is the character space column to translate.
Return value
The screen space x coordinate of the leftmost pixel in the character space
column column. In text modes, the return value is equal to the value of
column.
Restrictions
none
See also
fg_xalpha, fg_yalpha, fg_yconvert
Examples
7-7, 12-7
183
fg_xscreen
Prototype
int fg_xscreen (double x);
function FGxscreen% (x#)
integer*2 function fg_xscreen (real*8 x)
function fg_xscreen (x : real) : integer;
Description
The fg_xscreen routine translates a world space x coordinate to its screen
space equivalent.
Parameters
x is the world space coordinate to translate.
Return value
The screen space x coordinate equivalent to the world space coordinate x.
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_xworld, fg_yscreen, fg_yworld
184
fg_xworld
Prototype
double fg_xworld (int ix);
function FGxworld# (ix%)
real*8 function fg_xworld (integer*2 ix)
function fg_xworld (ix : integer) : real;
Description
The fg_xworld routine translates a screen space x coordinate to its world
space equivalent.
Parameters
ix is the screen space coordinate to translate.
Return value
The world space x coordinate equivalent to the screen space coordinate ix.
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_xscreen, fg_yscreen, fg_yworld
185
fg_yalpha
Prototype
int fg_yalpha (int iy);
function FGyalpha% (iy%)
integer*2 function fg_yalpha (integer*2 iy)
function fg_yalpha (iy : integer) : integer;
Description
The fg_yalpha routine translates a screen space y coordinate to the
character space row containing that coordinate.
Parameters
iy is the screen space coordinate to translate.
Return value
The character space row containing the screen space coordinate iy. In text
modes, the return value is equal to the value of iy.
Restrictions
none
See also
fg_xalpha, fg_xconvert, fg_yconvert
Examples
12-9
186
fg_yconvert
Prototype
int fg_yconvert (int row);
function FGyconvert% (row%)
integer*2 function fg_yconvert (integer*2 row)
function fg_yconvert (row : integer) : integer;
Description
The fg_yconvert routine translates a character space row to the screen
space coordinate of its top (lowest-numbered) pixel. In graphics video
modes, fg_yconvert(1) is an easy way to determine the height in pixels of a
character cell.
Parameters
row is the character space row to translate.
Return value
The screen space y coordinate of the top pixel in the character space row
row. In text modes, the return value is equal to the value of row.
Restrictions
none
See also
fg_xalpha, fg_xconvert, fg_yalpha
Examples
7-7, 12-7
187
fg_yscreen
Prototype
int fg_yscreen (double y);
function FGyscreen% (y#)
integer*2 function fg_yscreen (real*8 y)
function fg_yscreen (y : real) : integer;
Description
The fg_yscreen routine translates a world space y coordinate to its screen
space equivalent.
Parameters
y is the world space coordinate to translate.
Return value
The screen space y coordinate equivalent to the world space coordinate y.
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_xscreen, fg_xworld, fg_yworld
188
fg_yworld
Prototype
double fg_yworld (int iy);
function FGyworld# (iy%)
real*8 function fg_yworld (integer*2 iy)
function fg_yworld (iy : integer) : real;
Description
The fg_yworld routine translates a screen space y coordinate to its world
space equivalent.
Parameters
iy is the screen space coordinate to translate.
Return value
The world space y coordinate equivalent to the screen space coordinate iy.
Restrictions
This routine is not available in Fastgraph/Light.
See also
fg_xscreen, fg_xworld, fg_yscreen
189