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