\chapter {PLPLOT Subroutine Reference} \label{reference}

All the PLPLOT subroutines are listed below in alphabetical 
order.

\bname{pladv(sub);}\label{pladv}
\addcontentsline{toc}{subsection}{pladv}

\descr{Advances to the next subpage if {\tt sub=0} or to the specified 
subpage
if {\tt sub} is non-zero. This routine is called automatically (with 
{\tt sub=0})
by {\tt plenv}, but if {\tt plenv} is not used, {\tt pladv}
 must be called after {\tt plstar}
but before defining the viewport.}

\argu {{\tt sub} (int, input)}{Specifies the subpage number (starting from
1 in the top left corner and increasing along the rows) to which to advance.
Set to zero to advance to the next subpage.}



\bname{plbeg(dev,nx,ny);}\label{plbeg}
\addcontentsline{toc}{subsection}{plbeg}

\descr{Alternative to {\tt plstar} for initializing the plotting package. The
        device number of the desired output device must be supplied as
        an argument. The mapping from device numbers to devices varies
        from one implementation to another, and so use of {\tt plstar} which
        prompts for the device type is recommended. The device codes are
        the same as those printed out by {\tt plstar}. This routine also divides
        the output device into {\tt nx} by {\tt ny} sub-pages, each of which may
        be used independently. The subroutine {\tt pladv} is used to advance
        from one subpage to the next.}

\argu {{\tt dev} (int, input)}{Device number of the required output device.}

\argu {{\tt nx} (int, input)}{Number of subpages to divide output page in 
      the horizontal direction.}

\argu {{\tt ny} (int, input)}{Number of subpages to divide output page in 
      the vertical direction.}



\bname{plbin(nbin,x,y,cen);}\label{plbin}
\addcontentsline{toc}{subsection}{plbin}

