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.a
has been installed in a standard location where
the loader can find it. To compile, link, and run a graphics program
example.f
:
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
LINK
command, so
the following sequence of instructions suffices to compile, link, and
run a graphics program EXAMPLE.FOR
:
$ 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
LINK
commands like the following:
$ LINK EXAMPLE,PGPLOT_DIR:GRPSHR/LIBThe PGPLOT subroutines are not included in your
.EXE
file, but are
fetched from a shareable image when you execute the RUN
command.
This makes the .EXE
file much smaller, and means that the program need
not be relinked when changes are made to the graphics subroutines; but
the .EXE
file 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 .EXE
file, 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.
/XWINDOW
/TEK
(the logged-in terminal)
tta4/TEK
(VMS device _TTA4:
)
"/dev/tty6"/TEK
(Unix device tty6
)
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)
PGPLOT_
.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.
PGPLOT_DIR
, not
pgplot_dir
.
In VMS systems, environment variables are ``logical names'' and can be
defined with the DEFINE
or ASSIGN
command,
e.g.
$ DEFINE PGPLOT_DIR user_disk:[local.pgplot] $ DEASSIGN PGPLOT_DIRThe following environment variables affect all PGPLOT programs:
grfont.dat
and 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.dat
in the
directory specified by PGPLOT_DIR. e.g.setenv PGPLOT_FONT /usr/local/pgplot/grfont.dat
rgb.txt
in 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
PGBEG
consists 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
PGSCRN
with 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
PGSCRN
with 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 PGERAS
at the start of each
page. e.g. setenv PGPLOT_BACKGROUND slateblue
PGBBUF
is called immediately after opening the
graphics device, and PGEBUF
immediately 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