\chapter {Introduction}
\pagenumbering{arabic}
\section {The PLPLOT Plotting Library}

PLPLOT is a library of C functions for drawing graphs on a
variety of graphics devices using the Amiga personal computer.
The only assumption made about an
output device is that it is capable of displaying a 
line, so new graphics devices may be added readily by writing 
a small number of device-dependent routines. 

The library is Lattice C compatible and is accessible using the
Lattice C linker (blink).  The source code is standard C and should
be relatively easy to compile for use with other compiler/linker
packages.

This manual provides a description of the routines available to the 
programmer for producing graphical output. 
For most applications, the program can be device-independent, and the 
output can be directed to the appropriate graphics device at run-time. 
However, for specialized
applications, where the absolute size of a graph is important, it is
also possible to specify the plotting area in terms of absolute
coordinates (millimeters).

Many of the underlying concepts used in the PLPLOT subroutine package 
are based on ideas used in Tim Pearson's PGPLOT package originally 
written in VAX-specific Fortran-77.  Sze Tan of the University of
Auckland originally developed PLPLOT on an IBM PC, and subsequently
transferred it to a number of other machines.
Additional features were
added to allow three-dimensional plotting and better access to low-level
routines.  When I received PLPLOT from Sze Tan I ported it to a
Data General MV/20000 and added a few features as well.
I had been looking for a plotting package with
the features of PLPLOT for use on the Amiga.  
I do not have a FORTRAN compiler, so I rewrote PLPLOT in C and ported it
to the Amiga.

This document was originally written by Sze Tan.  I have edited it
so that it is applicable to the Amiga and the C programming language.

\section {Installing PLPLOT}
PLPLOT is distributed on a single floppy disk.  The disk (labelled
PLPLOT) contains the plotting library, some example programs, the source
code and
the documentation.

If you don't have a hard disk, then there is no installation procedure.
It might be wise to make backup copies of the floppy disks though.

If you have a hard disk and want to install PLPLOT on it
I recommend creating a :plplot/lib directory on your
harddisk and then copying the library there. The following commands will
do the trick.
\begin{verbatim}
makedir HDDISK:plplot/lib
copy plplot1:lib HDDISK:plplot/lib all
\end{verbatim}
Be sure to substitute the name of your own hard disk for {\tt HDDISK}
in the above commands.

\section {Linking Lattice C programs with PLPLOT}

If you don't have a hard disk or didn't install the library on it, then
a program can be compiled and linked with the library with the following
command:
\begin{verbatim}
lc -Lm+PLPLOT:lib/plplot.lib ProgramName
\end{verbatim}

If you have installed the PLPLOT library on a hard disk
in the recommended manner, then use the following command:
\begin{verbatim}
lc -Lm+HDDISK:plplot/lib/plplot.lib ProgramName
\end{verbatim}

Notice that the PLPLOT functions expect to be linked with the standard
Lattice math library.  You may want to create a new library that uses the
FFP routines or provides 68881 support.

\section {Devices Supported by PLPLOT on the Amiga}

At run time the user specifies whether the graphics should be drawn
on the Amiga's screen or stored in a device dependent file.  If the
Amiga screen is selected then a backdrop, borderless window is opened
on a high resolution, interlaced screen.  Two menus are available for
screen and graphics control.  When the window is first opened only
two menu selections are available.  These are the Interrupt selection
under the Graphics Control menu (Interrupt can also be selected by
typing CTRL-C) and the Screen to Back selection under the Screen
Control menu (Screen to Back can also be selected to by holding the
right Amiga key down and then hitting F).  The Screen to Back selection
will move the graphics screen behind any other screens you may have open.
The Interrupt selection will suspend any drawing operations.
After the Interrupt selection is made 
all other menu selections are enabled.  Under the Screen Control menu
the user can then select Screen to Back, Clear Screen, and Close Screen.
The Screen to Back selection has already been discussed.  The Clear
Screen and Close Screen operations can also 
be selected from the keyboard by
holding down the right Amiga key and typing either C or Q.  The Clear
Screen selection, as you've probably guessed, clears the screen.
The Close Screen selection closes the
screen, calls \rou{plend} and then calls the exit routine to end
program execution. The Close Screen selection does not return control
back to the user's main program.  It should be used only to gracefully
abort the program.
Under the Graphics Control menu the only enabled menu
selection is Continue (also selectable by hitting the RETURN key).
This will continue program execution at the point where it was
suspended.  When a program uses PLPLOT to create a sequence of graphs
then PLPLOT will automatically wait for the Continue selection before
erasing one graph and starting the next one.  After the last graph is
displayed (or the first one, if only one is being drawn) PLPLOT will
again wait for a Continue selection.  The screen will then be closed
and control returned to the user's program.  This is the preferred method
of closing the screen (as opposed to the Close Screen selection).

After one graph is complete, the user can move the Screen to Back to get
WorkBench access and
then use the GraphicDump (or similar) program to obtain hardcopy.
However, if you have a fairly high resolution printer
or plotter best results will be obtained if you use a specific
device driver.  
Three device drivers are supplied with PLPLOT. These drivers 
can be used as guidelines in writing your own drivers.
The supplied
drivers provide support for the following graphics languages:
\begin{itemize}
   \item HP LaserJet II.
   \item imPRESS,
   \item Tektronix,
\end{itemize}

The HP LaserJet II does not actually support any type of vector
graphics language.  Instead a bit map is created in memory and when
the graph is completed the bit map is written to a file (along
with some HP specific control sequences).  To keep the memory
requirements (for both the Amiga and LaserJet II)
low this driver only supports the 150 dot per inch mode of the laser
printer. The file sizes can be rather large if multiple graphs
are produced from a single main program.

Tektronix and imPRESS
devices do have vector drawing support and are the simplest type devices
to write drivers for.  The graphics commands are written to a file
on the fly, without the need for a bit map.  imPRESS is a page
description language for IMAGEN printers.
After the graphics
file is created just copy it to the appropriate device (do not send the
file to prt: use either ser: or par:).

\section{Adding Support for Other Devices}
If you know the fundamentals of C programming then
adding support for other devices should be relatively easy.
First, become familiar with the device.
Determine whether it
supports direct line drawing or raster graphics.  If it has
a line drawing mode then use either {\tt tektronix.c} 
or {\tt impress.c} (found in the src directory)
to guide you in creating the
new driver.  If only raster graphics (i.e.\ a bitmap device) are supported
then use {\tt laserjetii.c} as a guide.
You will also need to add the appropriate code to {\tt plstar.c} (also in
the src directory).  An examination of plstar.c should indicate
what changes have to be made.
A make file (LMKFILE) is provided in the root directory
of the PLPLOT disk to automate the process of updating
the library.  You will probably want to add the name of your driver to
this make file.

\section {Organization of this Manual}
The PLPLOT library has been designed so that it is easy to write programs
producing graphical output without having to set up large numbers of 
parameters. However, more precise control of the results may be necessary,
and these are accomodated by providing lower-level routines which change
the system defaults. In chapter \ref{simple}, the overall process of 
producing
a graph using the high-level routines is described. Chapter \ref{advanced}
discusses the underlying concepts of the plotting process and introduces
some of the more complex routines. The reference section of the manual,
chapter \ref{reference} is an alphabetical list of the user-accessible
PLPLOT functions with detailed descriptions.