home *** CD-ROM | disk | FTP | other *** search
/ The Devil's Doorknob BBS Capture (1996-2003) / devilsdoorknobbbscapture1996-2003.iso / Dloads / PROGRAMM / FGL112B.ZIP / USER11.DOC < prev    next >
Text File  |  1992-10-05  |  22KB  |  521 lines

  1.  
  2.  
  3. Chapter 11
  4.  
  5. Special Effects
  6. 200  Fastgraph User's Guide
  7.  
  8.  
  9. Overview
  10.  
  11.      This chapter will discuss the Fastgraph routines that help produce
  12. special visual effects.  These include the ability to dissolve the screen
  13. contents in small increments, scroll areas of the screen, and change the
  14. physical origin of the screen.  The accompanying example programs illustrate
  15. how to use these routines to produce some interesting effects.
  16.  
  17.  
  18. Screen Dissolving
  19.  
  20.      Screen dissolving is the process of replacing the entire screen contents
  21. in random small increments instead of all at once.  Fastgraph includes two
  22. routines, fg_fadeout and fg_fadein, for this purpose.  The fg_fadeout routine
  23. incrementally replaces the visual page contents with pixels of the current
  24. color, while fg_fadein incrementally replaces the visual page contents with
  25. the hidden page contents (that is, the page defined in the most recent call
  26. to fg_sethpage).  Both routines accept an integer argument that defines the
  27. delay between each incremental replacement.  A value of zero means to perform
  28. the replacement as quickly as possible, while 1 is slightly slower, 2 is
  29. slower yet, and so forth.  The fg_fadeout and fg_fadein routines have no
  30. effect in text video modes.
  31.  
  32.      Example 11-1 shows how to use the fg_fadeout routine.  The program,
  33. which runs in any graphics video mode, first fills the screen with a
  34. rectangle of color 2.  After waiting for a keystroke, the program
  35. incrementally replaces the screen contents with pixels of color 15 (the
  36. current color index when fg_fadeout is called).  After another keystroke, the
  37. program exits gracefully.
  38.  
  39.                                 Example 11-1.
  40.  
  41.                   #include <fastgraf.h>
  42.                   void main(void);
  43.  
  44.                   void main()
  45.                   {
  46.                      int old_mode;
  47.  
  48.                      old_mode = fg_getmode();
  49.                      fg_setmode(fg_automode());
  50.  
  51.                      fg_setcolor(2);
  52.                      fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  53.                      fg_waitkey();
  54.  
  55.                      fg_setcolor(15);
  56.                      fg_fadeout(0);
  57.                      fg_waitkey();
  58.  
  59.                      fg_setmode(old_mode);
  60.                      fg_reset();
  61.                   }
  62.  
  63.      Example 11-2 shows how to use the fg_fadein routine in any 320 by 200
  64. color graphics video mode.  The program first fills the screen with a
  65.                                              Chapter 11:  Special Effects  201
  66.  
  67. rectangle of color 2 and then fills video page 1 with a rectangle of color 1.
  68. After waiting for a keystroke, the program incrementally transfers the
  69. contents of page 1 to the visual page.  After the call to fg_fadein, both
  70. page 0 (the visual page) and page 1 (the hidden page) will contain rectangles
  71. of color 1 that fill the entire video page.  Finally, the program waits for
  72. another keystroke before returning to DOS.
  73.  
  74.                                 Example 11-2.
  75.  
  76.                 #include <fastgraf.h>
  77.                 #include <stdio.h>
  78.                 #include <stdlib.h>
  79.                 void main(void);
  80.  
  81.                 void main()
  82.                 {
  83.                    int new_mode, old_mode;
  84.  
  85.                    new_mode = fg_bestmode(320,200,2);
  86.                    if (new_mode < 0 || new_mode == 12) {
  87.                       printf("This program requires a 320 ");
  88.                       printf("x 200 color graphics mode.\n");
  89.                       exit(1);
  90.                       }
  91.                    old_mode = fg_getmode();
  92.                    fg_setmode(new_mode);
  93.                    fg_allocate(1);
  94.                    fg_sethpage(1);
  95.  
  96.                    fg_setcolor(2);
  97.                    fg_rect(0,319,0,199);
  98.                    fg_setpage(1);
  99.                    fg_setcolor(1);
  100.                    fg_rect(0,319,0,199);
  101.                    fg_waitkey();
  102.  
  103.                    fg_fadein(0);
  104.                    fg_waitkey();
  105.  
  106.                    fg_freepage(1);
  107.                    fg_setmode(old_mode);
  108.                    fg_reset();
  109.                 }
  110.  
  111.  
  112.      You also can produce some appealing visual effects by replacing the
  113. screen contents in a non-random fashion using the fg_restore or fg_transfer
  114. routines.  For example, you could copy the hidden page contents to the visual
  115. page with a through a series of concentric rectangular areas, each slightly
  116. larger than the previous, until the entire screen is copied.  Another
  117. interesting effect is to start around the screen perimeter and proceed toward
  118. the screen center, thus producing a "snake-like" effect.  Experimenting with
  119. such techniques may reveal other effects that suit your application.
  120. 202  Fastgraph User's Guide
  121.  
  122.  
  123. Scrolling
  124.  
  125.      Another useful effect is scrolling, and Fastgraph provides a routine
  126. that performs vertical scrolling within a given region of the active video
  127. page.  The fg_scroll routine scrolls a region defined in screen space or
  128. character space.  It can scroll up or down and offers two types of scrolling:
  129. circular and end-off.  In circular scrolling, rows that scroll off one edge
  130. of the defined region appear at its opposite edge.  In end-off scrolling,
  131. such rows are simply wind up above or below the scrolling area.  The
  132. following diagrams illustrate the two types of scrolling.
  133.  
  134.                 end-off scrolling            circular scrolling
  135.  
  136.               before         after          before         after
  137.  
  138.                                C                             B
  139.                  A                             A
  140.  
  141.                                A                             A
  142.                  B                             B
  143.  
  144.      In these diagrams, the area bounded by the double lines is the scrolling
  145. region, as specified in the call to fg_scroll.  Also, the scrolling direction
  146. is assumed to be down (that is, toward the bottom of the screen), and the
  147. number of rows to scroll is the height of the area designated B.  The number
  148. of rows to scroll is often called the scrolling increment.
  149.  
  150.      For the end-off scrolling example, the scrolling operation transfers
  151. region A downward so part of it is copied into area B.  The area C (which is
  152. the same size as area B) at the top of the scrolling region is filled with
  153. pixels of the current color index (as defined in the most recent call to
  154. fg_setcolor), and the original contents of area B are lost.  The circular
  155. scrolling example also copies region A downward into the original area B.
  156. Unlike end-off scrolling, however, circular scrolling preserves the area B by
  157. copying it to the opposite edge of the scrolling region.
  158.  
  159.      The fg_scroll routine takes six arguments.  The first four define the
  160. scrolling region in the order minimum x coordinate, maximum x coordinate,
  161. minimum y coordinate, and maximum y coordinate.  In graphics video modes, the
  162. x coordinates are extended by byte boundaries (see page 174) if needed.  The
  163. fifth argument is the scrolling increment.  It specifies the number of rows
  164. to scroll.  If it is positive, the scrolling direction is toward the bottom
  165. of the screen; if it is negative, the scrolling direction is toward the top
  166. of the screen.  The sixth and final argument specifies the scroll type.  If
  167. this value is zero, the scroll will be circular; if it is any other value,
  168. the scroll will be end-off.  If the scroll type is circular, Fastgraph will
  169. use the hidden page (as defined in the most recent call to fg_sethpage) as a
  170. workspace (more specifically, the area bounded by the scrolling region
  171. extremes on the hidden page will be used).  We'll now present three example
  172. programs that use the fg_scroll routine.
  173.  
  174.      Example 11-3 runs in any 320 by 200 graphics video mode.  The program
  175. displays two lines of text ("line one" and "line two") in the upper left
  176. corner of the screen against a white background.  It then uses the fg_scroll
  177. routine to move the second line down four pixel rows using an end-off scroll.
  178. After waiting for a keystroke, the program again uses fg_scroll to move the
  179.                                              Chapter 11:  Special Effects  203
  180.  
  181. text back to its original position.  Note especially how the fg_setcolor
  182. routine appears before the first call to fg_scroll to replace the "scrolled
  183. off" rows with pixels of color 15, thus preserving the white background.
  184.  
  185.                                 Example 11-3.
  186.  
  187.                 #include <fastgraf.h>
  188.                 #include <stdio.h>
  189.                 #include <stdlib.h>
  190.                 void main(void);
  191.  
  192.                 void main()
  193.                 {
  194.                    int new_mode, old_mode;
  195.  
  196.                    new_mode = fg_bestmode(320,200,1);
  197.                    if (new_mode < 0 || new_mode == 12) {
  198.                       printf("This program requires a 320 ");
  199.                       printf("x 200 color graphics mode.\n");
  200.                       exit(1);
  201.                       }
  202.                    old_mode = fg_getmode();
  203.                    fg_setmode(new_mode);
  204.  
  205.                    fg_setcolor(15);
  206.                    fg_rect(0,319,0,199);
  207.                    fg_setcolor(10);
  208.                    fg_text("line one",8);
  209.                    fg_locate(1,0);
  210.                    fg_text("line two",8);
  211.                    fg_waitkey();
  212.  
  213.                    fg_setcolor(15);
  214.                    fg_scroll(0,63,8,15,4,1);
  215.                    fg_waitkey();
  216.                    fg_scroll(0,63,12,19,-4,1);
  217.                    fg_waitkey();
  218.  
  219.                    fg_setmode(old_mode);
  220.                    fg_reset();
  221.                 }
  222.  
  223.      Example 11-4 is similar to example 11-3, but it runs in the 80-column
  224. color text mode (mode 3).  In text modes, we cannot scroll half a character
  225. row (four pixels) as in example 11-3, so the program scrolls the minimum one
  226. row instead.
  227.  
  228.                                 Example 11-4.
  229.  
  230.                          #include <fastgraf.h>
  231.                          void main(void);
  232.  
  233.                          void main()
  234.                          {
  235.                             int old_mode;
  236.  
  237. 204  Fastgraph User's Guide
  238.  
  239.                             old_mode = fg_getmode();
  240.                             fg_setmode(3);
  241.                             fg_cursor(0);
  242.  
  243.                             fg_setcolor(7);
  244.                             fg_rect(0,79,0,24);
  245.                             fg_setattr(10,7,0);
  246.                             fg_text("line one",8);
  247.                             fg_locate(1,0);
  248.                             fg_text("line two",8);
  249.                             fg_waitkey();
  250.  
  251.                             fg_setcolor(7);
  252.                             fg_scroll(0,7,1,1,1,1);
  253.                             fg_waitkey();
  254.                             fg_scroll(0,7,2,2,-1,1);
  255.                             fg_waitkey();
  256.  
  257.                             fg_setmode(old_mode);
  258.                             fg_reset();
  259.                          }
  260.  
  261.      Example 11-5, the final scrolling example, demonstrates a circular
  262. scroll.  The program runs in any 320 by 200 color graphics video mode; note
  263. the use of video page 1 for the workspace required when the fg_scroll routine
  264. performs a circular scroll.  The program first fills the screen with a light
  265. blue rectangle (cyan in CGA), displays a smaller white rectangle in the
  266. center of the screen, and then uses fg_move, fg_draw, and fg_paint to display
  267. a light green star (magenta in CGA) within the white rectangle.  The program
  268. executes a while loop to scroll the star upward in four pixel increments.
  269. Because the scroll is circular, rows of the star that "scroll off" the top
  270. edge of the white rectangle (whose height is the same as the scrolling
  271. region) reappear at its bottom edge.  The use of fg_waitfor within the loop
  272. simply slows down the scroll.  The scrolling continues until any key is
  273. pressed.
  274.  
  275.                                 Example 11-5.
  276.  
  277.                 #include <conio.h>
  278.                 #include <fastgraf.h>
  279.                 #include <stdio.h>
  280.                 #include <stdlib.h>
  281.                 void main(void);
  282.  
  283.                 void main()
  284.                 {
  285.                    int new_mode, old_mode;
  286.  
  287.                    new_mode = fg_bestmode(320,200,2);
  288.                    if (new_mode < 0 || new_mode == 12) {
  289.                       printf("This program requires a 320 ");
  290.                       printf("x 200 color graphics mode.\n");
  291.                       exit(1);
  292.                       }
  293.                    old_mode = fg_getmode();
  294.                    fg_setmode(new_mode);
  295.  
  296.                                              Chapter 11:  Special Effects  205
  297.                    fg_allocate(1);
  298.                    fg_sethpage(1);
  299.  
  300.                    fg_setcolor(9);
  301.                    fg_rect(0,319,0,199);
  302.                    fg_setcolor(15);
  303.                    fg_rect(132,188,50,150);
  304.  
  305.                    fg_setcolor(10);
  306.                    fg_move(160,67);
  307.                    fg_draw(175,107);
  308.                    fg_draw(140,82);
  309.                    fg_draw(180,82);
  310.                    fg_draw(145,107);
  311.                    fg_draw(160,67);
  312.                    fg_paint(160,77);
  313.                    fg_paint(150,87);
  314.                    fg_paint(160,87);
  315.                    fg_paint(170,87);
  316.                    fg_paint(155,97);
  317.                    fg_paint(165,97);
  318.  
  319.                    while (kbhit() == 0) {
  320.                       fg_waitfor(1);
  321.                       fg_scroll(136,184,50,150,-4,0);
  322.                       }
  323.                    fg_waitkey();
  324.  
  325.                    fg_freepage(1);
  326.                    fg_setmode(old_mode);
  327.                    fg_reset();
  328.                 }
  329.  
  330.  
  331. Changing the Screen Origin
  332.  
  333.      Fastgraph includes two routines for changing the screen origin.  By
  334. changing the screen origin, we simply mean defining the (x,y) coordinate of
  335. the upper left corner of the display area.  The fg_pan routine performs this
  336. function in screen space, while the fg_panw routine does in world space.
  337. Neither routine changes the graphics cursor position.
  338.  
  339.      Each of these routines has two arguments that specify the x and y
  340. coordinates of the screen origin.  For the fg_pan routine, the arguments are
  341. integer quantities.  For the fg_panw routine, they are floating point
  342. quantities.
  343.  
  344.      In the native EGA and VGA graphics modes (modes 13 through 18), you can
  345. set the screen origin to any (x,y) coordinate position (that is, to any
  346. pixel).  In the other graphics modes, certain restrictions exist, as imposed
  347. by specific video hardware.  These constraints limit the coordinate positions
  348. that can be used as the screen origin.  Fastgraph compensates for these
  349. restrictions by reducing the specified x and y coordinates to values that are
  350. acceptable to the current video mode, as shown in the following table.
  351. 206  Fastgraph User's Guide
  352.  
  353.  
  354.                            x will be reduced  y will be reduced
  355.                video mode  to a multiple of:  to a multiple of:
  356.  
  357.                   4, 5              8                  2
  358.                     6              16                  2
  359.                     9               4                  4
  360.                    11               8                  4
  361.                    12               4                2 or 3
  362.                 19 to 23            4                  1
  363.  
  364. For example, in modes 4 and 5, the x coordinate will be reduced to a multiple
  365. of 8 pixels, and the y coordinate will be reduced to a multiple of 2 pixels.
  366. In the Hercules low resolution mode (mode 12), the y coordinate reduction
  367. depends on whether or not the specified pixel row is scan doubled.
  368.  
  369.      Example 11-6 shows a useful effect that can be made with the fg_pan or
  370. fg_panw routines.  This program uses the fg_automode routine to select a
  371. video mode and then draws an unfilled rectangle in color 15 (bright white).
  372. The top and bottom sides of the rectangle are intentionally drawn just
  373. smaller than the physical screen size.  After waiting for a keystroke, the
  374. program uses a for loop to make the rectangle jiggle up and down.  The
  375. rectangle moves because the fg_pan routine is called inside the loop to
  376. switch the screen origin between the rectangle's upper left corner and the
  377. original origin.  Note also the use of the fg_waitfor routine to cause slight
  378. delays after each call to fg_pan.  If we didn't use fg_waitfor, the changing
  379. of the origin would occur so rapidly we wouldn't notice the effect.  Finally,
  380. the program restores the original video mode and screen attributes before
  381. returning to DOS.
  382.  
  383.                                 Example 11-6.
  384.  
  385.                  #include <fastgraf.h>
  386.                  #include <stdio.h>
  387.                  #include <stdlib.h>
  388.                  void main(void);
  389.  
  390.                  #define DELAY 2
  391.                  #define JUMP  4
  392.  
  393.                  void main()
  394.                  {
  395.                     int i;
  396.                     int old_mode;
  397.  
  398.                     old_mode = fg_getmode();
  399.                     fg_setmode(fg_automode());
  400.  
  401.                     fg_setcolor(15);
  402.                     fg_move(0,JUMP);
  403.                     fg_draw(fg_getmaxx(),JUMP);
  404.                     fg_draw(fg_getmaxx(),fg_getmaxy()-JUMP);
  405.                     fg_draw(0,fg_getmaxy()-JUMP);
  406.                     fg_draw(0,JUMP);
  407.                     fg_waitkey();
  408.  
  409.                                              Chapter 11:  Special Effects  207
  410.  
  411.                     for (i = 0; i < 6; i++) {
  412.                        fg_pan(0,JUMP);
  413.                        fg_waitfor(DELAY);
  414.                        fg_pan(0,0);
  415.                        fg_waitfor(DELAY);
  416.                        }
  417.  
  418.                     fg_setmode(old_mode);
  419.                     fg_reset();
  420.                  }
  421.  
  422.      The real power of the fg_pan routine becomes clear when it is used with
  423. the fg_resize routine to perform smooth panning.  Recall from Chapter 7 that
  424. fg_resize changes the video page dimensions in native EGA graphics modes
  425. (modes 13 through 16), native VGA graphics modes (modes 17 and 18), and the
  426. extended VGA graphics modes (modes 20 through 23).  We'll now present an
  427. example that shows how to use these two routines to perform panning in the
  428. low-resolution EGA graphics mode (mode 13).  The method it uses also would
  429. work in any mode that supports video page resizing.
  430.  
  431.      Example 11-7 begins by establishing the video mode and then immediately
  432. calls fg_resize to increase the video page size to 640 x 400 pixels.  Thus,
  433. the video page is now four times its original size.  Following this, the
  434. program fills the page (the entire page, not just what is displayed) with a
  435. bright green rectangle with a white border around it.  It then displays the
  436. message "Press arrow keys to pan" as close as possible to the center of the
  437. page.
  438.  
  439.      The main part of the program is a loop that accepts keystrokes and then
  440. calls fg_pan to perform the panning one pixel at a time.  When you press any
  441. of the four arrow keys, the program adjusts the x and y coordinates for the
  442. screen origin as directed.  For example, pressing the up arrow key scrolls
  443. the screen upward one pixel.  Note that when we reach the edge of the video
  444. page, the program prevents further scrolling in that direction.  This process
  445. continues until you press the Esc key, at which time the program restores the
  446. original video mode and screen attributes before exiting.
  447.  
  448.                                 Example 11-7.
  449.  
  450.                   #include <fastgraf.h>
  451.                   void main(void);
  452.  
  453.                   void main()
  454.                   {
  455.                      unsigned char key, aux;
  456.                      int old_mode;
  457.                      int x, y;
  458.  
  459.                      old_mode = fg_getmode();
  460.                      fg_setmode(13);
  461.                      fg_resize(640,400);
  462.  
  463.                      fg_setcolor(2);
  464.                      fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  465.                      fg_setcolor(15);
  466.                      fg_box(0,fg_getmaxx(),0,fg_getmaxy());
  467.  
  468. 208  Fastgraph User's Guide
  469.  
  470.                      fg_locate(24,28);
  471.                      fg_text("Press arrow keys to pan.",24);
  472.  
  473.                      x = 0;
  474.                      y = 0;
  475.  
  476.                      do {
  477.                         fg_getkey(&key,&aux);
  478.                         if (aux == 72 && y < 200)
  479.                            y++;
  480.                         else if (aux == 75 && x < 320)
  481.                            x++;
  482.                         else if (aux == 77 && x > 0)
  483.                            x--;
  484.                         else if (aux == 80 && y > 0)
  485.                            y--;
  486.                         fg_pan(x,y);
  487.                      } while (key != 27);
  488.  
  489.                      fg_setmode(old_mode);
  490.                      fg_reset();
  491.                   }
  492.  
  493.  
  494.  
  495. Summary of Special Effects Routines
  496.  
  497.      This section summarizes the functional descriptions of the Fastgraph
  498. routines presented in this chapter.  More detailed information about these
  499. routines, including their arguments and return values, may be found in the
  500. Fastgraph Reference Manual.
  501.  
  502.      FG_FADEIN incrementally replaces the visual page contents with the
  503. hidden page contents.  This routine has no effect in text video modes.
  504.  
  505.      FG_FADEOUT incrementally replaces the visual page contents with pixels
  506. of the current color.  This routine has no effect in text video modes.
  507.  
  508.      FG_PAN changes the screen origin (the upper left corner of the screen)
  509. to the specified screen space coordinates.  This routine has no effect in
  510. text video modes.
  511.  
  512.      FG_PANW is the world space version of the fg_pan routine.
  513.  
  514.      FG_RESIZE changes the dimensions of a video page in EGA and VGA graphics
  515. modes.
  516.  
  517.      FG_SCROLL vertically scrolls a region of the active video page.  The
  518. scrolling may be done either up or down, using either an end-off or circular
  519. method.  Circular scrolling uses part of the hidden page as a temporary
  520. workspace.
  521.