PGPLOT Subroutine Descriptions

Introduction

This appendix includes a list of all the PGPLOT subroutines, and then gives detailed instructions for the use of each routine in Fortran programs. The subroutine descriptions are in alphabetical order.

Arguments

The subroutine descriptions indicate the data type of each argument. When arguments are described as ``input'', they may be replaced with constants or expressions in the CALL statement, but make sure that the constant or expression has the correct data type.
INTEGER arguments:
these should be declared INTEGER or INTEGER*4 in the calling program, not INTEGER*2.
REAL arguments:
these should be declared REAL or REAL*4 in the calling program, not REAL*8 or DOUBLE PRECISION.
LOGICAL arguments:
these should be declared LOGICAL or LOGICAL*4 in the calling program.
CHARACTER arguments:
any valid Fortran CHARACTER variable may be used (declared CHARACTER*n for some integer n).

Index of Routines

Version 5.2

PGARRO -- draw an arrow

      SUBROUTINE PGARRO (X1, Y1, X2, Y2)
      REAL X1, Y1, X2, Y2

Draw an arrow from the point with world-coordinates (X1,Y1) to 
(X2,Y2). The size of the arrowhead at (X2,Y2) is determined by 
the current character size set by routine PGSCH. The default size 
is 1/40th of the smaller of the width or height of the view surface.
The appearance of the arrowhead (shape and solid or open) is
controlled by routine PGSAH.

Arguments:
 X1, Y1 (input)  : world coordinates of the tail of the arrow.
 X2, Y2 (input)  : world coordinates of the head of the arrow.

PGASK -- control new page prompting

      SUBROUTINE PGASK (FLAG)
      LOGICAL FLAG

Change the ``prompt state'' of PGPLOT. If the prompt state is
ON, PGPAGE will type ``Type RETURN for next page:'' and will wait
for the user to type a carriage-return before starting a new page.
The initial prompt state (after the device has been opened) is ON
for interactive devices. Prompt state is always OFF for
non-interactive devices.

Arguments:
 FLAG   (input)  : if .TRUE., and if the device is an interactive
                   device, the prompt state will be set to ON. If
                   .FALSE., the prompt state will be set to OFF.

PGAXIS -- draw an axis

      SUBROUTINE PGAXIS (OPT, X1, Y1, X2, Y2, V1, V2, STEP, NSUB,
     :                   DMAJL, DMAJR, FMIN, DISP, ORIENT)
      CHARACTER*(*) OPT
      REAL X1, Y1, X2, Y2, V1, V2, STEP, DMAJL, DMAJR, FMIN, DISP
      REAL ORIENT
      INTEGER NSUB

Draw a labelled graph axis from world-coordinate position (X1,Y1) to
(X2,Y2).

Normally, this routine draws a standard LINEAR axis with equal
subdivisions.   The quantity described by the axis runs from V1 to V2;
this may be, but need not be, the same as X or Y. 

If the 'L' option is specified, the routine draws a LOGARITHMIC axis.
In this case, the quantity described by the axis runs from 10**V1 to
10**V2. A logarithmic axis always has major, labeled, tick marks 
spaced by one or more decades. If the major tick marks are spaced
by one decade (as specified by the STEP argument), then minor
tick marks are placed at 2, 3, .., 9 times each power of 10;
otherwise minor tick marks are spaced by one decade. If the axis
spans less than two decades, numeric labels are placed at 1, 2, and
5 times each power of ten.

If the axis spans less than one decade, or if it spans many decades,
it is preferable to use a linear axis labeled with the logarithm of
the quantity of interest.

