Professional GEM - Part IX - VDI Graphics: Lines and solids

Professional GEM

Part I -- Windows
	In the beginning ♦ Open sesame ♦ Cleaning up ♦ Those fat sliders ♦ Coming up next ♦ Feedback
Part II -- Windows
	Excelsior ♦ Redrawing windows ♦ Caveat emptor ♦ Into the bits ♦ A small confession ♦ Window control request ♦ Window slider messages ♦ A common bug ♦ Dept. of dirty tricks ♦ A sin of omission ♦ Coming soon
Part III -- The dialog handler
	A meaningful dialog ♦ Defining terms ♦ Bug alert! ♦ A handy trick ♦ Clean up ♦ Recap ♦ Button Button ♦ Who's got the button? ♦ Coming up next ♦ Dispell gremlins
Part IV -- Resource structure
	A maze of twisty little passages ♦ Putting it to work ♦ Letters, we get letters ♦ Straw poll! ♦ Stay tuned!
Part V -- Resource tree structures
	How GEM does it ♦ Thought experiments ♦ A treewalker of our own
Part VI -- Raster operations
	Seasons greetings ♦ Defining terms ♦ Monochrome vs. color ♦ Standard vs. device-specific format ♦ Even-word vs. fringes ♦ MFDB's ♦ Let's operate ♦ Transform form ♦ Copy raster opaque ♦ Copy raster transparent ♦ The mode parameter ♦ Replace mode ♦ Erase mode ♦ Xor mode ♦ Transparent mode ♦ Reverse transparent mode ♦ The problem of color ♦ Optimizing raster operations ♦ Avoid merged copies ♦ Move to corresponding pixels ♦ Avoid fringes ♦ Use another method ♦ Feedback results ♦ The next question ♦ Coming up soon
Part VII -- Menu structures
	Happy new year ♦ Menu basics ♦ Menu structures ♦ Using the menu ♦ Getting fancy ♦ Check please? ♦ Now you see it now you don't ♦ Lunch and dinner menus ♦ Do it yourself ♦ Make pretty ♦ That's it for now!
Part VIII -- User interfaces
	And now for something completely different! ♦ Credit where it's due ♦ Fingertips ♦ Muscles ♦ Eyes ♦ Short-term memory ♦ Chunking ♦ Think! ♦ Are we not men? ♦ Of modes and bandwidth ♦ To do is to be! ♦ Amen...
Part IX -- VDI Graphics: Lines and solids
	A bit of history ♦ The line forms on the left ♦ Solids ♦ To be continued
Appendices
Main page

This issue of ST PRO GEM is the first in a series of two which will explore the fundamentals of VDI graphics output. In this installment, we will take a look at the commands necessary to output simple graphics such as lines, squares and circles as well as more complex figures such as polygons. The following episode will take a first look at graphics text output, with an emphasis on ways to optimize its drawing speed. It will also include another installment of ONLINE Feedback. As usual, there is a download with this column. You should find it under the name GEMCL9.C in DL3 of ATARI16 (PCS-58).

A bit of history

One of the reasons that the VDI can be confusing is that drawing anything at all, even a simple line, can involve setting around four different VDI parameters before making the draw call! (Given the state of the GEM documents, just FINDING them can be fun!) Looking backwards a bit sheds some light on why the VDI is structured this way, and also gives us a framework for organizing a discussion of graphics output.

The GEM VDI closely follows the so-called GKS standard, which defines capabilities and calling sequences for a standardized graphic input/output system. GKS is itself an evolution from an early system called "Core". Both of these standards were born in the days when pen plotters, vectored graphics displays, and minicomputers were the latest items. So, if you wonder why setting the drawing pen color is a separate command, just think back a few years when it actually meant what it says! (The cynical may choose instead to ponder the benefits of standardization.)

When doing VDI output, it helps if you pretend that the display screen really is a plotter or some other separate device, which has its own internal parameters which you can set up and read back. The class of VDI commands called Attribute Functions let you set the parameters. Output functions cause the "device" to actually draw someone once it is configured. The Inquire Functions let you read back the parameters if necessary.

There are two parameters which are relevant no matter what type of object you are trying to draw. They are the writing mode and the clipping rectangle. The writing mode is similar to that discussed in the column on raster operations.

It determines what effect the figure you are drawing will have on data already on the screen. The writing mode is set with the call:

 vswrmode(vdihandle, mode);

Vdihandle, here and below, is the handle obtained from grafhandle at the beginning of the program. Mode is a word which may be one of:

