This manual is intended for the Fortran programmer who wishes to write a program generating graphical output. For most applications, the program can be device-independent, and the output can be directed to the appropriate device at run time. The output device is described by a ``device specification,'' discussed below. The programmer can build a specific device specification into the program, but it is better to make this a parameter which the user of the program can supply.
All the examples in this manual use standard Fortran-77. PGPLOT itself is written mostly in standard Fortran-77, with a few non-standard, system-dependent subroutines.
Chapter 2 is tutorial: it presents a Fortran program for drawing a graph using the minimum number of PGPLOT subroutines, and explains what each of these subroutines does. After reading this chapter, you should be able to write your own PGPLOT program, although it may be helpful to refer to the individual subroutine descriptions in Appendix A.
The basic features of PGPLOT are introduced in Chapters 3, 4, and 5. Chapter 3 explains the positioning and scaling of plots on the page, Chapter 4 describes the basic (``primitive'') routines for drawing lines, writing text, drawing graph markers, and shading areas, and Chapter 5 describes the routines for changing the ``attributes'' of these primitives: color, line-style, line-width, text font, etc.
Chapter 6 describes some ``high level'' routines that use the primitive routines to build up more complicated pictures: e.g., function plots, histograms, bar charts, and contour maps.
Chapter 7 describes PGPLOT's capabilities for ``interactive'' graphics, whereby the user of the PGPLOT program can control its action with a cursor, joystick, mouse, etc.
There are seven appendices. Appendix A is a list of all the PGPLOT routines, with detailed instructions for their use. Appendix B shows the complete set of PGPLOT characters and symbols that can be used for annotating graphs. Appendix C is intended for those who want to call PGPLOT subroutines from a program written in C. Appendix D gives details of the devices supported by PGPLOT. Appendix E provides instructions for programmers who want to extend PGPLOT to support other devices. Appendix F provides installation instructions, and Appendix G gives some hints for porting PGPLOT to a new operating system.
libpgplot.ahas been installed in a standard location where the loader can find it. To compile, link, and run a graphics program
f77 -o example example.f -lpgplot exampleIn some installations, it may be necessary to include other libraries, such as the Xwindow library, and specify a directory to search for the PGPLOT library; e.g.
f77 -o example example.f -L /usr/local/pgplot -lpgplot -lX11 example
LINKcommand, so the following sequence of instructions suffices to compile, link, and run a graphics program
$ FORTRAN EXAMPLE $ LINK EXAMPLE $ RUN EXAMPLEOn other VMS computers, the automatic search of the graphics library may not occur. You will then need to include the graphics library explicitly by using a
LINKcommands like the following:
$ LINK EXAMPLE,PGPLOT_DIR:GRPSHR/LIBThe PGPLOT subroutines are not included in your
.EXEfile, but are fetched from a shareable image when you execute the
RUNcommand. This makes the
.EXEfile much smaller, and means that the program need not be relinked when changes are made to the graphics subroutines; but the
.EXEfile can only be run on a machine that has a copy of the shareable image and is running a compatible version of VMS. To make a transportable
.EXEfile, use the non-shared library as follows (the XLIB library is not required if your version of PGPLOT does not include an X-window driver):
$ LINK EXAMPLE,PGPLOT_DIR:GRPCKG/LIB,SYS$INPUT:/OPT SYS$SHARE:DECW$XLIBSHR.EXE/SHARE [ctrl-Z] $
A PGPLOT graphical output device is described by a ``device specification'' that consists of two parts, separated by a slash (/): the device name or file name, and the device type.
/), enclose the name in double quotation marks (
"). If the device name is omitted from the device specification, a default device is used, the default depending on the device type (see Appendix D). In Unix, device and file names are case-sensitive.
PGPLOT_TYPE). The device type is not case-sensitive: you can use uppercase or lowercase letters, or a mixture of the two.
/TEK(the logged-in terminal)
plot.ps/PS(in the current default directory)
plot.ps/VPS(the same, but in portrait orientation)
"/scr/tjp/plot.ps"/PS(in a specified directory)
In UNIX systems, environment variables can be defined using the shell. For the bash, bourne (sh), or korn (ksh) shell, use commands like the following:
PGPLOT_DIR="/usr/local/pgplot"; export PGPLOT_DIRFor the c-shell and tcsh, use
setenv PGPLOT_DIR "/usr/local/pgplot/"Note that the names of PGPLOT environment variables are specified using upper case characters, e.g.
In VMS systems, environment variables are ``logical names'' and can be
defined with the
$ DEFINE PGPLOT_DIR user_disk:[local.pgplot] $ DEASSIGN PGPLOT_DIRThe following environment variables affect all PGPLOT programs:
grfont.datand the color-name database is
rgb.txt. If this variable is undefined, or if the specified file does not exist in this directory, PGPLOT looks in the current default directory. e.g.
setenv PGPLOT_DIR /usr/local/lib/pgplot/
grfont.datin the directory specified by PGPLOT_DIR. e.g.
setenv PGPLOT_FONT /usr/local/pgplot/grfont.dat
rgb.txtin the directory specified by PGPLOT_DIR. The color-name database is only used by programs that call
PGSCRN, or when environment variable PGPLOT_BACKGROUND or PGPLOT_FOREGROUND is defined. e.g.
setenv PGPLOT_RGB /usr/local/pgplot/rgb.txt
PGBEG(or supplied by the user in response to the PGPLOT prompt) is a blank string, this device specification is used, e.g.
setenv PGPLOT_DEV /xwin
PGBEGconsists of a file name without a trailing slash (/) and device type, this device type is assumed. e.g.
setenv PGPLOT_TYPE ps
PGENV. The characters supplied are options for
PGBOX(in addition to those assumed by default by
PGENV, i.e., `BCNST'. Useful options include `G' to draw a grid, `V' to draw y-axis labels upright, `I' to draw axis tick marks outside the box instead of inside, `1' or `2' to change the numeric label style. e.g.
setenv PGPLOT_ENVOPT IVG
PGSCRNwith this name as argument immediately after the graphics device is opened. Color names are case-insensitive and embedded spaces are ignored. e.g.
setenv PGPLOT_FOREGROUND springgreen
PGSCRNwith this name as argument immediately after the graphics device is opened. On devices without a color lookup table, changing the background color only affects the color of elements explicitly drawn in color index 0. To ensure that the background of the entire view surface changes to the new color, it is also necessary to call
PGERASat the start of each page. e.g.
setenv PGPLOT_BACKGROUND slateblue
PGBBUFis called immediately after opening the graphics device, and
PGEBUFimmediately before closing it. It will have no effect on programs that already include these calls. On some devices, buffering output can lead to large improvements in speed, but enabling buffering may upset synchronization between graphical output and other program activity. e.g.
setenv PGPLOT_BUFFER yes
setenv PGPLOT_DEBUG yes