\c -*-latexinfo-*-
\c api.tex
\c Maurice LeBrun
\c 19 May 1994

\node API, Bibliography, Extended WISH, Top
\chapter{The PLplot Applications Programming Interface}

Documentation of each PLplot function.

Many new ones are still missing.

\begin{menu}
* pladv::		Advance the (sub-)page
* plbin::		Plot a histogram from binned data
* plbox::		Draw a box with axes, etc
* plbox3::		Draw a box with axes, etc, in 3-d
* plclr::		Eject current page
* plcol::		Set color
* plcon0::		Contour plot, identity mapping
* plcon1::		Contour plot, general 1-d mapping
* plcon2::		Contour plot, general 2-d mapping
* plconf::		Contour plot, general
* plcont::		Contour plot, fixed linear mapping
* plend::		End plotting session
* plend1::		End plotting session for 1 stream
* plenv::		Set up standard window and draw box
* plerrx::		Draw x error bar
* plerry::		Draw y error bar
* plexit::		Error abort
* plfill::		Area fill
* plfont::		Set character font
* plfontld::		Load character font
* plgfam::		Get family file paramters
* plgfile::		Get output file handle
* plgfnam::		Get output file name
* plgpage::		Get page parameters
* plgra::		Switch to graphics screen
* plgspa::		Get current subpage parameters
* plgstrm::		Get current stream number
* plgxax::		Get x axis parameters
* plgyax::		Get y axis parameters
* plgzax::		Get z axis parameters
* plhist::		Plot a histogram from unbinned data
* plinit::		Initialize PLplot
* pljoin::		Draw a line between two points
* pllab::		Simple routine to write labels
* plline::		Draw lines between a number of points
* pllsty::		Select line style
* plmesh::		Plot surface mesh
* plmtex::		Write text relative to viewport boundaries
* plot3d::		Plot 3-d surface plot
* plpage::		Begin a new page
* plpat::		Set area fill pattern
* plpoin::		Plots a character at the specified points
* plprec::		Set precision in numeric labels
* plpsty::		Select area fill pattern
* plptex::		Write text inside the viewport
* plschr::		Set character size
* plsfam::		Set family file parameters
* plsfile::		Set output file handle
* plsfnam::		Set output file name
* plsmaj::		Set length of major ticks
* plsmin::		Set length of minor ticks
* plsori::		Set orientation
* plspage::		Set page parameters
* plsstrm::		Set current output stream
* plssym::		Set symbol size
* plstar::		Initialization
* plstart::		Initialization
* plstyl::		Set line style
* plsvpa::		Specify viewport in absolute coordinates
* plsxax::		Set x axis parameters
* plsyax::		Set y axis parameters
* plsym::		Plots a symbol at the specified points
* plszax::		Set z axis parameters
* pltext::		Switch to text screen
* plvasp::		Specify viewport using aspect ratio only
* plvpas::		Specify viewport using coordinates and aspect ratio
* plvpor::		Specify viewport using coordinates
* plvsta::		Select standard viewport
* plw3d::		Set up window for 3-d plotting
* plwid::		Set pen width
* plwind::		Specify world coordinates of viewport boundaries
\end{menu}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\c
\c Each function is enclosed in a box with an indended description.  The
\c arguments are also offset with an indented explanation.  In order to
\c keep things as clean as possible, no sectioning commands are used,
\c rather, the sections are added to the table of contents "by hand".
\c Since latexinfo.sty requires a sectioning command to be used to get
\c the Latex cross references right, I also put these in by hand.
\c
\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node pladv, plbin, API, API


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

\descr{ Advances to the next subpage if \code{sub=0}, performing a page
advance if there are no remaining subpages on the current page.  If
subwindowing isn't being used, \code{pladv(0)} will always advance the
page.  If \code{sub>0}, PLplot switches to the specified subpage.  Note
that this allows you to overwrite a plot on the specified subpage; if this
is not what you intended, use \code{plclr} followed by \code{plpage} to
first advance the page.  This routine is called automatically (with
\code{sub=0}) by \code{plenv}, but if \code{plenv} is not used,
\code{pladv} must be called after initializing PLplot but before defining
the viewport.}

