\c -*-latexinfo-*-
\c simple.tex
\c Geoffrey Furnish
\c 9 May 1994

\node Simple Use, Advanced Use, Introduction, Top
\chapter{Simple Use of PLplot}

This is the simple introduction to plotting with plplot.

\begin{menu}
* Simple Plot::		Plotting a Simple Graph
* Initializing::	PLplot
* Scales::		Defining Plot Scales and Axes
* Labelling::		The Graph
* Drawing::		The Graph
* Finishing::		Up...
* Error::		In case of...
\end{menu}

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

\node Simple Plot, Initializing, Simple Use, Simple Use
\section{Plotting a Simple Graph}
\cindex{Simple Graph}

We shall first consider plotting simple graphs showing the dependence of
one variable upon another.  Such a graph may be composed of several
elements:

\begin{itemize}
\item
A box which defines the ranges of the variables, perhaps with axes
and numeric labels along its edges.

\item
A set of points or lines within the box showing the functional
dependence.

\item
A set of labels for the variables and a title for the graph.
\end{itemize}

In order to draw such a graph, it is necessary to call at least four of
the PLplot functions:

\begin{enumerate}
\item
\code{plinit}, to initialize PLplot.

\item
\code{plenv}, to define the range and scale of the graph, and
draw labels, axes, etc.\refill

\item
One or more calls to \code{plline} or \code{plpoin} to draw lines or
points as needed.  Other more complex routines include
\code{plbin} and \code{plhist} to draw histograms, \code{plerrx} and
\code{plerry} to draw error-bars.\refill

\item
\code{plend}, to close the plot.
\end{enumerate}

More than one graph can be drawn on a single set of axes by making
repeated calls to the routines listed in item 3 above.  PLplot only needs
to be initialized once unless plotting to multiple output devices.\refill

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

\node Initializing, Scales, Simple Plot, Simple Use
\section{Initializing PLplot}
\cindex{Starting up}
\cindex{Initialization}

Before any actual plotting calls are made, a graphics program must call
\rou{plinit}, is the main initialization routine for PLplot.  It sets up
all internal data structures necessary for plotting and initializes the
output device driver.  If the output device has not already
been specified when \code{plinit} is called, a list of valid output
devices is given and the user is prompted for a choice.  Either the
device number or a device keyword is accepted.\refill

There are several routines affecting the initialization that must be
called \emph{before} \code{plinit}, if they are used.  The function
\rou{plsdev} allows you to set the device explicitly.  The function
\rou{plsdev} may be called to divide the output device plotting area
into several subpages of equal size, each of which can be used
separately.\refill

One advances to the next page (or screen) via \rou{pladv}.  If subpages
are used, this can be used to advance to the next subpage or to a
particular subpage.\refill

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

\node Scales, Labelling, Initializing, Simple Use
\section{Defining Plot Scales and Axes}

The function \code{plenv} is used to define the scales and axes for
simple graphs.  \code{plenv} starts a new picture on the next subpage
(or a new page if necessary), and defines the ranges of the variables
required.  The routine will also draw a box, axes, and numeric labels if
requested.  The syntax for \code{plenv} is:\refill

\c -------------------------------------------------------------------------
\name{plenv(xmin, xmax, ymin, ymax, just, axis)}

\argu{\code{xmin, xmax} (PLFLT, input)}{
The left and right limits for the horizontal axis.}

\argu{\code{ymin, ymax} (PLFLT, input)}{
The bottom and top limits for the vertical axis.}

\argu{\code{just} (PLINT, input)}{
This should be zero or one.  If \code{just} is one, the scales of the
x-axis and y-axis will be the same (in units per millimeter); otherwise
the axes are scaled independently.  This parameter is useful for
ensuring that objects such as circles have the correct aspect ratio in
the final plot.}