Arguments:
 OPT    (input)  : a string containing single-letter codes for
                   various options. The options currently
                   recognized are:
                   L : draw a logarithmic axis
                   N : write numeric labels
                   1 : force decimal labelling, instead of automatic
                       choice (see PGNUMB).
                   2 : force exponential labelling, instead of
                       automatic.
 X1, Y1 (input)  : world coordinates of one endpoint of the axis.
 X2, Y2 (input)  : world coordinates of the other endpoint of the axis.
 V1     (input)  : axis value at first endpoint.
 V2     (input)  : axis value at second endpoint.
 STEP   (input)  : major tick marks are drawn at axis value 0.0 plus
                   or minus integer multiples of STEP. If STEP=0.0,
                   a value is chosen automatically.
 NSUB   (input)  : minor tick marks are drawn to divide the major
                   divisions into NSUB equal subdivisions (ignored if
                   STEP=0.0). If NSUB <= 1, no minor tick marks are
                   drawn. NSUB is ignored for a logarithmic axis.
 DMAJL  (input)  : length of major tick marks drawn to left of axis
                   (as seen looking from first endpoint to second), in
                   units of the character height.
 DMAJR  (input)  : length of major tick marks drawn to right of axis,
                   in units of the character height.
 FMIN   (input)  : length of minor tick marks, as fraction of major.
 DISP   (input)  : displacement of baseline of tick labels to
                   right of axis, in units of the character height.
 ORIENT (input)  : orientation of label text, in degrees; angle between
                   baseline of text and direction of axis (0-360°).

PGBAND -- read cursor position, with anchor

      INTEGER FUNCTION PGBAND (MODE, POSN, XREF, YREF, X, Y, CH)
      INTEGER MODE, POSN
      REAL XREF, YREF, X, Y
      CHARACTER*(*) CH

Read the cursor position and a character typed by the user.
The position is returned in world coordinates.  PGBAND positions
the cursor at the position specified (if POSN=1), allows the user to
move the cursor using the mouse or arrow keys or whatever is available
on the device. When he has positioned the cursor, the user types a
single character on the keyboard; PGBAND then returns this
character and the new cursor position (in world coordinates).

Some interactive devices offer a selection of cursor types,
implemented as thin lines that move with the cursor, but without
erasing underlying graphics. Of these types, some extend between
a stationary anchor-point at XREF,YREF, and the position of the
cursor, while others simply follow the cursor without changing shape
or size. The cursor type is specified with one of the following MODE
values. Cursor types that are not supported by a given device, are
treated as MODE=0.

-- If MODE=0, the anchor point is ignored and the routine behaves
like PGCURS.
-- If MODE=1, a straight line is drawn joining the anchor point 
and the cursor position.
-- If MODE=2, a hollow rectangle is extended as the cursor is moved,
with one vertex at the anchor point and the opposite vertex at the
current cursor position; the edges of the rectangle are horizontal
and vertical.
-- If MODE=3, two horizontal lines are extended across the width of
the display, one drawn through the anchor point and the other
through the moving cursor position. This could be used to select
a Y-axis range when one end of the range is known.
-- If MODE=4, two vertical lines are extended over the height of
the display, one drawn through the anchor point and the other
through the moving cursor position. This could be used to select an
X-axis range when one end of the range is known.
-- If MODE=5, a horizontal line is extended through the cursor
position over the width of the display. This could be used to select
an X-axis value such as the start of an X-axis range. The anchor point
is ignored.
-- If MODE=6, a vertical line is extended through the cursor
position over the height of the display. This could be used to select
a Y-axis value such as the start of a Y-axis range. The anchor point
is ignored.
-- If MODE=7, a cross-hair, centered on the cursor, is extended over
the width and height of the display. The anchor point is ignored.

Returns:
 PGBAND          : 1 if the call was successful; 0 if the device
                   has no cursor or some other error occurs.
Arguments:
 MODE   (input)  : display mode (0, 1, ..7: see above).
 POSN   (input)  : if POSN=1, PGBAND attempts to place the cursor
                   at point (X,Y); if POSN=0, it leaves the cursor
                   at its current position. (On some devices this
                   request may be ignored.)
 XREF   (input)  : the world x-coordinate of the anchor point.
 YREF   (input)  : the world y-coordinate of the anchor point.
 X      (in/out) : the world x-coordinate of the cursor.
 Y      (in/out) : the world y-coordinate of the cursor.
 CH     (output) : the character typed by the user; if the device has
                   no cursor or if some other error occurs, the value
                   CHAR(0) [ASCII NUL character] is returned.

Note: The cursor coordinates (X,Y) may be changed by PGBAND even if
the device has no cursor or if the user does not move the cursor.
Under these circumstances, the position returned in (X,Y) is that of
the pixel nearest to the requested position.

PGBBUF -- begin batch of output (buffer)

      SUBROUTINE PGBBUF