1 - Replace Mode 2 - Transparent Mode 3 - XOR mode 4 - Reverse Transparent Mode

In replace mode, whatever is on the screen is overwritten. If you are writing characters, this means the background of each character cell will be erased.

In transparent mode, only the pixels directly under the "positive" part of the image, that is, where 1-bits are being written, will be changed. When writing characters, the background of the cell will be left intact.

In XOR mode, an exclusive or is performed between the screen contents and what is being written. The effect is to reverse the image under areas where a 1-bit occurs.

Reverse transparent is like transparent, but with a "reverse color scheme". That is, only places where a 0-bit is to be put are changed to the current writing color. When you write characters in reverse transparent (over white), the effect is reverse video.

The other common parameter is the clipping rectangle. It defines the area on the screen where the VDI is permitted to draw. Any output which would fall outside of this area is ignored; it is effectively a null operation. The clip rectangle is set with the call:

 vsclip(vdihandle, flag, pxy);

Pxy is a four-word array. Pxy[0] and pxy[1] are the X and Y screen coordinates, respectively, of one corner of your clipping rectangle. Pxy[2] and pxy[3] are the coordinates of the diagonally opposite corner of the rectangle. (When working with the AES, use of a GRECT to define the clip is often more convenient. The routine setclip() in the download does this.)

Flag is set to TRUE if clipping is to be used. If you set it to FALSE, the entire screen is assumed to be fair game.