\argu{\code{axis} (PLINT, input)}{
\code{axis} controls whether a box, tick marks, labels, axes, and/or a
grid are drawn.

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

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

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

\item
\code{axis =  1}: In addition to box and labels, draw the two axes X = 0 and
Y = 0. \refill

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

\item
\code{axis = 10}: Logarithmic X axis, linear Y axis.

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

\item
\code{axis = 20}: Linear X axis, logarithmic Y axis.

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

\item
\code{axis = 30}: Logarithmic X and Y axes.
\end{itemize}
}
\namend
\c -------------------------------------------------------------------------

Note: Logarithmic axes only affect the appearance of the axes and their
labels, so it is up to the user to compute the logarithms prior to
passing them to \code{plenv} and any of the other routines.  Thus, if a
graph has a 3-cycle logarithmic axis from 1 to 1000, we need to set
\code{xmin} = \t{log10}(1) = 0.0, and \code{xmax} = \t{log10}(1000) =
3.0.\refill

For greater control over the size of the plots, axis labelling and tick
intervals, more complex graphs should make use of the functions
\rou{plvpor}, \rou{plvasp}, \rou{plvpas}, \rou{plwind}, \rou{plbox}, and
routines for manipulating axis labelling \rou{plgxax} through
\rou{plszax}.\refill

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

\node Labelling, Drawing, Scales, Simple Use
\section{Labelling the Graph}

The function \code{pllab} may be called after \code{plenv} to write
labels on the x and y axes, and at the top of the picture.  All the
variables are character variables or constants.  Trailing spaces are
removed and the label is centered in the appropriate field.  The syntax
for \code{pllab} is:\refill

\c -------------------------------------------------------------------------
\name{pllab(xlbl, ylbl, toplbl)}

\argu{\code{xlbl} (char *, input)}{
Pointer to string with label for the X-axis (bottom of graph).}

\argu{\code{ylbl} (char *, input)}{
Pointer to string with label for the Y-axis (left of graph).}

\argu{\code{toplbl} (char *, input)}{
Pointer to string with label for the plot (top of picture).}
\namend
\c -------------------------------------------------------------------------

More complex labels can be drawn using the function \rou{plmtex}.
For discussion of writing text in a plot \pxref{Text}, and for
more detailed discussion about label generation \pxref{Annotation}.\refill

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

\node Drawing, Finishing, Labelling, Simple Use
\section{Drawing the Graph}

PLplot can draw graphs consisting of points with optional error bars,
line segments or histograms.  Functions which perform each of these
actions may be called after setting up the plotting environment using
\code{plenv}.  All of the following functions draw within the box
defined by \code{plenv}, and any lines crossing the boundary are
clipped.  Functions are also provided for drawing surface and contour
representations of multi-dimensional functions.  \xref{Advanced Use} for
discussion of finer control of plot generation.\refill

\begin{menu}
* Points::		Drawing Points
* Lines::		Drawing Lines or Curves
* Text::		Writing Text
* Fills::		Area fills
* Complex::		More complex graphs
\end{menu}

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

\node Points, Lines, Drawing, Drawing
\subsection{Drawing Points}
\cindex{Point plotting}

\code{plpoin} and \code{plsym} mark out \code{n} points \code{(x[i],
y[i])} with the specified symbol.  The routines differ only in the
interpretation of the symbol codes.  \code{plpoin} uses an extended
ASCII representation, with the printable ASCII codes mapping to the
respective characters in the current font, and the codes from 0--31
mapping to various useful symbols.  In \code{plsym} however, the code is
a Hershey font code number.  Example programs are provided which display
each of the symbols available using these routines.\refill

\c -------------------------------------------------------------------------
\name{plpoin(n, x, y, code) \\
plsym(n, x, y, code)}

\argu{\code{n} (PLINT, input)}{
The number of points to plot.}

\argu{\code{x, y} (PLFLT *, input)}{
Pointers to arrays of the coordinates of the \code{n} points.}

\argu{\code{code} (PLINT, input)}{
Code number of symbol to draw.}
\namend
\c -------------------------------------------------------------------------

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

\node Lines, Text, Points, Drawing
\subsection{Drawing Lines or Curves}
\cindex{Line plotting}

PLplot provides two functions for drawing line graphs.  All lines are
drawn in the currently selected color, style and width.
\xref{Line Attributes} for information about changing these
parameters.\refill