\argu{ \code{sub} (PLINT, 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.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plbin, plbox, pladv, API


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

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

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

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

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plbox, plbox3, plbin, API


\bname{plbox(xopt, xtick, nxsub, yopt, ytick, nysub)}
\label{plbox}
\findex{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 \code{plbox}
should only be called after defining both viewport and window.  The
character strings \code{xopt} and \code{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{ \code{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
\code{a}: Draws axis, X-axis is horizontal line \code{y=0}, and Y-axis
is vertical line \code{x=0}.

\item
\code{b}: Draws bottom (X) or left (Y) edge of frame.

\item
\code{c}: Draws top (X) or right (Y) edge of frame.

\item
\code{g}: Draws a grid at the major tick interval.

\item
\code{i}: Inverts tick marks, so they are drawn outwards, rather than
inwards.

\item
\code{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
\code{m}: Writes numeric labels at major tick intervals in the
unconventional location (above box for X, right of box for Y).

\item
\code{n}: Writes numeric labels at major tick intervals in the
conventional location (below box for X, left of box for Y).

\item
\code{s}: Enables subticks between major ticks, only valid if \code{t} is
also specified.

\item
\code{t}: Draws major ticks.
\end{itemize}
}

\argu{ \code{xtick} (PLFLT, 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{ \code{nxsub} (PLINT, 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{ \code{yopt} (char *, input)}{Pointer to character string specifying
options for vertical axis.  The string can include any combination of the
letters defined above for \code{xopt}, and in addition may contain:

\begin{itemize} 
\item
\code{v}: Write numeric labels for vertical axis
parallel to the base of the graph, rather than parallel to the axis.
\end{itemize}
}

\argu{ \code{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{ \code{nysub} (PLINT, 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.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plbox3, plclr, plbox, API


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

\descr{ Draws axes, numeric and text labels for a three-dimensional surface
plot.  For a more complete description of three-dimensional plotting
\pxref{3-d Plots}.}

\argu{ \code{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
\code{b}: Draws axis at base, at height \code{z=zmin} where \code{zmin}
is defined by call to \code{plw3d}.  This character must be specified in
order to use any of the other options.

\item
\code{i}: Inverts tick marks, so they are drawn downwards, rather than
upwards.

\item
\code{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
\code{n}: Writes numeric labels at major tick intervals.

\item
\code{s}: Enables subticks between major ticks, only valid if \code{t} is
also specified.

\item
\code{t}: Draws major ticks.

\item
\code{u}: If this is specified, the text label for the axis is written
under the axis.
\end{itemize}
}

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

\argu{ \code{xtick} (PLFLT, 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{ \code{nxsub} (PLINT, 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{ \code{yopt} (char *, input)}{Pointer to character string specifying
options for the y axis.  The string is interpreted in the same way as
\code{xopt}.}

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

\argu{ \code{ytick} (PLFLT, 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{ \code{nysub} (PLINT, 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{ \code{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
\code{b}: Draws z axis to the left of the surface plot.

\item
\code{c}: Draws z axis to the right of the surface plot.

\item
\code{d}: Draws grid lines parallel to the x-y plane behind the figure.
These lines are not drawn until after \code{plot3d} or \code{plmesh} are called
because of the need for hidden line removal.

\item
\code{i}: Inverts tick marks, so they are drawn away from the center.

\item
\code{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
\code{m}: Writes numeric labels at major tick intervals on the right-hand
verical axis.

\item
\code{n}: Writes numeric labels at major tick intervals on the left-hand
verical axis.

\item
\code{s}: Enables subticks between major ticks, only valid if \code{t} is
also specified.

\item
\code{t}: Draws major ticks.

\item
\code{u}: If this is specified, the text label is written beside the
left-hand axis.

\item
\code{v}: If this is specified, the text label is written beside the
right-hand axis.
\end{itemize}
}

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

\argu{ \code{ztick} (PLFLT, 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{ \code{nzsub} (PLINT, 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.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plclr, plcol, plbox3, API


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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plcol, plcon0, plclr, API


\bname{plcol(color)}
\label{plcol}
\findex{plcol}
\addcontentsline{toc}{subsection}{plcol}

\descr{ Sets the color for subsequent lines.}

\argu{ \code{color} (PLINT, input)}{Integer representing the color.  The
defaults at present are (these may change):

\begin{enumerate}
\item
black (default background)
\item
red
\item
yellow
\item
green
\item
aquamarine
\item
pink
\item
wheat
\item
grey
\item
brown
\item
blue
\item
BlueViolet
\item
cyan
\item
turquoise
\item
magenta
\item
salmon
\item
white (default foreground)
\end{enumerate}
}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plcon0, plcon1, plcol, API


\bnameF{plcon0(z, nx, ny, kx, lx, ky, ly, clevel, nlevel)}
\label{plcon0}
\findex{plcon0}
\addcontentsline{toc}{subsection}{plcon0}

\descr{ Draws a contour plot of the data in \code{z[nx][ny]}, using the
\code{nlevel} contour levels specified by \code{clevel}.  Only the region
of the array from \code{kx} to \code{lx} and from \code{ky} to \code{ly}
is plotted out.  \xref{Contour plots} for more information.}

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

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

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

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

\argu{ \code{clevel} (PLFLT *, input)}{Pointer to array specifying
    levels at which to draw contours.}

\argu{ \code{nlevel} (PLINT, input)}{Number of contour levels to draw.}

NOTE: this function is intended for use from a Fortran caller only.  The C
user should instead call \code{plcont} using the built-in transformation
function \code{pltr0} for the same capability. 

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plcon1, plcon2, plcon0, API


\bnameF{plcon1(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, xg, yg)}
\label{plcon1}
\findex{plcon1}
\addcontentsline{toc}{subsection}{plcon1}

\descr{ Draws a contour plot of the data in \code{z[nx][ny]}, using the
\code{nlevel} contour levels specified by \code{clevel}.  Only the region
of the array from \code{kx} to \code{lx} and from \code{ky} to \code{ly}
is plotted out.  The arrays \code{xg} and \code{yg} are used to specify
the transformation between array indices and world coordinates.  
\xref{Contour plots} for more information.}

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

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

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

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

\argu{ \code{clevel} (PLFLT *, input)}{Pointer to array specifying
levels at which to draw contours.}

\argu{ \code{nlevel} (PLINT, input)}{Number of contour levels to draw.}

\argu{ \code{xg, yg} (PLFLT *, input)}{Pointers to arrays which specify the
transformation from array indices to world coordinates.  These must be
one-dimensional arrays, used for a transformation of the form:
\code{tx$=$f(x), ty$=$f(y)}.  Function values at locations between grid
points are obtained via linear interpolation. }

NOTE: this function is intended for use from a Fortran caller only.  The C
user should instead call \code{plconf} using the built-in transformation
function \code{pltr1} for the same capability. 

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plcon2, plconf, plcon1, API


\bnameF{plcon2(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, xg, yg)}
\label{plcon2}
\findex{plcon2}
\addcontentsline{toc}{subsection}{plcon2}

\descr{ Draws a contour plot of the data in \code{z[nx][ny]}, using the
\code{nlevel} contour levels specified by \code{clevel}.  Only the region
of the array from \code{kx} to \code{lx} and from \code{ky} to \code{ly}
is plotted out.  The arrays \code{xg} and \code{yg} are used to specify
the transformation between array indices and world coordinates.  
\xref{Contour plots} for more information.}

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

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

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

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

\argu{ \code{clevel} (PLFLT *, input)}{Pointer to array specifying
    levels at which to draw contours.}

\argu{ \code{nlevel} (PLINT, input)}{Number of contour levels to draw.}

\argu{ \code{xg, yg} (PLFLT *, input)}{Pointers to arrays which specify the
transformation from array indices to world coordinates.  These must be
two-dimensional arrays, used for a transformation of the form:
\code{tx$=$f(x, y), ty$=$f(x, y)}.  Function values at locations between
grid points are obtained via linear interpolation.}

NOTE: this function is intended for use from a Fortran caller only.  The C
user should instead call \code{plconf} using the built-in transformation
function \code{pltr2} for the same capability. 

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plconf, plcont, plcon2, API


\bnameC{plconf(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr, xg, yg)}
\label{plconf}
\findex{plconf}
\addcontentsline{toc}{subsection}{plconf}

\descr{ Draws a contour plot of the data in \code{z[nx][ny]}, using the
\code{nlevel} contour levels specified by \code{clevel}.  Only the region
of the array from \code{kx} to \code{lx} and from \code{ky} to \code{ly}
is plotted out.  A transformation routine \code{pltr} is used to map
indicies within the array to the world coordinates, using the
transformation arrays \code{xg} and \code{yg}.  \xref{Contour plots} for
more information.}

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

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

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

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

\argu{ \code{clevel} (PLFLT *, input)}{Pointer to array specifying
    levels at which to draw contours.}

\argu{ \code{nlevel} (PLINT, input)}{Number of contour levels to draw.}

\argu{ \code{pltr} (void *, input)}{Pointer to function that defines
transformation between indicies in array \code{z} and the world coordinates.
The function should have the form \name{pltr(x, y, tx, ty, xg, yg, nx, ny)}

\argu{ \code{x, y} (PLFLT, input)}{ Specifies the position in the array through
which the contour runs in terms of the array indicies.}

\argu{ \code{tx, ty} (PLFLT *, output)}{Pointers to the
world coordinates corresponding to the point \code{(x, y)}.}

\argu{ \code{xg, yg} (PLFLT *, input)}{Pointers to transformation arrays.}

\argu{ \code{nx, ny} (PLINT, input)}{Array dimensions in \code{x} and
\code{y}, respectively.}

\argu{ \code{xg, yg} (PLFLT *, input)}{Pointers to arrays which define the
transformation from \code{(x, y)} to \code{(tx, ty)}, used as input to the
transformation function \code{pltr}.}
}

Two transformation functions are provided: \code{pltr1}, for one
dimensional mappings (i.e. \code{tx = f(x), ty = f(y)}), and
\code{pltr2}, for two dimensional mappings (i.e. \code{tx = f(x, y), ty
= f(x, y)}).  Function values at locations between grid points are
obtained via linear interpolation.\refill

NOTE:  this routine cannot be called directly from Fortran.  Use
\code{plcon0}, \code{plcon1}, or \code{plcon2} instead.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plcont, plend, plconf, API


\bnameCF{
plcont(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr)}{(C)}{
plcont(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, tr)}{\ \ (Fortran)}

\label{plcont}
\findex{plcont}
\addcontentsline{toc}{subsection}{plcont}

\descr{ Draws a contour plot of the data in \code{z[nx][ny]}, using the
\code{nlevel} contour levels specified by \code{clevel}.  Only the region
of the array from \code{kx} to \code{lx} and from \code{ky} to \code{ly}
is plotted out.  A transformation routine \code{pltr} is used to map
indicies within the array to the world coordinates.  \xref{Contour
plots} for more information.}

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

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

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

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

\argu{ \code{clevel} (PLFLT *, input)}{Pointer to array specifying
    levels at which to draw contours.}

\argu{ \code{nlevel} (PLINT, input)}{Number of contour levels to draw.}

\argu{ \code{pltr} (void *, input)}{Pointer to function that defines
transformation between indicies in array \code{z} and the world coordinates
(C only).  Two transformation functions are provided:  \code{xform}, for
simple linear mappings, and \code{pltr0}, if no mapping is required.
\code{xform} is not actually compiled into the PLplot library due to the
need for external data; instead you must include it as part of your
program.  The function should have the form:

\name{pltr(x, y, tx, ty)}

\argu{ \code{x, y} (PLFLT, input)}{ Specifies the position in the array
through which the contour runs in terms of the array indicies.} 

\argu{ \code{tx, ty} (PLFLT *, output)}{Pointers to the world coordinates
corresponding to the point \code{(x, y)}.} }

\argu{ \code{tr} (PLFLT *, input)}{Pointer to 6-element array specifying
coefficients to use in the \code{xform} transformation function (Fortran
only).  Since this is somewhat inflexible, the user is recommended to call
either of \code{plcon0}, \code{plcon1}, or \code{plcon2} instead.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plend, plend1, plcont, API


\bname{plend()}
\label{plend}
\findex{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.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plend1, plenv, plend, API


\bname{plend1()}
\label{plend1}
\findex{plend1}
\addcontentsline{toc}{subsection}{plend}

\descr{ Ends a plotting session for the current output stream only.
See \code{plsstrm} for more info.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plenv, plerrx, plend1, API


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

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

\argu{ \code{xmin} (PLFLT, input)}{Value of x at left-hand edge of window.}

\argu{ \code{xmax} (PLFLT, input)}{Value of x at right-hand edge of window.}

\argu{ \code{ymin} (PLFLT, input)}{Value of y at bottom edge of window.}

\argu{ \code{ymax} (PLFLT, input)}{Value of y at top edge of window.}

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

\argu{ \code{axis} (PLINT, input)}{Controls drawing of the box around the plot:

\begin{itemize}
\item
\code{-2}: No box or annotation.

\item
\code{-1}: Draw box only.

\item
\code{0}: Draw box, labelled with coordinate values around edge.

\item
\code{1}: In addition to box and labels, draw the two axes \code{x=0}
and \code{y=0}. 

\item
\code{2}: As for \code{axis=1}, but also draw a grid at the major tick
interval. 

\item
\code{10}: Logarithmic x axis, linear y axis.

\item
\code{11}: Logarithmic x axis, linear y axis and draw line \code{y=0}.

\item
\code{20}: Linear x axis, logarithmic y axis.

\item
\code{21}: Linear x axis, logarithmic y axis and draw line \code{x=0}.

\item
\code{30}: Logarithmic x and y axes.
\end{itemize}
}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plerrx, plerry, plenv, API


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

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

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

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

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

\argu{ \code{y} (PLFLT *, input)}{Pointer to array with y coordinates of
error bar.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plerry, plexit, plerrx, API


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

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

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

\argu{ \code{x} (PLFLT *, input)}{Pointer to array with x coordinates of
error bars.}

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plexit, plfill, plerry, API


\bname{plexit(message)}
\label{plexit}
\findex{plexit}
\addcontentsline{toc}{subsection}{plexit}

\descr{ This routine is called in case an error is encountered during
execution of a PLplot routine.  It prints the error message, tries to
release allocated resources, calls \code{pl\_exit} and then exits.  If
cleanup needs to be done in the driver program then the user may want to
supply his/her own version of \code{pl\_exit}.}

\argu{ \code{message} (char *, input)}{Error message.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plfill, plfont, plexit, API


\bname{plfill(n, x, y)}
\label{plfill}
\findex{plfill}
\addcontentsline{toc}{subsection}{plfill}

\descr{ Fills the polygon defined by the \code{n} points \code{(x[i], y[i])}
using the pattern defined by \code{plpsty} or \code{plpat}.  The routine will
automatically close the polygon between the last and first vertices.  If
multiple closed polygons are passed in \code{x} and \code{y} then \code{plfill}
will fill in between them.}

\argu{ \code{n} (PLINT, input)}{Number of vertices in polygon.}

\argu{ \code{x} (PLFLT *, input)}{Pointer to array with x coordinates of
vertices.}

\argu{ \code{y} (PLFLT *, input)}{Pointer to array with y coordinates of
vertices.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plfont, plfontld, plfill, API


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

\descr{ Sets the default character font for subsequent character drawing.
Also affects symbols produced by \code{plpoin}.}  This routine has no effect
unless the extended character set is loaded (see \code{plfontld}).

\argu{ \code{font} (PLINT, input)}{Specifies the font:

\begin{itemize}
\item
\code{1}: Normal font (simplest and fastest)

\item
\code{2}: Roman font

\item
\code{3}: Italic font

\item
\code{4}: Script font
\end{itemize}
}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plfontld, plgfam, plfont, API


\bname{plfontld(set)}
\label{plfontld}
\findex{plfontld}
\addcontentsline{toc}{subsection}{plfontld}

\descr{ Sets the character set to use for subsequent character drawing.
May be called before calling initializing PLplot.}

\argu{ \code{set} (PLINT, input)}{Specifies the character set to load:
\begin{itemize}
\item
\code{0}: Standard character set

\item
\code{1}: Extended character set
\end{itemize}
}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgfam, plgfile, plfontld, API


\bname{plgfam(fam, num, bmax)}
\label{plgfam}
\findex{plgfam}
\addcontentsline{toc}{subsection}{plgfam}

\descr{ Gets information about current family file, if familying is
enabled.  See Section \ref{sec:family} for more information.}

\argu{ \code{fam} (PLINT *, output)}{Pointer to variable with the boolean
family flag value.   If nonzero, familying is enabled.}

\argu{ \code{num} (PLINT *, output)}{Pointer to variable with the current 
family file number.}

\argu{ \code{bmax} (PLINT *, output)}{Pointer to variable with the maximum
file size (in bytes) for a family file.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgfile, plgfnam, plgfam, API


\bname{plgfile(file)}
\label{plgfile}
\findex{plgfile}
\addcontentsline{toc}{subsection}{plgfile}

\descr{ Gets the current output file handle, if applicable. }

\argu{ \code{file} (FILE *, output)}{File pointer to current output file.}

NOTE: cannot be called from Fortran.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgfnam, plgpage, plgfile, API


\bname{plgfnam(fnam)}
\label{plgfnam}
\findex{plgfnam}
\addcontentsline{toc}{subsection}{plgfnam}

\descr{ Gets the current output file name, if applicable. }

\argu{ \code{fnam} (char *, output)}{Pointer to file name string.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgpage, plgra, plgfnam, API


\bname{plgpage(xp, yp, xleng, yleng, xoff, yoff)}
\label{plgpage}
\findex{plgpage}
\addcontentsline{toc}{subsection}{plgpage}

\descr{ Gets the current page configuration. }

\argu{ \code{xp} (PLINT *, output)}{Pointer to number of pixels in x.}

\argu{ \code{yp} (PLINT *; output)}{Pointer to number of pixels in y.}

\argu{ \code{xleng} (PLINT *, output)}{Pointer to x page length value.}

\argu{ \code{yleng} (PLINT *, output)}{Pointer to y page length value.}

\argu{ \code{xoff} (PLINT *, output)}{Pointer to x page offset.}

\argu{ \code{yoff} (PLINT *, output)}{Pointer to y page offset.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgra, plgspa, plgpage, API


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

\descr{ Sets an interactive device to graphics mode, used in conjunction
with \code{pltext} to allow graphics and text to be interspersed.  On a
device which supports separate text and graphics windows, this command
causes control to be switched to the graphics window.  If already in
graphics mode, this command is ignored.  It is also ignored on devices which
only support a single window or use a different method for shifting focus.  
See also \code{pltext}.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgspa, plgstrm, plgra, API


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

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

\argu{ \code{xmin} (PLFLT *, output)}{Pointer to variable with position of
left hand edge of subpage in millimeters.}

\argu{ \code{xmax} (PLFLT *, output)}{Pointer to variable with position of
right hand edge of subpage in millimeters.}

\argu{ \code{ymin} (PLFLT *, output)}{Pointer to variable with position of
bottom edge of subpage in millimeters.}

\argu{ \code{ymax} (PLFLT *, output)}{Pointer to variable with position of
top edge of subpage in millimeters.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgstrm, plgxax, plgspa, API


\bname{plgstrm(strm)}
\label{plgstrm}
\findex{plgstrm}
\addcontentsline{toc}{subsection}{plgstrm}

\descr{ Gets the number of the current output stream. See also
\code{plsstrm}.}

\argu{ \code{strm} (PLINT *, output)}{Pointer to current stream value.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgxax, plgyax, plgstrm, API


\bname{plgxax(digmax, digits)}
\label{plgxax}
\findex{plgxax}
\addcontentsline{toc}{subsection}{plgxax}

\descr{ Returns current values of the \code{digmax} and \code{digits} flags
for the x axis.  \code{digits} is updated after the plot is drawn, so so
this routine should only be called \emph{after} the call to \code{plbox}
(or \code{plbox3}) is complete.  \xref{Annotation} for more information.}

\argu{ \code{digmax} (PLINT *, output)}{Pointer to variable with the maximum
number of digits.  If nonzero, the printed label will be switched to a
floating point representation when the number of digits exceeds
\code{digmax}.}

\argu{ \code{digits} (PLINT *, output)}{Pointer to variable with the actual
number of digits for the numeric labels (x axis) from the last plot.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgyax, plgzax, plgxax, API


\bname{plgyax(digmax, digits)}
\label{plgyax}
\findex{plgyax}
\addcontentsline{toc}{subsection}{plgyax}

\descr{ Identical to \code{plgxax}, except that arguments are flags for 
y axis.  See the description of \code{plgxax} for more detail.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plgzax, plhist, plgyax, API


\bname{plgzax(digmax, digits)}
\label{plgzax}
\findex{plgzax}
\addcontentsline{toc}{subsection}{plgzax}

\descr{ Identical to \code{plgxax}, except that arguments are flags for 
z axis.  See the description of \code{plgxax} for more detail.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plhist, pljoin, plgzax, API


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

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

\argu{ \code{n} (PLINT, input)}{Number of data points.}

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

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

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

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plinit, pljoin, plhist, API

\bname{plinit()}
\label{plinit}
\findex{plinit}
\addcontentsline{toc}{subsection}{plinit}

\descr{ Initializing the plotting package.  The program prompts for the
device keyword or number of the desired output device.  Hitting a RETURN in
response to the prompt is the same as selecting the first device.  
\code{plinit} will issue no prompt if either the device was specified
previously (via command line flag or the \code{plsdev} function), or if
only one device is enabled when PLplot is installed.  If subpages have
been specified, the output device is divided into \code{nx} by \code{ny}
sub-pages, each of which may be used independently.  If \code{plinit} is
called again during a program, the previously opened file will be
closed.  The subroutine \code{pladv} is used to advance from one subpage
to the next.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node pljoin, pllab, plhist, API


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

\descr{ Joins the point \code{(x1, y1)} to \code{(x2, y2)}.}

\argu{ \code{x1} (PLFLT, input)}{x coordinate of first point.}

\argu{ \code{y1} (PLFLT, input)}{y coordinate of first point.}

\argu{ \code{x2} (PLFLT, input)}{x coordinate of second point.}

\argu{ \code{y2} (PLFLT, input)}{y coordinate of second point.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node pllab, plline, pljoin, API


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

\descr{ Routine for writing simple labels. Use \code{plmtex} for more complex
labels.}

\argu{ \code{xlabel} (char *, input)}{Label for horizontal axis.}

\argu{ \code{ylabel} (char *, input)}{Label for vertical axis.}

\argu{ \code{tlabel} (char *, input)}{Title of graph.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plline, pllsty, pllab, API


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

\descr{ Draws \code{n-1} line segments joining points \code{(x[i], y[i])}.}

\argu{ \code{n} (PLINT, input)}{Number of points to join.}

\argu{ \code{x} (PLFLT *, input)}{Pointer to array with x coordinates of
points.}

\argu{ \code{y} (PLFLT *, input)}{Pointer to array with y coordinates of
points.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node pllsty, plmesh, plline, API


\bname{pllsty(n)}
\label{pllsty}
\findex{pllsty}
\addcontentsline{toc}{subsection}{pllsty}

\descr{ This sets the line style according to one of eight predefined patterns
(also see \code{plstyl}).}

\argu{ \code{n} (PLINT, input)}{Integer value between 1 and 8.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plmesh, plmtex, pllsty, API


\bnameCF{
plmesh(x, y, z, nx, ny, opt)}{\qquad(C)}{
plmesh(x, y, z, nx, ny, opt, mx)}{(Fortran)}

\label{plmesh}
\findex{plmesh}
\addcontentsline{toc}{subsection}{plmesh}

\descr{ Plots a surface mesh within the environment set up by \code{plw3d}.
The surface is defined by the two-dimensional array \code{z[][]}, the point
\code{z[i][j]} being the value of the function at \code{(x[i], y[j])}.  Note
that the points in arrays \code{x} and \code{y} do not need to be equally
spaced, but must be stored in ascending order.  The parameter \code{opt}
controls the way in which the surface is displayed.  For further details
\pxref{3-d Plots}.}

\argu{ \code{x} (PLFLT *, input)}{Pointer to set of x coordinate values at
which the function is evaluated.}

\argu{ \code{y} (PLFLT *, input)}{Pointer to set of y coordinate values at
which the function is evaluated.}

\argu{ \code{z} (PLFLT **, input)}{Pointer to a vectored two-dimensional
array with set of function values.}

\argu{ \code{nx} (PLINT, input)}{Number of \code{x} values at which function is
evaluated.}

\argu{ \code{ny} (PLINT, input)}{Number of \code{y} values at which function is
evaluated.}

\argu{ \code{opt} (PLINT, input)}{Determines the way in which the surface
is represented:

\begin{itemize}
\item
\code{1}: Lines are drawn showing \code{z} as a function of \code{x} for
each value of \code{y[j]}.

\item
\code{2}: Lines are drawn showing \code{z} as a function of \code{y} for
each value of \code{x[i]}.

\item
\code{3}: Network of lines is drawn connecting points at which function
is defined.
\end{itemize}
}

\argu{ \code{mx} (PLINT, input)}{Length of array in x direction, for plotting
subarrays (Fortran only).}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plmtex, plot3d, plmesh, API


\bname{plmtex(side, disp, pos, just, text)}
\label{plmtex}
\findex{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 \code{just}, and the position of the reference point relative to the
viewport is set by \code{disp} and \code{pos}.}

\argu{ \code{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
\code{b}: Bottom of viewport.

\item
\code{l}: Left of viewport, text written parallel to edge.

\item
\code{lv}: Left of viewport, text written at right angles to edge.

\item
\code{r}: Right of viewport, text written parallel to edge.

\item
\code{rv}: Right of viewport, text written at right angles to edge.

\item
\code{t}: Top of viewport.
\end{itemize}
}

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

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

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plot3d, plpage, plmtex, API


\bnameCF{
plot3d(x, y, z, nx, ny, opt, side)}{\qquad(C)}{
plot3d(x, y, z, nx, ny, opt, side, mx)}{(Fortran)}

\label{plot3d}
\findex{plot3d}
\addcontentsline{toc}{subsection}{plot3d}

\descr{ Plots a three dimensional surface plot within the environment set up
by \code{plw3d}.  The surface is defined by the two-dimensional array
\code{z[][]}, the point \code{z[i][j]} being the value of the function at
\code{(x[i], y[j])}.  Note that the points in arrays \code{x} and \code{y}
do not need to be equally spaced, but must be stored in ascending order.
The parameter \code{opt} controls the way in which the surface is
displayed.  For further details \pxref{3-d Plots}.} 

\argu{ \code{x} (PLFLT *, input)}{Pointer to set of x coordinate values at
which the function is evaluated.}

\argu{ \code{y} (PLFLT *, input)}{Pointer to set of y coordinate values at
which the function is evaluated.}

\argu{ \code{z} (PLFLT **, input)}{Pointer to a vectored two-dimensional
array with set of function values.}

\argu{ \code{nx} (PLINT, input)}{Number of \code{x} values at which function
is evaluated.}

\argu{ \code{ny} (PLINT, input)}{Number of \code{y} values at which function
is evaluated.}

\argu{ \code{opt} (PLINT, input)}{Determines the way in which the surface
is represented:

\begin{itemize}
\item
\code{1}: Lines are drawn showing \code{z} as a function of \code{x} for
each value of \code{y[j]}.

\item
\code{2}: Lines are drawn showing \code{z} as a function of \code{y} for
each value of \code{x[i]}.

\item
\code{3}: Network of lines is drawn connecting points at which function
is defined.
\end{itemize}
}

\argu{ \code{side} (PLINT, input)}{Flag to indicate whether or not ``sides''
should be draw on the figure.  If \code{side=0} no sides are drawn, otherwise
the sides are drawn.}

\argu{ \code{mx} (PLINT, input)}{Length of array in x direction, for plotting
subarrays (Fortran only).}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plpage, plpat, plot3d, API


\bname{plpage()}
\label{plpage}
\findex{plpage}
\addcontentsline{toc}{subsection}{plpage}

\descr{ Begins a new page.  For a file driver, the output file is opened if
necessary.  Advancing the page via \code{plclr} and \code{plpage} is useful
when a page break is desired at a particular point when plotting to
subpages.  Another use for \code{plclr} and \code{plpage} is when plotting
pages to different files, since you can manually set the file name (or file
handle) by calling \code{plsfnam} or \code{plsfile} after the call to
\code{plclr} (in fact some drivers may only support a single page per
file, making this a necessity).  One way to handle this case automatically
is to page advance via \code{pladv}, but enable familying (see
\code{plsfam}) with a small byte per file limit so that a new family
member file will be created on each page break.

Except for one of these circumstances, it is best to advance the page or
subpage simply by the call \code{pladv(0)}.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plpat, plpoin, plpage, API


\bname{plpat(nlin, inc, del)}
\label{plpat}
\findex{plpat}
\addcontentsline{toc}{subsection}{plpat}

\descr{ Sets the area fill pattern.  The pattern consists of 1 or 2 sets of
parallel lines with specified inclinations and spacings.  The arguments to
this routine are the number of sets to use (1 or 2) followed by two pointers
to integer arrays (of 1 or 2 elements) specifying the inclinations in tenths
of a degree and the spacing in micrometers.  (also see \code{plpsty})}

\argu{\code{nlin} (PLINT, input)}{Number of sets of lines making up the
pattern, either 1 or 2.}

\argu{\code{inc} (PLINT *, input)}{Pointer to array with \code{nlin} elements.
Specifies the line inclination in tenths of a degree.  (Should be between
-900 and 900).}

\argu{\code{del} (PLINT *, input)}{Pointer to array with \code{nlin} elements.
Specify the spacing in micrometers between the lines making up the pattern.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plpoin, plprec, plpat, API


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

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

\argu{ \code{n} (PLINT, input)}{Number of points to be marked.}

\argu{ \code{x} (PLFLT *, input)}{Pointer to array with set of x coordinate
values for the points.}

\argu{ \code{y} (PLFLT *, input)}{Pointer to array with set of y coordinate
values for the points.}

\argu{ \code{code} (PLINT, input)}{Code number for the symbol to be plotted.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plprec, plpsty, plpoin, API


\bname{plprec(set, prec)}
\label{plprec}
\findex{plprec}
\addcontentsline{toc}{subsection}{plprec}

\descr{ Sets the number of places after the decimal point in numeric labels.}

\argu{ \code{set} (PLINT, input)}{ If \code{set} is equal to 0 then PLplot
automatically determines the number of places to use after the decimal point
in numeric labels (like those used to label axes).  If \code{set} is 1 then
\code{prec} sets the number of places.}

\argu{ \code{prec} (PLINT, input)}{The number of characters to draw after the
decimal point in numeric labels.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plpsty, plptex, plprec, API


\bname{plpsty(n)}
\label{plpsty}
\findex{plpsty}
\addcontentsline{toc}{subsection}{plpsty}

\descr{ Select one of eight predefined area fill patterns to use (also see
\code{plpat}).}

\argu{ \code{n} (PLINT *, input)}{The desired pattern.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plptex, plschr, plpsty, API


\bname{plptex(x, y, dx, dy, just, text)}
\label{plptex}
\findex{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 \code{just}, the reference point is placed at world coordinates
\code{(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{ \code{x} (PLFLT, input)}{x coordinate of reference point of string.}

\argu{ \code{y} (PLFLT, input)}{y coordinate of reference point of string.}

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

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

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plschr, plsfam, plptex, API


\bname{plschr(def, scale)}
\label{plschr}
\findex{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{ \code{def} (PLFLT, input)}{The default height of a character in
millimeters, should be set to zero if the default height is to remain
unchanged.}

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsfam, plsfile, plschr, API


\bname{plsfam(fam, num, bmax)}
\label{plsfam}
\findex{plsfam}
\addcontentsline{toc}{subsection}{plsfam}

\descr{ Sets variables dealing with output file familying.  Does nothing if
familying not supported by the driver.  This routine, if used, must be
called before initializing PLplot.  See Section \ref{sec:family} for more
information.}

\argu{ \code{fam} (PLINT, input)}{Family flag (boolean).  If nonzero, 
familying is enabled.}

\argu{ \code{num} (PLINT, input)}{Current family file number.}

\argu{ \code{bmax} (PLINT, input)}{Maximum file size (in bytes) 
for a family file.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsfile, plsfnam, plsfam, API


\bname{plsfile(file)}
\label{plsfile}
\findex{plsfile}
\addcontentsline{toc}{subsection}{plsfile}

\descr{ Sets the current output file handle, if applicable.  If the file has
has not been previously opened and is required by the driver, the user will
be prompted for the file name.  This routine, if used, must be called before
initializing PLplot.}

\argu{ \code{file} (FILE *, input)}{File pointer.}

NOTE: cannot be called from Fortran.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsfnam, plsmaj, plsfile, API


\bname{plsfnam(fnam)}
\label{plsfnam}
\findex{plsfnam}
\addcontentsline{toc}{subsection}{plsfnam}

\descr{ Sets the current output file name, if applicable.  If the file name
has not been specified and is required by the driver, the user will be
prompted for it.  If using the X-windows output driver, this sets the
display name.  This routine, if used, must be called before initializing
PLplot.}

\argu{ \code{fnam} (char *, input)}{Pointer to file name string.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsmaj, plsmin, plsfnam, API


\bname{plsmaj(def, scale)}
\label{plsmaj}
\findex{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{ \code{def} (PLFLT, input)}{The default length of a major tick in
millimeters, should be set to zero if the default length is to remain
unchanged.}

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsmin, plsori, plsmaj, API


\bname{plsmin(def, scale)}
\label{plsmin}
\findex{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{ \code{def} (PLFLT, input)}{The default length of a minor tick in
millimeters, should be set to zero if the default length is to remain
unchanged.}

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsori, plspage, plsmin, API


\bname{plsori(ori)}
\label{plsori}
\findex{plsori}
\addcontentsline{toc}{subsection}{plsori}

\descr{ Sets the current orientation.  If \code{ori} is equal to zero
(default) then landscape is used (x axis is parallel to the longest edge of
the page), otherwise portrait is used.  This option is not supported by all
output drivers (in particular, most interactive screen drivers ignore the
orientation).  This routine, if used, must be called before initializing
PLplot.}

\argu{ \code{ori} (PLINT, input)}{Orientation value.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plspage, plsstrm, plsori, API


\bname{plspage(xp, yp, xleng, yleng, xoff, yoff)}
\label{plspage}
\findex{plspage}
\addcontentsline{toc}{subsection}{plspage}

\descr{ Sets the page configuration (optional).  Not all parameters
recognized by all drivers.  The X-window driver uses the length and offset
parameters to determine the window size and location.  This routine, if
used, must be called before initializing PLplot.}

\argu{ \code{xp} (PLINT *, output)}{ Number of pixels, x.}
\argu{ \code{yp} (PLINT *; output)}{ Number of pixels, y.}
\argu{ \code{xleng} (PLINT *, output)}{ Page length, x.}
\argu{ \code{yleng} (PLINT *, output)}{ Page length, y.}
\argu{ \code{xoff} (PLINT *, output)}{ Page offset, x.}
\argu{ \code{yoff} (PLINT *, output)}{ Page offset, y.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsstrm, plssym, plspage, API


\bname{plsstrm(strm)}
\label{plsstrm}
\findex{plsstrm}
\addcontentsline{toc}{subsection}{plsstrm}

\descr{ Sets the number of the current output stream.  The stream number
defaults to 0 unless changed by this routine.  The first use of this routine
must be followed by a call initializing PLplot (e.g. \code{plstar}).}

\argu{ \code{strm} (PLINT *, output)}{Pointer to current stream number.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plssym, plstar, plsstrm, API


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

\descr{ This sets up the size of all subsequent symbols drawn by
\code{plpoin} and \code{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{ \code{def} (PLFLT, input)}{The default height of a symbol in
millimeters, should be set to zero if the default height is to remain
unchanged.}

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plstar, plstart, plssym, API


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

\descr{ Initializing the plotting package.  The program prompts for the
device keyword or number of the desired output device.  Hitting a RETURN in
response to the prompt is the same as selecting the first device.  If only
one device is enabled when PLplot is installed, \code{plstar} will issue no
prompt.  The output device is divided into \code{nx} by \code{ny} sub-pages,
each of which may be used independently.  The subroutine \code{pladv} is used
to advance from one subpage to the next.}

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plstart, plstyl, plstar, API


\bname{plstart(device, nx, ny)}
\label{plstart}
\findex{plstart}
\addcontentsline{toc}{subsection}{plstart}

\descr{ Alternative to \code{plstar} for initializing the plotting package.
The device name keyword for the desired output device must be supplied as an
argument.  The device keywords are the same as those printed out by
\code{plstar}.  If the requested device is not available, or if the input
string is empty or begins with ``?'', the prompted startup of
\code{plstar} is used.  This routine also divides the output device into
\code{nx} by \code{ny} sub-pages, each of which may be used independently.  The
subroutine \code{pladv} is used to advance from one subpage to the next.}

\argu{ \code{device} (char *, input)}{Device name (keyword) of the required
output device.  If NULL or if the first character is a ``?'', the normal
(prompted) startup is used.}

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plstyl, plsvpa, plstart, API


\bname{plstyl(nels, mark, space)}
\label{plstyl}
\findex{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 \code{mark} and
\code{space} respectively.  The number of mark-space pairs is specified by
\code{nels}.  In order to return the line style to the default continuous
line,  \code{plstyl} should be called with \code{nels=0}.(also see
\code{pllsty})} 

\argu{ \code{nels} (PLINT, input)}{The number of \code{mark} and \code{space}
elements in a line.  Thus a simple broken line can be obtained by setting
\code{nels=1}.  A continuous line is specified by setting \code{nels=0}.}

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsvpa, plsxax, plstyl, API


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

\descr{ Alternate routine to \code{plvpor} for setting up the viewport.  This
routine should be used only if the viewport is required to have a definite
size in millimeters.  The routine \code{plgspa} is useful for finding out the
size of the current subpage.  }

\argu{ \code{xmin} (PLFLT, input)}{The distance of the left-hand edge of the
viewport from the left-hand edge of the subpage in millimeters.}

\argu{ \code{xmax} (PLFLT, input)}{The distance of the right-hand edge of the
viewport from the left-hand edge of the subpage in millimeters.}

\argu{ \code{ymin} (PLFLT, input)}{The distance of the bottom edge of the
viewport from the bottom edge of the subpage in millimeters.}

\argu{ \code{ymax} (PLFLT, input)}{The distance of the top edge of the
viewport from the top edge of the subpage in millimeters.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsxax, plsyax, plsvpa, API


\bname{plsxax(digmax, digits)}
\label{plsxax}
\findex{plsxax}
\addcontentsline{toc}{subsection}{plsxax}

\descr{ Returns current values of the \code{digmax} and \code{digits} flags
for the x axis.  \code{digits} is updated after the plot is drawn, so so this
routine should only be called \emph{after} the call to \code{plbox} 
(or \code{plbox3}) is complete.  \xref{Annotation} for more information.}

\argu{ \code{digmax} (PLINT, output)}{Variable to set the maximum
number of digits.  If nonzero, the printed label will be switched to a
floating point representation when the number of digits exceeds
\code{digmax}.}

\argu{ \code{digits} (PLINT, input)}{Field digits value.  Currently, changing
its value here has no effect since it is set only by \code{plbox} or
\code{plbox3}.  However, the user may obtain its value after a call to
\code{plbox} by calling \code{plgxax}.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsyax, plsym, plsxax, API


\bname{plsyax(digmax, digits)}
\label{plsyax}
\findex{plsyax}
\addcontentsline{toc}{subsection}{plsyax}

\descr{ Identical to \code{plsxax}, except that arguments are flags for 
y axis.  See the description of \code{plsxax} for more detail.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plsym, plszax, plsyax, API


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

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

\argu{ \code{n} (PLINT, input)}{Number of points to be marked.}

\argu{ \code{x} (PLFLT *, input)}{Pointer to array with set of x coordinate
values for the points.}

\argu{ \code{y} (PLFLT *, input)}{Pointer to array with set of y coordinate
values for the points.}

\argu{ \code{code} (PLINT, input)}{Code number for the symbol to be plotted.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plszax, pltext, plsym, API


\bname{plszax(digmax, digits)}
\label{plszax}
\findex{plszax}
\addcontentsline{toc}{subsection}{plszax}

\descr{ Identical to \code{plsxax}, except that arguments are flags for 
z axis.  See the description of \code{plsxax} for more detail.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node pltext, plvasp, plszax, API


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

\descr{ Sets an interactive device to text mode, used in conjunction with
\code{plgra} to allow graphics and text to be interspersed.  On a device
which supports separate text and graphics windows, this command causes
control to be switched to the text window.  This can be useful for printing
diagnostic messages or getting user input, which would otherwise interfere
with the plots.  The user \emph{must} switch back to the graphics window
before issuing plot commands, as the text (or console) device will probably
become quite confused otherwise.  If already in text mode, this command is
ignored.  It is also ignored on devices which only support a single window
or use a different method for shifting focus (also \pxref{plgra}).}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plvasp, plvpas, pltext, API


\bname{plvasp(aspect)}
\label{plvasp}
\findex{plvasp}
\addcontentsline{toc}{subsection}{plvasp}

\descr{ Sets the viewport so that the ratio of the length of the y axis to
that of the x axis is equal to \code{aspect}.}

\argu{ \code{aspect} (PLFLT, input)}{Ratio of length of y axis to length of x
axis.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plvpas, plvpor, plvasp, API


\bname{plvpas(xmin, xmax, ymin, ymax, aspect)}
\label{plvpas}
\findex{plvpas}
\addcontentsline{toc}{subsection}{plvpas}

\descr{ Device-independent routine for setting up the viewport.  The
viewport is chosen to be the largest with the given aspect ratio that fits
within the specified region (in terms of normalized subpage coordinates).
This routine is functionally equivalent to \code{plvpor} when a ``natural''
aspect ratio (0.0) is chosen.  Unlike \code{plvasp}, this routine reserves
no extra space at the edges for labels.}

\argu{ \code{xmin} (PLFLT, input)}{The normalized subpage coordinate of the
left-hand edge of the viewport.}

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

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

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

\argu{ \code{aspect} (PLFLT, input)}{Ratio of length of y axis to length of x
axis.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plvpor, plvsta, plvpas, API


\bname{plvpor(xmin, xmax, ymin, ymax)}
\label{plvpor}
\findex{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 \code{plsvpa} in order to create
a viewport of a definite size.}

\argu{ \code{xmin} (PLFLT, input)}{The normalized subpage coordinate of the
left-hand edge of the viewport.}

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

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

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plvsta, plw3d, plvpor, API


\bname{plvsta()}
\label{plvsta}
\findex{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.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plw3d, plwid, plvsta, API


\bname{plw3d(basex, basey, height, xmin, xmax, ymin, ymax, zmin, zmax, alt, az)}
\label{plw3d}
\findex{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 \code{xmin}, \code{xmax}, \code{ymin}, \code{ymax}, \code{zmin}
and \code{zmax} in user-coordinate space is mapped into a box of world
coordinate size \code{basex} by \code{basey} by \code{height} so that
\code{xmin} maps to \code{-basex/2}, \code{xmax} maps to \code{basex/2},
\code{ymin} maps to \code{-basey/2}, \code{ymax} maps to \code{basey/2},
\code{zmin} maps to \code{0} and \code{zmax} maps to \code{height}.  The
resulting world-coordinate box is then viewed by an observer at altitude
\code{alt} and azimuth \code{az}.  This routine must be called before
\code{plbox3} or \code{plot3d}.  For a more complete description of
three-dimensional plotting \pxref{3-d Plots}.}

\argu{ \code{basex} (PLFLT, input)}{The x coordinate size of the
world-coordinate box.}

\argu{ \code{basey} (PLFLT, input)}{The y coordinate size of the
world-coordinate box.}

\argu{ \code{height} (PLFLT, input)}{The z coordinate size of the
world-coordinate box.}

\argu{ \code{xmin} (PLFLT, input)}{The minimum user x coordinate value.}

\argu{ \code{xmax} (PLFLT, input)}{The maximum user x coordinate value.}

\argu{ \code{ymin} (PLFLT, input)}{The minimum user y coordinate value.}

\argu{ \code{ymax} (PLFLT, input)}{The maximum user y coordinate value.}

\argu{ \code{zmin} (PLFLT, input)}{The minimum user z coordinate value.}

\argu{ \code{zmax} (PLFLT, input)}{The maximum user z coordinate value.}

\argu{ \code{alt} (PLFLT, input)}{The viewing altitude in degrees above the
xy plane.}

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

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plwid, plwind, plw3d, API


\bname{plwid(width)}
\label{plwid}
\findex{plwid}
\addcontentsline{toc}{subsection}{plwid}

\descr{ Sets the pen width.}

\argu{ \code{width} (PLINT, input)}{The desired pen width.  The pen width
must be between 1 and a device dependent maximum value.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node plwind, , plwid, API


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

\descr{ Sets up the world coordinates of the edges of the viewport.}

\argu{ \code{xmin} (PLFLT, input)}{The world x coordinate of the
left-hand edge of the viewport.}

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

\argu{ \code{ymin} (PLFLT, input)}{The world y coordinate of the
bottom edge of the viewport.}

\argu{ \code{ymax} (PLFLT, input)}{The world y coordinate of the
top edge of the viewport.}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