Normally, you should walk the rectangle list for the current window to obtain your clipping rectangles. (See ST PRO GEM #2 for more details.) However, turning off the clip speeds up all output operations, particularly text. You may do this ONLY when you are absolutely certain that the figure you are drawing will not extend out of the top-most window, or out of a dialog.

The line forms on the left

The VDI line drawing operations include polyline, arc, elliptical arc, and rounded rectangle. I'll first look at the Attribute Functions for line drawing, then go through the drawing primitives themselves.

The most common used line attributes are color and width. The color is set with:

 vslcolor(vdihandle, color);

where color is one of the standard VDI color indices, ranging from zero to 15. (As discussed in column #6, the color which actually appears will depend on the pallette setting of your ST.)

The line width may only be set to ODD positive values, for reasons of symmetry. If you try to set an even value, the VDI will take the next lower odd value. The call is:

 vslwidth(vdihandle, width);

The two less used line parameters are the end style and pattern. With the end style you can cause the output line to have rounded ends or arrowhead ends. The call is:

 vslends(vdihandle, beginstyle, endstyle);

Beginstyle and endstyle are each words which may have the values zero for square ends (the default), one for arrowed ends, or two for rounded ends. They determine the styles for the starting and finishing ends of the line, respectively.

The line pattern attribute can select dotted or dashed lines as well as more complicated patterns. Before continuing, you should note one warning: VDI line output DOES NOT compensate for pixel aspect ratio. That is, the dashes on a line will look twice as long drawn vertically on a medium-res ST screen as they do when drawn horizontally. The command for setting the pattern is:

 vsltype(vdihandle, style);

Style is a word with a value between 1 and 7. The styles selected are:

1 - Solid (the default) 2 - Long Dash 3 - Dot 4 - Dash, Dot 5 - Dash 6 - Dash, Dot, Dot 7 - (User defined style)

The user defined style is determined by a 16-bit pattern supplied by the application. A one bit in the pattern turns a pixel on, a zero bit leaves it off. The pattern is cycled through repeatedly, using the high bit first. To use a custom style, you must make the call:

 vsludsty(vdihandle, pattern);

before doing vsltype().

As I mentioned above, the line type Output Functions available are polyline, circular and ellliptical arc, and rounded rectangle. Each has its own calling sequence. The call for a polyline is:

 vpline(vdihandle, points, pxy);

Points tells how many vertices will appear on the polyline. For instance, a straight line has two vertices: the end and the beginning. A closed square would have five, with the first and last identical. (There is no requirement that the figure described be closed.)

The pxy array contains the X and Y raster coordinates for the vertices, with a total of 2 * points entries. Pxy[0] and pxy[1] are the first X-Y pair, and so on.

If you happen to be using the XOR drawing mode, remember that drawing twice at a point is equivalent to no drawing at all. Therefore, for a figure to appear closed in XOR mode, the final stroke should actually stop one pixel short of the origin of the figure.

You may notice that in the GEM VDI manual the rounded rectangle and arc commands are referred to as GDPs (Generalized Drawing Primitives). This denotation is historical in nature, and has no effect unless you are writing your own VDI bindings.

The rounded rectangle is nice to use for customized buttons in windows and dialogs. It gives a "softer" look to the screen than the standard square objects. The drawing command is:

 vrbox(vdihandle, pxy);

Pxy is a four word array giving opposite corners of the rectangle, just as for the vsclip() call. The corner rounding occurs within the confines of this rectangle. Nothing will protrude unless you specify a line thickness greater than one. The corner rounding is approximately

circular; there is no user control over the degree or shape of rounding. 

Both the arc and elliptical arc commands use a curious method of specifying angles. The units are tenths of degrees, so an entire circle is 3600 units. The count starts at ninety degrees right of vertical, and proceeds counterclockwise. This means that "3 o'clock" is 0 units, "noon" is 900 units, "9 o'clock" is 1800 units, and 2700 units is at "half-past". 3600 units take you back to "3 o'clock".

The command for drawing a circular arc is:

 varc(vdihandle, x, y, radius, begin, end);

X and y specify the raster coordinates of the center of the circle. Radius specifies the distance from center to all points on the arc. Begin and end are angles given in units as described above, both with values between 0 and 3600. The drawing of the arc ALWAYS proceeds counterclockwise, in the direction of increasing arc number. So values of 0 and 900 for begin and end would draw a quarter circle from

"three o'clock" to "noon". Reversing the values would draw the other three quarters of the circle. 

A varc() command which specifies a "full turn" is the fastest way to draw a complete circle on the screen. Be warned, however, that the circle drawing algorithm used in the VDI seems to have some serious shortcomings at small radii! You can experiment with the CIRCLE primitive in ST Logo, which uses varc(), to see what I mean.

Notice that if you want an arc to strike one or more given points on the screen, then you are in for some trigonometry. If your math is a bit rusty, I highly recommend the book "A Programmer's Geometry", by Bowyer and Woodwark, published by Butterworths (London, Boston, Toronto).

Finally, the elliptical arc is generated with:

 vellarc(vdihandle, x, y, xrad, yrad, begin, end);

X, y, begin, and end are just as before. Xrad and yrad give the horizontal and vertical radii of the defining ellipse. This means that the distance of the arc from center will be yrad pixels at "noon" and "half-past", and it will be xrad pixels at "3 and 9 o'clock". Again, the arc is always drawn counterclockwise.

There are a number of approaches to keeping the VDI's attributes "in sync" with the actual output operations. Probably the LEAST efficient is to use the Inquire Functions to determine the current attributes. For this reason, I have omitted a discussion of these calls from this column.

Another idea is to keep a local copy of all significant attributes, use a test-before-set method to minimize the number of Attribute Functions which need to be called. This puts a burden on the programmer to be sure that the local attribute variables are correctly maintained. Failure to do so may result in obscure drawing bugs. If your application employs user defined AES objects, you must be very careful because GEM might call your draw code in the middle of a VDI operation (particularly if the user defined objects are in the menu).

Always setting the attributes is a simplistic method, but often proves most effective. The routines plperim() and rrperim() in the download exhibit this approach. Modification for other primitives is straightforward. This style is most useful when drawing operations are scattered throughout the program, so that keeping track of the current attribute status is difficult. Although inherently inefficient, the difference is not very noticable if the drawing operation requested is itself time consuming.

In many applications, such as data graphing programs or "Draw" packages, the output operations are centralized, forming the primary functionality of the code. In this case, it is both easy and efficient to keep track of attribute status between successive drawing operations.

Solids

There are a wider variety of VDI calls for drawing solid figures. They include rectangle or bar, disk, pie, ellipse, elliptical pie, filled rounded rectangle, and filled polygonal area. Of course, filled figure calls also have their own set of attributes which you will need to set.

The fill color index determines what pen color will be used to draw the solid. It is set with:

 vsfcolor(vdihandle, color);

Color is just the same as for line drawing. A solid may or may not have a visible border. This is determined with the call:

 vsfperimeter(vdihandle, vis);

Vis is a Boolean. If it is true, the figure will be given a solid one pixel outline in the current fill color index. This is often useful to improve the appearance of solids drawn with a dithered fill pattern. If vis is false, then no outline is drawn.

There are two parameters which together determine the pattern used to fill your figure. They are called interior style and interior index. The style determines the general type of fill, and the index is used to select a particular pattern if necessary. The style is set with the command:

 vsfinterior(vdihandle, style);

where style is a value from zero through four. Zero selects a hollow style: the fill is performed in color zero, which is usually white. Style one selects a solid fill with the current fill color. A style of two is called "pattern" and a three is called "hatch", which are terms somewhat suggestive of the options which can then be selected using the interior index. Style four selects the user defined pattern, which is described below.

The interior index is only significant for styles two and three. To set it, use:

 vsfstyle(vdihandle, index);

(Be careful here: it is very easy to confuse this call with the one above due to the unfortunate choice of name.) The index selects the actual drawing pattern. The GEM VDI manual shows fill patterns corresponding to index values from 1 to 24 under style 2, and from 1 to 12 under style 3. However, some of these are implemented differently on the ST. Rather than try to describe them all here, I would suggest that you experiment. You can do so easily in ST Logo by opening the Graphics Settings dialog and playing with the style and index values there.

The user defined style gives you some interesting options for multi-color fills. It is set with:

 vsfudpat(vdihandle, pattern, planes);

Planes determines the number of color planes in the pattern which you supply. It is set to one if you are setting a monochrome pattern. (Remember, monochrome is not necessarily black). It may be set to higher values on color systems: two for ST medium-res mode, or four for low-res mode. If you use a number lower than four under low-res, the other planes are zero filled.

The pattern parameter is an array of words which is a multiple of 16 words long. The pattern determined is 16 by 16 pixels, with each word forming one row of the pattern. The rows are arranged top to bottom, with the most significant bit to the left. If you have selected a multi-plane pattern, the entire first plane is stored, then the second, and so on.

Note that to use a multi-plane pattern, you set the writing mode to replace using vswrmode(). Since the each plane can be different, you can produce multi-colored patterns. If you use a writing color other than black, some of the planes may "disappear".

Most of the solids Output Functions have analogous line drawing commands. The polyline command corresponds to the filled area primitive. The filled area routine is:

 vfillarea(vdihandle, count, pxy);

Count and pxy are just the same as for vpline(). If the polygon defined by pxy is not closed, then the VDI will force closure with a straight line from the last to the first point. The polygon may be concave or self-intersecting. If perimeter show is on, the area will be outlined.

One note of caution is necessary for both vfillarea() and vpline(). There is a limit on the number of points which may be stored in pxy[]. This limit occurs because the contents of pxy[] are copied to the intin[] binding array before the VDI is called. You can determine the maximum number of vertices by checking intout[14] after using the extended inquire function vqextnd().

For reasons unknown to this writer, there are TWO different filled rectangle commands in the VDI. The first is

 vrrecfl(vdihandle, pxy);

Pxy is a four word array defining two opposite corners of the rectangle, just as in vsclip(). Vrrecfl() uses the fill attribute settings, except that it NEVER draws a perimeter.

The other rectangle routine is vbar(), with exactly the same arguments as vrrecfl(). The only difference is that the perimeter setting IS respected. These two routines are the fastest way to produce a solid rectangle using the VDI. They may be used in XOR mode with a BLACK fill color to quickly invert an area of the screen. You can improve the speed even further by turning off the clip (if possible), and byte aligning the left and right edges of the rectangle.

Separate commands are provided for solid circle and ellipse. The circle call is:

 vcircle(vdihandle, x, y, radius);

and the ellipse command is:

 vellipse(vdihandle, x, y, xrad, yrad);

All of the parameters are identical to those given above for varc() and vellarc(). The solid analogue of an arc is a "pie slice". The VDI pie commands are:

 vpieslice(vdihandle, x, y, radius, begin, end);

for a slice from a circular pie, and

 vellpie(vdihandle, x, y, xrad, yrad, begin, end);

for a slice from a "squashed" pie. Again, the parameters are identical to those in varc() and vellarc(). The units and drawing order of angles are also the same. The final solids Output Function is:

 vrfbox(vdihandle, pxy);

which draws a filled rounded rectangle. The pxy array defines two two opposite corners of the bounding box, as shown for vsclip().

The issues involved in correctly setting the VDI attributes for a fill operation are identical to those in drawing lines. For those who want to employ the "always set" method, I have again included two skeleton routines in the download, which can be modified as desired.

To be continued

This concludes the first part of our expedition through basic VDI operations. The next issue will tackle the problems of drawing bit mapped text at a reasonable speed. This first pass will not attempt to tackle alternate or proportional fonts, or alternate font sizes. Instead, I will concentrate on techniques for squeezing greater performance out of the standard monospaced system fonts.