home *** CD-ROM | disk | FTP | other *** search
/ C++ Games Programming / CPPGAMES.ISO / fgl / fglight / manuals.arj / USER17.DOC < prev    next >
Text File  |  1995-02-06  |  12KB  |  290 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6. Chapter 17
  7.  
  8.  
  9.  
  10.  
  11.  
  12. Miscellaneous Routines                                                         
  13. 350   Fastgraph User's Guide
  14.  
  15.  
  16. Overview
  17.  
  18.      There are a few remaining Fastgraph routines that really don't fit into
  19. any of the categories discussed so far. For this reason, we'll describe them
  20. separately in this chapter.
  21.  
  22.  
  23. Determining Available Memory
  24.  
  25.      The fg_memavail routine returns the amount of free conventional memory
  26. (in bytes) available to DOS. It returns the amount of memory as its function
  27. value, which is a 32-bit unsigned integer, and it has no arguments.
  28.  
  29.      Example 17-1 uses fg_memavail to show the effects of creating and
  30. releasing virtual pages. When run in a video mode in which video pages 1 and 2
  31. are physical pages, the amount of free memory remains the same because these
  32. pages use memory that is resident on the video adapter. However, in modes
  33. where pages 1 and 2 are virtual pages, the amount of free memory decreases
  34. after each call to fg_allocate and returns to its original value after the
  35. calls to fg_freepage. Note how the program requests and validates the video
  36. mode.
  37.  
  38.                                  Example 17-1.
  39.  
  40.        #include <fastgraf.h>
  41.        #include <stdio.h>
  42.        #include <stdlib.h>
  43.        void main(void);
  44.  
  45.        void main()
  46.        {
  47.           long original, mem0, mem1, mem2;
  48.           int  mode, old_mode;
  49.  
  50.           printf("Which video mode? ");
  51.           scanf("%d",&mode);
  52.  
  53.           fg_initpm();
  54.           if (fg_testmode(mode,0) == 0) {
  55.              printf("Your system does not support that video mode.\n");
  56.              exit(1);
  57.              }
  58.           if (fg_testmode(mode,3) == 0) {
  59.              printf("Your system does not have enough memory.\n");
  60.              exit(1);
  61.              }
  62.  
  63.           original = fg_memavail();
  64.           old_mode = fg_getmode();
  65.           fg_setmode(mode);
  66.           mem0 = fg_memavail();
  67.           fg_allocate(1);
  68.           mem1 = fg_memavail();
  69.           fg_allocate(2);
  70.           mem2 = fg_memavail();                                                
  71.                                      Chapter 17:  Miscellaneous Routines   351
  72.  
  73.  
  74.           fg_freepage(1);
  75.           fg_freepage(2);
  76.           fg_setmode(old_mode);
  77.           fg_reset();
  78.  
  79.           printf("originally     = %ld\n",original);
  80.           printf("after setmode  = %ld\n",mem0);
  81.           printf("after 1st page = %ld\n",mem1);
  82.           printf("after 2nd page = %ld\n",mem2);
  83.           printf("at end         = %ld\n",memavail());
  84.        }
  85.  
  86.  
  87.  
  88. Choosing the Video Memory Update Function
  89.  
  90.      In Chapter 12, we saw how to use the fg_setfunc routine to perform XOR
  91. animation in native EGA and VGA graphics modes (modes 13 to 18). In these
  92. video modes, fg_setfunc controls the logical operation applied when the
  93. contents of video memory change. The specific operation is defined by its
  94. argument, as shown here:
  95.  
  96.                                  value of  logical
  97.                                  argument operation
  98.  
  99.                                     0    replacement
  100.                                     1        and
  101.                                     2         or
  102.                                     3    exclusive or
  103.  
  104. If a program does not call fg_setfunc, replacement mode is always used. That
  105. is, information written to video memory replaces whatever was there before.
  106. The fg_setfunc routine applies only to video memory, even if a virtual buffer
  107. is active, and is meaningful only in 16-color EGA, VGA, and SVGA graphics
  108. modes.
  109.  
  110.      Example 17-2 demonstrates the fg_setfunc routine. The program is similar
  111. to example 6-11, which displays 200 random rectangles on the screen. However,
  112. example 17-2 displays the rectangles in XOR mode, which makes the rectangle
  113. intersections appear in different colors.
  114.  
  115.                                  Example 17-2.
  116.  
  117.              #include <fastgraf.h>
  118.              #include <stdio.h>
  119.              #include <stdlib.h>
  120.              void main(void);
  121.  
  122.              #define RECTANGLES 200
  123.              #define SWAP(a,b,temp) { temp = a; a = b; b = temp; }
  124.  
  125.              void main()
  126.              {
  127.                 int i;
  128.                 int minx, maxx, miny, maxy;                                    
  129. 352   Fastgraph User's Guide
  130.  
  131.                 int old_mode;
  132.                 int temp;
  133.                 int xres, yres;
  134.  
  135.                 fg_initpm();
  136.                 if (fg_egacheck() == 0) {
  137.                    printf("This program requires EGA or VGA.\n");
  138.                    exit(1);
  139.                    }
  140.  
  141.                 old_mode = fg_getmode();
  142.                 fg_setmode(fg_automode());
  143.                 fg_setfunc(3);
  144.  
  145.                 xres = fg_getmaxx() + 1;
  146.                 yres = fg_getmaxy() + 1;
  147.  
  148.                 for (i = 0; i < RECTANGLES; i++) {
  149.                    minx = rand() % xres;
  150.                    maxx = rand() % xres;
  151.                    miny = rand() % yres;
  152.                    maxy = rand() % yres;
  153.                    if (minx > maxx)
  154.                       SWAP(minx,maxx,temp);
  155.                    if (miny > maxy)
  156.                       SWAP(miny,maxy,temp);
  157.                    fg_setcolor(rand()%16);
  158.                    fg_rect(minx,maxx,miny,maxy);
  159.                    }
  160.  
  161.                 fg_setmode(old_mode);
  162.                 fg_reset();
  163.              }
  164.  
  165.  
  166.  
  167. Controlling Vertical Retrace Synchronization
  168.  
  169.      The vertical retrace is the brief period when the monitor's electron beam
  170. travels from the bottom of the screen back to the upper left corner to begin a
  171. new display refresh cycle. Depending on the monitor, the vertical retrace
  172. typically occurs between 50 and 60 times per second.
  173.  
  174.      Certain graphics operations must be performed during a vertical retrace
  175. interval to avoid potential screen flickering or snow. These include page
  176. flipping, panning, and reading or writing a block of video DAC registers or
  177. palettes. By default, Fastgraph's routines that perform these operations
  178. automatically provide the necessary vertical retrace synchronization. In most
  179. applications, these vertical retrace controls are completely sufficient. There
  180. are times, however, when you may wish to disable Fastgraph's vertical retrace
  181. checking and perform the vertical retrace synchronization at the application
  182. level.
  183.  
  184.      This is the purpose of Fastgraph's fg_waitvr routine. To disable all
  185. internal vertical retrace synchronization within Fastgraph, call fg_waitvr
  186. with a zero argument. If you want to re-enable it, pass a non-zero value to    
  187.                                      Chapter 17:  Miscellaneous Routines   353
  188.  
  189. fg_waitvr (note that this is the default state). The Fastgraph routines
  190. relevant to the vertical retrace are fg_getdacs, fg_palettes, fg_pan,
  191. fg_setdacs, and fg_setvpage; and in 256-color modes, fg_getrgb, fg_palette,
  192. and fg_setrgb. The vertical retrace is also applicable to Fastgraph's routines
  193. for displaying or creating PCX, GIF, or flic files in 16-color and 256-color
  194. graphics modes when the palette or DAC values are manipulated.
  195.  
  196.      As an example of why you might want to do disable Fastgraph's vertical
  197. retrace controls, consider page flipping. After fg_setvpage defines the
  198. display start address for the new visual page, it waits for a vertical retrace
  199. interval so the new starting address can take effect. If fg_setvpage didn't do
  200. this, graphics displayed before the next vertical retrace would sometimes
  201. appear on the screen before the old visual page is completely removed.
  202. Suppose, though, that immediately after the page flip you did some
  203. calculations or other work that didn't affect the video display. If you
  204. disable Fastgraph's vertical retrace synchronization, you might achieve a
  205. faster frame rate because you can perform the post-page-flip calculations
  206. while the system is normally waiting for the vertical retrace. Depending on
  207. the extent of these calculations, you may find that it's not even necessary to
  208. wait for the vertical retrace following a page flip.
  209.  
  210.  
  211. External SVGA Bank Switching
  212.  
  213.      One of the most important features that occurs during Fastgraph's SVGA
  214. kernel initialization is the setup of chipset-specific bank switching
  215. functions. When a bank switch is needed, the current Fastgraph routine
  216. performs the bank switch through pre-defined entry points in the SVGA kernel.
  217. This removes the low-level details of knowing when and how to bank switch from
  218. an application's high-level code.
  219.  
  220.      If you have an application that performs some or all of its SVGA graphics
  221. outside of Fastgraph, you can still use Fastgraph's extensive SVGA chipset
  222. autodetection and bank switching functions. After successfully initializing
  223. the SVGA kernel with fg_svgainit and establishing an SVGA graphics video mode,
  224. the read and write bank numbers will be set to zero. When you need to change
  225. SVGA banks, call the fg_setbanks routine; its two arguments specify the new
  226. read and write bank numbers. Note that fg_setbanks doesn't tell you when to
  227. perform a bank switch, it merely handles the details of how to do it. A
  228. complementary routine, fg_getbanks, returns the SVGA kernel's current read and
  229. write bank numbers.
  230.  
  231.  
  232. Saving and Restoring the Video State
  233.  
  234.      If you call Fastgraph routines from an interrupt service routine (ISR) in
  235. a VGA, XVGA, or SVGA graphics mode, the ISR is responsible for saving and
  236. restoring the VGA state. This is required because an interrupt might occur
  237. while performing other graphics operations, and the Fastgraph routines called
  238. from the ISR will almost certainly change the VGA state. When control returns
  239. to the point of interruption, the VGA will likely be in a different state than
  240. expected.
  241.  
  242.      The fg_vgastate routine saves and restores the VGA registers that
  243. Fastgraph expects to be in specific states. These registers are:               
  244. 354   Fastgraph User's Guide
  245.  
  246.      * Graphics Controller index
  247.      * Graphics Controller registers 0-8
  248.      * Sequence Controller index
  249.      * Sequence Controller register 2
  250.  
  251. To save the state of these registers, call fg_vgastate(0). To restore them to
  252. their previously saved values, call fg_vgastate(1). If you request a
  253. fg_vgastate save operation before performing a restore operation, nothing
  254. happens. The fg_vgastate routine is meaningful only in video modes numbered 13
  255. and above when running on a VGA or SVGA system.
  256.  
  257.      If you need to save and restore the VGA state in an SVGA graphics mode,
  258. you should use fg_vgastate to preserve the VGA registers plus fg_getbanks and
  259. fg_setbanks (described in the previous section) to preserve the SVGA bank
  260. numbers.
  261.  
  262.  
  263. Summary of Miscellaneous Routines
  264.  
  265.      This section summarizes the functional descriptions of the Fastgraph
  266. routines presented in this chapter. More detailed information about these
  267. routines, including their arguments and return values, may be found in the
  268. Fastgraph Reference Manual.
  269.  
  270.      FG_GETBANKS returns the current SVGA read and write bank numbers. These
  271. values will be correct only if set through the SVGA kernel, or with
  272. fg_setbanks.
  273.  
  274.      FG_MEMAVAIL returns the amount of memory available to DOS.
  275.  
  276.      FG_SETBANKS defines the SVGA read and write bank numbers. This routine is
  277. not usually called in an application but is provided as a high-level interface
  278. to Fastgraph's SVGA kernel.
  279.  
  280.      FG_SETFUNC specifies the logical operation (replacement, or, and,
  281. exclusive or) applied when video memory changes in the 16-color EGA, VGA, and
  282. SVGA graphics modes. This routine has no effect in other video modes and does
  283. not apply to information written to virtual buffers.
  284.  
  285.      FG_VGASTATE saves or restores the state of the VGA Graphics Controller
  286. and Sequence Controller registers used by Fastgraph.
  287.  
  288.      FG_WAITVR disables or enables vertical retrace synchronization within
  289. Fastgraph.
  290.