Begin saving graphical output commands in an internal buffer; the
commands are held until a matching PGEBUF call (or until the buffer
is emptied by PGUPDT). This can greatly improve the efficiency of
PGPLOT.  PGBBUF increments an internal counter, while PGEBUF
decrements this counter and flushes the buffer to the output
device when the counter drops to zero.  PGBBUF and PGEBUF calls
should always be paired.

Arguments: none

PGBEG -- open a graphics device

      INTEGER FUNCTION PGBEG (UNIT, FILE, NXSUB, NYSUB)
      INTEGER       UNIT
      CHARACTER*(*) FILE
      INTEGER       NXSUB, NYSUB

Note: new programs should use PGOPEN rather than PGBEG. PGOPEN
is retained for compatibility with existing programs. Unlike PGOPEN,
PGBEG closes any graphics devices that are already open, so it 
cannot be used to open devices to be used in parallel.

PGBEG opens a graphical device or file and prepares it for
subsequent plotting. A device must be opened with PGBEG or PGOPEN
before any other calls to PGPLOT subroutines for the device.

If any device  is already open for PGPLOT output, it is closed before
the new device is opened.

Returns:
 PGBEG         : a status return value. A value of 1 indicates
                   successful completion, any other value indicates
                   an error. In the event of error a message is
                   written on the standard error unit.  
                   To test the return value, call
                   PGBEG as a function, eg IER=PGBEG(...); note
                   that PGBEG must be declared INTEGER in the
                   calling program. Some Fortran compilers allow
                   you to use CALL PGBEG(...) and discard the
                   return value, but this is not standard Fortran.
Arguments:
 UNIT  (input)   : this argument is ignored by PGBEG (use zero).
 FILE  (input)   : the "device specification" for the plot device.
                   (For explanation, see description of PGOPEN.)
 NXSUB  (input)  : the number of subdivisions of the view surface in
                   X (>0 or <0).
 NYSUB  (input)  : the number of subdivisions of the view surface in
                   Y (>0).
                   PGPLOT puts NXSUB x NYSUB graphs on each plot
                   page or screen; when the view surface is sub-
                   divided in this way, PGPAGE moves to the next
                   panel, not the  next physical page. If
                   NXSUB > 0, PGPLOT uses the panels in row
                   order; if <0, PGPLOT uses them in column order.

PGBIN -- histogram of binned data

      SUBROUTINE PGBIN (NBIN, X, DATA, CENTER)
      INTEGER NBIN
      REAL X(*), DATA(*)
      LOGICAL CENTER

Plot a histogram of NBIN values with X(1..NBIN) values along
the ordinate, and DATA(1...NBIN) along the abscissa. Bin width is
spacing between X values.

Arguments:
 NBIN   (input)  : number of values.
 X      (input)  : abscissae of bins.
 DATA   (input)  : data values of bins.
 CENTER (input)  : if .TRUE., the X values denote the center of the
                   bin; if .FALSE., the X values denote the lower
                   edge (in X) of the bin.

PGBOX -- draw labeled frame around viewport

      SUBROUTINE PGBOX (XOPT, XTICK, NXSUB, YOPT, YTICK, NYSUB)
      CHARACTER*(*) XOPT, YOPT
      REAL XTICK, YTICK
      INTEGER NXSUB, NYSUB

Annotate the viewport with frame, axes, numeric labels, etc.
PGBOX is called by on the user's behalf by PGENV, but may also be
called explicitly.

Arguments:
 XOPT   (input)  : string of options for X (horizontal) axis of
                   plot. Options are single letters, and may be in
                   any order (see below).
 XTICK  (input)  : world coordinate interval between major tick marks
                   on X axis. If XTICK=0.0, the interval is chosen by
                   PGBOX, so that there will be at least 3 major tick
                   marks along the axis.
 NXSUB  (input)  : the number of subintervals to divide the major
                   coordinate interval into. If XTICK=0.0 or NXSUB=0,
                   the number is chosen by PGBOX.
 YOPT   (input)  : string of options for Y (vertical) axis of plot.
                   Coding is the same as for XOPT.
 YTICK  (input)  : like XTICK for the Y axis.
 NYSUB  (input)  : like NXSUB for the Y axis.