\descr{Plots a histogram consisting of {\tt n} bins. The value associated
       with the {\tt i}'th bin is placed in {\tt x[i]}, and the number of points
       in the bin is placed in {\tt y[i]}. For proper operation, the values
       in {\tt x[i]} must form a strictly increasing sequence. If {\tt centre} is
       false, {\tt x[i]} is the left-hand edge of the {\tt i'th} bin, and if
       {\tt centre} is true, the bin boundaries are placed midway between the
       values in the {\tt x}~array. Also see {\tt plhist} for drawing
       histograms from unbinned data.} 

\argu {{\tt nbin} (int, input)}{Number of bins (i.e., number of values in $x$
and $y$ arrays.)}

\argu {{\tt x} (float *, input)}{Pointer to array containing
values associated with bins. These must form
a strictly increasing sequence.}

\argu {{\tt y} (float *, input)}{Pointer to array containing
number of points in bin. This is a 
{\bf float}
array so as to allow histograms of probabilities, etc.}

\argu {{\tt cen} (int, input)}{Indicates whether the values in {\tt x} 
represent the lower bin boundaries ({\tt cen=0}) or whether
the bin boundaries are to be midway between the {\tt x} values ({\tt cen=1}).
If the values in {\tt x} are equally spaced and {\tt cen=1}, 
the values in {\tt x}
are the centre values of the bins.}



\bname{plbox(xopt,xtick,nxsub,yopt,ytick,nysub);}\label{plbox}
\addcontentsline{toc}{subsection}{plbox}

\descr{Draws a box around the currently defined viewport, and labels it
       with world coordinate values appropriate to the window. Thus
       {\tt plbox} should only be called after defining both viewport and
       window. The character strings {\tt xopt} and {\tt yopt} specify how the
       box should be drawn as described below. If ticks and/or subticks
       are to be drawn for a particular axis, the tick intervals and number
       of subintervals may be specified explicitly, or they may be
       defaulted by setting the appropriate arguments to zero.}

\argu {{\tt xopt} (char *, input)}{Pointer to
character string specifying options for
horizontal axis. The string can include any combination of the following
letters (upper or lower case) in any order:
\begin{itemize}
\item{{\tt a :}} Draws axis, X-axis is horizontal line {\tt y=0}, and Y-axis is
vertical line {\tt y=0}.
\item{{\tt b :}} Draws bottom (X) or left (Y) edge of frame.
\item{{\tt c :}} Draws top (X) or right (Y) edge of frame.
\item{{\tt g :}} Draws a grid at the major tick interval.
\item{{\tt i :}} Inverts tick marks, so they are drawn outwards, rather than
inwards.
\item{{\tt l :}} Labels axis logarithmically. This only affects the labels,
not the data, and so it is necessary to compute the logarithms of data 
points before passing them to any of the drawing routines.
\item{{\tt m :}} Writes numeric labels at major tick intervals in the
unconventional location (above box for X, right of box for Y).
\item{{\tt n :}} Writes numeric labels at major tick intervals in the 
conventional location (below box for X, left of box for Y).
\item{{\tt s :}} Enables subticks between major ticks, only valid if {\tt t} is
also specified.
\item{{\tt t :}} Draws major ticks.
\end{itemize}}

\argu {{\tt xtick} (float, input)}{World coordinate interval between major ticks
on the x~axis. If it is set to zero, PLPLOT automatically generates a
suitable tick interval}

\argu {{\tt nxsub} (int, input)}{Number of subintervals between major x~axis
ticks for minor ticks. If it is set to zero, PLPLOT automatically generates a
suitable minor tick interval.}

\argu {{\tt yopt} (char *, input)}{Pointer to
character string specifying options for
vertical axis. The string can include any combination of the letters
defined above for {\tt xopt}, and in addition may contain:
\begin{itemize}
\item{{\tt v }}{: Write numeric labels for vertical axis parallel to the
base of the graph, rather than parallel to the axis.}
\end{itemize}
}

\argu {{\tt ytick} (real, input)}{World coordinate interval between major ticks
on the y~axis. If it is set to zero, PLPLOT automatically generates a
suitable tick interval}

\argu {{\tt nysub} (int, input)}{Number of subintervals between major y~axis
ticks for minor ticks. If it is set to zero, PLPLOT automatically generates a
suitable minor tick interval.}



\bname{ \begin{tabular}{l@{\strut}l}
        plbox3(&xopt,xlabel,xtick,nxsub,yopt,ylabel,ytick,nysub,\\
        &zopt,zlabel,ztick,nzsub);
        \end{tabular}
      } \label{plbox3}
\addcontentsline{toc}{subsection}{plbox3}

\descr{Draws axes, numeric and text labels for a three-dimensional surface
       plot. See Section \ref{threed} on page \pageref{threed} for a
       more complete description of three-dimensional plotting.}

\argu {{\tt xopt} (char *, input)}{Pointer to
character string specifying options for
the x~axis. The string can include any combination of the following
letters (upper or lower case) in any order:
\begin{itemize}
\item{{\tt b :}} Draws axis at base, at height {\tt z=zmin} where {\tt zmin} is defined
by call to {\tt plw3d}. This character must be specified in order to use any 
of the other options.
\item{{\tt i :}} Inverts tick marks, so they are drawn downwards, rather than
upwards.
\item{{\tt l :}} Labels axis logarithmically. This only affects the labels,
not the data, and so it is necessary to compute the logarithms of data 
points before passing them to any of the drawing routines.
\item{{\tt n :}} Writes numeric labels at major tick intervals.
\item{{\tt s :}} Enables subticks between major ticks, only valid if {\tt t} is
also specified.
\item{{\tt t :}} Draws major ticks.
\item{{\tt u :}} If this is specified, the text label for the axis is written
under the axis.
\end{itemize}
}

\argu {{\tt xlabel} (char *, input)}{Pointer to
character string specifying text label
for the x~axis. It is only drawn if {\tt u} is in the {\tt xopt} string.}

\argu {{\tt xtick} (float, input)}{World coordinate interval between major ticks
on the x~axis. If it is set to zero, PLPLOT automatically generates a
suitable tick interval}

\argu {{\tt nxsub} (int, input)}{Number of subintervals between major x~axis
ticks for minor ticks. If it is set to zero, PLPLOT automatically generates a
suitable minor tick interval.}

\argu {{\tt yopt} (char *, input)}{Pointer to 
character string specifying options for
the y~axis. The string is interpreted in the same way as {\tt xopt}.}

\argu {{\tt ylabel} (char *, input)}{Pointer to
character string specifying text label
for the y~axis. It is only drawn if {\tt u} is in the {\tt yopt} string.}

\argu {{\tt ytick} (float, input)}{World coordinate interval between major ticks
on the y~axis. If it is set to zero, PLPLOT automatically generates a
suitable tick interval}

\argu {{\tt nysub} (int, input)}{Number of subintervals between major y~axis
ticks for minor ticks. If it is set to zero, PLPLOT automatically generates a
suitable minor tick interval.}

\argu {{\tt zopt} (char *, input)}{Pointer to
character string specifying options for
the z~axis. The string can include any combination of the following
letters (upper or lower case) in any order:
\begin{itemize}
\item{{\tt b :}} Draws z~axis to the left of the surface plot.
\item{{\tt c :}} Draws z~axis to the right of the surface plot.
\item{{\tt i :}} Inverts tick marks, so they are drawn away from the centre.
\item{{\tt l :}} Labels axis logarithmically. This only affects the labels,
not the data, and so it is necessary to compute the logarithms of data 
points before passing them to any of the drawing routines.
\item{{\tt m :}} Writes numeric labels at major tick intervals on the right-hand 
verical axis.
\item{{\tt n :}} Writes numeric labels at major tick intervals on the left-hand 
verical axis.
\item{{\tt s :}} Enables subticks between major ticks, only valid if {\tt t} is
also specified.
\item{{\tt t :}} Draws major ticks.
\item{{\tt u :}} If this is specified, the text label is written beside the 
left-hand axis.
\item{{\tt v :}} If this is specified, the text label is written beside the
right-hand axis.
\end{itemize}
}

\argu {{\tt zlabel} (char *, input)}{Pointer to
character string specifying text label
for the z~axis. It is only drawn if {\tt u} or {\tt v} are in the {\tt zopt} string.}

\argu {{\tt ztick} (float, input)}{World coordinate interval between major ticks
on the z~axis. If it is set to zero, PLPLOT automatically generates a
suitable tick interval}

\argu {{\tt nzsub} (int, input)}{Number of subintervals between major z~axis
ticks for minor ticks. If it is set to zero, PLPLOT automatically generates a
suitable minor tick interval.}



\bname{plclr}\label{plclr();}
\addcontentsline{toc}{subsection}{plclr}

\descr{Clears the graphics screen of an interactive device, or ejects
       a page on a plotter.}

\bname{plcol(colour);}\label{plcol}
\addcontentsline{toc}{subsection}{plcol}

\descr{Sets the colour for subsequent lines.}

\argu {{\tt colour} (int, input)}{Integer representing the colour.}

\bname{plcont(z,nx,ny,kx,lx,ky,ly,clevel,nlevel,tr);}\label{plcont}
\addcontentsline{toc}{subsection}{plcont}

\descr{Draws a contour plot of the data in {\tt z[nx][ny]}, using the 
        {\tt nlevel} contour levels specified by {\tt clevel}. Only
        the region of the array from {\tt kx} to {\tt lx} and from {\tt ky}
        to {\tt ly} is plotted out. A transformation routine {\tt tr} is
        used to map indicies within the array to the world coordinates
        (see Section \ref{contour} on page \ref{contour}).
        }

\argu {{\tt z} (float *, input)} 
       {Pointer to a two-dimensional array containing data 
        to be contoured.}

\argu {{\tt nx, ny} (int, input)} {Physical dimensions of array {\tt z}.}

\argu {{\tt kx, lx} (int, input)} {Range of {\tt x} indicies to consider.}

\argu {{\tt ky, ly} (int, input)} {Range of {\tt y} indicies to consider.}

\argu {{\tt clevel} (float *, input)} {Pointer to array specifying
            levels at which to draw contours}

\argu {{\tt nlevel} (int, input)} {Number of contour levels to draw}

\argu {{\tt tr} (void *,input)} {Pointer to function that
defines transformation between indicies
in array {\tt z} and the world coordinates. The function should have the
form
\name{tr(x,y,tx,ty);}
\argu {{\tt x, y} (float, input)}{ Specifies the position in the array through
which the contour runs in terms of the array indicies }
\argu {{\tt tx, ty} (float *, output)}{Pointers to the
world coordinates corresponding to the
point {\tt (x,y)} }
}
A transformation function {\tt xform} is provided for simple linear mappings.
See Section \ref{contour} for information.

\bname{plend();}\label{plend}
\addcontentsline{toc}{subsection}{plend}

\descr{Ends a plotting session, tidies up all the output files, 
       switches interactive devices back into text mode and frees up
       any memory that was allocated. Must be called
       before end of program.}



\bname{plenv(xmin,xmax,ymin,ymax,just,axis);}\label{plenv}
\addcontentsline{toc}{subsection}{plenv}

\descr{Sets up plotter environment for simple graphs by calling {\tt pladv}
and setting up viewport and window to sensible default values. {\tt plenv} leaves
enough room around most graphs for axis labels and a title. When these
defaults are not suitable, use the individual routines {\tt plvspa} or {\tt PLVPOR}
for setting up the viewport, {\tt plwind} for defining the window, and {\tt PLBOX}
for drawing the box.}

\argu {{\tt xmin} (float, input)}{Value of~x at left-hand edge of window.}

\argu {{\tt xmax} (float, input)}{Value of~x at right-hand edge of window.}

\argu {{\tt ymin} (float, input)}{Value of~y at bottom edge of window.}

\argu {{\tt ymax} (float, input)}{Value of~y at top edge of window.}

\argu {{\tt just} (int, input)}{If {\tt just=0}, the x~and~y axes are scaled
independently to use as much of the screen as possible, but if {\tt just=1}, the
scales of the x~and~y axes are made equal.}

\argu {{\tt axis} (int, input)}{Controls drawing of the box around the plot:
\begin{itemize}
\item{-2}: No box or annotation.
\item{-1}: Draw box only.
\item{0}: Draw box, labelled with coordinate values around edge.
\item{1}: In addition to box and labels, draw the two axes 
{\tt x=0} and {\tt y=0}.
\item{2}: As for {\tt axis=1}, but also draw a grid at the major tick interval.
\item{10}: Logarithmic x axis, linear y axis.
\item{11}: Logarithmic x axis, linear y axis and draw line {\tt y=0}.
\item{20}: Linear x axis, logarithmic y axis.
\item{21}: Linear x axis, logarithmic y axis and draw line {\tt x=0}.
\item{30}: Logarithmic x and y axes.
\end{itemize}
}



\bname{plerrx(n,xmin,xmax,y)}\label{plerrx}
\addcontentsline{toc}{subsection}{plerrx}

\descr{Draws a set of {\tt n} horizontal error bars, the {\tt i}'th error bar
extending from {\tt xmin[i]} to {\tt xmax[i]} at y~coordinate {\tt y[i]}. The terminals
of the error bar are of length equal to the minor tick length (settable
using {\tt plsmin}).}

\argu {{\tt n} (int, input)}{Number of error bars to draw.}

\argu {{\tt xmin} (float *, input)}{Pointer to array with
x~coordinates of left-hand endpoint of error bars.}

\argu {{\tt xmax} (float *, input)}{Pointer to array with
x~coordinates of right-hand endpoint of error bars.}

\argu {{\tt y} (float *, input)}{Pointer to array with
y~coordinates of error bar.}



\bname{plerry(n,x,ymin,ymax);}\label{plerry}
\addcontentsline{toc}{subsection}{plerry}

\descr{Draws a set of {\tt n} vertical error bars, the {\tt i}'th error bar
extending from {\tt ymin[i]} to {\tt ymax[i]} at x~coordinate {\tt x[i]}. The terminals
of the error bar are of length equal to the minor tick length (settable
using {\tt plsmin}).}

\argu {{\tt n} (int, input)}{Number of error bars to draw.}

\argu {{\tt x} (float *, input)}{Pointer to array with
x~coordinates of error bars.}

\argu {{\tt ymin} (float *, input)}{Pointer to array with
y~coordinates of lower endpoint of error bars.}

\argu {{\tt ymax} (float *, input)}{Pointer to array with
y~coordinate of upper endpoint of error bar.}



\bname{plfont(font);}\label{plfont}
\addcontentsline{toc}{subsection}{plfont}

\descr{Sets the default character font for subsequent character drawing.
       Also affects symbols produced by {\tt plpoin}.}

\argu {{\tt font} (int, input)}{Specifies the font:
\begin{itemize}
\item{1}: Normal font (simplest and fastest)
\item{2}: Roman font
\item{3}: Italic font
\item{4}: Script font
\end{itemize}
}

\bname{plgra();}\label{plgra}
\addcontentsline{toc}{subsection}{plgra}

\descr{Sets an interactive device to graphics mode, used in conjunction
       with {\tt pltext} to allow graphics and text to be interspersed.}

\bname{plgrid3(ztick);}\label{plgrid3}
\addcontentsline{toc}{subsection}{plgrid3}

\descr{Draws grid lines perpendicular to the z axis.
        For use only when doing three dimensional plots.  If used
        this routine must
        be called after calling {\tt plot3d} first (in order for the
        hidden line removal to work).}

\argu {{\tt ztick} (float, input)}{World coordinate 
interval between grid lines on the z~axis. Usually this variable has
the same value as {\tt ztick} in {\tt plbox3}.  If {\tt ztick} is
zero PLPLOT will automatically generate a suitable tick interval.}

\bname{plgspa(xmin,xmax,ymin,ymax);}\label{plgspa}
\addcontentsline{toc}{subsection}{plgspa}

\descr{Gets the size of the current subpage in millimetres measured
        from the bottom left hand corner of the output device page
        or screen. Can be used in conjunction with {\tt plsvpa} for setting
        the size of a viewport in absolute coordinates (millimetres).}

\argu {{\tt xmin} (float *, output)}{Pointer to variable with
position of left hand edge of subpage in millimetres}

\argu {{\tt xmax} (float *, output)}{Pointer to variable with
position of right hand edge of subpage in millimetres}

\argu {{\tt ymin} (float *, output)}{Pointer to variable with
position of bottom edge of subpage in millimetres}

\argu {{\tt ymax} (float *, output)}{Pointer to variable with
position of top edge of subpage in millimetres}

\bname{plhist(n,data,datmin,datmax,nbin,oldwin);}\label{plhist}
\addcontentsline{toc}{subsection}{plhist}

\descr{Plots a histogram from {\tt n} data points stored in the array {\tt data}.
       This routine bins the data into {\tt nbin} bins equally spaced between
       {\tt datmin} and {\tt datmax}, and calls {\tt plbin} to draw the resulting
       histogram. Parameter {\tt oldwin} allows the histogram either to
       be plotted in an existing window or causes {\tt plhist} to call
       {\tt plenv} with suitable limits before plotting the histogram.}
       
\argu {{\tt n} (int, input)}{Number of data points}

\argu {{\tt data} (float *, input)}{Pointer to array with
values of the {\tt n} data points.}

\argu {{\tt datmin} (float, input)}{Left-hand edge of lowest-valued bin.}

\argu {{\tt datmax} (float, input)}{Right-hand edge of highest-valued bin.}

\argu {{\tt nbin} (int, input)}{Number of (equal-sized) bins into which
to divide the interval {\tt xmin} to {\tt xmax}}

\argu {{\tt oldwin} (int, input)}{If one, the histogram is plotted in the
currently-defined window, and if zero, {\tt plenv} is called automatically
before plotting.}



\bname{pljoin(x1,y1,x2,y2);}\label{pljoin}
\addcontentsline{toc}{subsection}{pljoin}

\descr{Joins the point {\tt (x1,y1)} to {\tt (x2,y2)}.}
       
\argu {{\tt x1} (float, input)}{x~coordinate of first point.}

\argu {{\tt y1} (float, input)}{y~coordinate of first point.}
       
\argu {{\tt x2} (float, input)}{x~coordinate of second point.}

\argu {{\tt y2} (float, input)}{y~coordinate of second point.}



\bname{pllab(xlabel,ylabel,tlabel);}\label{pllab}
\addcontentsline{toc}{subsection}{pllab}

\descr{Routine for writing simple labels. Use {\tt plmtex} for more complex
       labels.}
       
\argu {{\tt xlabel} (char *, input)}{Label for horizontal axis.}

\argu {{\tt ylabel} (char *, input)}{Label for vertical axis.}
       
\argu {{\tt tlabel} (char *, input)}{Title of graph.}



\bname{plline(n,x,y);}\label{plline}
\addcontentsline{toc}{subsection}{plline}

\descr{Draws {\tt n-1} line segments joining points {\tt (x[i],y[i])}.}
       
\argu {{\tt n} (int, input)}{Number of points to join.}

\argu {{\tt x} (float *, input)}{Pointer to array with 
x~coordinates of points.}
       
\argu {{\tt y} (float *, input)}{Pointer to array with 
y~coordinates of points.}



\bname{plmtex(side,disp,pos,just,text);}\label{plmtex}
\addcontentsline{toc}{subsection}{plmtex}

\descr{Writes text at a specified position relative to the viewport
       boundaries. Text may be written inside or outside the viewport,
       but is clipped at the subpage boundaries.
       The reference point of a string lies along a line passing
       through the string at half the height of a capital letter.
       The position of the reference point along this line is determined
       by {\tt just}, and the position of the reference point relative to
       the viewport is set by {\tt disp} and {\tt pos}.}
       
\argu {{\tt side} (char *, input)}{Specifies the side of the viewport along
which the text is to be written. The string must be one of:
\begin{itemize}
\item{b}: Bottom of viwport.
\item{l}: Left of viewport, text written parallel to edge.
\item{lv}: Left of viewport, text written at right angles to edge.
\item{r}: Right of viewport, text written parallel to edge.
\item{rv}: Right of viewport, text written at right angles to edge.
\item{t}: Top of viewport.
\end{itemize}
}

\argu {{\tt disp} (float, input)}{Position of the reference point of string,
measured outwards from the specified viewport edge in units of the
current character height. Use negative {\tt disp} to write within the
viewport.}

\argu {{\tt pos} (float, input)}{Position of the reference point of string along
the specified edge, expressed as a fraction of the length of the edge.}

\argu {{\tt just} (float, input)}{Specifies the position of the string relative
to its reference point. If {\tt just=0}, the reference point is at the left
and if {\tt just=1}, it is at the right of the string. Other values of {\tt just}
give intermediate justifications.}

\argu {{\tt text} (char *, input)}{The string to be written out.}



\bname{plot3d(x,y,z,work,ly,nx,ny,opt);}\label{plot3d}
\addcontentsline{toc}{subsection}{plot3d}

\descr{Plots a three dimensional surface plot within the environment
        set up by {\tt plw3d}. The surface is defined by the two-dimensional
        array {\tt z[][ly]}, the point {\tt z[i][j]} being the value of the
        function at {\tt (x[i],y[j])}. Note that the points in arrays {\tt x} and
        {\tt y} do not need to be equally spaced, but must be stored in
        ascending order. The parameter {\tt opt} controls the way in which the
        surface is displayed. See Section \ref{threed} on page \pageref{threed} 
        for further details.}
        
\argu {{\tt x} (float *, input)}{Pointer to 
set of x~coordinate values at which the
function is evaluated.}
       
\argu {{\tt y} (float *, input)}{Pointer to 
set of y~coordinate values at which the
function is evaluated.}
       
\argu {{\tt z} (float *, input)}{Pointer to two dimensional array with
set of function values.}

\argu {{\tt work} (int *, input and output)}{Pointer to
work array of dimension at
least four times the maximum of {\tt nx} and {\tt ny}.}

\argu {{\tt ly} (int, input)}{Declared second dimension of {\tt z}~array.}

\argu {{\tt nx} (int, input)}{Number of {\tt x}~values at which function is
evaluated.}

\argu {{\tt ny} (int, input)}{Number of {\tt y}~values at which function is
evaluated.}

\argu {{\tt opt} (int, input)}{Determines the way in which the surface
is represented:
\begin{itemize}
\item{1}: Lines are drawn showing {\tt z} as a function of {\tt x} for each value
          of {\tt y[j]}.
\item{2}: Lines are drawn showing {\tt z} as a function of {\tt y} for each value
          of {\tt x[i]}.
\item{3}: Network of lines is drawn connecting points at which function is
          defined.
\end{itemize}
}



\bname{plpoin(n,x,y,code);}\label{plpoin}
\addcontentsline{toc}{subsection}{plpoin}

\descr{Marks out a set of {\tt n} points at positions {\tt (x(i),y(i))}, using
       the symbol defined by {\tt code}. If {\tt code} is between 32 and 127,
       the symbol is simply the printable ASCII character in the default
       font.}
        
\argu {{\tt n} (int, input)}{Number of points to be marked.}

\argu {{\tt x} (float *, input)}{Pointer to array with
set of x~coordinate values for the points.}
       
\argu {{\tt y} (float *, input)}{Pointer to array with
set of y~coordinate values for the points.}
       
\argu {{\tt code} (int, input)}{Code number for the symbol to be plotted.}



\bname{plptex(x,y,dx,dy,just,text);}\label{plptex}
\addcontentsline{toc}{subsection}{plptex}

\descr{Writes text at a specified position and inclination within the 
       viewport. Text is clipped at the viewport boundaries.
       The reference point of a string lies along a line passing
       through the string at half the height of a capital letter.
       The position of the reference point along this line is determined
       by {\tt just}, the reference point is placed at world coordinates
       {\tt (x,y)} within the viewport. The inclination of the string is
       specified in terms of differences of world coordinates making
       it easy to write text parallel to a line in a graph.}
       
\argu {{\tt x} (float, input)}{x coordinate of reference point of string.}

\argu {{\tt y} (float, input)}{y coordinate of reference point of string.}

\argu {{\tt dx} (float, input)}{Together with {\tt dy}, this specifies the inclination 
of the string. The baseline of the string is parallel to a line joining 
{\tt (x,y)} to {\tt (x+dx,y+dy)}.}

\argu {{\tt dy} (float, input)}{Together with {\tt dx}, this specifies the inclination
of the string.}

\argu {{\tt just} (float, input)}{Specifies the position of the string relative
to its reference point. If {\tt just=0}, the reference point is at the left
and if {\tt just=1}, it is at the right of the string. Other values of {\tt just}
give intermediate justifications.}

\argu {{\tt text} (char *, input)}{The string to be written out.}



\bname{plschr(def,scale);}\label{plschr}
\addcontentsline{toc}{subsection}{plschr}

\descr {This sets up the size of all subsequent characters drawn. The 
        actual height of a character is the product of the default 
        character size and a scaling factor.}

\argu {{\tt def} (float, input)}{The default height of a character in millimetres,
        should be set to zero if the default height is to remain unchanged.}

\argu {{\tt scale} (float, input)}{Scale factor to be applied to default to
        get actual character height.}


\bname{plside3(x,y,z,ly,nx,ny,opt);}\label{plside3}
\addcontentsline{toc}{subsection}{plside3}

\descr{Draws sides on three dimensional plots. The sides extend from
the plotted function down to the x-y plane.  Should only be called
after {\tt plot3d}. The arguments passed to {\tt plside3} should be
the same as those used in {\tt plot3d}.}
        
\argu {{\tt x} (float *, input)}{Pointer to 
set of x~coordinate values at which the
function is evaluated.}
       
\argu {{\tt y} (float *, input)}{Pointer to 
set of y~coordinate values at which the
function is evaluated.}
       
\argu {{\tt z} (float *, input)}{Pointer to two dimensional array with
set of function values.}

\argu {{\tt ly} (int, input)}{Declared second dimension of {\tt z}~array.}

\argu {{\tt nx} (int, input)}{Number of {\tt x}~values at which function is
evaluated.}

\argu {{\tt ny} (int, input)}{Number of {\tt y}~values at which function is
evaluated.}

\argu {{\tt opt} (int, input)}{Determines the way in which the sides
are drawn:
\begin{itemize}
\item{1}: Lines are drawn from {\tt z} down to the y axis at each value
          of {\tt y[j]}.
\item{2}: Lines are drawn from {\tt z} down to the x axis at each value
          of {\tt x[i]}.
\item{3}: Lines are drawn from {\tt z} to both axes.
\end{itemize}
}



\bname{plsmaj(def,scale);}\label{plsmaj}
\addcontentsline{toc}{subsection}{plsmaj}

\descr {This sets up the length of the major ticks. The 
        actual length is the product of the default length and a scaling 
        factor as for character height.}

\argu {{\tt def} (float, input)}{The default length of a major tick in millimetres,
        should be set to zero if the default length is to remain unchanged.}

\argu {{\tt scale} (float, input)}{Scale factor to be applied to default to
        get actual tick length.}



\bname{plsmin(def,scale);}\label{plsmin}
\addcontentsline{toc}{subsection}{plsmin}

\descr {This sets up the length of the minor ticks and the length of the
        terminals on error bars. The actual length is the product of the 
        default length and a scaling factor as for character height.}

\argu {{\tt def} (float, input)}{The default length of a minor tick in millimetres,
        should be set to zero if the default length is to remain unchanged.}

\argu {{\tt scale} (float, input)}{Scale factor to be applied to default to
        get actual tick length.}



\bname{plssym(def,scale);}\label{plssym}
\addcontentsline{toc}{subsection}{plssym}

\descr {This sets up the size of all subsequent symbols drawn by
        {\tt plpoin} and {\tt plsym}. The 
        actual height of a symbol is the product of the default 
        symbol size and a scaling factor as for the character height. }

\argu {{\tt def} (float, input)}{The default height of a symbol in millimetres,
        should be set to zero if the default height is to remain unchanged.}

\argu {{\tt scale} (float, input)}{Scale factor to be applied to default to
        get actual symbol height.}

\bname{plstar(nx,ny);}\label{plstar}
\addcontentsline{toc}{subsection}{plstar}

\descr{Initializing the plotting package. The program prompts for the
device number of the desired output device. The output device is divided
into {\tt nx} by {\tt ny} sub-pages, each of which may be used
independently. The subroutine {\tt pladv} is used to advance from one
subpage to the next.}

\argu {{\tt nx} (int, input)}{Number of subpages to divide output page in 
      the horizontal direction.}

\argu {{\tt ny} (int, input)}{Number of subpages to divide output page in 
      the vertical direction.}



\bname{plstyl(nels,mark,space);}\label{plstyl}
\addcontentsline{toc}{subsection}{plstyl}

\descr {This sets up the line style for all lines subsequently drawn.
        A line consists of segments in which the pen is alternately
        down and up. The lengths of these segments are passed in the
        arrays {\tt mark} and {\tt space} respectively. The number of mark-space
        pairs is specified by {\tt nels}. In order to return the line style
        to the default continuous line, {\tt PLSTYL} should be called with
        {\tt nels=0}.}
        
\argu {{\tt nels} (int, input)}{The number of mark and space elements in
        a line. Thus a simple broken line can be obtained by setting
        {\tt nels=1}. A continuous line is specified by 
        setting {\tt nels=0}.}

\argu {{\tt mark} (int *, input)}
       {Pointer to array with the lengths of the segments during which
        the pen is down, measured in micrometres.}

\argu {{\tt space} (int *, input)}
       {Pointer to array with the lengths of the segments during which
        the pen is up, measured in micrometres.}



\bname{plsvpa(xmin,xmax,ymin,ymax);}\label{plsvpa}
\addcontentsline{toc}{subsection}{plsvpa}

\descr {Alternate routine to {\tt plvpor} for setting up the viewport. This routine
        should be used only if the viewport is required to have a definite
        size in millimetres. The routine {\tt plgspa} is useful for finding
        out the size of the current subpage. }
        
\argu {{\tt xmin} (float, input)}{The distance of the left-hand edge of the
        viewport from the left-hand edge of the subpage in millimetres.}

\argu {{\tt xmax} (float, input)}{The distance of the right-hand edge of the
        viewport from the left-hand edge of the subpage in millimetres.}

\argu {{\tt ymin} (float, input)}{The distance of the bottom edge of the
        viewport from the bottom edge of the subpage in millimetres.}

\argu {{\tt ymax} (float, input)}{The distance of the top edge of the
        viewport from the top edge of the subpage in millimetres.}



\bname{plsym(n,x,y,code);}\label{plsym}
\addcontentsline{toc}{subsection}{plsym}

\descr{Marks out a set of {\tt n} points at positions {\tt (x[i],y[i])}, using
       the symbol defined by {\tt code}. The code is interpreted as an
       index in the Hershey font tables.}
        
\argu {{\tt n} (int, input)}{Number of points to be marked.}

\argu {{\tt x} (float *, input)}{Pointer to array with
set of x~coordinate values for the points.}
       
\argu {{\tt y} (float *, input)}{Pointer to array with
set of y~coordinate values for the points.}
       
\argu {{\tt code} (int, input)}{Code number for the symbol to be plotted.}



\bname{pltext();}\label{pltext}
\addcontentsline{toc}{subsection}{pltext}

\descr{Sets an interactive device to text mode, used in conjunction
       with {\tt plgra} to allow graphics and text to be interspersed.
       This is not currently supported on the Amiga. All the labelling
       is drawn in vector mode.}



\bname{plvpor(xmin,xmax,ymin,ymax);}\label{plvpor}
\addcontentsline{toc}{subsection}{plvpor}

\descr {Device-independent routine for setting up the viewport.
        This defines the viewport in terms of normalized subpage
        coordinates which run from 0.0 to 1.0 (left to right and
        bottom to top) along each edge of the current subpage. Use
        the alternate routine {\tt plsvpa} in order to create a viewport 
        of a definite size.}
        
\argu {{\tt xmin} (float, input)}{The normalized subpage coordinate of the 
        left-hand edge of the viewport.}

\argu {{\tt xmax} (float, input)}{The normalized subpage coordinate of the 
        right-hand edge of the viewport.}

\argu {{\tt ymin} (float, input)}{The normalized subpage coordinate of the 
        bottom edge of the viewport.}

\argu {{\tt ymax} (float, input)}{The normalized subpage coordinate of the 
        top edge of the viewport.}



\bname{plvsta();}\label{plvsta}
\addcontentsline{toc}{subsection}{plvsta}

\descr {Sets up a standard viewport, leaving a left-hand margin of 
        seven character heights, and four character heights around the
        other three sides.}



\bname{plw3s(basex,basey,height,xmin,xmax,ymin,ymax,zmin,zmax,alt,az);}\label{plw3d}
\addcontentsline{toc}{subsection}{plw3d}

\descr {Sets up a window for a three-dimensional surface plot within the
currently defined two-dimensional window. The enclosing box for the
surface plot defined by {\tt xmin}, {\tt xmax}, {\tt ymin}, {\tt ymax},
{\tt zmin} and {\tt zmax} in user-coordinate space is mapped into a box
of world coordinate size {\tt basex} by {\tt basey} by {\tt height} so
that {\tt xmin} maps to {\tt -basex/2}, {\tt xmax} maps to {\tt
basex/2}, {\tt ymin} maps to {\tt -basey/2}, {\tt ymax} maps to {\tt
basey/2}, {\tt zmin} maps to {\tt 0} and {\tt zmax} maps to {\tt
height}. The resulting world-coordinate box is then viewed by an
observer at altitude {\tt alt} and azimuth {\tt az}. This routine must
be called before {\tt plbox3} or {\tt plot3d}. See Section \ref{threed}
on page \pageref{threed} for a more complete description of
three-dimensional plotting.}

\argu {{\tt basex} (float, input)}{The x~coordinate size of the world-coordinate
box.}

\argu {{\tt basey} (float, input)}{The y~coordinate size of the world-coordinate
box.}

\argu {{\tt height} (float, input)}{The z~coordinate size of the world-coordinate
box.}

\argu {{\tt xmin} (float, input)}{The minimum user x~coordinate value.}

\argu {{\tt xmax} (float, input)}{The maximum user x~coordinate value.}

\argu {{\tt ymin} (float, input)}{The minimum user y~coordinate value.}

\argu {{\tt ymax} (float, input)}{The maximum user y~coordinate value.}

\argu {{\tt zmin} (float, input)}{The minimum user z~coordinate value.}

\argu {{\tt zmax} (float, input)}{The maximum user z~coordinate value.}

\argu {{\tt alt} (float, input)}{The viewing altitude in degrees above the xy~plane.}

\argu {{\tt az} (float, input)}{The viewing azimuth in degrees. When {\tt az=0},
the observer is looking face onto the zx~plane, and as {\tt az} is increased,
the observer moves clockwise around the box when viewed from above the 
xy~plane.}



\bname{plwind(xmin,xmax,ymin,ymax);}\label{plwind}
\addcontentsline{toc}{subsection}{plwind}

\descr {Sets up the world coordinates of the edges of the viewport.}
        
\argu {{\tt xmin} (float, input)}{The world x~coordinate of the 
        left-hand edge of the viewport.}

\argu {{\tt xmax} (float, input)}{The world x~coordinate of the 
        right-hand edge of the viewport.}

\argu {{\tt ymin} (float, input)}{The world y~coordinate of the 
        bottom edge of the viewport.}

\argu {{\tt ymax} (float, input)}{The world y~coordinate of the 
        top edge of the viewport.}