home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 10: Diskmags / nf_archive_10.iso / MAGS / ST_USER / 1990 / USERSP90.MSA / TEXT_GEM.DOC < prev    next >
Text File  |  1990-07-25  |  5KB  |  110 lines
  1.                            ON THE RIGHT LINES
  2.  
  3.  
  4.          Exploring GEM's VDI line functions with Roland Waddilove
  5.  
  6.  
  7. GEM's virtual device interface, or VDI for short, is a powerful, yet very
  8. complex part of the operating system that all programmers must eventually get
  9. to grips with if they want to harness the power of the ST. The VDI handles all
  10. text and graphic output to the screen and last month we examined a host of
  11. related text functions that enable you to display characters in a variety of
  12. styles, sizes and colours.
  13.  
  14.     This month I'll move on to look at drawing lines, which might seem like a
  15. simple subject, but there's more to it than meets the eye. Last month's colour
  16. and mono test cards have been repeated on this month's disk because they
  17. contain some simple examples of drawing lines using the VDI.
  18.  
  19.     If you have a C compiler you can compile the two test cards and run them.
  20. (Any programming language that enables you to call GEM will use the same
  21. function calls so you can still follow this series even if you're a Pascal or
  22. BASIC user.) Here is the section of C code that produces the lines:
  23.  
  24. short y,i,j,line[4];
  25. vsl_color(handle,0);                    /* colour=white */
  26. vsl_width(handle,1);                    /* line width=1 pixel */
  27. for ( y=-1; y<2; y+=2 ) {
  28.      line[0] = 91;                      /* start x */
  29.      line[1] = 90 + y*32;               /* start y */
  30.      line[2] = line[0];                 /* end x */
  31.      line[3] = line[1] + 20;            /* end y */
  32.      for ( i=1; i<5; ++i )
  33.           for ( j=0; j<14; ++j ) {
  34.                v_pline(handle,2,line);  /* draw line */
  35.                line[0] += i;
  36.                line[2] += i;
  37.           }
  38. }
  39.  
  40.     The function that draws the line is called v_pline(). It doesn't simply
  41. draw a line between two coordinates, you pass an array or list of coordinates
  42. and it joins up the points with straight lines. If there are two points in the
  43. array a single straight line is drawn, but if there are three points then lines
  44. will be drawn from the first to the second and from the second to the third.
  45. There's no limit to the number of points you can pass in the array and you
  46. could easily arrange the points to make a triangle, rectangle or octagon. Any
  47. open or closed shape is possible.
  48.  
  49.     The VDI v_pline() function takes three parameters: the VDI handle, the
  50. number of points and the address of the array (or list) of coordinates. To draw
  51. a single line between two points in C you would set up a word array, store the
  52. coordinates in it and then call the VDI like:
  53.  
  54. short handle, line[4];
  55. ...
  56. line[0] = 0;
  57. line[1] = 10;
  58. line[2] = 50;
  59. line[3] = 100;
  60. v_pline(handle, 2, line);
  61.  
  62.     This short piece of code draws a line from 0,10 to 50,100. The number 2 in
  63. the function call tells the VDI that there are two pairs of coordinates.
  64.  
  65.     You can simply call the v_pline(handle,count,array) function straight away
  66. to draw a line, but there are several other parameters that can be set to
  67. produce a variety of effects and styles. Using vswr_mode(handle,mode) the
  68. writing mode can be set to replace (mode=1), transparent (mode=2), XOR (mode=3)
  69. or reverse transparent (mode=4).
  70.  
  71.     Lines can be drawn either solid or dashed, and there are several varieties
  72. of dashed lines. The type is chosen using vsl_type(handle, style where the
  73. value of style is in the range 1 to 7:
  74.  
  75. 1   solid          ---------------------------------------------
  76. 2   long dashed    ----------  ----------  ---------- ----------
  77. 3   dotted         --  --  --  --  --  --  --  --  --  --  --  --
  78. 4   dash-dot       ----------  --  ----------  --  ----------  --
  79. 5   dashed         -----    -----    -----   -----    -----    -----
  80. 6   dash-dot-dot   -----  --  --  -----  --  --  -----  --  --  -----
  81. 7   user defined using vsl_udsty(handle,pattern)
  82.  
  83.     Line type 7, as you can see, enables you to define your own pattern using
  84. the vsl_udsty(handle,pattern) VDI function. The pattern parameter is a 16-bit
  85. number whose bit pattern defines the style, so 0101010101010101 (21,845 in
  86. decimal) would be a fine dot pattern and 0011001100110011 (13,107 in decimal)
  87. would be a coarser dot pattern.
  88.  
  89.     Once you have set the drawing mode and line type, possibly user defined,
  90. you should set the line width by calling vsl_width(handle,width). For some
  91. strange reason the VDI will only draw lines with odd widths (measured in
  92. pixels) - 1, 3, 5, 7 and so on.
  93.  
  94.     Next you should set the colour using vsl_color(handle,colour) where the
  95. colour number ranges from 0 to 15. You must remember however, that you can only
  96. display two colours in monochrome (black and white), four in medium res and 16
  97. in low res.
  98.  
  99.     Every line has a start and a finish, and you can instruct the VDI to square
  100. off, round or draw arrows at either of the line ends. The VDI function used is
  101. vsl_ends(handle,beginning,end). The two parameters, beginning and end, can be
  102. zero (squared end), one (arrow end) or two (round end). All the parameters are
  103. 16-bit words.
  104.  
  105.     And that rounds up this month's look at the VDI's functions. See you next
  106. time with some more programming GEMs!
  107.  
  108.  
  109.  
  110.