Options (for parameters XOPT and YOPT):
 A : draw Axis (X axis is horizontal line Y=0, Y axis is vertical
     line X=0).
 B : draw bottom (X) or left (Y) edge of frame.
 C : draw top (X) or right (Y) edge of frame.
 G : draw Grid of vertical (X) or horizontal (Y) lines.
 I : Invert the tick marks; ie draw them outside the viewport
     instead of inside.
 L : label axis Logarithmically (see below).
 N : write Numeric labels in the conventional location below the
     viewport (X) or to the left of the viewport (Y).
 P : extend ("Project") major tick marks outside the box (ignored if
     option I is specified).
 M : write numeric labels in the unconventional location above the
     viewport (X) or to the right of the viewport (Y).
 T : draw major Tick marks at the major coordinate interval.
 S : draw minor tick marks (Subticks).
 V : orient numeric labels Vertically. This is only applicable to Y.
     The default is to write Y-labels parallel to the axis.
 1 : force decimal labelling, instead of automatic choice (see PGNUMB).
 2 : force exponential labelling, instead of automatic.

To get a complete frame, specify BC in both XOPT and YOPT.
Tick marks, if requested, are drawn on the axes or frame
or both, depending which are requested. If none of ABC is specified,
tick marks will not be drawn. When PGENV calls PGBOX, it sets both
XOPT and YOPT according to the value of its parameter AXIS:
-1: 'BC', 0: 'BCNST', 1: 'ABCNST', 2: 'ABCGNST'.

For a logarithmic axis, the major tick interval is always 1.0. The
numeric label is 10**(x) where x is the world coordinate at the
tick mark. If subticks are requested, 8 subticks are drawn between
each major tick at equal logarithmic intervals.

To label an axis with time (days, hours, minutes, seconds) or
angle (degrees, arcmin, arcsec), use routine PGTBOX.

PGCIRC -- draw a circle, using fill-area attributes

      SUBROUTINE PGCIRC (XCENT, YCENT, RADIUS)
      REAL XCENT, YCENT, RADIUS

Draw a circle. The action of this routine depends
on the setting of the Fill-Area Style attribute. If Fill-Area Style
is SOLID (the default), the interior of the circle is solid-filled
using the current Color Index. If Fill-Area Style is HOLLOW, the
outline of the circle is drawn using the current line attributes
(color index, line-style, and line-width).

Arguments:
 XCENT  (input)  : world x-coordinate of the center of the circle.
 YCENT  (input)  : world y-coordinate of the center of the circle.
 RADIUS (input)  : radius of circle (world coordinates).

PGCLOS -- close the selected graphics device

      SUBROUTINE PGCLOS

Close the currently selected graphics device. After the device has
been closed, either another open device must be selected with PGSLCT
or another device must be opened with PGOPEN before any further
plotting can be done. If the call to PGCLOS is omitted, some or all 
of the plot may be lost.

[This routine was added to PGPLOT in Version 5.1.0. Older programs
use PGEND instead.]

Arguments: none

PGCONB -- contour map of a 2D data array, with blanking

      SUBROUTINE PGCONB (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, TR, 
     1                   BLANK)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, NC
      REAL    A(IDIM,JDIM), C(*), TR(6), BLANK

Draw a contour map of an array. This routine is the same as PGCONS,
except that array elements that have the "magic value" defined by
argument BLANK are ignored, making gaps in the contour map. The
routine may be useful for data measured on most but not all of the
points of a grid.

Arguments:
 A      (input)  : data array.
 IDIM   (input)  : first dimension of A.
 JDIM   (input)  : second dimension of A.
 I1,I2  (input)  : range of first index to be contoured (inclusive).
 J1,J2  (input)  : range of second index to be contoured (inclusive).
 C      (input)  : array of contour levels (in the same units as the
                   data in array A); dimension at least NC.
 NC     (input)  : number of contour levels (less than or equal to
                   dimension of C). The absolute value of this
                   argument is used (for compatibility with PGCONT,
                   where the sign of NC is significant).
 TR     (input)  : array defining a transformation between the I,J
                   grid of the array and the world coordinates. The
                   world coordinates of the array point A(I,J) are
                   given by:
                     X = TR(1) + TR(2)*I + TR(3)*J
                     Y = TR(4) + TR(5)*I + TR(6)*J
                   Usually TR(3) and TR(5) are zero - unless the
                   coordinate transformation involves a rotation
                   or shear.
 BLANK   (input) : elements of array A that are exactly equal to
                   this value are ignored (blanked).