\code{plline} draws a line or curve.  The curve consists of \code{n-1} line
segments joining the \code{n} points in the input arrays.  For single
line segments, \code{pljoin} is used to join two points.\refill

\c -------------------------------------------------------------------------
\name{plline(n, x, y)}

\argu{\code{n} (PLINT, input)}{
The number of points.}

\argu{\code{x, y} (PLFLT *, input)}{
Pointers to arrays with coordinates of the \code{n} points.}
\namend
\c -------------------------------------------------------------------------

\c -------------------------------------------------------------------------
\name{pljoin(x1, y1, x2, y2)}

\argu{\code{x1, y1} (PLFLT, input)}{
Coordinates of the first point.}

\argu{\code{x2, y2} (PLFLT, input)}{
Coordinates of the second point.}
\namend
\c -------------------------------------------------------------------------

\node Text, Fills, Lines, Drawing
\subsection{Writing Text on a Graph}
\cindex{Annotation}
\cindex{Writing Text}
\cindex{Labels}

\code{plptex} allows text to be written within the limits set by
\code{plenv}.  The reference point of a text string may be located
anywhere along an imaginary horizontal line passing through the string
at half the height of a capital letter.  The parameter \code{just}
specifies where along this line the reference point is located.  The
string is then rotated about the reference point through an angle
specified by the parameters \code{dx} and \code{dy}, so that the string
becomes parallel to a line joining \code{(x, y)} to \code{(x+dx,
y+dy)}.\refill

\c -------------------------------------------------------------------------
\name{plptex(x, y, dx, dy, just, text)}

\argu{\code{x, y} (PLFLT, input)}{
Coordinates of the reference point.}

\argu{\code{dx, dy} (PLFLT, input)}{
These specify the angle at which the text is to be printed.  The text is
written parallel to a line joining the points \code{(x, y)} to
\code{(x+dx, y+dy)} on the graph.}

\argu{\code{just} (PLFLT, input)}{
Determines justification of the string by specifying which point within
the string is placed at the reference point \code{(x, y)}.  This
parameter is a fraction of the distance along the string.  Thus if
\code{just = 0.0}, the reference point is at the left-hand edge of the
string.  If \code{just = 0.5}, it is at the center and if \code{just = 1.0},
it is at the right-hand edge.}

\argu{\code{text} (char *, input)}{
Pointer to the string of characters to be written.}
\namend
\c -------------------------------------------------------------------------

\node Fills, Complex, Text, Drawing
\subsection{Area Fills}
\cindex{Area fills}

Area fills are done in the currently selected color, line style, line
width and pattern style.

\code{plfill} fills a polygon.  The polygon consists of \code{n}
vertices which define the polygon.\refill

\c -------------------------------------------------------------------------
\name{plfill(n, x, y)}

\argu{\code{n} (PLINT, input)}{
The number of vertices.}

\argu{\code{x, y} (PLFLT *, input)}{
Pointers to arrays with coordinates of the \code{n} vertices.}
\namend
\c -------------------------------------------------------------------------

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

\node Complex, , Fills, Drawing
\subsection{More Complex Graphs}
\cindex{Complex Graphs}

Functions \rou{plbin} and \rou{plhist} are provided for drawing
histograms, and functions \rou{plerrx} and \rou{plerry} draw error bars
about specified points.  There are lots more too (\pxref{API}).\refill

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

\node Finishing, Error, Drawing, Simple Use
\section{Finishing Up}

Before the end of the program, \emph{always} call \rou{plend} to close
any output plot files and to free up resources.  For devices that have
separate graphics and text modes, \code{plend} resets the device to text
mode.\refill

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

\node Error, , Finishing, Simple Use
\section{In Case of Error}

If a fatal error is encountered during execution of a PLplot routine then
\rou{plexit} is called.  This routine prints an error message, does resource
recovery, and then exits.  The user may specify an error handler via
\rou{plsexit} that gets called before anything else is done, allowing
either the user to abort the error termination, or clean up
user-specific data structures before exit.\refill
