            Chapter 8: Elementary Plot Routines

This chapter  describes  elementary  subroutines  that  plot
lines,  vectors, circles,  ellipses,  pie segments and poly-
gons. There are versions for plot and user coordinates;  the
routines for user coordinates begin with  the keyword  'RL'.
These routines can only be called from level 2 or 3 after an
axis system has been defined.

8.1 Lines

XMOVE and  XDRAW are simple  subroutines for plotting lines.
They require absolute  page coordinates and are,  therefore,
not affected by a call to ORIGIN. Different line styles can-
not be used.  The routine  XMOVE  moves  the pen  to a point
while XDRAW draws a line to a point.

The calls are:  CALL XMOVE (X, Y)              level 1, 2, 3
                CALL XDRAW (X, Y)              level 1, 2, 3

X, Y            are absolute page coordinates.

The subroutines  STRTPT  and CONNPT require plot coordinates
as real numbers and allow different line styles to be used.

The calls are:  CALL STRTPT (X, Y)             level 1, 2, 3
                CALL CONNPT (X, Y)             level 1, 2, 3

X, Y            are real numbers containing the plot coordi-
                nates.

The corresponding routines for user coordinates are:

The calls are:  CALL RLSTRT (X, Y)                level 2, 3
                CALL RLCONN (X, Y)                level 2, 3

Note:           Lines plotted with  RLSTRT  and  RLCONN will
                not be cut off  at the  borders  of an  axis
                system. This can be enabled with the routine
                CLPBOR.  Points  lying  outside  of the axis
                scaling  will not be  listed by  RLSTRT  and
                RLCONN.

                          L I N E

LINE joins two points with a line. Different line styles can
be used.

The call is:  CALL LINE (NX, NY, NU, NV)       level 1, 2, 3

NX, NY        are the plot coordinates of the first point.
NU, NV        are the plot coordinates of the second point.

                         R L I N E

RLINE is the corresponding routine for user coordinates.

The call is:  CALL RLINE (X, Y, U, V)             level 2, 3

X, Y          are the user coordinates of the first point.
U, V          are the user coordinates of the second point.

Note:         RLINE  draws only that part  of the line lying
              inside the axis system. If NOCHEK is not used,
              points lying outside  the axis scaling will be
              listed.

8.2 Vectors

                         V E C T O R

VECTOR plots vectors with none, one or two arrow heads.

The call is:  CALL VECTOR (IX1, IY1, IX2, IY2, IVEC)
                                               level 1, 2, 3

IX1, IY1      are the plot coordinates of the start point.
IX2, IY2      are the plot coordinates of the end point.
IVEC          is an integer number  that defines the form of
              the arrow heads.  If IVEC = -1, the arrow head
              can be defined with the routine VECOPT. Other-
              wise,  IVEC can  contain  a four  digit number
              'wxyz'  specifying  the arrow  heads where the
              digits have the following meaning:

      w:      determines  the  ratio  of  width  and  length
              (0 - 9).
      x:      determines the size (0 - 9).
      y:      determines the form:
         = 0  filled
         = 1  not filled
         = 2  opened
         = 3  closed
         = 4  sharp, filled
         = 5  sharp, not filled.
      z:      determines the position:
         = 0  no arrow heads are plotted
         = 1  at end points
         = 2  at start and end points
         = 3  at start and end points and in the same direc-
              tion.

                         R L V E C

RLVEC is the corresponding routine for user coordinates.

The call is:  CALL RLVEC (X1, Y1, X2, Y2, IVEC)   level 2, 3

                         V E C C L R

VECCLR defines the colour of arrow heads,  or enables colour
scaling in the routines FIELD, VECFLD, FIELD3D and VECF3D.

The call is:  CALL VECCLR (ICLR)               level 1, 2, 3

ICLR          is a colour number.  If ICLR has the value -2, 
              colour scaling is enabled in vector fields.
              If ICLR = -1,  arrow heads  are plotted in the 
              foreground colour.  Otherwise, arrow heads are
              plotted in the colour ICLR.

                         V E C O P T

VECOPT  defines  some  vector options  such  as the  size of 
arrow heads and the appearance of  user-defined  arrows that
are enabled with  the vector number -1  in VECTOR and RLVEC.
The routine can also  disable  automatic scaling  of vectors
in vector fields.

The call is:  CALL VECOPT (XOPT, CKEY)         level 1, 2, 3

XOPT          contains a floating point option.
CKEY          is a character string that can have one of the
              following values:
 = 'ANGLE'    defines the angle in degrees that is used  for
              arrow heads plotted with the vector number -1.   
 = 'LENGTH'   defines the ratio of the arrow head and vector
              length for vectors plotted with the number -1.
 = 'SCALE'    sets a  scaling  factor  that is  used for the
              vector length in vector field routines such as
              VECFLD  and  VECMAT.  If XOPT = 0.,  automatic 
              scaling is enabled.
 = 'SIZE'     defines a scaling factor for the size of arrow
              heads.
                 Defaults: (20., 'ANGLE'), (0.25, 'LENGTH'),
                              (0., 'SCALE'),  (1.0, 'SIZE').

8.3 Filled Triangles

                         T R I F L L

The routine TRIFLL plots solid filled triangles.