PGCONF -- fill between two contours

      SUBROUTINE PGCONF (A, IDIM, JDIM, I1, I2, J1, J2, C1, C2, TR)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      REAL    A(IDIM,JDIM), C1, C2, TR(6)

Shade the region between two contour levels of a function defined on
the nodes of a rectangular grid. The routine uses the current fill
attributes, hatching style (if appropriate), and color index.

If you want to both shade between contours and draw the contour
lines, call this routine first (once for each pair of levels) and 
then CALL PGCONT (or PGCONS) to draw the contour lines on top of the
shading.

Note 1: This routine is not very efficient: it generates a polygon
fill command for each cell of the mesh that intersects the desired
area, rather than consolidating adjacent cells into a single polygon.

Note 2: If both contours intersect all four edges of a particular
mesh cell, the program behaves badly and may consider some parts
of the cell to lie in more than one contour range.

Note 3: If a contour crosses all four edges of a cell, this
routine may not generate the same contours as PGCONT or PGCONS
(these two routines may not agree either). Such cases are always
ambiguous and the routines use different approaches to resolving
the ambiguity.

Arguments:
 A      (input)  : data array.
 IDIM   (input)  : first dimension of A.
 JDIM   (input)  : second dimension of A.
 I1,I2  (input)  : range of first index to be contoured (inclusive).
 J1,J2  (input)  : range of second index to be contoured (inclusive).
 C1, C2 (input)  : contour levels; note that C1 must be less than C2.
 TR     (input)  : array defining a transformation between the I,J
                   grid of the array and the world coordinates. The
                   world coordinates of the array point A(I,J) are
                   given by:
                     X = TR(1) + TR(2)*I + TR(3)*J
                     Y = TR(4) + TR(5)*I + TR(6)*J
                   Usually TR(3) and TR(5) are zero - unless the
                   coordinate transformation involves a rotation
                   or shear.

PGCONL -- label contour map of a 2D data array 

      SUBROUTINE PGCONL (A, IDIM, JDIM, I1, I2, J1, J2, C, TR,
     1                   LABEL, INTVAL, MININT)
      INTEGER IDIM, JDIM, I1, J1, I2, J2, INTVAL, MININT
      REAL A(IDIM,JDIM), C, TR(6)
      CHARACTER*(*) LABEL

Label a contour map drawn with routine PGCONT. Routine PGCONT should
be called first to draw the contour lines, then this routine should be
called to add the labels. Labels are written at intervals along the
contour lines, centered on the contour lines with lettering aligned
in the up-hill direction. Labels are opaque, so a part of the under-
lying contour line is obscured by the label. Labels use the current
attributes (character height, line width, color index, character
font).

The first 9 arguments are the same as those supplied to PGCONT, and
should normally be identical to those used with PGCONT. Note that
only one contour level can be specified; tolabel more contours, call
PGCONL for each level.

The Label is supplied as a character string in argument LABEL.

The spacing of labels along the contour is specified by parameters
INTVAL and MININT. The routine follows the contour through the
array, counting the number of cells that the contour crosses. The
first label will be written in the MININT'th cell, and additional
labels will be written every INTVAL cells thereafter. A contour
that crosses less than MININT cells will not be labelled. Some
experimentation may be needed to get satisfactory results; a good
place to start is INTVAL=20, MININT=10.

Arguments:
 A      (input) : data array.
 IDIM   (input) : first dimension of A.
 JDIM   (input) : second dimension of A.
 I1, I2 (input) : range of first index to be contoured (inclusive).
 J1, J2 (input) : range of second index to be contoured (inclusive).
 C      (input) : the level of the contour to be labelled (one of the
                  values given to PGCONT).
 TR     (input) : array defining a transformation between the I,J
                  grid of the array and the world coordinates.
                  The world coordinates of the array point A(I,J)
                  are given by:
                    X = TR(1) + TR(2)*I + TR(3)*J
                    Y = TR(4) + TR(5)*I + TR(6)*J
                  Usually TR(3) and TR(5) are zero - unless the
                  coordinate transformation involves a rotation or
                  shear.
 LABEL  (input) : character strings to be used to label the specified
                  contour. Leading and trailing blank spaces are
                  ignored.
 INTVAL (input) : spacing along the contour between labels, in
                  grid cells.
 MININT (input) : contours that cross less than MININT cells
                  will not be labelled.

