home *** CD-ROM | disk | FTP | other *** search
/ C++ Games Programming / CPPGAMES.ISO / fgl / fglight / manuals.arj / USER04.DOC < prev    next >
Text File  |  1995-02-06  |  18KB  |  453 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Chapter 4
  8.  
  9.  
  10.  
  11.  
  12.  
  13. Coordinate Systems                                                             
  14. 58   Fastgraph User's Guide
  15.  
  16.  
  17. Overview
  18.  
  19.      Fastgraph uses three coordinate systems to perform text and graphics
  20. output -- character space, screen space, and world space. Character space is
  21. used in text modes and optionally for displaying character strings in graphics
  22. modes. Screen space is the basic coordinate system for graphics video modes
  23. and uses the screen's physical device coordinates. Viewports are an extension
  24. of screen space that let you assign an alternate integer-based coordinate
  25. system to rectangular subsets of the screen. Finally, world space is a user-
  26. definable coordinate system for graphics modes that uses floating point
  27. values. The world space coordinate system is not available in Fastgraph/Light.
  28.  
  29.  
  30. Character Space
  31.  
  32.      The coordinate system used for displaying characters is called character
  33. space. Fastgraph uses character space for displaying characters in both text
  34. and graphics video modes (you can also use screen space to display characters
  35. in graphics modes). Character space can be thought of as a grid of rows and
  36. columns, with each cell in the grid holding one character. Each cell is
  37. identified by its unique (row,column) integer coordinates. The rows and
  38. columns are numbered starting at zero; the origin is always the upper left
  39. corner of the screen. For example, in the 80-column by 25-row text modes (2,
  40. 3, and 7), the default (row,column) coordinates of the screen corners are
  41. shown in the following diagram.
  42.  
  43.  
  44.                             (0,0)           (0,79)
  45.  
  46.  
  47.  
  48.                             (24,0)         (24,79)
  49.  
  50.  
  51. The number of rows and columns depends on the video mode, as shown in the
  52. following table. For graphics modes, the table also includes the width and
  53. height in pixels of a character cell.
  54.  
  55.                            Mode   No. of No. of Char. Char.
  56.                           Number  Columns Rows  WidthHeight
  57.  
  58.                              0      40     25
  59.                              1      40     25
  60.                              2      80     25
  61.                              3      80     25
  62.                              4      40     25     8     8
  63.                              5      40     25     8     8
  64.                              6      80     25     8     8
  65.                              7      80     25
  66.                              9      40     25     8     8
  67.                             11      80     25     9    14
  68.                             12      40     25     8     8
  69.                             13      40     25     8     8
  70.                             14      80     25     8     8
  71.                             15      80     25     8    14                      
  72.                                            Chapter 4:  Coordinate Systems   59
  73.  
  74.                             16      80     25     8    14
  75.                             17      80     30     8    16
  76.                             18      80     30     8    16
  77.                             19      40     25     8     8
  78.                             20      40     25     8     8
  79.                             21      40     50     8     8
  80.                             22      40     30     8     8
  81.                             23      40     60     8     8
  82.                             24      80     25     8    16
  83.                             25      80     30     8    16
  84.                             26      100    37     8    16
  85.                             27      128    48     8    16
  86.                             28      100    37     8    16
  87.                             29      128    48     8    16
  88.  
  89.      Fastgraph includes two routines, fg_getmaxx and fg_getmaxy, that
  90. respectively return the maximum column and row numbers in text modes. Example
  91. 4-1 demonstrates these two routines in a text mode. The program uses
  92. fg_getmaxx and fg_getmaxy to obtain the maximum column and row numbers in mode
  93. 3. It then displays these values (79 and 24).
  94.  
  95.                                  Example 4-1.
  96.  
  97.                      #include <fastgraf.h>
  98.                      #include <stdio.h>
  99.                      void main(void);
  100.  
  101.                      void main()
  102.                      {
  103.                         int max_col;
  104.                         int max_row;
  105.                         int mode;
  106.  
  107.                         fg_initpm();
  108.                         mode = fg_getmode();
  109.                         fg_setmode(3);
  110.  
  111.                         max_col = fg_getmaxx();
  112.                         max_row = fg_getmaxy();
  113.  
  114.                         fg_setmode(mode);
  115.                         fg_reset();
  116.  
  117.                         printf("Last col = %d\n",max_col);
  118.                         printf("Last row = %d\n",max_row);
  119.                      }
  120.  
  121.  
  122. Screen Space
  123.  
  124.      Screen space is one of two available coordinate systems in graphics
  125. modes. It uses the physical device coordinates. Screen space can be thought of
  126. as a grid of rows and columns, with each unit in the grid holding one pixel.
  127. Each pixel is identified by its unique (x,y) integer coordinates. The pixel
  128. rows and columns are numbered starting at zero; the origin is always the upper 
  129. 60   Fastgraph User's Guide
  130.  
  131. left corner of the screen. For example, in the 320x200 graphics modes, the
  132. (x,y) coordinates of the screen corners are shown in the following diagram.
  133.  
  134.  
  135.                             (0,0)          (319,0)
  136.  
  137.  
  138.  
  139.                             (0,199)      (319,199)
  140.  
  141.  
  142.      The Fastgraph routines fg_getmaxx and fg_getmaxy return the maximum x and
  143. y screen coordinates when used in graphics modes, as shown in example 4-2. The
  144. program uses fg_getmaxx and fg_getmaxy to obtain the maximum x and y
  145. coordinates in the standard VGA/MCGA 256-color graphics mode (mode 19). It
  146. then displays these values (319 and 199).
  147.  
  148.                                  Example 4-2.
  149.  
  150.                        #include <fastgraf.h>
  151.                        #include <stdio.h>
  152.                        void main(void);
  153.  
  154.                        void main()
  155.                        {
  156.                           int maxx;
  157.                           int maxy;
  158.                           int mode;
  159.  
  160.                           fg_initpm();
  161.                           mode = fg_getmode();
  162.                           fg_setmode(19);
  163.  
  164.                           maxx = fg_getmaxx();
  165.                           maxy = fg_getmaxy();
  166.  
  167.                           fg_setmode(mode);
  168.                           fg_reset();
  169.  
  170.                           printf("(%d,%d)\n",maxx,maxy);
  171.                        }
  172.  
  173.  
  174. Viewports
  175.  
  176.      Viewports provide an alternate integer-based coordinate system for
  177. referencing pixels. Fastgraph includes routines to create a viewport, return
  178. the viewport limits, and convert viewport coordinates to their screen space
  179. values.
  180.  
  181.      A viewport definition consists of its extremes in "viewport space" and
  182. the corresponding limits in screen space. The fg_setview routine defines a
  183. viewport. Its first four parameters represent the minimum x, maximum x,
  184. minimum y, and maximum y viewport coordinates, and its last four parameters
  185. represent the corresponding screen space pixel values defining the viewport's
  186. physical size and location. For example, the call                              
  187.                                            Chapter 4:  Coordinate Systems   61
  188.  
  189.  
  190.                     fg_setview(100,739,100,499,0,159,0,99);
  191.  
  192. would create a 640x400 viewport in the upper left corner of a 320x200 screen.
  193. The viewport's coordinates would range from 100 to 739 horizontally and 100 to
  194. 499 vertically. In other words, the viewport coordinate (100,100) would map to
  195. the screen space pixel (0,0). The following diagram illustrates this viewport.
  196. The viewport space coordinates appear in boldface, while the other values are
  197. the equivalent screen space coordinates.
  198.  
  199.                   (100,100)  (739,100)
  200.  
  201.                   (0,0)        (159,0)               (319,0)
  202.  
  203.  
  204.                   (0,99)      (159,99)
  205.  
  206.                   (100,499)  (739,499)
  207.  
  208.  
  209.                   (0,199)                          (319,199)
  210.  
  211.  
  212. Fastgraph's fg_getview routine returns the current viewport limits and
  213. corresponding screen space limits, as defined in the most recent call to
  214. fg_setview.
  215.  
  216.      Once you've defined a viewport, the fg_xview and fg_yview functions
  217. translate viewport coordinates to their screen space equivalents. The
  218. translated values can then be passed to any Fastgraph routine that expects
  219. screen space coordinates. For example, Fastgraph's fg_rect routine draws a
  220. filled rectangle in screen space. If you wanted to fill the viewport defined
  221. above with color 10 pixels, you could do this as follows:
  222.  
  223.        fg_setcolor(10);
  224.        fg_rect(fg_xview(100),fg_xview(739),fg_yview(100),fg_yview(499));
  225.  
  226.      Example 4-3 demonstrates a simple use of viewports in the standard
  227. 320x200 VGA/MCGA 256-color graphics mode. After filling the screen with white
  228. (color 15) pixels, it sets up a viewport in the upper left quadrant of the
  229. screen and uses fg_rect to fill it with light blue (color 9) pixels. It then
  230. defines three new viewports in the other screen quadrants, similarly filling
  231. the upper right quadrant with light green (color 10) pixels, the lower left
  232. quadrant with light cyan (color 11) pixels, and finally the lower right
  233. quadrant with light red (color 12) pixels. Note how the same viewport
  234. coordinates are used to fill the viewport in each case; only the viewport
  235. position changes.
  236.  
  237.                                  Example 4-3.
  238.  
  239.        #include <fastgraf.h>
  240.        void main(void);
  241.  
  242.        void main()
  243.        {
  244.           int mode;                                                            
  245. 62   Fastgraph User's Guide
  246.  
  247.  
  248.           fg_initpm();
  249.           mode = fg_getmode();
  250.           fg_setmode(19);
  251.           fg_setcolor(15);
  252.           fg_rect(0,319,0,199);
  253.           fg_waitkey();
  254.  
  255.           fg_setview(0,639,0,399,0,159,0,99);
  256.           fg_setcolor(9);
  257.           fg_rect(fg_xview(0),fg_xview(639),fg_yview(0),fg_yview(399));
  258.           fg_waitkey();
  259.  
  260.           fg_setview(0,639,0,399,160,319,0,99);
  261.           fg_setcolor(10);
  262.           fg_rect(fg_xview(0),fg_xview(639),fg_yview(0),fg_yview(399));
  263.           fg_waitkey();
  264.  
  265.           fg_setview(0,639,0,399,0,159,100,199);
  266.           fg_setcolor(11);
  267.           fg_rect(fg_xview(0),fg_xview(639),fg_yview(0),fg_yview(399));
  268.           fg_waitkey();
  269.  
  270.           fg_setview(0,639,0,399,160,319,100,199);
  271.           fg_setcolor(12);
  272.           fg_rect(fg_xview(0),fg_xview(639),fg_yview(0),fg_yview(399));
  273.           fg_waitkey();
  274.  
  275.           fg_setmode(mode);
  276.           fg_reset();
  277.        }
  278.  
  279.  
  280.      To make a viewport a "true" viewport, it is often desirable to establish
  281. clipping limits at the viewport's extremes. This way, Fastgraph's functions
  282. that support clipping will only draw within the viewport itself. The following
  283. call to fg_setclip will establish the desired clipping limits:
  284.  
  285.      fg_setclip(fg_xview(100),fg_xview(739),fg_yview(100),fg_yview(499));
  286.  
  287. The fg_setclip routine will be described in more detail in Chapter 6.
  288.  
  289.  
  290. World Space
  291.  
  292.      World space is the other available coordinate system in graphics modes.
  293. It utilizes user-defined floating point coordinates. Fastgraph translates
  294. world space coordinates into physical device coordinates (screen space), and
  295. because of this it is somewhat slower than using screen space. World space can
  296. be thought of as a standard cartesian plane extending from the lower left
  297. corner of the screen.  The world space vertical orientation is thus inverted
  298. relative to screen space and viewports.
  299.  
  300.      Any program that uses world space coordinates must first initialize
  301. Fastgraph's internal world space parameters. The Fastgraph routine fg_initw is 
  302.                                            Chapter 4:  Coordinate Systems   63
  303.  
  304. provided for this purpose. The fg_initw routine has no arguments and must be
  305. called before any other routine that uses world space coordinates.
  306.  
  307.      The next step in using world space is to use the Fastgraph routine
  308. fg_setworld to define the world space coordinates of the screen edges. The
  309. fg_setworld routine has four floating-point arguments -- the minimum x
  310. coordinate (left edge), the maximum x coordinate (right edge), the minimum y
  311. coordinate (bottom edge), and the maximum y coordinate (top edge). For
  312. example, if you define the world space coordinates with the statement
  313.  
  314.                        fg_setworld(-10.0,10.0,0.0,2.5);
  315.  
  316. the (x,y) coordinates of the screen corners would be defined as shown in the
  317. following diagram.
  318.  
  319.  
  320.                             (-10.0,2.5) (10.0,2.5)
  321.  
  322.  
  323.  
  324.                             (-10.0,0.0) (10.0,0.0)
  325.  
  326.  
  327. Fastgraph includes a routine fg_getworld that returns the world space extremes
  328. as defined in the most recent call to fg_setworld.
  329.  
  330.      Example 4-4 uses fg_setworld and fg_getworld to illustrate an interesting
  331. application of world space. This program calls another routine named redraw
  332. (not shown) that erases the screen and draws a certain image using world space
  333. coordinates. The program draws the image, waits for a keystroke, reduces the
  334. world space by a factor of two in each direction, and then draws the image
  335. again. This produces a zoom effect in which the image appears twice as large
  336. as it was originally.
  337.  
  338.                                  Example 4-4.
  339.  
  340.               #include <fastgraf.h>
  341.               #include <stdio.h>
  342.               #include <stdlib.h>
  343.               void main(void);
  344.               void redraw(void);
  345.  
  346.               void main()
  347.               {
  348.                  int new_mode, old_mode;
  349.                  double xmin, xmax, ymin, ymax;
  350.  
  351.                  fg_initpm();
  352.                  old_mode = fg_getmode();
  353.                  new_mode = fg_automode();
  354.  
  355.                  if (new_mode == 0) {
  356.                     printf("This program requires graphics.\n");
  357.                     exit(1);
  358.                     }                                                          
  359. 64   Fastgraph User's Guide
  360.  
  361.                  fg_setmode(new_mode);
  362.                  fg_initw();
  363.  
  364.                  fg_setworld(0.0,40.0,0.0,30.0);
  365.                  redraw();
  366.                  fg_waitkey();
  367.  
  368.                  fg_getworld(&xmin,&xmax,&ymin,&ymax);
  369.                  fg_setworld(0.0,xmax*0.5,0.0,ymax*0.5);
  370.                  redraw();
  371.                  fg_waitkey();
  372.  
  373.                  fg_setmode(old_mode);
  374.                  fg_reset();
  375.               }
  376.  
  377.  
  378.  
  379. Conversion Routines
  380.  
  381.      Sometimes it's necessary to convert coordinates between character space,
  382. screen space, and world space. Fastgraph includes eight conversion routines,
  383. four for x coordinates and four for y coordinates, to perform such
  384. conversions. These routines return the translated coordinate as their function
  385. value.
  386.  
  387.      The fg_xalpha and fg_yalpha routines convert screen space coordinates to
  388. character space. The fg_xalpha routine converts a screen space x coordinate to
  389. the character space column that contains the coordinate. Similarly, the
  390. fg_yalpha routine converts a screen space y coordinate to the character space
  391. row that contains the coordinate.
  392.  
  393.      The fg_xconvert and fg_yconvert routines convert character space
  394. coordinates to screen space. The fg_xconvert routine converts a character
  395. space column to the screen space coordinate of its leftmost pixel. Similarly,
  396. the fg_yconvert routine converts a character space row to the screen space
  397. coordinate of its top (lowest-numbered) pixel.
  398.  
  399.      The fg_xscreen and fg_yscreen routines convert world space coordinates to
  400. screen space. The fg_xscreen routine translates x coordinates, while the
  401. fg_yscreen routine translates y coordinates. Conversely, the fg_xworld and
  402. fg_yworld routines convert screen space coordinates to world space. The
  403. fg_xworld routine translates x coordinates, while the fg_yworld routine
  404. translates y coordinates.
  405.  
  406.  
  407. Summary of Coordinate Routines
  408.  
  409.      This section summarizes the functional descriptions of the Fastgraph
  410. routines presented in this chapter. More detailed information about these
  411. routines, including their arguments and return values, may be found in the
  412. Fastgraph Reference Manual.
  413.  
  414.      FG_GETMAXX returns the maximum x coordinate in screen space when used in
  415. a graphics mode. It returns the maximum column number in character space when
  416. used in a text mode.                                                           
  417.                                            Chapter 4:  Coordinate Systems   65
  418.  
  419.  
  420.      FG_GETMAXY returns the maximum y coordinate in screen space when used in
  421. a graphics mode. It returns the maximum row number in character space when
  422. used in a text mode.
  423.  
  424.      FG_GETVIEW returns the current viewport limits and their screen space
  425. equivalents, as defined in the most recent call to fg_setview.
  426.  
  427.      FG_GETWORLD returns the current world space limits, as defined in the
  428. most recent call to fg_setworld.
  429.  
  430.      FG_INITW initializes Fastgraph's internal parameters for world space.
  431. This routine must be called once, before any other routine that uses world
  432. coordinates.
  433.  
  434.      FG_SETVIEW defines a viewport with the specified extremes at the
  435. specified screen space position.
  436.  
  437.      FG_SETWORLD defines the world space coordinates that correspond to the
  438. physical edges of the screen.
  439.  
  440.      FG_XALPHA and FG_YALPHA convert screen space coordinates to character
  441. space.
  442.  
  443.      FG_XCONVERT and FG_YCONVERT convert character space coordinates to screen
  444. space.
  445.  
  446.      FG_XSCREEN and FG_YSCREEN convert world space coordinates to screen
  447. space.
  448.  
  449.      FG_XVIEW and FG_YVIEW convert viewport coordinates to screen space.
  450.  
  451.      FG_XWORLD and FG_YWORLD convert screen space coordinates to world space.  
  452. 66   Fastgraph User's Guide
  453.