home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 10: Diskmags / nf_archive_10.iso / MAGS / ST_USER / 1990 / USEROC90.MSA / TEXT_GEM.DOC < prev    next >
Text File  |  1990-08-19  |  8KB  |  161 lines
  1.                              GEM  PROGRAMMING
  2.  
  3.  
  4.         Roland Waddilove  continues  his  exploration of the ST's
  5.         almost impenetrable virtual device interface, this month,
  6.         shedding  some  light  on rectangles  and  fill  patterns
  7.  
  8.  
  9. Those of you who have been following this series from the start (on the July
  10. '90 cover disk), will be familiar with the TV/monitor test card. This was
  11. written to demonstrate some of the VDI's most common functions. The source code
  12. is repeated yet again on this month's disk - it still contains functions that
  13. we have yet to explore.
  14.  
  15.     This month I'll be looking at the various VDI functions for drawing
  16. rectangles and filling them with patterns. There are four that you need to
  17. remember:
  18.  
  19. -----------------------------------------------------------------------
  20.     FUNCTION                         RESULT
  21. -----------------------------------------------------------------------
  22.     vr_recfl(handle,xyarray)         Draw a filled rectangle
  23.     v_bar(handle,xyarray)            Draw a filled rectangle
  24.     v_rbox(handle,xyarray)           Draw a rounded rectangle
  25.     v_rfbox(handle,xyarray)          Draw a filled rounded rectangle
  26. -----------------------------------------------------------------------
  27.  
  28.     Notice that the parameters are always the same - the VDI handle, followed
  29. by 'xyarray'. The 'xyarray' parameter is a short (16 bit) pointer to an array
  30. which holds the coordinates of the top left corner and bottom right corner. As
  31. with previous VDI functions we have looked at, there are dozens of parameters
  32. which have to be set before you can call one of these rectangle functions.
  33. Let's take a look at them.
  34.  
  35.     The first thing you must decide is how you want the rectangle to be drawn,
  36. and by this I mean using replace, transparent, XOR or reverse transparent mode.
  37. Replace mode obscures anything behind the rectangle. Transparent lets the
  38. background show through, for instance, if it's a hollow rectangle. XOR mode
  39. exclusively ORs the rectangle and contents with the background. Reverse
  40. transparent lets the background show through only where parts of the rectangle
  41. or contents are filled in.
  42.  
  43.     The best way to find out what these VDI functions really mean in practice
  44. is to try them out and see. The function vswr_mode(handle,mode) sets the
  45. drawing mode (in fact, all VDI output, including text). The (short) 'mode'
  46. parameter takes the value 1 (replace), 2 (transparent), 3 (XOR) or 4 (reverse
  47. transparent):
  48.  
  49. ----------------------------------------------------------------------------
  50.     FUNCTION                EFFECT
  51. ----------------------------------------------------------------------------
  52.     vswr_mode(handle,1)     Replace background
  53.     vswr_mode(handle,2)     Background shows through where pixels not set
  54.     vswr_mode(handle,3)     Exclusively ORed with background
  55.     vswr_mode(handle,4)     Background shows through where pixels set
  56. ----------------------------------------------------------------------------
  57.  
  58.     The next three functions are related because they tell the VDI how you want
  59. the interior of the rectangle drawn. Should it be hollow, filled with a solid
  60. colour, a pre-set pattern or one you have designed yourself? The first
  61. function, vsf_interior(handle,type), tells the VDI whether the rectangle should
  62. be drawn hollow (type=0), filled with a solid colour (type=1), filled with a
  63. pre-set pattern (type=2), filled with a pre-set hatch pattern (type=3) or
  64. filled with some pattern you have designed yourself (type=4).
  65.  
  66. ----------------------------------------------------------------------------
  67.   FUNCTION                 EFFECT
  68. ----------------------------------------------------------------------------
  69.   vsf_interior(handle,0)   Hollow rectangle - no fill
  70.   vsf_interior(handle,1)   Rectangle to be filled with colour
  71.   vsf_interior(handle,2)   Rectangle to be filled with a pre-set pattern
  72.   vsf_interior(handle,3)   Rectangle to be filled with a pre-set hatch
  73.   vsf_interior(handle,4)   Rectangle to be filled with user defined pattern
  74. ----------------------------------------------------------------------------
  75.  
  76.  
  77.  
  78.     (The function, vsf_color(handle,colour), is very simple - it just sets the
  79. colour if you are using a solid fill colour with vsf_interior(handle,1). The
  80. 'colour' parameter ranges from 0 to 15, but don't forget that you can only
  81. display four colours in medium res and two in monocrome.)
  82.  
  83.     The second of the related functions mentioned above is
  84. vsf_style(handle,style). The (short) 'style' parameter is used to select the
  85. type of pattern or hatch when using vsf_interior(handle,2) or
  86. vsf_interior(handle,3). There are 24 patterns and 12 hatches to choose from. If
  87. you wanted to draw a rectangle that was filled with hatch type three you would
  88. use the following code:
  89.  
  90. vsf_interior(handle,3)       /* we want a hatch fill, ok? */
  91. vsf_style(handle,3)          /* we'll choose hatch number 3 */
  92. .
  93. .
  94. .
  95.  
  96.     The third related function is only used when you want to design your own
  97. fill patterns, for which you would use vsf_interior(handle,4). The VDI function
  98. that defines a fill pattern is vsf_udpat(handle,word,planes) - all short (16
  99. bit) parameters. The 'planes' parameter relates to the number of planes the
  100. screen display is made up of, and is four in low res, two in medium res and one
  101. in mono. The 'word' parameter is a pointer to an array that contains 16, word,
  102. entries for each plane.
  103.  
  104.     It's quite easy to design your own fill patterns for a monochrome display,
  105. because only one plane is required and each bit set corresponds to a pixel on
  106. the screen. Here's a short piece of code to define a fill pattern and set the
  107. fill option so that all filled shapes use this new design:
  108.  
  109. pat[0]  = 0x0F0F;
  110. pat[1]  = 0x0F0F;
  111. pat[2]  = 0x0000;
  112. pat[3]  = 0x0000;
  113. pat[4]  = 0xAAAA;
  114. pat[5]  = 0xAAAA;
  115. pat[6]  = 0xBBBB;
  116. pat[7]  = 0xBBBB;
  117. pat[8]  = 0xCCCC;
  118. pat[9]  = 0xCCCC;
  119. pat[10] = 0xBBBB;
  120. pat[11] = 0xBBBB;
  121. pat[12] = 0x0000;
  122. pat[13] = 0x0000;
  123. pat[14] = 0x1234;
  124. pat[15] = 0x4321;
  125. vsf_udpat(handle,pat,1);         /* define my own pattern - 1 plane mono */
  126. vsf_interior(handle,4);          /* set user defined fill */
  127.  
  128.     Now that we can set all the parameters like colour, writing mode, hatch or
  129. fill pattern, pre-set or user defined, how about actually drawing a rectangle?
  130. It's now quite easy, so here is a section of code taken from the PATTERNS.C
  131. program on this month's cover disk. It draws 24 rounded rectangles and then
  132. fills them with the 24 different patterns:
  133.  
  134. /* draw the fill patterns */
  135. vsf_color(handle,1);                   /* colour=black */
  136. for ( x=0; x<24; ++x )     {           /* pattern styles 1-24 */
  137.     vsf_interior(handle,2);            /* set patterned fill */
  138.     vsf_style(handle,x+1);             /* choose pattern to fill with*/
  139.     xyarray[0] = x*26;                 /* top left x */
  140.     xyarray[1] = 0;                    /* top left y */
  141.     xyarray[2] = xyarray[0]+23;        /* bottom right x */
  142.     xyarray[3] = xyarray[1]+40;        /* bottom right y */
  143.     v_rfbox(handle,xyarray);           /* draw rounded filled box */
  144. }
  145.  
  146.     When a rectangle is drawn using the vr_recfl(handle,xyarray) function, the
  147. perimeter of the shape is never drawn. If you specifically wanted to draw a
  148. perimeter around it you would use v_bar(handle,xyarray) instead, however, you
  149. would also need to tell the VDI to draw the perimeter with a call to
  150. vsf_perimeter(handle,flag) where flag=1. The perimeter is drawn using the line
  151. attributes that we looked at last month.
  152.  
  153.     The functions v_rbox(handle,xyarray) and v_rfbox(handle,xyarray) are
  154. identical except that the former simply draws a rounded box outline, while the
  155. latter also fills it with the current fill/hatch/user defined pattern.
  156.  
  157.     That's all for now. See you next month when I'll be documenting more VDI
  158. functions. In the meantime, try running PATTERNS.PRG and look at the different
  159. patterns and hatches. There's also a user defined one, too. The source code is
  160. in PATTERNS.C and was written with Digital Wisdom C.
  161.