PGCONS -- contour map of a 2D data array (fast algorithm)

      SUBROUTINE PGCONS (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, TR)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, NC
      REAL    A(IDIM,JDIM), C(*), TR(6)

Draw a contour map of an array. The map is truncated if
necessary at the boundaries of the viewport.  Each contour line is
drawn with the current line attributes (color index, style, and
width).  This routine, unlike PGCONT, does not draw each contour as a
continuous line, but draws the straight line segments composing each
contour in a random order.  It is thus not suitable for use on pen
plotters, and it usually gives unsatisfactory results with dashed or
dotted lines.  It is, however, faster than PGCONT, especially if
several contour levels are drawn with one call of PGCONS.

Arguments:
 A      (input)  : data array.
 IDIM   (input)  : first dimension of A.
 JDIM   (input)  : second dimension of A.
 I1,I2  (input)  : range of first index to be contoured (inclusive).
 J1,J2  (input)  : range of second index to be contoured (inclusive).
 C      (input)  : array of contour levels (in the same units as the
                   data in array A); dimension at least NC.
 NC     (input)  : number of contour levels (less than or equal to
                   dimension of C). The absolute value of this
                   argument is used (for compatibility with PGCONT,
                   where the sign of NC is significant).
 TR     (input)  : array defining a transformation between the I,J
                   grid of the array and the world coordinates. The
                   world coordinates of the array point A(I,J) are
                   given by:
                     X = TR(1) + TR(2)*I + TR(3)*J
                     Y = TR(4) + TR(5)*I + TR(6)*J
                   Usually TR(3) and TR(5) are zero - unless the
                   coordinate transformation involves a rotation
                   or shear.

PGCONT -- contour map of a 2D data array (contour-following)

      SUBROUTINE PGCONT (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, TR)
      INTEGER IDIM, JDIM, I1, J1, I2, J2, NC
      REAL A(IDIM,JDIM), C(*), TR(6)

Draw a contour map of an array.  The map is truncated if
necessary at the boundaries of the viewport.  Each contour line
is drawn with the current line attributes (color index, style, and
width); except that if argument NC is positive (see below), the line
style is set by PGCONT to 1 (solid) for positive contours or 2
(dashed) for negative contours.

Arguments:
 A      (input) : data array.
 IDIM   (input) : first dimension of A.
 JDIM   (input) : second dimension of A.
 I1, I2 (input) : range of first index to be contoured (inclusive).
 J1, J2 (input) : range of second index to be contoured (inclusive).
 C      (input) : array of NC contour levels; dimension at least NC.
 NC     (input) : +/- number of contour levels (less than or equal
                  to dimension of C). If NC is positive, it is the
                  number of contour levels, and the line-style is
                  chosen automatically as described above. If NC is
                  negative, it is minus the number of contour
                  levels, and the current setting of line-style is
                  used for all the contours.
 TR     (input) : array defining a transformation between the I,J
                  grid of the array and the world coordinates.
                  The world coordinates of the array point A(I,J)
                  are given by:
                    X = TR(1) + TR(2)*I + TR(3)*J
                    Y = TR(4) + TR(5)*I + TR(6)*J
                  Usually TR(3) and TR(5) are zero - unless the
                  coordinate transformation involves a rotation or
                  shear.

PGCONX -- contour map of a 2D data array (non rectangular)

      SUBROUTINE PGCONX (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, PLOT)
      INTEGER  IDIM, JDIM, I1, J1, I2, J2, NC
      REAL     A(IDIM,JDIM), C(*)
      EXTERNAL PLOT

