The PGPLOT Graphics Subroutine Library is a Fortran- or C-callable, device-independent graphics package for making simple scientific graphs. It is intended for making graphical images of publication quality with minimum effort on the part of the user. For most applications, the program can be device-independent, and the output can be directed to the appropriate device at run time.
The PGPLOT library consists of two major parts: a device-independent part and a set of device-dependent ``device handler'' subroutines for output on various workstations, terminals, image displays, dot-matrix printers, laser printers, and pen plotters. PGPLOT supports standard file formats such as PostScript and GIF.
PGPLOT itself is written mostly in standard Fortran-77, with a few non-standard, system-dependent subroutines. PGPLOT subroutines can be called directly from a Fortran-77 or Fortran-90 program. A C binding library (cpgplot) and header file (cpgplot.h) are provided that allow PGPLOT to be called from a C or C++ program; the binding library handles conversion between C and Fortran argument-passing conventions.
The examples in this manual show how PGPLOT can be used in both Fortran-77 and C programs.
PGPLOT is not public-domain software. The source code and documentation are copyrighted by California Institute of Technology, and may not be redistributed or placed on public Web servers without permission. The software is provided ``as is'' with no warranty.
Many people have contributed to PGPLOT over the years, and I thank all who have contributed code and device drivers or who have helped in debugging PGPLOT on a variety of systems. I am particularly grateful to the following for their major contributions: Klaus-Georg Adams, Scott Allendorf, Robert Deverill, C. T. Dum, Alan Fey, Karl Glazebrook, Diab Jerius, Chris Jacobs, Neil Killeen, Harry Lehto, Colin Lonsdale, Grant McIntosh, Massimo Manghi, Michael Michelsen, Jim Morgan, Pete Ratzlaff, Robin Sergeant, Phil Seeger, Sam Southard, Allyn Tennant, David Terrett, Peter Teuben, Jean-Marc Zucconi. I am especially grateful to my colleague Martin Shepherd, who is responsible for the X-window drivers, the Tcl/Tk widget driver, and the C binding.
Documentation for PGPLOT consists of three manuals:
For the latest version of PGPLOT, and additional information, see the PGPLOT Web site.
This manual is intended both as a tutorial introduction to PGPLOT and as a reference manual.
Chapter 2 is tutorial: it presents both a Fortran program and a C 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 Chapter 13.
Chapter 3 describes how to compile, link, and run a program that uses the PGPLOT library, such as the example program of Chapter 2.
The basic features of PGPLOT are introduced in Chapters 4, 5, 6, and 7:
Chapter 4 explains how to open and close graphical output files or devices, and introduces the primary routines for controlling and switching between devices.
Chapter 5 introduces the concepts of viewports and windows, and explains the positioning and scaling of plots on the page
Chapter 6 describes the basic (``primitive'') routines for drawing lines, writing text, drawing graph markers, and shading areas.
Chapter 7 describes the routines for changing the ``attributes'' of these primitives: color, line-style, line-width, text font, etc.
Chapters 8, 9, 10, and 11 describe more advanced features:
Chapter 8 gives additional information about drawing scientific graphs, in particular information about the routines for graph axes and annotation.
Chapter 9 describes the PGPLOT routines for drawing contour maps.
Chapter 10 describes the PGPLOT routines for manipulating ``images'' or ''pixel arrays.''
Chapter 11 describes PGPLOT's capabilities for ``interactive'' graphics, whereby the user of the PGPLOT program can control its action with a cursor or mouse, and explains how to produce animated graphics.
The remainder of the manual is a reference section:
Chapter 12 is an annotated list of all the PGPLOT subroutines, and is the place to look when you want to find out which subroutine to use to do something,
Chapter 13 is an alphabetical list of all the PGPLOT subroutines, with detailed instructions for their use.
Chapter 14 shows the complete set of PGPLOT characters and symbols that can be used for annotating graphs.
Chapter 15 provides additional information for those who want to call PGPLOT subroutines from a program written in C or C++. Many of the examples in the rest of the manual use Fortran terminology, and this chapter may be of help in translating Fortran concepts to C.
The examples in this manual use both Fortran and C. Color is used to distinguish the two languages. The individual subroutines are referred to by their Fortran names, which start with the letters PG and have a maximum length of six characters (set by the Fortran-77 standard). The subroutine names are written in upper case, although most Fortran compilers are not case-sensitive (e.g., PGOPEN). The limitation of six characters means that many of the subroutine names are far from mnemonic. C programs use the C binding for PGPLOT, in which the prefix PG is replaced by cpg and the names are written in lower case (e.g., cpgopen). C compilers are case sensitive. In most cases the argument lists are the same for both languages, but note syntactic differences: in C, character strings are enclosed in double quotation marks while in Fortran they are enclosed in single quotation marks; and output arguments must be passed by reference (pointer) in C (see Chapter 15).