5 PLOTTING LINES

5.1 Polylines

Many graphics packages have line drawing routines based on a ‘current position’ concept. A single straight line is drawn either by calling first a ‘set current position’ routine then calling a ‘draw line from current position to new position’ routine, or by calling a general ‘move’ routine twice with a ‘pen up/down’ argument suitably set each time. Though familiar and convenient, this approach is prone to various subtle problems, for example where the coordinate system is changed during plotting. The GKS line drawing primitive, on the other hand, does not use a current position but instead allows a series of connected straight lines, called a polyline, to be plotted as one object. The SGS package supports both concepts, and includes ‘current position’ style routines, called SGS_BPOLY, SGS_APOLY and SGS_OPOLY, which construct and output GKS polylines.

The SGS_BPOLY routine is used to begin a polyline:

where X,Y are the starting coordinates for the polyline. (This is the equivalent of ‘move to x,y with pen up’ in other plotting packages.)

The polyline is then built up by calls to SGS_APOLY, each of which appends a single line from the current end of the polyline to the new X, Y:

(This is the equivalent of ‘move to x,y with pen down’.)

Finally, when the polyline is complete, it can be output using:

Thus the following code would plot a triangle, with vertices at (0,0),(3,0) and (0,4):

In most cases the call to SGS_OPOLY may be omitted; any polyline awaiting output is automatically plotted if a new polyline is begun (via SGS_BPOLY or SGS_LINE) or at various other critical places within SGS. It is, however, good practice to issue SGS_OPOLY if there is any uncertainty—redundant calls to SGS_OPOLY are harmless. For example, at the end of a general purpose subroutine is a good place, as the subroutine might be called in a case where direct access to GKS routines occurs before any subsequent SGS line-drawing takes place:

At any time, the current end coordinates of the polyline being built can be obtained by:

(Only a limited amount of space is reserved for building the polyline; however, when this space is filled the polyline is automatically plotted and a new one, starting from the last point given, is begun. Thus polylines of arbitrary length may be plotted via the SGS routines. Only if a dotted linetype are in use will the joins show, an occasion on which direct use of the GKS polyline routine might be preferable.)

When the polyline to be drawn is merely a single line, it may be most convenient to use the routine SGS_LINE, which opens a new polyline consisting of a single line:

The polyline begins at (X1,Y1) and ends at (X2,Y2). Output of the polyline is not forced, so the LINE routine can be used to begin a polyline of any length.

Notes:

(1)

All of the SGS calls which affect the coordinate transformation, change pen, etc, automatically arrange for any pending polyline to be plotted before the change occurs.

(2)

Improperly begun polylines (where no call to SGS_BPOLY or to SGS_LINE has been made) are nevertheless plotted. The starting point is either the end of the previous polyline or—immediately upon opening or after calling one of the routines which affect the coordinate transformation—the first X, Y to be appended to the new polyline. This property of SGS should not be exploited.

(3)

There will be occasions when the GKS polyline routine offers a more convenient facility than the SGS routines. The call is:

  CALL GPL(LENGTH, XARRAY, YARRAY)

where LENGTH is the size of the one-dimensional arrays XARRAY and YARRAY, which contain the X and Y coordinates of the vertices of the polyline, in world coordinates.

The triangle plotted in the example given earlier can be produced with the following code:

  REAL XA(4), YA(4)
   :
  DATA XA/0.0, 3.0, 0.0, 0.0/
  DATA YA/0.0, 0.0, 4.0, 0.0/
   :
   :
  CALL GPL(4, XA, YA)

5.2 Plotting rectangular boxes

Rectangular boxes, with sides parallel to the axes, can be plotted by means of the routine SGS_BOX:

The arguments are the x and y extents of the box.

5.3 Plotting arcs and circles

The SGS package includes facilities for outputting both complete circles and arcs of circles:

The arc or circle is centred on X, Y and has radius R. The start and finish angles of the arc are THETA1 and THETA2 respectively; they are expressed in radians and have the conventional zero point and direction (e.g. an arc from 0 to $\pi /2$ would begin at [X+R,Y] and end at [X,Y+R]).

The arcs and circles are, of course, plotted as such in world coordinates, and will appear distorted if the window has been set so that the window-to-display-surface scales in x and y are different.

5.4 Clearing rectangular areas

A rectangular area of the display surface can be cleared with:

where the arguments are the x and y extents of the area. This routine never affects anything outside the specified area and so on some devices may not have any effect at all. It never causes a frame advance on hard copy devices.

The routine might be used, for example, to clear the area in which some text was to be plotted in order to avoid the text being obscured by existing plotting. On a device that cannot clear selected areas no clearing would take place and the end result would be the best that could be achieved without re-plotting the entire picture. If you wish to guarantee that an area is clear SGS_CLRZ should be used instead.