Draw a contour map of an array using a user-supplied plotting
routine.  This routine should be used instead of PGCONT when the
data are defined on a non-rectangular grid.  PGCONT permits only
a linear transformation between the (I,J) grid of the array
and the world coordinate system (x,y), but PGCONX permits any
transformation to be used, the transformation being defined by a
user-supplied subroutine. The nature of the contouring algorithm,
however, dictates that the transformation should maintain the
rectangular topology of the grid, although grid-points may be
allowed to coalesce.  As an example of a deformed rectangular
grid, consider data given on the polar grid theta=0.1n(pi/2),
for n=0,1,...,10, and r=0.25m, for m=0,1,..,4. This grid
contains 55 points, of which 11 are coincident at the origin.
The input array for PGCONX should be dimensioned (11,5), and
data values should be provided for all 55 elements.  PGCONX can
also be used for special applications in which the height of the
contour affects its appearance, e.g., stereoscopic views.

The map is truncated if necessary at the boundaries of the viewport.
Each contour line is drawn with the current line attributes (color
index, style, and width); except that if argument NC is positive
(see below), the line style is set by PGCONX to 1 (solid) for
positive contours or 2 (dashed) for negative contours. Attributes
for the contour lines can also be set in the user-supplied
subroutine, if desired.

Arguments:
 A      (input) : data array.
 IDIM   (input) : first dimension of A.
 JDIM   (input) : second dimension of A.
 I1, I2 (input) : range of first index to be contoured (inclusive).
 J1, J2 (input) : range of second index to be contoured (inclusive).
 C      (input) : array of NC contour levels; dimension at least NC.
 NC     (input) : +/- number of contour levels (less than or equal
                  to dimension of C). If NC is positive, it is the
                  number of contour levels, and the line-style is
                  chosen automatically as described above. If NC is
                  negative, it is minus the number of contour
                  levels, and the current setting of line-style is
                  used for all the contours.
 PLOT   (input) : the address (name) of a subroutine supplied by
                  the user, which will be called by PGCONX to do
                  the actual plotting. This must be declared
                  EXTERNAL in the program unit calling PGCONX.

The subroutine PLOT will be called with four arguments:
     CALL PLOT(VISBLE,X,Y,Z)
where X,Y (input) are real variables corresponding to
I,J indices of the array A. If  VISBLE (input, integer) is 1,
PLOT should draw a visible line from the current pen
position to the world coordinate point corresponding to (X,Y);
if it is 0, it should move the pen to (X,Y). Z is the value
of the current contour level, and may be used by PLOT if desired.
Example:
      SUBROUTINE PLOT (VISBLE,X,Y,Z)
      REAL X, Y, Z, XWORLD, YWORLD
      INTEGER VISBLE
      XWORLD = X*COS(Y) ! this is the user-defined
      YWORLD = X*SIN(Y) ! transformation
      IF (VISBLE.EQ.0) THEN
          CALL PGMOVE (XWORLD, YWORLD)
      ELSE
          CALL PGDRAW (XWORLD, YWORLD)
      END IF
      END

PGCTAB -- install the color table to be used by PGIMAG

      SUBROUTINE PGCTAB(L, R, G, B, NC, CONTRA, BRIGHT)
      INTEGER NC
      REAL    L(NC), R(NC), G(NC), B(NC), CONTRA, BRIGHT

Use the given color table to change the color representations of
all color indexes marked for use by PGIMAG. To change which
color indexes are thus marked, call PGSCIR before calling PGCTAB
or PGIMAG. On devices that can change the color representations
of previously plotted graphics, PGCTAB will also change the colors
of existing graphics that were plotted with the marked color
indexes. This feature can then be combined with PGBAND to
interactively manipulate the displayed colors of data previously
plotted with PGIMAG.

Limitations:
 1. Some devices do not propagate color representation changes
    to previously drawn graphics.
 2. Some devices ignore requests to change color representations.
 3. The appearance of specific color representations on grey-scale
    devices is device-dependent.

Notes:
 To reverse the sense of a color table, change the chosen contrast
 and brightness to -CONTRA and 1-BRIGHT.

 In the following, the term 'color table' refers to the input
 L,R,G,B arrays, whereas 'color ramp' refers to the resulting
 ramp of colors that would be seen with PGWEDG.