The call is:  CALL TRIFLL (XRAY, YRAY)         level 1, 2, 3

XRAY, YRAY    are floating point arrays containing the three
              corners of a triangle.

                         T R I F L C

The routine  TRIFLC plots solid filled triangles with inter-
polated colours.

The call is:  CALL TRIFLC (XRAY, YRAY, ICRAY, N)
                                               level 1, 2, 3

XRAY, YRAY    are floating point arrays containing  triangle
              corners. 
ICRAY         are the colour values of the triangle corners.
N             is the number  of points in  the arrays above.
              N should be a  multiple of three.  You can in-
              crease performance  by passing  multiple  tri-
              angles to  TRIFLC  instead  of calling  TRIFLC 
              several times.

8.4 Wind Speed Symbols

                         W I N D B R

The routine WINDBR plots wind speed symbols (wind barbs).

The call is:  CALL WINDBR (X, NXP, NYP, NW, A) level 1, 2, 3

X             is the wind speed in knots.
NXP, NYP      are the plot coordinates of the lower left 
              corner of the wind speed symbol.
NW            is the length of the symbol in plot coordina-
              tes. If NW < 0, the wind flags are plotted on
              the  opposite site  as usual in  the southern
              hemisphere.
A             is the wind direction in degrees.

                         R L W I N D

RLWIND is the corresponding routine to  WINDBR  for user 
coordinates.

The call is:  CALL RLWIND (X, XP, YP, NW, A)      level 2, 3

8.5 Geometric Figures

The following  subroutines  plot  geometric figures  such as
rectangles,  circles,  ellipses,  pie segments and polygons.
These routines  can be  used  to plot  only  the outlines of
figures  or the  figures  can be  filled in with shaded pat-
terns.

                         R E C T A N

RECTAN plots rectangles.

The call is:  CALL RECTAN (NX, NY, NW, NH)     level 1, 2, 3

NX, NY        are  the plot  coordinates  of the  upper left
              corner.
NW, NH        are the width and height in plot coordinates.

                         R N D R E C

RECTAN plots an rectangle where the corners will be rounded.

The call is:  CALL RNDREC (NX, NY, NW, NH, IOPT)
                                               level 1, 2, 3

NX, NY        are  the plot  coordinates  of the  upper left
              corner.
NW, NH        are the width and height in plot coordinates.
IOPT          defines  the rounding of corners (0 <= IOPT <=
              9). For IOPT = 0, rounding is disabled.

                         C I R C L E

CIRCLE plots circles.

The call is:  CALL CIRCLE (NX, NY, NR)         level 1, 2, 3

NX, NY        are the plot coordinates of the centre point.
NR            is the radius in plot coordinates.

                         E L L I P S

ELLIPS plots ellipses.

The call is:  CALL ELLIPS (NX, NY, NA, NB)     level 1, 2, 3

NX, NY        are the plot coordinates of the centre point.
NA, NB        are the radii in plot coordinates.

                           P I E

PIE plots pie segments.

The call is:  CALL PIE (NX, NY, NR, ALPHA, BETA) 
                                               level 1, 2, 3

NX, NY        are the plot coordinates of the centre point.
NR            is the radius in plot coordinates.
ALPHA, BETA   are the start and end angles  measured  in de-
              grees in a counter-clockwise direction.

                         A R C E L L

ARCELL plots elliptical arcs where the arcs can be rotated.

The call is:  CALL ARCELL (NX, NY, NA, NB, ALPHA, BETA, T)
                                               level 1, 2, 3

NX, NY        are the plot coordinates of the centre point.
NA, NB        are the radii in plot coordinates.
ALPHA, BETA   are the start and end angles  measured in  de-
              grees in a counter-clockwise direction.
T             is the rotation angle  measured in  degrees in
              a counter-clockwise direction.

                         A R E A F

AREAF draws polygons.

The call is:  CALL AREAF (NXRAY, NYRAY, N)     level 1, 2, 3

NXRAY, NYRAY  are arrays  containing the plot coordinates of
              the corner points. Start and end points can be
              different.
N             is the number of points.

The corresponding routines for user coordinates are:

The calls are:  CALL RLREC   (X, Y, WIDTH, HEIGHT) lev. 2, 3
                CALL RLRND   (X, Y, WIDTH, HEIGHT, IOPT)
                CALL RLCIRC  (XM, YM, R)
                CALL RLELL   (XM, YM, A, B)
                CALL RLPIE   (XM, YM, R, ALPHA, BETA)
                CALL RLARC   (XM, YM, A, B, ALPHA, BETA, T)
                CALL RLAREA  (XRAY, YRAY, N)

Notes:     -  Shading patterns  can be  defined with  SHDPAT
              and MYPAT. If the pattern number is zero,  the
              figures will  only be outlined.  With CALL NO-
              ARLN, the outline will be suppressed.
           -  The number of points in  AREAF and  RLAREA  is
              limited to 25000 for  Fortran 77.  There is no
              limitation for the  C and Fortran 90  versions
              of DISLIN. 
           -  For the  calculation  of the  radius in RLCIRC
              and RLPIE, the X-axis scaling is used.
           -  The interpolation of circles  and ellipses can
              be altered with  CIRCSP (NSPC)  where  NSPC is
              the  arc length  in plot coordinates.  The de-
              fault value is 10.

