home *** CD-ROM | disk | FTP | other *** search
/ The Devil's Doorknob BBS Capture (1996-2003) / devilsdoorknobbbscapture1996-2003.iso / Dloads / PROGRAMM / FGL112B.ZIP / USER03.DOC < prev    next >
Text File  |  1992-10-05  |  23KB  |  547 lines
  1. Chapter 3
  2.  
  3. Initializing the
  4. Video Environment
  5. 28  Fastgraph User's Guide
  6.  
  7.  
  8. Overview
  9.  
  10.      Before Fastgraph can perform any text or graphics video operations, you
  11. must select a video mode in which your program will run.  An important part
  12. of this selection depends on whether your program will run in a text mode, a
  13. graphics mode, or both.  This chapter discusses the necessary video
  14. initialization for each case.
  15.  
  16.  
  17. Establishing a Text Mode
  18.  
  19.      When you write a program that only uses text modes, you must determine
  20. if the program will run on monochrome systems, color systems, or both.  In
  21. general, there is no reason to exclude one type of system, because the
  22. additional programming required to support both is rather trivial.
  23.  
  24.      The Fastgraph routine fg_setmode establishes a video mode and
  25. initializes Fastgraph's internal parameters for that mode.  This routine has
  26. a single integer argument whose value is a video mode number between 0 and
  27. 23.  Its value can also be -1, which tells Fastgraph to use the current video
  28. mode.  Specifying an fg_setmode argument of -1 is often useful in programs
  29. that only use text video modes.
  30.  
  31.      When you establish a text video mode, the ROM BIOS text cursor is made
  32. visible, and this is often undesirable.  The Fastgraph routine fg_cursor
  33. controls the visibility of the text cursor.  The fg_cursor routine has a
  34. single integer argument that specifies the cursor visibility.  If its value
  35. is 0, the cursor is made invisible; if its value is 1, the cursor is made
  36. visible.
  37.  
  38.      At this point, an example may help to clarify things.  The following
  39. program shows how to initialize Fastgraph for the 80-column color text mode
  40. (mode 3) and turn off the text mode cursor.  It uses two Fastgraph routines
  41. that we have not yet discussed, fg_setcolor and fg_text.  These routines will
  42. be discussed in later sections of this document.  For now, it should suffice
  43. to know the call to fg_setcolor makes subsequent text appear in bright white,
  44. and the call to fg_text displays the characters passed to it.
  45.  
  46.                                  Example 3-1.
  47.  
  48.                        #include <fastgraf.h>
  49.                        void main(void);
  50.  
  51.                        void main()
  52.                        {
  53.                           fg_setmode(3);
  54.                           fg_cursor(0);
  55.  
  56.                           fg_setcolor(15);
  57.                           fg_text("Hello, world.",13);
  58.                        }
  59.  
  60.      If you run example 3-1, notice the text displayed by the program appears
  61. in the upper left corner of the screen.  On the line below this, the DOS
  62. prompt appears, waiting for your next DOS command.  Furthermore, if your
  63. system uses the ANSI.SYS driver to set screen attributes (such as with
  64.                             Chapter 3:  Initializing the Video Environment  29
  65.  
  66. Norton's SA program), you should also notice only the DOS prompt appears in
  67. the colors defined by the screen attributes -- the rest of the screen is
  68. blank.
  69.  
  70.      A more graceful return to DOS is needed.  In example 3-2, we'll use the
  71. Fastgraph routine fg_reset.  This routine erases the screen, and if the
  72. ANSI.SYS driver is loaded, fg_reset also restores any previously set screen
  73. attributes.  We've also included a call to the Fastgraph routine fg_waitkey
  74. to wait for a keystroke before exiting.  If we didn't do this, we would never
  75. see the program's output.
  76.  
  77.                                  Example 3-2.
  78.  
  79.                        #include <fastgraf.h>
  80.                        void main(void);
  81.  
  82.                        void main()
  83.                        {
  84.                           fg_setmode(3);
  85.                           fg_cursor(0);
  86.  
  87.                           fg_setcolor(15);
  88.                           fg_text("Hello, world.",13);
  89.                           fg_waitkey();
  90.  
  91.                           fg_reset();
  92.                        }
  93.  
  94.      Since examples 3-1 and 3-2 specifically used video mode 3, they would
  95. not work on a monochrome system.  Ideally, we would like to use fg_setmode(3)
  96. for color systems and fg_setmode(7) for monochrome systems.  To do this, we
  97. need a way to determine whether the program is being run on a color system or
  98. on a monochrome system.  The next example illustrates an easy way to
  99. accomplish this.
  100.  
  101.      Example 3-3 uses the Fastgraph routine fg_testmode to determine if the
  102. user's system will support the video mode number specified as its first
  103. argument (the second argument is the number of video pages required, which
  104. will be 1 for all examples in this section).  The fg_testmode routine returns
  105. a value of 1 (as its function value) if the requested video mode can be used,
  106. and it returns 0 if not.  The program first sees if an 80-column color text
  107. mode is available (mode 3), and if so, it selects that mode.  If the color
  108. mode is not available, it checks if the monochrome text mode is available
  109. (mode 7), and if so, it chooses the monochrome mode.  If neither mode is
  110. available, then the program assumes the user's system has a 40-column
  111. display, issues a message indicating the program requires an 80-column
  112. display, and then exits.
  113.  
  114.                                  Example 3-3.
  115.  
  116.                    #include <fastgraf.h>
  117.                    #include <stdio.h>
  118.                    #include <stdlib.h>
  119.                    void main(void);
  120.  
  121.                    void main()
  122.  
  123. 30  Fastgraph User's Guide
  124.  
  125.                    {
  126.                       int old_mode;
  127.  
  128.                       old_mode = fg_getmode();
  129.  
  130.                       if (fg_testmode(3,1))
  131.                          fg_setmode(3);
  132.                       else if (fg_testmode(7,1))
  133.                          fg_setmode(7);
  134.                       else {
  135.                          printf("This program requires\n");
  136.                          printf("an 80-column display.\n");
  137.                          exit(1);
  138.                          }
  139.  
  140.                       fg_cursor(0);
  141.  
  142.                       fg_setcolor(15);
  143.                       fg_text("Hello, world.",13);
  144.                       fg_waitkey();
  145.  
  146.                       fg_setmode(old_mode);
  147.                       fg_reset();
  148.                    }
  149.  
  150.  
  151.      Example 3-3 also illustrates another useful procedure.  It is
  152. recommended, especially in graphics modes, to restore the original video mode
  153. and screen attributes before a program returns to DOS.  We've already seen
  154. how the fg_reset routine restores the screen attributes, but how do we
  155. restore the original video mode?  The Fastgraph routine fg_getmode returns
  156. the current video mode as its function value.  If we call fg_getmode before
  157. calling fg_setmode, we can use the return value from fg_getmode and again
  158. call fg_setmode before the program exits.
  159.  
  160.      You also can use another Fastgraph routine, fg_bestmode, to determine if
  161. a video mode with a specific resolution is available on the user's system.
  162. The fg_bestmode routine requires three integer arguments:  a horizontal
  163. resolution, a vertical resolution, and the number of video pages required.
  164. As its function value, fg_bestmode returns the video mode number that offers
  165. the most capabilities for the resolution and number of pages requested.  It
  166. returns a value of -1 if no available video mode offers the requested
  167. criteria.
  168.  
  169.      For example, if we require an 80 by 25 text mode, we can use the
  170. function call fg_bestmode(80,25,1) to pick the "best" video mode available
  171. that offers this capability.  In text modes, the term best means to give
  172. preference to a color text mode over a monochrome text mode.  Example 3-4
  173. performs the same function as example 3-3, but it uses fg_bestmode rather
  174. than fg_testmode.
  175.  
  176.                                  Example 3-4.
  177.  
  178.                    #include <fastgraf.h>
  179.                    #include <stdio.h>
  180.                    #include <stdlib.h>
  181.  
  182.                             Chapter 3:  Initializing the Video Environment  31
  183.  
  184.                    void main(void);
  185.  
  186.                    void main()
  187.                    {
  188.                       int old_mode;
  189.                       int new_mode;
  190.  
  191.                       old_mode = fg_getmode();
  192.                       new_mode = fg_bestmode(80,25,1);
  193.                       if (new_mode < 0) {
  194.                          printf("This program requires\n");
  195.                          printf("an 80-column display.\n");
  196.                          exit(1);
  197.                          }
  198.  
  199.                       fg_setmode(new_mode);
  200.                       fg_cursor(0);
  201.  
  202.                       fg_setcolor(15);
  203.                       fg_text("Hello, world.",13);
  204.                       fg_waitkey();
  205.  
  206.                       fg_setmode(old_mode);
  207.                       fg_reset();
  208.                    }
  209.  
  210. 43-line and 50-line Text Modes
  211.  
  212.      When using an 80-column text mode on a system equipped with an EGA, VGA,
  213. or MCGA video display and adapter, you can extend the screen size from 25
  214. lines to 43 or 50 lines.  While all systems offer 25-line text modes, EGA
  215. systems also offer 43-line modes, MCGA systems also offer 50-line modes, and
  216. VGA systems offer both 43-line and 50-line modes.  The 43-line mode is not
  217. available on EGA systems equipped with an RGB display.  If you extend the
  218. screen size to 43 or 50 lines, the physical character size is reduced
  219. proportionally so all lines appear on the screen.
  220.  
  221.      The fg_setlines routine defines the number of text rows per screen.  It
  222. has a single integer argument whose value must be 25, 43, or 50.  If you pass
  223. any other value to fg_setlines, or pass a value not supported by the host
  224. system's video configuration, fg_setlines does nothing.  In addition, calling
  225. fg_setlines makes the text cursor visible.  Another Fastgraph routine,
  226. fg_getlines, returns as its function value the number of text rows currently
  227. in effect.  You also can use fg_getlines in graphics video modes.
  228.  
  229.      Example 3-5 illustrates the use of the fg_setlines and fg_getlines
  230. routines.  The program first establishes the 80-column color text mode (this
  231. sets the screen size to its 25-line default) and makes the text cursor
  232. invisible.  It then displays the words "first line" in the upper left corner
  233. of the screen.  Next, the program checks if an EGA with enhanced display is
  234. available, and if so, changes the screen to 43 lines (video mode 16 is only
  235. available on EGA systems equipped with an enhanced display).  Next, the
  236. program checks if a VGA or MCGA is available, and if so changes the screen to
  237. 50 lines (video mode 17 is only available on VGA and MCGA systems).  Finally,
  238. the program restores the original video mode, restores the number of lines
  239. per screen to its original setting, and restores the original screen
  240. attributes before exiting.
  241. 32  Fastgraph User's Guide
  242.  
  243.                                  Example 3-5.
  244.  
  245.                         #include <fastgraf.h>
  246.                         void main(void);
  247.  
  248.                         void main()
  249.                         {
  250.                            int lines;
  251.                            int old_lines;
  252.                            int old_mode;
  253.  
  254.                            old_lines = fg_getlines();
  255.                            old_mode = fg_getmode();
  256.                            fg_setmode(3);
  257.                            fg_cursor(0);
  258.  
  259.                            fg_setcolor(15);
  260.                            fg_text("first line",10);
  261.                            fg_waitkey();
  262.  
  263.                            if (fg_testmode(16,0)) {
  264.                               fg_setlines(43);
  265.                               fg_cursor(0);
  266.                               fg_waitkey();
  267.                               }
  268.  
  269.                            if (fg_testmode(17,0)) {
  270.                               fg_setlines(50);
  271.                               fg_cursor(0);
  272.                               fg_waitkey();
  273.                               }
  274.  
  275.                            fg_setmode(old_mode);
  276.                            fg_setlines(old_lines);
  277.                            fg_reset();
  278.                         }
  279.  
  280.  
  281.  
  282. Establishing a Graphics Mode
  283.  
  284.      The steps for establishing a graphics mode are similar to establishing a
  285. text mode.  However, there are more restrictions since some systems may not
  286. support all the graphics video modes.  For example, a program could not run
  287. in mode 13 on a CGA system, nor could a program run in mode 9 on anything
  288. except a Tandy 1000 or PCjr system.
  289.  
  290.      Example 3-6 shows one way to write an EGA-specific program.  The program
  291. in this example uses mode 16, the 640 x 350 EGA mode that requires an
  292. Enhanced Color Display (ECD).  It uses the Fastgraph routine fg_egacheck to
  293. determine if an EGA and ECD are present.  The fg_egacheck routine returns a
  294. value of 0 if an EGA is not found, or if there is an EGA but no ECD.  If an
  295. EGA and ECD are found, it returns a positive integer indicating the number of
  296. 64K-byte increments of video memory on the EGA.  Since mode 16 requires
  297. 112,000 bytes of video memory for a single video page, there must be at least
  298. 128K bytes of video memory on the EGA to run this program.  Hence, we must be
  299. sure that fg_egacheck returns a value of at least 2.
  300.                             Chapter 3:  Initializing the Video Environment  33
  301.  
  302.                                  Example 3-6.
  303.  
  304.     #include <fastgraf.h>
  305.     #include <stdio.h>
  306.     #include <stdlib.h>
  307.     void main(void);
  308.  
  309.     void main()
  310.     {
  311.        int mode;
  312.  
  313.        if (fg_egacheck() < 2) {
  314.           printf("This program requires an Enhanced Graphics Adapter\n");
  315.           printf("(EGA) and an Enhanced Color Display (ECD).\n");
  316.           exit(1);
  317.           }
  318.  
  319.        mode = fg_getmode();
  320.        fg_setmode(16);
  321.  
  322.        fg_setcolor(15);
  323.        fg_text("Hello, world.",13);
  324.        fg_waitkey();
  325.  
  326.        fg_setmode(mode);
  327.        fg_reset();
  328.     }
  329.  
  330.  
  331.  
  332.      For graphics programs, it may suffice to write a program to run in a
  333. specific video mode, but it is often more desirable to write a program that
  334. will run in any of several video modes.  This is especially true for
  335. commercial products, since they should run on as many different video
  336. configurations as possible.
  337.  
  338.      Fastgraph includes a routine named fg_automode that determines the
  339. graphics video mode that offers the most functionality for the user's video
  340. hardware configuration.  For example, the Tandy 1000 series computers support
  341. all three CGA modes (4, 5, and 6) and the 320 by 200 16-color Tandy 1000 mode
  342. (9).  Of these modes, mode 9 offers the most features from a graphics
  343. standpoint, so fg_automode will return a value of 9 when run on a Tandy 1000
  344. computer.  The following table summarizes the video mode numbers returned by
  345. fg_automode for given adapter-display combinations.
  346.  
  347.                                ------- display -------
  348.                       adapter   mono   RGB   ECD   VGA
  349.  
  350.                         MDA       7     0     7     7
  351.                         HGC      11     0     0    11
  352.                         CGA       0     4     0     0
  353.                         EGA      15    13    16     0
  354.                         VGA      17    17    17    18
  355.                        MCGA      17    17    17    19
  356.                       Tandy       7     9     0     0
  357.                        PCjr       7     9     0     0
  358.  
  359. 34  Fastgraph User's Guide
  360.  
  361.  
  362.      Example 3-7 shows how to use fg_automode to determine the "best"
  363. graphics mode for the user's video hardware.  In graphics modes, the term
  364. best means the highest resolution, followed by the number of available
  365. colors.  The program displays a message that includes the selected video mode
  366. number.
  367.  
  368.                                  Example 3-7.
  369.  
  370.                     #include <fastgraf.h>
  371.                     #include <stdio.h>
  372.                     void main(void);
  373.  
  374.                     void main()
  375.                     {
  376.                        int old_mode;
  377.                        int new_mode;
  378.                        char string[4];
  379.  
  380.                        old_mode = fg_getmode();
  381.                        new_mode = fg_automode();
  382.                        fg_setmode(new_mode);
  383.  
  384.                        fg_setcolor(15);
  385.                        fg_text("I'm running in mode ",20);
  386.                        sprintf(string,"%d.",new_mode);
  387.                        fg_text(string,3);
  388.                        fg_waitkey();
  389.  
  390.                        fg_setmode(old_mode);
  391.                        fg_reset();
  392.                     }
  393.  
  394.      For simple programs such as example 3-7, different screen resolutions
  395. may not be an issue.  However, in more complex graphics programs it is often
  396. desirable to write a program for a fixed screen resolution.  A common
  397. practice is to develop graphics programs to run in modes 4 (for CGA), 9
  398. (Tandy 1000 or PCjr), 12 (Hercules), 13 (EGA or VGA), and 19 or 20 (MCGA or
  399. VGA).  The reason for selecting these five modes is they all use the same 320
  400. by 200 resolution and will run on any IBM PC or PS/2 with graphics
  401. capabilities.
  402.  
  403.      Example 3-8 performs the same function as example 3-7, but it uses the
  404. fg_bestmode routine instead of fg_automode to restrict the program to 320 by
  405. 200 graphics modes.  For this resolution, the fg_bestmode routine will first
  406. check the availability of mode 19, followed by modes 13, 9, 4, and 12.  If
  407. fg_bestmode determines no 320 by 200 graphics mode is available (indicated by
  408. a return value of -1), the program prints an informational message and exits.
  409. Otherwise it selects the video mode fg_bestmode proposes and continues.
  410.  
  411.                                  Example 3-8.
  412.  
  413.      #include <fastgraf.h>
  414.      #include <stdio.h>
  415.      #include <stdlib.h>
  416.      void main(void);
  417.  
  418.                             Chapter 3:  Initializing the Video Environment  35
  419.  
  420.      void main()
  421.      {
  422.         int old_mode;
  423.         int new_mode;
  424.         char string[4];
  425.  
  426.         old_mode = fg_getmode();
  427.         new_mode = fg_bestmode(320,200,1);
  428.  
  429.         if (new_mode < 0) {
  430.            printf("This program requires a 320 by 200 graphics mode.\n");
  431.            exit(1);
  432.            }
  433.  
  434.         fg_setmode(new_mode);
  435.  
  436.         fg_setcolor(15);
  437.         fg_text("I'm running in mode ",20);
  438.         sprintf(string,"%d.",new_mode);
  439.         fg_text(string,3);
  440.         fg_waitkey();
  441.  
  442.         fg_setmode(old_mode);
  443.         fg_reset();
  444.      }
  445.  
  446.      If your program will not support all PC and PS/2 video modes with the
  447. same resolution (for example, it will run in some but not all 320 by 200
  448. graphics modes), you may want to consider using the fg_testmode routine
  449. instead of fg_bestmode to check for available video modes.  You also may want
  450. to use fg_testmode to change the video mode precedence used by fg_bestmode.
  451. For example, mode 13 (EGA) is faster than mode 19 (MCGA), so you may want to
  452. consider giving EGA precedence over MCGA, especially if your program does not
  453. use more than 16 colors.
  454.  
  455.      Example 3-9 is similar to example 3-8, but it will only run in the 320
  456. by 200 EGA, MCGA, and CGA graphics modes (video modes 13, 19, and 4
  457. respectively).  The program uses fg_testmode to select its video mode.  Note
  458. the order of calls to fg_testmode gives EGA precedence over MCGA, and MCGA
  459. precedence over CGA.
  460.  
  461.                                  Example 3-9.
  462.  
  463.         #include <fastgraf.h>
  464.         #include <stdio.h>
  465.         #include <stdlib.h>
  466.         void main(void);
  467.  
  468.         void main()
  469.         {
  470.            int old_mode;
  471.            char string[4];
  472.  
  473.            old_mode = fg_getmode();
  474.  
  475.            if (fg_testmode(13,1))
  476.  
  477. 36  Fastgraph User's Guide
  478.  
  479.               fg_setmode(13);
  480.            else if (fg_testmode(19,1))
  481.               fg_setmode(19);
  482.            else if (fg_testmode(4,1))
  483.               fg_setmode(4);
  484.            else {
  485.               printf("This program requires an EGA, MCGA, or CGA.\n");
  486.               exit(1);
  487.               }
  488.  
  489.            fg_setcolor(15);
  490.            fg_text("I'm running in mode ",20);
  491.            sprintf(string,"%d.",getmode());
  492.            fg_text(string,3);
  493.            fg_waitkey();
  494.  
  495.            fg_setmode(old_mode);
  496.            fg_reset();
  497.         }
  498.  
  499.  
  500.  
  501. Summary of Video Initialization Routines
  502.  
  503.      This section summarizes the functional descriptions of the Fastgraph
  504. routines presented in this chapter.  More detailed information about these
  505. routines, including their arguments and return values, may be found in the
  506. Fastgraph Reference Manual.
  507.  
  508.      FG_AUTOMODE determines the graphics video mode that offers the most
  509. features for the user's display and adapter configuration.  The value it
  510. returns helps determine a suitable value to pass to the fg_setmode routine.
  511.  
  512.      FG_BESTMODE is similar to fg_automode, but it excludes video modes that
  513. do not offer the specified resolution and video page requirements.
  514.  
  515.      FG_CURSOR makes the text mode cursor visible or invisible.  This routine
  516. has no effect when used in a graphics mode.
  517.  
  518.      FG_EGACHECK returns information about the active EGA or VGA adapter and
  519. display.  It is useful in checking if the adapter has enough memory to run an
  520. EGA-specific program.
  521.  
  522.      FG_GETLINES returns the number of text rows per screen for the current
  523. video mode.
  524.  
  525.      FG_GETMODE returns the current video mode.  It is typically one of the
  526. first Fastgraph routines called in a program.  The value returned by
  527. fg_getmode can be retained to restore the original video mode when a program
  528. transfers control back to DOS.
  529.  
  530.      FG_RESET is generally the last Fastgraph routine called in a program.
  531. It only functions in text video modes.  When the ANSI.SYS driver is not
  532. loaded, fg_reset merely erases the screen.  When ANSI.SYS is loaded, fg_reset
  533. also restores any previously set screen attributes.
  534.                             Chapter 3:  Initializing the Video Environment  37
  535.  
  536.      FG_SETLINES extends an 80-column text mode to 25, 43, or 50 lines per
  537. screen.  This routine is only meaningful when running in 80-column text modes
  538. on EGA, VGA, or MCGA systems (in other cases it does nothing).
  539.  
  540.      FG_SETMODE establishes a video mode and initializes Fastgraph's internal
  541. parameters for that video mode.  It must be called before any Fastgraph
  542. routine that performs video output.  A program can call fg_setmode as many
  543. times as needed to switch between different video modes.
  544.  
  545.      FG_TESTMODE determines whether or not a specified video mode (with a
  546. given number of video pages) is available on the user's system.
  547. 38  Fastgraph User's Guide