Arguments:
 L      (input)  : An array of NC normalized ramp-intensity levels
                   corresponding to the RGB primary color intensities
                   in R(),G(),B(). Colors on the ramp are linearly
                   interpolated from neighbouring levels.
                   Levels must be sorted in increasing order.
                    0.0 places a color at the beginning of the ramp.
                    1.0 places a color at the end of the ramp.
                   Colors outside these limits are legal, but will
                   not be visible if CONTRA=1.0 and BRIGHT=0.5.
 R      (input)  : An array of NC normalized red intensities.
 G      (input)  : An array of NC normalized green intensities.
 B      (input)  : An array of NC normalized blue intensities.
 NC     (input)  : The number of color table entries.
 CONTRA (input)  : The contrast of the color ramp (normally 1.0).
                   Negative values reverse the direction of the ramp.
 BRIGHT (input)  : The brightness of the color ramp. This is normally
                   0.5, but can sensibly hold any value between 0.0
                   and 1.0. Values at or beyond the latter two
                   extremes, saturate the color ramp with the colors
                   of the respective end of the color table.

PGCURS -- read cursor position

      INTEGER FUNCTION PGCURS (X, Y, CH)
      REAL X, Y
      CHARACTER*(*) CH

Read the cursor position and a character typed by the user.
The position is returned in world coordinates.  PGCURS positions
the cursor at the position specified, allows the user to move the
cursor using the joystick or arrow keys or whatever is available on
the device. When he has positioned the cursor, the user types a
single character on the keyboard; PGCURS then returns this
character and the new cursor position (in world coordinates).

Returns:
 PGCURS         : 1 if the call was successful; 0 if the device
                   has no cursor or some other error occurs.
Arguments:
 X      (in/out) : the world x-coordinate of the cursor.
 Y      (in/out) : the world y-coordinate of the cursor.
 CH     (output) : the character typed by the user; if the device has
                   no cursor or if some other error occurs, the value
                   CHAR(0) [ASCII NUL character] is returned.

Note: The cursor coordinates (X,Y) may be changed by PGCURS even if
the device has no cursor or if the user does not move the cursor.
Under these circumstances, the position returned in (X,Y) is that of
the pixel nearest to the requested position.

PGDRAW -- draw a line from the current pen position to a point

      SUBROUTINE PGDRAW (X, Y)
      REAL X, Y

Draw a line from the current pen position to the point
with world-coordinates (X,Y). The line is clipped at the edge of the
current window. The new pen position is (X,Y) in world coordinates.

Arguments:
 X      (input)  : world x-coordinate of the end point of the line.
 Y      (input)  : world y-coordinate of the end point of the line.

PGEBUF -- end batch of output (buffer)

      SUBROUTINE PGEBUF

A call to PGEBUF marks the end of a batch of graphical output begun
with the last call of PGBBUF.  PGBBUF and PGEBUF calls should always
be paired. Each call to PGBBUF increments a counter, while each call
to PGEBUF decrements the counter. When the counter reaches 0, the
batch of output is written on the output device.

Arguments: none

PGEND -- close all open graphics devices

      SUBROUTINE PGEND

Close and release any open graphics devices. All devices must be
closed by calling either PGCLOS (for each device) or PGEND before
the program terminates. If a device is not closed properly, some
or all of the graphical output may be lost.

Arguments: none

PGENV -- set window and viewport and draw labeled frame

      SUBROUTINE PGENV (XMIN, XMAX, YMIN, YMAX, JUST, AXIS)
      REAL XMIN, XMAX, YMIN, YMAX
      INTEGER JUST, AXIS

Set PGPLOT "Plotter Environment".  PGENV establishes the scaling
for subsequent calls to PGPT, PGLINE, etc.  The plotter is
advanced to a new page or panel, clearing the screen if necessary.
If the "prompt state" is ON (see PGASK), confirmation
is requested from the user before clearing the screen.
If requested, a box, axes, labels, etc. are drawn according to
the setting of argument AXIS.

Arguments:
 XMIN   (input)  : the world x-coordinate at the bottom left corner
                   of the viewport.
 XMAX   (input)  : the world x-coordinate at the top right corner
                   of the viewport (note XMAX may be less than XMIN).
 YMIN   (input)  : the world y-coordinate at the bottom left corner
                   of the viewport.
 YMAX   (input)  : the world y-coordinate at the top right corner
                   of the viewport (note YMAX may be less than YMIN).
 JUST   (input)  : if JUST=1, the scales of the x and y axes (in
                   world coordinates per inch) will be equal,
                   otherwise they will be scaled independently.
 AXIS   (input)  : controls the plotting of axes,