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

GRAREA -- define a clipping window

      SUBROUTINE GRAREA (IDENT,X0,Y0,XSIZE,YSIZE)

GRPCKG: Define a rectangular window in the current plotting area. All
graphics (except characters written with GRCHAR) will be blanked
outside this window.  The default window is the full plotting area
defined by default or by GRSETS.

Arguments:

IDENT (input, integer): the plot identifier, returned by GROPEN.
X0, Y0 (input, real): the lower left corner of the window, in absolute
      device coordinates.
XSIZE, YSIZE (input, real): width and height of the window in absolute
      coordinates; if either is negative, the window will be reset to
      the full plotting area.

GRBPIC -- begin picture

      SUBROUTINE GRBPIC

GRPCKG (internal routine). Send a "begin picture" command to the
device driver, and send commands to set deferred attributes (color,
line width, etc.)

***********************************************************************
*                                                                     *
*  PGPLOT Fortran Graphics Subroutine Library                         *
*                                                                     *
*  T. J. Pearson, California Institute of Technology,                 *
*  Pasadena, California 91125.                                        *
*                                                                     *
*  Routines for handling the obsolete character set                   *
*  ------------------------------------------------                   *
*  These routines are not called by PGPLOT but are called by some     *
*  old user-written programs.                                         *
***********************************************************************

******* Index of Modules **********************************************

* GRCHAR -- draw a string of characters
* GRCHR0 -- support routine for GRCHAR and GRMARK
* GRDAT2 -- character set definition (block data)
* GRGTC0 -- obtain character digitization
* GRMARK -- mark points with specified symbol

***********************************************************************

GRCHAR -- draw a string of characters

      SUBROUTINE GRCHAR (IDENT,CENTER,ORIENT,ABSXY,X0,Y0,STRING)

GRPCKG: Draw a string of characters. The plot is not windowed
in the current subarea, but in the full plotting area.

Arguments:

IDENT (input, integer): plot identifier, as returned by GROPEN.
CENTER (input, logical): if .TRUE., the first character of the string
     is centered at (X0,Y0); otherwise the bottom left corner of the
     first character is placed at (X0,Y0).
ORIENT (input, real): the angle in degrees that the string is to make
     with the horizontal, increasing anticlockwise.
ABSXY (input, logical): if .TRUE., (X0,Y0) are absolute device
     coordinates; otherwise they are world coordinates (the scaling
     transformation is applied).
X0, Y0 (input, real): position of first character (see CENTER).
STRING (input, character): the string of ASCII characters; control
     characters 0-20 have special representations; all other
     non-graphic characters are plotted as blank spaces.

(1-Feb-1983)

GRCHR0 -- support routine for GRCHAR and GRMARK

      SUBROUTINE GRCHR0 (WINDOW,CENTER,ORIENT,ABSXY,X0,Y0,STRING)

GRPCKG (internal routine): Support routine for GRCHAR and GRMARK.
Draw a string of characters.

Arguments:

WINDOW (input, logical): if .TRUE., the plot is windowed in the
     current window.
CENTER (input, logical): if .TRUE., the first character of the string
     is centered at (X0,Y0); otherwise the bottom left corner of the
     first character is placed at (X0,Y0).
ORIENT (input, real): the angle in degrees that the string is to make
     with the horizontal, increasing anticlockwise.
ABSXY (input, logical): if .TRUE., (X0,Y0) are absolute device
     coordinates; otherwise they are world coordinates (the scaling
     transformation is applied).
X0, Y0 (input, real): position of first character (see CENTER).
STRING (input, character): the string of ASCII characters; control
     characters 0-20 have special representations; all other
     non-graphic characters are plotted as blank spaces.

(1-Mar-1983)

GRCHSZ -- inquire default character attributes

      SUBROUTINE GRCHSZ (IDENT,XSIZE,YSIZE,XSPACE,YSPACE)

GRPCKG: Obtain the default character attributes.

Arguments:

IDENT (input, integer): the plot identifier, returned by GROPEN.
XSIZE, YSIZE (output, real): the default character size
     (absolute device units).
XSPACE, YSPACE (output, real): the default character spacing
     (absolute units); XSPACE is the distance between the lower left
     corners of adjacent characters in a plotted string; YSPACE
     is the corresponding vertical spacing.

GRCLIP -- clip a point against clipping rectangle

      SUBROUTINE GRCLIP (X,Y,XMIN,XMAX,YMIN,YMAX,C)
      REAL X,Y
      REAL XMIN,XMAX,YMIN,YMAX
      INTEGER C

GRPCKG (internal routine): support routine for the clipping algorithm;
called from GRLIN0 only. C is a 4 bit code indicating the relationship
between point (X,Y) and the window boundaries; 0 implies the point is
within the window.

Arguments:

GRCLOS -- close graphics device

      SUBROUTINE GRCLOS

GRPCKG: Close the open plot on the current device. Any pending output
is sent to the device, the device is released for other users or the
disk file is closed, and no further plotting is allowed on the device
without a new call to GROPEN.

Arguments: none.

GRCLPL -- clip line against clipping rectangle

      SUBROUTINE GRCLPL (X0,Y0,X1,Y1,VIS)

GRPCKG (internal routine): Change the end-points of the line (X0,Y0)
(X1,Y1) to clip the line at the window boundary.  The algorithm is
that of Cohen and Sutherland (ref: Newman & Sproull).

Arguments:

X0, Y0 (input/output, real): device coordinates of starting point
      of line.
X1, Y1 (input/output, real): device coordinates of end point of line.
VIS (output, logical): .TRUE. if line lies wholly or partially
      within the clipping rectangle; .FALSE. if it lies entirely
      outside the rectangle.

GRCTOI -- convert character string to integer

      INTEGER FUNCTION GRCTOI (S, I)
      CHARACTER*(*) S
      INTEGER I

GRCTOI: attempt to read an integer from a character string, and return
the result. No attempt is made to avoid integer overflow. A valid 
integer is any sequence of decimal digits.

Returns:
 GRCTOI           : the value of the integer; if the first character
                   read is not a decimal digit, the value returned
                   is zero.
Arguments:
 S      (input)  : character string to be parsed.
 I      (in/out) : on input, I is the index of the first character
                   in S to be examined; on output, either it points
                   to the next character after a valid integer, or
                   it is equal to LEN(S)+1.

GRCURS -- read cursor position

      INTEGER FUNCTION GRCURS (IDENT,IX,IY,IXREF,IYREF,MODE,POSN,CH)
      INTEGER IDENT, IX, IY, IXREF, IYREF, MODE, POSN
      CHARACTER*(*) CH

GRPCKG: Read the cursor position and a character typed by the user.
The position is returned in absolute device coordinates (pixels).
GRCURS positions the cursor at the position specified, and
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 his
keyboard; GRCURS then returns this character and the new cursor
position.

"Rubber band" feedback of cursor movement can be requested (although
it may not be supported on some devices). If MODE=1, a line from
the anchor point to the current cursor position is displayed as
the cursor is moved. If MODE=2, a rectangle with vertical and
horizontal sides and one vertex at the anchor point and the opposite
vertex at the current cursor position is displayed as the cursor is
moved.

Returns:

GRCURS (integer): 1 if the call was successful; 0 if the device
     has no cursor or some other error occurs. 

Arguments:

IDENT (integer, input):  GRPCKG plot identifier (from GROPEN).
IX    (integer, in/out): the device x-coordinate of the cursor.
IY    (integer, in/out): the device y-coordinate of the cursor.
IXREF (integer, input):  x-coordinate of anchor point.
IYREF (integer, input):  y-coordinate of anchor point.
MODE  (integer, input):  type of rubber-band feedback.
CH    (char,    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.

GRDAT2 -- character set definition (block data)

      BLOCK DATA GRDAT2

GRPCKG (internal routine): Block data for to define the character set.

Arguments: none.

(1-Feb-1983)

GRDOT0 -- draw a dot

      SUBROUTINE GRDOT0 (X,Y)

GRPCKG (internal routine): Draw a single dot (pixel) at a specified
location.

Arguments:

X, Y (real, input): absolute device coordinates of the dot (these
      are rounded to the nearest integer by GRDOT0).

GRDOT1 -- draw dots

      SUBROUTINE GRDOT1(POINTS, X, Y)
      INTEGER POINTS
      REAL X(POINTS), Y(POINTS)

GRPCKG (internal routine): Draw a set of dots.

Arguments:

POINTS (input, integer): the number of coordinate pairs.
X, Y (input, real arrays, dimensioned POINTS or greater): the
      X and Y world coordinates of the points.

GRDTYP -- decode graphics device type string

      INTEGER FUNCTION GRDTYP (TEXT)

GRPCKG (internal routine): determine graphics device type code from
type name. It compares the argument with the table of known device
types in common.

Argument:

TEXT (input, character): device type name, eg 'PRINTRONIX'; the name
      may be abbreviated to uniqueness.

Returns:

GRDTYP (integer): the device type code, in the range 1 to
      GRTMAX, zero if the type name is not recognised, or -1
      if the type name is ambiguous.

GREPIC -- end picture

      SUBROUTINE GREPIC

GRPCKG: End the current picture.

Arguments: none.

GRESC -- escape routine

      SUBROUTINE GRESC (TEXT)

GRPCKG: "Escape" routine. The specified text is sent directly to the
selected graphics device, with no interpretation by GRPCKG. This
routine must be used with care; e.g., the programmer needs to know
the device type of the currently selected device, and the instructions
that that device can accept.

Arguments: none.
 TEXT (input, character*(*)):  text to be sent to the device.

15-May-1985 - new routine [TJP].
26-May-1987 - add GREXEC support [TJP].
19-Dec-1988 - start new page if necessary [TJP].
 4-Feb-1997 - RBUF should be an array, not a scalar [TJP].

GRETXT -- erase text from graphics screen

      SUBROUTINE GRETXT

GRPCKG: Erase the text screen.  Some graphics devices have
two superimposed view surfaces, of which one is used for graphics and
the other for alphanumeric text.  This routine erases the text
view surface without affecting the graphics view surface. It does
nothing if there is no text view surface associated with the device.

Arguments: none.

GRFA -- fill area (polygon)

      SUBROUTINE GRFA (N,PX,PY)
      INTEGER N
      REAL PX(*), PY(*)

GRPCKG: FILL AREA: fill a polygon with solid color.  The polygon
is defined by the (x,y) world coordinates of its N vertices.  If
this is not a function supported by the device, shading is
accomplished by drawing horizontal lines spaced by 1 pixel.  By
selecting color index 0, the interior of the polygon can be erased
on devices which permit it.  The polygon need not be convex, but if
it is re-entrant (i.e., edges intersect other than at the vertices),
it may not be obvious which regions are "inside" the polygon.  The
following rule is applied: for a given point, create a straight line
starting at the point and going to infinity. If the number of
intersections between the straight line and the polygon is odd, the
point is within the polygon; otherwise it is outside. If the
straight line passes a polygon vertex tangentially, the
intersection  count is not affected. The only attribute which applies
to FILL AREA is color index: line-width and line-style are ignored.
There is a limitation on the complexity of the polygon: GFA will
fail if any horizontal line intersects more than 32 edges of the
polygon.

Arguments:

N (input, integer): the number of vertices of the polygon (at least
      3).
PX, PY (input, real arrays, dimension at least N): world coordinates
      of the N vertices of the polygon.

GRFAO - format character string containing integers

      SUBROUTINE GRFAO (FORMAT, L, STR, V1, V2, V3, V4)
      CHARACTER*(*) FORMAT
      INTEGER L
      CHARACTER*(*) STR
      INTEGER V1, V2, V3, V4

The input string FORMAT is copied to the output string STR with
the first occurrence of '#' replaced by the value of V1, the second
by the value of V2, etc.  The length of the resulting string is 
returned in L.

GRGFIL -- find data file

      SUBROUTINE GRGFIL(TYPE, NAME)
      CHARACTER*(*) TYPE, NAME

This routine encsapsulates the algorithm for finding the PGPLOT
run-time data files.

1. The binary font file: try the following in order:
    file specified by PGPLOT_FONT
    file "grfont.dat" in directory specified by PGPLOT_DIR
                      (with or without '/' appended)
    file "grfont.dat" in directory /usr/local/pgplot/

2. The color-name database: try the following in order:
    file specified by PGPLOT_RGB
    file "rgb.txt" in directory specified by PGPLOT_DIR
                      (with or without '/' appended)
    file "rgb.txt" in directory /usr/local/pgplot/

Arguments:
 TYPE (input)  : either 'FONT' or 'RGB' to request the corresponding
                 file.
 NAME (output) : receives the file name.

GRGRAY -- gray-scale map of a 2D data array

      SUBROUTINE GRGRAY (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   FG, BG, PA, MININD, MAXIND, MODE)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, MININD, MAXIND, MODE
      REAL    A(IDIM,JDIM)
      REAL    FG, BG
      REAL    PA(6)

This is a device-dependent support routine for PGGRAY.

Draw gray-scale map of an array in current window. Array
values between FG and BG are shaded in gray levels determined
by linear interpolation. FG may be either less than or greater
than BG.  Array values outside the range FG to BG are
shaded black or white as appropriate.

GRGRAY uses GRIMG0 on devices with enough color indices available.
Note that it changes the color table to gray-scale.
Otherwise in does a random dither with GRIMG3.

Arguments:
 A      (input)  : the array to be plotted.
 IDIM   (input)  : the first dimension of array A.
 JDIM   (input)  : the second dimension of array A.
 I1, I2 (input)  : the inclusive range of the first index
                   (I) to be plotted.
 J1, J2 (input)  : the inclusive range of the second
                   index (J) to be plotted.
 FG     (input)  : the array value which is to appear in
                   foreground color.
 BG     (input)  : the array value which is to appear in
                   background color.
 PA     (input)  : transformation matrix between array grid and
                   device coordinates (see GRCONT).
 MODE   (input)  : transfer function.

GRGTC0 -- obtain character digitization

      SUBROUTINE GRGTC0 (CHAR,CENTER,POINTS,X,Y,MORE)

GRPCKG (internal routine): obtain character digitization.

(10-Feb-1983)

GRIMG0 -- color image of a 2D data array

      SUBROUTINE GRIMG0 (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   A1, A2, PA, MININD, MAXIND, MODE)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, MININD, MAXIND, MODE
      REAL    A(IDIM,JDIM), A1, A2, PA(6)

This is a support routine for PGIMAG.

Arguments:
 A      (input)  : the array to be plotted.
 IDIM   (input)  : the first dimension of array A.
 JDIM   (input)  : the second dimension of array A.
 I1, I2 (input)  : the inclusive range of the first index
                   (I) to be plotted.
 J1, J2 (input)  : the inclusive range of the second
                   index (J) to be plotted.
 A1     (input)  : the array value which is to appear in color
                   index MININD.
 A2     (input)  : the array value which is to appear in color
                   index MAXIND.
 PA     (input)  : transformation matrix between array grid and
                   device coordinates.
 MININD (input)  : minimum color index to use.
 MAXIND (input)  : maximum color index to use.
 MODE   (input)  : =0 for linear, =1 for logarithmic, =2 for
                   square-root mapping of array values to color
                   indices.

GRIMG1 -- image of a 2D data array (image-primitive devices)

      SUBROUTINE GRIMG1 (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   A1, A2, PA, MININD, MAXIND, MODE)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, MININD, MAXIND, MODE
      REAL    A(IDIM,JDIM), A1, A2, PA(6)

(This routine is called by GRIMG0.)

GRIMG2 -- image of a 2D data array (pixel-primitive devices)

      SUBROUTINE GRIMG2 (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   A1, A2, PA, MININD, MAXIND, MODE)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, MININD, MAXIND, MODE
      REAL    A(IDIM,JDIM)
      REAL    A1, A2
      REAL    PA(6)

(This routine is called by GRIMG0.)

GRIMG3 -- gray-scale map of a 2D data array, using dither

      SUBROUTINE GRIMG3 (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   BLACK, WHITE, PA, MODE)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, MODE
      REAL    A(IDIM,JDIM)
      REAL    BLACK, WHITE
      REAL    PA(6)

GRINIT -- initialize GRPCKG

      SUBROUTINE GRINIT

Initialize GRPCKG and read font file. Called by GROPEN, but may be 
called explicitly if needed.

GRINQFONT -- inquire current font [obsolete]

GRINQLI -- *obsolete routine*

      SUBROUTINE GRINQLI (INTEN)

GRPCKG: obtain the line intensity of the current graphics device.
Obsolete routine.
Argument:

INTEN (integer, output): always returns 1.

GRINQPEN -- *obsolete routine*

      SUBROUTINE GRINQPEN (IP)

GRPCKG: obtain the pen number of the current graphics device.
Obsolete routine.
Argument:

IP (integer, output): always receives 1.

GRITOC - convert integer to character string

      INTEGER FUNCTION GRITOC(INT, STR)
      INTEGER INT
      CHARACTER*(*) STR

Convert integer INT into (decimal) character string in STR.

GRLDEV -- list supported device types

      SUBROUTINE GRLDEV

Support routine for PGLDEV.

Arguments: none

GRLEN -- inquire plotted length of character string

      SUBROUTINE GRLEN (STRING, D)

GRPCKG: length of text string (absolute units)

GRLIN0 -- draw a line

      SUBROUTINE GRLIN0 (XP,YP)

GRPCKG (internal routine): draw a line from the current position to a
specified position, which becomes the new current position. This
routine takes care of clipping at the viewport boundary, dashed and
thick lines.

Arguments:

XP, YP (input, real): absolute device coordinates of the end-point of
      the line.

GRLIN1 -- draw a dashed line

      SUBROUTINE GRLIN1 (X0,Y0,X1,Y1,RESET)

GRPCKG : dashed line. Generate a visible dashed line between points
(X0,Y0) and (X1,Y1) according to the dash pattern stored in common.
If RESET = .TRUE., the pattern will start from the beginning.
Otherwise, it will continue from its last position.
    DASHED LINE PATTERN ARRAY CONTAINING LENGTHS OF
         MARKS AND SPACES IN UNIT CUBE: GRPATN(*)
    OFFSET IN CURRENT PATTERN SEGMENT: GRPOFF
    CURRENT PATTERN SEGMENT NUMBER: GRIPAT
    NUMBER OF PATTERN SEGMENTS: 8

GRLIN2 -- draw a normal line

      SUBROUTINE GRLIN2 (X0,Y0,X1,Y1)

GRPCKG : plot a visible line segment in absolute coords from
(X0,Y0) to (X1,Y1).  The endpoints of the line segment are rounded
to the nearest integer and passed to the appropriate device-specific
routine. It is assumed that the entire line-segment lies within the
view surface, and that the physical device coordinates are
non-negative.

GRLIN3 -- draw a thick line (multiple strokes)

      SUBROUTINE GRLIN3 (X0,Y0,X1,Y1)

GRPCKG: draw a heavy line from (X0,Y0) to (X1,Y1) by making multiple
strokes.  In order to simulate a thick pen, the line drawn has
circular, rather than square, end points.  If this is not done,
thick letters and other figures have an abnormal and unpleasant
appearance.

Vocabulary:

LINEWT: the number of strokes required to draw the line; if
      this is odd, one stroke will lie along the requested vector.
      The nominal line thickness is (LINEWT-1)*0.005 in.
RSQURD: the square of the semi-line thickness.
(DX,DY): the vector length of the line.
(VX,VY): a vector of length 1 pixel in the direction of the line.
(VY,-VX): a vector of length 1 pixel perpendicular to (VX,VY).
OFF: the offset parallel to (VY,-VX) of the K'th stroke.
(VXK,VYK): the vector increment of the K'th stroke to allow for the
      semi-circular terminal on the line.
(PXK,PYK): the vector offset of the K'th stroke perpendicular to the
      line vector.

GRLINA -- draw a line (absolute, world coordinates)

      SUBROUTINE GRLINA (X,Y)

GRPCKG: draw line from current position to a specified position.

Arguments:

X, Y (real, input): world coordinates of the end-point of the line.

GRLINR -- draw a line (relative, world coordinates)

      SUBROUTINE GRLINR (DX,DY)

GRPCKG: draw a line from the current position by a specified
relative displacement.

Arguments:

DX, DY (real, input): the displacement in world coordinates: the pen
      position is incremented by DX in x and DY in y.

GRMARK -- mark points with specified symbol

      SUBROUTINE GRMARK (IDENT,CENTER,SYMBOL,ABSXY,POINTS,X,Y)

GRPCKG: mark a sequence of points with a specified symbol. The
plot is windowed in the current subarea.

Arguments:

IDENT (integer, input): plot identifier from GROPEN.
CENTER (input, logical): if .TRUE. the symbol is centered on the point,
     otherwise the bottom left corner is placed at the point.
SYMBOL (byte or integer, input): code number of symbol in range 0-127
     (ASCII character or special symbol); if SYMBOL is outside this
     range, nothing is plotted.
ABSXY (logical, input): if .TRUE. (X,Y) are absolute (device)
     coordinates; otherwise they are world coordinates and the
     scaling transformation is applied.
POINTS (integer, input): the number of points; if POINTS is less than
     or equal to 0, nothing is plotted.
X,Y (real arrays, dimension at least POINTS, input): the coordinate
     pairs; if POINTS=1, these may be scalars instead of arrays.

(9-Mar-1983)

GRMKER -- draw graph markers

      SUBROUTINE GRMKER (SYMBOL,ABSXY,N,X,Y)

GRPCKG: Draw a graph marker at a set of points in the current
window. Line attributes (color, intensity, and  thickness)
apply to markers, but line-style is ignored. After the call to
GRMKER, the current pen position will be the center of the last
marker plotted.

Arguments:

SYMBOL (input, integer): the marker number to be drawn. Numbers
      0-31 are special marker symbols; numbers 32-127 are the
      corresponding ASCII characters (in the current font). If the
      number is >127, it is taken to be a Hershey symbol number.
      If -ve, a regular polygon is drawn.
ABSXY (input, logical): if .TRUE., the input corrdinates (X,Y) are
      taken to be absolute device coordinates; if .FALSE., they are
      taken to be world coordinates.
N (input, integer): the number of points to be plotted.
X, Y (input, real arrays, dimensioned at least N): the (X,Y)
      coordinates of the points to be plotted.

GRMOVA -- move pen (absolute, world coordinates)

      SUBROUTINE GRMOVA (X,Y)

GRPCKG: move the pen to a specified location.

Arguments:

X, Y (real, input): world coordinates of the new pen position.

GRMOVR -- move pen (relative, world coordinates)

      SUBROUTINE GRMOVR (DX,DY)

GRPCKG: move the pen through a specified displacement.

Arguments:

DX, DY (real, input): the displacement in world coordinates: the pen
      position is incremented by DX in x and DY in y.

GRMSG -- issue message to user

      SUBROUTINE GRMSG (TEXT)
      CHARACTER*(*) TEXT

Display a message on standard output.

Argument:
 TEXT (input): text of message to be printed (the string
     may not be blank).

GROPEN -- open device for graphics

      INTEGER FUNCTION GROPEN (TYPE,DUMMY,FILE,IDENT)
      INTEGER   TYPE, DUMMY, IDENT
      CHARACTER*(*) FILE

GRPCKG: assign a device and prepare for plotting.  GROPEN must be
called before all other calls to GRPCKG routines.

Returns:

GROPEN (output, integer): 1 => success, any other value
      indicates a failure (usually the value returned will
      be a VMS error code). In the event of an error, a
      message will be sent to the standard error unit.

Arguments:

TYPE (input, integer): default device type (integer code).
DUMMY (input, integer): not used at present.
FILE (input, character): plot specifier, of form 'device/type'.
IDENT (output, integer): plot identifier to be used in later
      calls to GRPCKG.

 1-Jun-1984 - [TJP].
 2-Jul-1984 - change to call GRSLCT [TJP].
13-Jul-1984 - add device initialization [TJP].
23-Jul-1984 - add /APPEND qualifier.
19-Oct-1984 - add VV device [TJP].
26-Dec-1984 - obtain default file name from common [TJP].
29-Jan-1985 - add HP2648 device [KS/TJP].
 5-Aug-1986 - add GREXEC support [AFT].
12-Oct-1986 - fix bug causing GREXEC to erase screen [AFT].
 3-Jun-1987 - remove declaration of exit handler [TJP].
15-Dec-1988 - standardize [TJP].
25-Jun-1989 - remove code that removes spaces from the device name 
              [TJP].
26-Nov-1990 - [TJP].
 5-Jan-1993 - [TJP].
 1-Sep-1994 - store device capabilities in common for later use [TJP].
17-Apr-1995 - zero-length string fix [TJP].
 6-Jun-1995 - explicitly initialize GRSTAT [TJP].
29-Apr-1996 - moved initialization into GRINIT [TJP].

GRPAGE -- end picture

      SUBROUTINE GRPAGE

GRPCKG: Advance the plotting area to a new page. For video devices,
this amounts to erasing the screen; for hardcopy devices, the plot
buffer is written to the output file followed by a form-feed to
advance the paper to the start of the next page.

Arguments: none.

GRPARS -- parse device specification string

      INTEGER FUNCTION GRPARS (SPEC,DEV,TYPE,APPEND)
      CHARACTER*(*) SPEC, DEV
      INTEGER  TYPE
      LOGICAL  APPEND

GRPCKG: decode a device-specification; called by GROPEN.

Returns:
 GRPARS (output): 1 if the device-specification is
      acceptable; any other value indicates an error.

Arguments:
 SPEC (input): the device specification.
 DEV  (output):  device name or file spec.
 TYPE (output): device type (integer code); 0 if no device
      type is specified.
 APPEND (output): .TRUE. if /APPEND specified, .FALSE. otherwise.

GRPIXL -- solid-fill multiple rectangular areas

      SUBROUTINE GRPIXL (IA, IDIM, JDIM, I1, I2, J1, J2, 
     1                   X1, X2, Y1, Y2)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      INTEGER IA(IDIM,JDIM)
      REAL    X1, X2, Y1, Y2

Determine the size of each rectangular element. If it is equal
to the device pen width and the device supports pixel primitives,
use pixel primitives. Otherwise, if the size is smaller than the
device pen width emulate pixel output by plotting points. If the
size is larger than the device pen width, emulate by outputting
solid-filled rectangles.

Arguments:
 IA     (input)  : the array to be plotted.
 IDIM   (input)  : the first dimension of array A.
 JDIM   (input)  : the second dimension of array A.
 I1, I2 (input)  : the inclusive range of the first index
                   (I) to be plotted.
 J1, J2 (input)  : the inclusive range of the second
                   index (J) to be plotted.
 X1, Y1 (input)  : world coordinates of one corner of the output
                   region
 X2, Y2 (input)  : world coordinates of the opposite corner of the
                   output region

GRPOCL -- polygon clip

      SUBROUTINE GRPOCL (N,PX,PY, EDGE, VAL, MAXOUT, NOUT, QX, QY)
      INTEGER N, NOUT, EDGE, MAXOUT
      REAL    PX(*), PY(*), QX(*), QY(*)
      REAL    VAL

Clip a polygon against a rectangle: Sutherland-Hodgman algorithm.
this routine must be called four times to clip against each of the
edges of the rectangle in turn.      

Arguments:

N (input, integer): the number of vertices of the polygon (at least
      3).
PX, PY (input, real arrays, dimension at least N): world coordinates
      of the N vertices of the input polygon.
EDGE (input, integer):
    1: clip against left edge,   X > XMIN=VAL
    2: clip against right edge,  X < XMAX=VAL
    3: clip against bottom edge, Y > YMIN=VAL
    4: clip against top edge,    Y < YMIN=VAL
VAL  (input, real): coordinate value of current edge.
MAXOUT (input, integer): maximum number of vertices allowed in
    output polygon (dimension of QX, QY).
NOUT (output, integer): the number of vertices in the clipped polygon.
QX, QY (output, real arrays, dimension at least MAXOUT): world
      coordinates of the NOUT vertices of the output polygon.

GRPROM -- prompt user before clearing screen

      SUBROUTINE GRPROM

If the program is running under control of a terminal, display
message and wait for the user to type <CR> before proceeding.

Arguments:
 none

GRPXPO -- Emulate pixel operations using points

      SUBROUTINE GRPXPO (IA, IDIM, JDIM, I1, I2, J1, J2, 
     1                   X1, X2, Y1, Y2)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      INTEGER IA(IDIM,JDIM)
      REAL    X1, X2, Y1, Y2

Arguments:
 IA     (input)  : the array to be plotted.
 IDIM   (input)  : the first dimension of array A.
 JDIM   (input)  : the second dimension of array A.
 I1, I2 (input)  : the inclusive range of the first index
                   (I) to be plotted.
 J1, J2 (input)  : the inclusive range of the second
                   index (J) to be plotted.
 X1, X2 (input)  : the horizontal range of the output region
 Y1, Y2 (input)  : the vertical range of the output region

GRPXPS -- pixel dump for color or grey PostScript.

      SUBROUTINE GRPXPS (IA, IDIM, JDIM, I1, I2, J1, J2,
     :                   XMIN, XMAX, YMIN, YMAX)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      INTEGER IA(IDIM,JDIM)
      REAL XMIN, XMAX, YMIN, YMAX

This routine is called by GRPIXL.

GRPXPX -- Perform pixel operations using pixel primitive

      SUBROUTINE GRPXPX (IA, IDIM, JDIM, I1, I2, J1, J2, X, Y)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      INTEGER IA(IDIM,JDIM)
      REAL    X, Y

Arguments:
 IA     (input)  : the array to be plotted.
 IDIM   (input)  : the first dimension of array A.
 JDIM   (input)  : the second dimension of array A.
 I1, I2 (input)  : the inclusive range of the first index
                   (I) to be plotted.
 J1, J2 (input)  : the inclusive range of the second
                   index (J) to be plotted.
 X, Y   (input)  : the lower left corner of the output region
                   (device coordinates)

GRPXRE -- Emulate pixel operations using rectangles

      SUBROUTINE GRPXRE (IA, IDIM, JDIM, I1, I2, J1, J2, 
     1                   X1, X2, Y1, Y2)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      INTEGER IA(IDIM,JDIM)
      REAL    X1, X2, Y1, Y2

Arguments:
 IA     (input)  : the array to be plotted.
 IDIM   (input)  : the first dimension of array A.
 JDIM   (input)  : the second dimension of array A.
 I1, I2 (input)  : the inclusive range of the first index
                   (I) to be plotted.
 J1, J2 (input)  : the inclusive range of the second
                   index (J) to be plotted.
 X1, X2 (input)  : the horizontal range of the output region
 Y1, Y2 (input)  : the vertical range of the output region

GRQCAP -- inquire device capabilities

      SUBROUTINE GRQCAP (STRING)
      CHARACTER*(*) STRING

GRPCKG: obtain the "device capabilities" string from the device
driver for the current device.

Arguments:

STRING (output, CHARACTER*(*)): receives the device capabilities
      string.

GRQCI -- inquire current color index

      SUBROUTINE GRQCI (C)

GRPCKG: obtain the color index of the current graphics device.

Argument:

C (integer, output): receives the current color index (0-255).

GRQCOL -- inquire color capability

      SUBROUTINE GRQCOL (CI1, CI2)
      INTEGER  CI1, CI2

Query the range of color indices available on the current device.

Argument:
 CI1    (output) : the minimum available color index. This will be
                   either 0 if the device can write in the
                   background color, or 1 if not.
 CI2    (output) : the maximum available color index. This will be
                   1 if the device has no color capability, or a
                   larger number (e.g., 3, 7, 15, 255).

GRQCR -- inquire color representation

      SUBROUTINE GRQCR (CI, CR, CG, CB)
      INTEGER  CI
      REAL     CR, CG, CB

Return the color representation (red, green, blue intensities) 
currently associated with the specified color index. This may be
different from that requested on some devices.

Arguments:

CI (integer, input): color index.
CR, CG, CB (real, output): red, green, and blue intensities,
      in range 0.0 to 1.0.

GRQDEV -- inquire current device

      SUBROUTINE GRQDEV (DEVICE, L)
      CHARACTER*(*) DEVICE
      INTEGER L

Obtain the name of the current graphics device or file.

Argument:
 DEVICE (output): receives the device name of the
      currently active device.
 L (output): number of characters in DEVICE, excluding trailing
      blanks.

GRQDT -- inquire current device and type

      SUBROUTINE GRQDT (DEVICE)

GRPCKG: obtain the name and type of the current graphics device.

Argument:

DEVICE (output, character): receives the device name and type of the
      currently active device in the form 'device/type'; this is a
      valid string for input to GROPEN.

GRQFNT -- inquire current font

      SUBROUTINE GRQFNT (IF)

GRPCKG: obtain the font number of the current graphics device.

Argument:

IF (integer, output): receives the current font number (1-3).

GRQLS -- inquire current line-style

      SUBROUTINE GRQLS (ISTYLE)
      INTEGER  ISTYLE

GRPCKG: obtain the line-style of the current graphics device.

Argument:
 ISTYLE (output): receives the current line-style code.

GRQLW -- inquire current line width

      SUBROUTINE GRQLW (IWIDTH)
      INTEGER  IWIDTH

GRPCKG: obtain the line-width of the current graphics device.

Argument:
 IWIDTH (output): receives the current line-width.

GRQPOS -- return current pen position (absolute, world coordinates)

      SUBROUTINE GRQPOS(X,Y)

GRQPOS: returns the current pen position in absolute, world
coordinates.

Arguments:

X, Y (real, output): world coordinates of the pen position.

GRQTXT -- get text bounding box

      SUBROUTINE GRQTXT (ORIENT,X0,Y0,STRING, XBOX, YBOX)

GRPCKG: get the bounding box of a string drawn by GRTEXT.

GRQTYP -- inquire current device type

      SUBROUTINE GRQTYP (TYPE,INTER)
      CHARACTER*(*) TYPE
      LOGICAL INTER

GRPCKG: obtain the device type of the currently selected graphics
device, and determine whether or not it is an interactive device.

Arguments:

TYPE (output, CHARACTER*(*)): receives the device type, as a
      character string, eg 'PRINTRONIX', 'TRILOG', 'VERSATEC',
      'TEK4010', 'TEK4014', 'GRINNELL', or 'VT125'.  The character
      string should have a length of at least 8 to ensure that the
      type is unique.
INTER (output, LOGICAL): receives the value .TRUE. if the device is
      interactive, .FALSE. otherwise.

GRQUIT -- report a fatal error and abort execution

      SUBROUTINE GRQUIT (TEXT)
      CHARACTER*(*) TEXT

Report a fatal error (via GRWARN) and exit program.
This routine should be called in the event of an unrecoverable 
PGPLOT error.

Argument:
 TEXT (input): text of message to be sent to GRWARN.

GRREC0 -- fill a rectangle (device coordinates)

      SUBROUTINE GRREC0 (X0,Y0,X1,Y1)
      REAL X0, Y0, X1, Y1

GRPCKG: Fill a rectangle with solid color.  The rectangle
is defined by the (x,y) device coordinates of its lower left and
upper right corners; the edges are parallel to the coordinate axes.
X0 is guaranteed to be <= X1 and Y0 <= Y1. The rectangle possible
extends beyond the clipping boundaries

Arguments:

X0, Y0 (input, real): device coordinates of one corner of the 
      rectangle.
X1, Y1 (input, real): device coordinates of the opposite corner of 
      the rectangle.

GRRECT -- fill a rectangle

      SUBROUTINE GRRECT (X0,Y0,X1,Y1)
      REAL X0, Y0, X1, Y1

GRPCKG: Fill a rectangle with solid color.  The rectangle
is defined by the (x,y) world coordinates of its lower left and upper 
right corners; the edges are parallel to the coordinate axes.

Arguments:

X0, Y0 (input, real): world coordinates of one corner of the 
      rectangle.
X1, Y1 (input, real): world coordinates of the opposite corner of the 
      rectangle.

GRSCI -- set color index

      SUBROUTINE GRSCI (IC)

GRPCKG: Set the color index for subsequent plotting. Calls to GRSCI
are ignored for monochrome devices. The default color index is 1,
usually white on a black background for video displays or black on a
white background for printer plots. The color index is an integer in
the range 0 to a device-dependent maximum. Color index 0 corresponds
to the background color; lines may be "erased" by overwriting them
with color index 0.

Color indices 0-7 are predefined as follows: 0 = black (background
color), 1 = white (default), 2 = red, 3 = green, 4 = blue, 5 = cyan
(blue + green), 6 = magenta (red + blue), 7 = yellow (red + green).
The assignment of colors to color indices can be changed with
subroutine GRSCR (set color representation).

Argument:

IC (integer, input): the color index to be used for subsequent
      plotting on the current device (in range 0-255). If the
      index exceeds the device-dependent maximum, the result is
      device-dependent.

GRSCR -- set color representation

      SUBROUTINE GRSCR (CI, CR, CG, CB)
      INTEGER  CI
      REAL     CR, CG, CB

GRPCKG: SET COLOUR REPRESENTATION -- define the colour to be
associated with a colour index.  Ignored for devices which do not
support variable colour or intensity.  On monochrome output
devices (e.g. VT125 terminals with monochrome monitors), the
monochrome intensity is computed from the specified Red, Green, Blue
intensities as 0.30*R + 0.59*G + 0.11*B, as in US color television
systems, NTSC encoding.  Note that most devices do not have an
infinite range of colours or monochrome intensities available;
the nearest available colour is used.

Arguments:

CI (integer, input): colour index. If the colour index is outside the
      range available on the device, the call is ignored. Colour
      index 0 applies to the background colour.
CR, CG, CB (real, input): red, green, and blue intensities,
      in range 0.0 to 1.0.

      SUBROUTINE GRSCRL (DX, DY)
      INTEGER DX, DY

Shift the pixels in the viewport by DX and DY in device coordinates.

GRSETC -- set character size

      SUBROUTINE GRSETC (IDENT,XSIZE)

GRPCKG : change the character size (user-callable routine).

Input:   IDENT : plot identifier
         XSIZE : the new character width. The character height
                 and spacing will be scaled by the same factor.
                 If XSIZE is negative or zero, the character size
                 will be set to the default size.

GRSETFONT -- set text font [obsolete]

GRSETLI -- *obsolete routine*

      SUBROUTINE GRSETLI (IN)

GRPCKG: Set the line intensity for subsequent plotting on the current
device. *** OBSOLETE ROUTINE *** Intensity is now set with GRSCI
and GRSCR. For compatibility, GRSETLI now sets color zero if its
argument is 0, and resets the previous color if its argument is
non-zero.

Argument:

IN (integer, input): the intensity to be used for subsequent
      plotting on the current device (in range 0-3).

GRSETPEN -- *obsolete routine*

      SUBROUTINE GRSETPEN

GRPCKG: Set the pen number for subsequent plotting.  Obsolete
routine: ignored.

GRSETS -- change size of view surface

      SUBROUTINE GRSETS (IDENT,XSIZE,YSIZE)

GRPCKG : change size of plotting area. The requested dimensions
will be reduced to the absolute maximum of the plot device if
necessary.

Arguments:

IDENT (input, integer): plot identifier from GROPEN.
XSIZE (input, real): new x dimension of plot area (absolute
              units); if less than zero, the default dimension
              will be used.
YSIZE (input, real): new y dimension of plot area (absolute
              units); if less than zero, the default dimension
              will be used.

GRSFNT -- set text font

      SUBROUTINE GRSFNT (IF)
      INTEGER IF

GRPCKG: Set the font for subsequent text plotting.
The default font is 1 ("Normal" font); others available are 2
("Roman"), 3 ("Italic"), and 4 ("Script").

Argument:
 IF (input): the font number to be used for subsequent
      text plotting on the current device (in range 1-4).

GRSIZE -- inquire device size and resolution

      SUBROUTINE GRSIZE (IDENT,XSZDEF,YSZDEF,XSZMAX,YSZMAX,
     1                   XPERIN,YPERIN)

GRPCKG : obtain device parameters (user-callable routine).

GRSKPB -- skip blanks in character string

      SUBROUTINE GRSKPB (S, I)
      CHARACTER*(*) S
      INTEGER I

GRSKPB: increment I so that it points to the next non-blank
character in string S.  'Blank' characters are space and tab (ASCII 
character value 9).

Arguments:
 S      (input)  : character string to be parsed.
 I      (in/out) : on input, I is the index of the first character
                   in S to be examined; on output, either it points
                   to the next non-blank character, or it is equal
                   to LEN(S)+1 (if all the rest of the string is 
                   blank).

GRSLCT -- select active output device

      SUBROUTINE GRSLCT (IDENT)

GRPCKG: Check that IDENT is a valid plot identifier, and select the
corresponding plot as the current plot. All subsequent plotting will
be directed to this device until the assignment is changed by another
call to GRSLCT.

Argument:

IDENT (input, integer): the identifier of the plot to be selected, as
      returned by GROPEN.

GRSLS -- set line style

      SUBROUTINE GRSLS (IS)
      INTEGER IS

GRPCKG: Set the line style for subsequent plotting on the current
device. The different line styles are generated in hardware on
some devices and by GRPCKG software for the other devices. Five
different line styles are available, with the following codes:
1 (full line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted),
5 (dash-dot-dot-dot). The default is 1 (normal full line). Line
style is ignored when drawing characters, which are always drawn with
a full line.

Argument:

IS (input, integer): the line-style code for subsequent plotting on
      the current device (in range 1-5).

GRSLW -- set line width

      SUBROUTINE GRSLW (IW)
      INTEGER IW

GRPCKG: Set the line width for subsequent plotting on the current
device. If the hardware does not support thick lines, they are
simulated by tracing each line with multiple strokes offset in the
direction perpendicular to the line. The line width is specified by
the number of strokes to be used, which must be in the range 1-201.
The actual line width obtained depends on the device resolution.
If the hardware does support thick lines, the width of the line
is approximately 0.005 inches times the value of argument IW.

Argument:

IW (integer, input): the number of strokes to be used for subsequent
      plotting on the current device (in range 1-201).

GRSYDS -- decode character string into list of symbol numbers

      SUBROUTINE GRSYDS (SYMBOL, NSYMBS, TEXT, FONT)
      INTEGER SYMBOL(*), NSYMBS, FONT
      CHARACTER*(*) TEXT

Given a character string, this routine returns a list of symbol
numbers to be used to plot it. It is responsible for interpreting
all escape sequences.  Negative `symbol numbers' are inserted in the
list to represent pen movement. The following escape sequences are
defined (the letter following the \ may be either upper or lower 
case):

\u       :      up one level (returns -1)
\d       :      down one level (returns -2)
\b       :      backspace (returns -3)
\A       :      (upper case only) Angstrom symbol, roman font
\x       :      multiplication sign
\.       :      centered dot
\\       :      \, returns the code for backslash
\gx      :      greek letter corresponding to roman letter x
\fn      :      switch to Normal font
\fr      :      switch to Roman font
\fi      :      switch to Italic font
\fs      :      switch to Script font
\mn or \mnn :   graph marker number n or nn (1 or 2 digits)
\(nnn)   :      Hershey symbol number nnn (any number of digits)

Arguments:
 SYMBOL (output) : receives the list of symbol numers.
 NSYMBS (output) : receives the actual number of symbols specified
                   by the string; it is assumed that the dimension of
                   SYMBOL is big enough (not less than LEN(TEXT)).
 TEXT   (input)  : the text string to be decoded.
 FONT   (input)  : the font number (1..4) to be used for decoding the
                   string (this can be overridden by an escape
                   sequence within the string).

GRSYMK -- convert character number into symbol number

      SUBROUTINE GRSYMK (CODE, FONT, SYMBOL)
      INTEGER CODE, FONT, SYMBOL

This routine returns the Hershey symbol number (SYMBOL) corresponding
to ASCII code CODE in font FONT.

Characters 0-31 are the same in all fonts, and are the standard
graph markers. Characters 32-127 are standard representations of
the ASCII codes. Characters 128-255 are reserved for the upper
half of the ISO Latin-1 character set. Characters 256-303 are
used for the greek alphabet.

Arguments:
 CODE   (input)  : the extended ASCII code number.
 FONT   (input)  : the font to be used 31 (range 1-4).
 SYMBOL (output) : the number of the symbol to be plotted.

GRSYXD -- obtain the polyline representation of a given symbol

      SUBROUTINE GRSYXD (SYMBOL, XYGRID, UNUSED)
      INTEGER SYMBOL
      INTEGER XYGRID(300)
      LOGICAL UNUSED

Return the digitization coordinates of a character. Each character is
defined on a grid with X and Y coordinates in the range (-49,49), 
with the origin (0,0) at the center of the character.  The coordinate
system is right-handed, with X positive to the right, and Y positive
upward.  

Arguments:
 SYMBOL (input)  : symbol number in range (1..3000).
 XYGRID (output) : height range, width range, and pairs of (x,y)
                   coordinates returned.  Height range = (XYGRID(1),
                   XYGRID(3)).  Width range = (XYGRID(4),XYGRID(5)).
                   (X,Y) = (XYGRID(K),XYGRID(K+1)) (K=6,8,...).
 UNUSED (output) : receives .TRUE. if SYMBOL is an unused symbol
                   number. A character of normal height and zero width
                   is returned. Receives .FALSE. if SYMBOL is a 
                   valid symbol number.

The height range consists of 3 values: (minimum Y, baseline Y,
maximum Y).  The first is reached by descenders on lower-case g, p,
q, and y.  The second is the bottom of upper-case letters.  The third
is the top of upper-case letters.  A coordinate pair (-64,0) requests
a pen raise, and a pair (-64,-64) terminates the coordinate list. It
is assumed that movement to the first coordinate position will be
done with the pen raised - no raise command is explicitly included to
do this.

GRTERM -- flush buffer to output device

      SUBROUTINE GRTERM

GRPCKG: flush the buffer associated with the current plot. GRTERM
should be called only when it is necessary to make sure that all the
graphics created up to this point in the program are visible on the
device, e.g., before beginning a dialog with the user. GRTERM has no
effect on hardcopy devices.

Arguments: none.

GRTEXT -- draw text

      SUBROUTINE GRTEXT (CENTER,ORIENT,ABSXY,X0,Y0,STRING)

GRPCKG: Write a text string using the high-quality character set.
The text is NOT windowed in the current viewport, but may extend over
the whole view surface.  Line attributes (color, intensity thickness)
apply to text, but line-style is ignored.  The current pen position
after a call to GRTEXT is undefined.

Arguments:

STRING (input, character): the character string to be plotted. This
      may include standard escape-sequences to represent non-ASCII
      characters and special commands. The number of characters in
      STRING (i.e., LEN(STRING)) should not exceed 256.

GRTOUP -- convert character string to upper case

      SUBROUTINE GRTOUP (DST, SRC)
      CHARACTER*(*) DST, SRC

GRPCKG (internal routine): convert character string to upper case.

Arguments:
 DST    (output) : output string (upper case).
 SRC    (input)  : input string to be converted.

GRTRAN -- define scaling transformation

      SUBROUTINE GRTRAN (IDENT,XORG,YORG,XSCALE,YSCALE)

GRPCKG (internal routine): Define scaling transformation.

Arguments:

IDENT (input, integer): plot identifier, as returned by GROPEN.
XORG, YORG, XSCALE, YSCALE (input, real): parameters of the scaling
      transformation. This is defined by:
              XABS = XORG + XWORLD * XSCALE,
              YABS = YORG + YWORLD * YSCALE,
      where (XABS, YABS) are the absolute device coordinates
      corresponding to world coordinates (XWORLD, YWORLD).

GRTRIM -- length of string excluding trailing blanks

      INTEGER FUNCTION GRTRIM(S)
      CHARACTER*(*) S

Find the length of a character string excluding trailing blanks.
A blank string returns a value of 0.

Argument:
 S      (input)  : character string.

Returns:
 GRTRIM          : number of characters in S, excluding trailing
                   blanks, in range 0...LEN(S). A blank string
                   returns a value of 0.

Subroutines required:
 None

Fortran 77 extensions:
 None

History:
 1987 Nov 12 - TJP.

GRTRN0 -- define scaling transformation

      SUBROUTINE GRTRN0 (XORG,YORG,XSCALE,YSCALE)

GRPCKG (internal routine): Define scaling transformation for current
device (equivalent to GRTRAN without device selection).

Arguments:

XORG, YORG, XSCALE, YSCALE (input, real): parameters of the scaling
      transformation. This is defined by:
              XABS = XORG + XWORLD * XSCALE,
              YABS = YORG + YWORLD * YSCALE,
      where (XABS, YABS) are the absolute device coordinates
      corresponding to world coordinates (XWORLD, YWORLD).

GRTXY0 -- convert world coordinates to device coordinates

      SUBROUTINE GRTXY0 (ABSXY,X,Y,XT,YT)

GRPCKG (internal routine): Convert scaled position to absolute
position.

Arguments:

ABSXY (input, logical): if FALSE, convert world coordinates to
      absolute device coordinates; if TRUE, return the input
      coordinates unchanged.
X, Y (input, real): input coordinates (absolute or world, depending
      on setting of ABSXY).
XT, YT (output, real): output absolute device coordinates.

GRVCT0 -- draw line segments or dots

      SUBROUTINE GRVCT0 (MODE,ABSXY,POINTS,X,Y)

GRPCKG (internal routine): Draw a line or a set of dots. This
is the same as GRVECT, but without device selection. It can be used to
draw a single line-segment, a continuous series of line segments, or
one or more single dots (pixels).

Arguments:

MODE (input, integer): if MODE=1, a series of line segments is drawn,
      starting at the current position, moving to X(1),Y(1), ... and
      ending at X(POINTS),Y(POINTS).
      If MODE=2, the first vector is blanked, so the line starts at
      X(1),Y(1).
      If MODE=3, a single dot is placed at each coordinate pair, with
      no connecting lines.
ABSXY (input, logical): if TRUE, the coordinates are absolute device
      coordinates; if FALSE, they are world coordinates and the
      scaling transformation is applied.
POINTS (input, integer): the number of coordinate pairs.
X, Y (input, real arrays, dimensioned POINTS or greater): the
      X and Y coordinates of the points.

GRVECT -- draw line segments or dots

      SUBROUTINE GRVECT (IDENT,MODE,ABSXY,POINTS,X,Y)

GRPCKG: Draw a line or a set of dots. This routine can be used to
draw a single line-segment, a continuous series of line segments, or
one or more single dots (pixels).

Arguments:

IDENT (input, integer): the plot identifier, as returned by GROPEN.
MODE (input, integer): if MODE=1, a series of line segments is drawn,
      starting at the current position, moving to X(1),Y(1), ... and
      ending at X(POINTS),Y(POINTS).
      If MODE=2, the first vector is blanked, so the line starts at
      X(1),Y(1).
      If MODE=3, a single dot is placed at each coordinate pair, with
      no connecting lines.
ABSXY (input, logical): if TRUE, the coordinates are absolute device
      coordinates; if FALSE, they are world coordinates and the
      scaling transformation is applied.
POINTS (input, integer): the number of coordinate pairs.
X, Y (input, real arrays, dimensioned POINTS or greater): the
      X and Y coordinates of the points.

GRWARN -- issue warning message to user

      SUBROUTINE GRWARN (TEXT)
      CHARACTER*(*) TEXT

Report a warning message on standard output, with prefix "%PGPLOT, ".

Argument:
 TEXT (input): text of message to be printed (the string
     may not be blank).

GRXHLS -- convert RGB color to HLS color

      SUBROUTINE GRXHLS (R,G,B,H,L,S)

GRPCKG: Convert a color specified in the RGB color model to one in
the HLS model.  This is a support routine: no graphics I/O occurs.
The inverse transformation is accomplished with routine GRXRGB.
Reference: SIGGRAPH Status Report of the Graphic Standards Planning
Committee, Computer Graphics, Vol.13, No.3, Association for
Computing Machinery, New York, NY, 1979.

Arguments:

R,G,B (real, input): red, green, blue color coordinates, each in the
      range 0.0 to 1.0. Input outside this range causes HLS = (0,1,0)
      [white] to be returned.
H,L,S (real, output): hue (0 to 360), lightness (0 to 1.0), and
      saturation (0 to 1.0).

GRXRGB -- convert HLS color to RGB color

      SUBROUTINE GRXRGB (H,L,S,R,G,B)

GRPCKG: Convert a color specified in the HLS color model to one in
the RGB model.  This is a support routine: no graphics I/O occurs.
The inverse transformation is accomplished with routine GRXHLS.
Reference: SIGGRAPH Status Report of the Graphic Standards Planning
Committee, Computer Graphics, Vol.13, No.3, Association for
Computing Machinery, New York, NY, 1979.

Arguments:

H,L,S (real, input): hue (0 to 360), lightness (0 to 1.0), and
      saturation (0 to 1.0).
R,G,B (real, output): red, green, blue color coordinates, each in the
      range 0.0 to 1.0.

PGADVANCE -- non-standard alias for PGPAGE

      SUBROUTINE PGADVANCE

See description of PGPAGE.

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.

PGBEGIN -- non-standard alias for PGBEG

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

See description of PGBEG.

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.

PGCURSE -- non-standard alias for PGCURS

      INTEGER FUNCTION PGCURSE (X, Y, CH)
      REAL X, Y
      CHARACTER*1 CH

See description of PGCURS.

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, tick marks, etc:
     AXIS = -2 : draw no box, axes or labels;
     AXIS = -1 : draw box only;
     AXIS =  0 : draw box and label it with coordinates;
     AXIS =  1 : same as AXIS=0, but also draw the
                 coordinate axes (X=0, Y=0);
     AXIS =  2 : same as AXIS=1, but also draw grid lines
                 at major increments of the coordinates;
     AXIS = 10 : draw box and label X-axis logarithmically;
     AXIS = 20 : draw box and label Y-axis logarithmically;
     AXIS = 30 : draw box and label both axes logarithmically.

For other axis options, use routine PGBOX. PGENV can be persuaded to
call PGBOX with additional axis options by defining an environment
parameter PGPLOT_ENVOPT containing the required option codes. 
Examples:
  PGPLOT_ENVOPT=P      ! draw Projecting tick marks
  PGPLOT_ENVOPT=I      ! Invert the tick marks
  PGPLOT_ENVOPT=IV     ! Invert tick marks and label y Vertically

PGERAS -- erase all graphics from current page

      SUBROUTINE PGERAS

Erase all graphics from the current page (or current panel, if
the view surface has been divided into panels with PGSUBP).

Arguments: none

PGERR1 -- horizontal or vertical error bar

      SUBROUTINE PGERR1 (DIR, X, Y, E, T)
      INTEGER DIR
      REAL X, Y, E
      REAL T

Plot a single error bar in the direction specified by DIR.
This routine draws an error bar only; to mark the data point at
the start of the error bar, an additional call to PGPT is required.
To plot many error bars, use PGERRB.

Arguments:
 DIR    (input)  : direction to plot the error bar relative to
                   the data point. 
                   One-sided error bar:
                     DIR is 1 for +X (X to X+E);
                            2 for +Y (Y to Y+E);
                            3 for -X (X to X-E);
                            4 for -Y (Y to Y-E).
                   Two-sided error bar:
                     DIR is 5 for +/-X (X-E to X+E); 
                            6 for +/-Y (Y-E to Y+E).
 X      (input)  : world x-coordinate of the data.
 Y      (input)  : world y-coordinate of the data.
 E      (input)  : value of error bar distance to be added to the
                   data position in world coordinates.
 T      (input)  : length of terminals to be drawn at the ends
                   of the error bar, as a multiple of the default
                   length; if T = 0.0, no terminals will be drawn.

PGERRB -- horizontal or vertical error bar

      SUBROUTINE PGERRB (DIR, N, X, Y, E, T)
      INTEGER DIR, N
      REAL X(*), Y(*), E(*)
      REAL T

Plot error bars in the direction specified by DIR.
This routine draws an error bar only; to mark the data point at
the start of the error bar, an additional call to PGPT is required.

Arguments:
 DIR    (input)  : direction to plot the error bar relative to
                   the data point. 
                   One-sided error bar:
                     DIR is 1 for +X (X to X+E);
                            2 for +Y (Y to Y+E);
                            3 for -X (X to X-E);
                            4 for -Y (Y to Y-E).
                   Two-sided error bar:
                     DIR is 5 for +/-X (X-E to X+E); 
                            6 for +/-Y (Y-E to Y+E).
 N      (input)  : number of error bars to plot.
 X      (input)  : world x-coordinates of the data.
 Y      (input)  : world y-coordinates of the data.
 E      (input)  : value of error bar distance to be added to the
                   data position in world coordinates.
 T      (input)  : length of terminals to be drawn at the ends
                   of the error bar, as a multiple of the default
                   length; if T = 0.0, no terminals will be drawn.

Note: the dimension of arrays X, Y, and E must be greater
than or equal to N. If N is 1, X, Y, and E may be scalar
variables, or expressions.

PGERRX -- horizontal error bar

      SUBROUTINE PGERRX (N, X1, X2, Y, T)
      INTEGER N
      REAL X1(*), X2(*), Y(*)
      REAL T

Plot horizontal error bars.
This routine draws an error bar only; to mark the data point in
the middle of the error bar, an additional call to PGPT or
PGERRY is required.

Arguments:
 N      (input)  : number of error bars to plot.
 X1     (input)  : world x-coordinates of lower end of the
                   error bars.
 X2     (input)  : world x-coordinates of upper end of the
                   error bars.
 Y      (input)  : world y-coordinates of the data.
 T      (input)  : length of terminals to be drawn at the ends
                   of the error bar, as a multiple of the default
                   length; if T = 0.0, no terminals will be drawn.

Note: the dimension of arrays X1, X2, and Y must be greater
than or equal to N. If N is 1, X1, X2, and Y may be scalar
variables, or expressions, eg:
      CALL PGERRX(1,X-SIGMA,X+SIGMA,Y)

PGERRY -- vertical error bar

      SUBROUTINE PGERRY (N, X, Y1, Y2, T)
      INTEGER N
      REAL X(*), Y1(*), Y2(*)
      REAL T

Plot vertical error bars.
This routine draws an error bar only; to mark the data point in
the middle of the error bar, an additional call to PGPT or
PGERRX is required.

Arguments:
 N      (input)  : number of error bars to plot.
 X      (input)  : world x-coordinates of the data.
 Y1     (input)  : world y-coordinates of top end of the
                   error bars.
 Y2     (input)  : world y-coordinates of bottom end of the
                   error bars.
 T      (input)  : length of terminals to be drawn at the ends
                   of the error bar, as a multiple of the default
                   length; if T = 0.0, no terminals will be drawn.

Note: the dimension of arrays X, Y1, and Y2 must be greater
than or equal to N. If N is 1, X, Y1, and Y2 may be scalar
variables or expressions, eg:
      CALL PGERRY(1,X,Y+SIGMA,Y-SIGMA)

PGETXT -- erase text from graphics display

      SUBROUTINE PGETXT

Some graphics terminals display text (the normal interactive dialog)
on the same screen as graphics. This routine erases the text from the
view surface without affecting the graphics. It does nothing on
devices which do not display text on the graphics screen, and on
devices which do not have this capability.

Arguments:
 None

PGFUNT -- function defined by X = F(T), Y = G(T)

      SUBROUTINE PGFUNT (FX, FY, N, TMIN, TMAX, PGFLAG)
      REAL FX, FY
      EXTERNAL FX, FY
      INTEGER N
      REAL TMIN, TMAX
      INTEGER PGFLAG

Draw a curve defined by parametric equations X = FX(T), Y = FY(T).

Arguments:
 FX     (external real function): supplied by the user, evaluates
                   X-coordinate.
 FY     (external real function): supplied by the user, evaluates
                   Y-coordinate.
 N      (input)  : the number of points required to define the
                   curve. The functions FX and FY will each be
                   called N+1 times.
 TMIN   (input)  : the minimum value for the parameter T.
 TMAX   (input)  : the maximum value for the parameter T.
 PGFLAG (input)  : if PGFLAG = 1, the curve is plotted in the
                   current window and viewport; if PGFLAG = 0,
                   PGENV is called automatically by PGFUNT to
                   start a new plot with automatic scaling.

Note: The functions FX and FY must be declared EXTERNAL in the
Fortran program unit that calls PGFUNT.

PGFUNX -- function defined by Y = F(X)

      SUBROUTINE PGFUNX (FY, N, XMIN, XMAX, PGFLAG)
      REAL FY
      EXTERNAL FY
      INTEGER N
      REAL XMIN, XMAX
      INTEGER PGFLAG

Draw a curve defined by the equation Y = FY(X), where FY is a
user-supplied subroutine.

Arguments:
 FY     (external real function): supplied by the user, evaluates
                   Y value at a given X-coordinate.
 N      (input)  : the number of points required to define the
                   curve. The function FY will be called N+1 times.
                   If PGFLAG=0 and N is greater than 1000, 1000
                   will be used instead.  If N is less than 1,
                   nothing will be drawn.
 XMIN   (input)  : the minimum value of X.
 XMAX   (input)  : the maximum value of X.
 PGFLAG (input)  : if PGFLAG = 1, the curve is plotted in the
                   current window and viewport; if PGFLAG = 0,
                   PGENV is called automatically by PGFUNX to
                   start a new plot with X limits (XMIN, XMAX)
                   and automatic scaling in Y.

Note: The function FY must be declared EXTERNAL in the Fortran
program unit that calls PGFUNX.  It has one argument, the
x-coordinate at which the y value is required, e.g.
  REAL FUNCTION FY(X)
  REAL X
  FY = .....
  END

PGFUNY -- function defined by X = F(Y)

      SUBROUTINE PGFUNY (FX, N, YMIN, YMAX, PGFLAG)
      REAL    FX
      EXTERNAL FX
      INTEGER N
      REAL    YMIN, YMAX
      INTEGER PGFLAG

Draw a curve defined by the equation X = FX(Y), where FY is a
user-supplied subroutine.

Arguments:
 FX     (external real function): supplied by the user, evaluates
                   X value at a given Y-coordinate.
 N      (input)  : the number of points required to define the
                   curve. The function FX will be called N+1 times.
                   If PGFLAG=0 and N is greater than 1000, 1000
                   will be used instead.  If N is less than 1,
                   nothing will be drawn.
 YMIN   (input)  : the minimum value of Y.
 YMAX   (input)  : the maximum value of Y.
 PGFLAG (input)  : if PGFLAG = 1, the curve is plotted in the
                   current window and viewport; if PGFLAG = 0,
                   PGENV is called automatically by PGFUNY to
                   start a new plot with Y limits (YMIN, YMAX)
                   and automatic scaling in X.

Note: The function FX must be declared EXTERNAL in the Fortran
program unit that calls PGFUNY.  It has one argument, the
y-coordinate at which the x value is required, e.g.
  REAL FUNCTION FX(Y)
  REAL Y
  FX = .....
  END

PGGRAY -- gray-scale map of a 2D data array

      SUBROUTINE PGGRAY (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   FG, BG, TR)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      REAL    A(IDIM,JDIM), FG, BG, TR(6)

Draw gray-scale map of an array in current window. The subsection
of the array A defined by indices (I1:I2, J1:J2) is mapped onto
the view surface world-coordinate system by the transformation
matrix TR. The resulting quadrilateral region is clipped at the edge
of the window and shaded with the shade at each point determined
by the corresponding array value.  The shade is a number in the
range 0 to 1 obtained by linear interpolation between the background
level (BG) and the foreground level (FG), i.e.,

  shade = [A(i,j) - BG] / [FG - BG]

The background level BG can be either less than or greater than the
foreground level FG.  Points in the array that are outside the range
BG to FG are assigned shade 0 or 1 as appropriate.

PGGRAY uses two different algorithms, depending how many color
indices are available in the color index range specified for images.
(This range is set with routine PGSCIR, and the current or default
range can be queried by calling routine PGQCIR).

If 16 or more color indices are available, PGGRAY first assigns
color representations to these color indices to give a linear ramp
between the background color (color index 0) and the foreground color
(color index 1), and then calls PGIMAG to draw the image using these
color indices. In this mode, the shaded region is "opaque": every
pixel is assigned a color.

If less than 16 color indices are available, PGGRAY uses only
color index 1, and uses  a "dithering" algorithm to fill in pixels,
with the shade (computed as above) determining the faction of pixels
that are filled. In this mode the shaded region is "transparent" and
allows previously-drawn graphics to show through.

The transformation matrix TR is used to calculate the world
coordinates of the center of the "cell" that represents each
array element. The world coordinates of the center of the cell
corresponding to array element 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.  The corners of the
quadrilateral region that is shaded by PGGRAY are given by
applying this transformation to (I1-0.5,J1-0.5), (I2+0.5, J2+0.5).

Arguments:
 A      (input)  : the array to be plotted.
 IDIM   (input)  : the first dimension of array A.
 JDIM   (input)  : the second dimension of array A.
 I1, I2 (input)  : the inclusive range of the first index
                   (I) to be plotted.
 J1, J2 (input)  : the inclusive range of the second
                   index (J) to be plotted.
 FG     (input)  : the array value which is to appear with the
                   foreground color (corresponding to color index 1).
 BG     (input)  : the array value which is to appear with the
                   background color (corresponding to color index 0).
 TR     (input)  : transformation matrix between array grid and
                   world coordinates.

PGHI2D -- cross-sections through a 2D data array

      SUBROUTINE PGHI2D (DATA, NXV, NYV, IX1, IX2, IY1, IY2, X, IOFF,
     1                   BIAS, CENTER, YLIMS)
      INTEGER NXV, NYV, IX1, IX2, IY1, IY2
      REAL    DATA(NXV,NYV)
      REAL    X(IX2-IX1+1), YLIMS(IX2-IX1+1)
      INTEGER IOFF
      REAL    BIAS
      LOGICAL CENTER

Plot a series of cross-sections through a 2D data array.
Each cross-section is plotted as a hidden line histogram.  The plot
can be slanted to give a pseudo-3D eff