Pgplot Manual

PGPLOT

GRAPHICS SUBROUTINE LIBRARY

T� J� Pearson

June ��

California Institute of TechnologyPasadena� California ��

��

Copyright c� �� by California Institute of Technology

PGPLOT� Version �� June ��Subroutine descriptions updated to Version ��D�

Please address comments on PGPLOT and this manual� including requests forcopies� bug reports� and requests for improvements� to the author�

Tim Pearson�

Astronomy Department�

Caltech ��

Pasadena ��

USA�

Telephone� � ��

INTERNET� tjp�astro�caltech�edu

Contents

� INTRODUCTION � � � � � � � � � � � � � � � � � � � � � � ��

PGPLOT � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

This Manual � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Using PGPLOT � � � � � � � � � � � � � � � � � � � � � � � � � ��

Graphics Devices � � � � � � � � � � � � � � � � � � � � � � � � � ��

Environment variables � � � � � � � � � � � � � � � � � � � � � � ��

� SIMPLE USE OF PGPLOT � � � � � � � � � � � � � � � � � � ��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

An Example � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Data Initialization � � � � � � � � � � � � � � � � � � � � � � � � ��

Starting PGPLOT � � � � � � � � � � � � � � � � � � � � � � � � ��

De�ning Plot Scales and Drawing Axes � � � � � � � � � � � � � � � ��

Labeling the Axes � � � � � � � � � � � � � � � � � � � � � � � � ��

Drawing Graph Markers � � � � � � � � � � � � � � � � � � � � � ��

Drawing Lines � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Ending the Plot � � � � � � � � � � � � � � � � � � � � � � � � � ��

Compiling and running the program � � � � � � � � � � � � � � � � ��

WINDOWS AND VIEWPORTS � � � � � � � � � � � � � � � ��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Selecting a View Surface � � � � � � � � � � � � � � � � � � � � � ��

De�ning the Viewport � � � � � � � � � � � � � � � � � � � � � � ��

De�ning the Window � � � � � � � � � � � � � � � � � � � � � � � ��

Annotating the Viewport � � � � � � � � � � � � � � � � � � � � � ��

Routine PGENV � � � � � � � � � � � � � � � � � � � � � � � � � ��

� PRIMITIVES � � � � � � � � � � � � � � � � � � � � � � � � � ��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Clipping � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Lines � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Graph Markers � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Text � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Area Fill � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

� ATTRIBUTES � � � � � � � � � � � � � � � � � � � � � � � � ��

iii

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Color Index � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Color Representation � � � � � � � � � � � � � � � � � � � � � � � ��

Line Style � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Line Width � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Character Height � � � � � � � � � � � � � � � � � � � � � � � � � ��

Character Font � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Fill�Area Style � � � � � � � � � � � � � � � � � � � � � � � � � � ��

� HIGHER�LEVEL ROUTINES � � � � � � � � � � � � � � � � ��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

XY�plots � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Histograms � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Functions of two variables � � � � � � � � � � � � � � � � � � � � � ��

� INTERACTIVE GRAPHICS � � � � � � � � � � � � � � � � � ��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

The Cursor � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Using the Cursor � � � � � � � � � � � � � � � � � � � � � � � � � ��

Bu�ering � � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

� METAFILES � � � � � � � � � � � � � � � � � � � � � � � � � ��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � ��

Creating Meta�les � � � � � � � � � � � � � � � � � � � � � � � � ��

Translating Meta�les � � � � � � � � � � � � � � � � � � � � � � � ��

A SUBROUTINE DESCRIPTIONS � � � � � � � � � � � � � � A��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � A��

Arguments � � � � � � � � � � � � � � � � � � � � � � � � � � � A��

Classi�ed List � � � � � � � � � � � � � � � � � � � � � � � � � � A��

Subroutine Synopses � � � � � � � � � � � � � � � � � � � � � � � A��

PGADVANCE � non�standard alias for PGPAGE � � � � � � � � � � � A�

PGASK � control new page prompting � � � � � � � � � � � � � � � A�

PGBBUF � begin batch of output �bu�er� � � � � � � � � � � � � � � A�

PGBEG � begin PGPLOT� open output device � � � � � � � � � � � � A��

PGBEGIN � non�standard alias for PGBEG � � � � � � � � � � � � � A��

PGBIN � histogram of binned data � � � � � � � � � � � � � � � � � A��

PGBOX � draw labeled frame around viewport � � � � � � � � � � � � A��

PGCONB � contour map of a �D data array� with blanking � � � � � � A��

PGCONS � contour map of a �D data array �fast algorithm� � � � � � � A��

iv

PGCONT � contour map of a �D data array �contour�following� � � � � A��

PGCONX � contour map of a �D data array �non�rectangular� � � � � � A��

PGCURS � read cursor position � � � � � � � � � � � � � � � � � � A��

PGCURSE � non�standard alias for PGCURS � � � � � � � � � � � � A��

PGDRAW � draw a line from the current pen position to a point � � � � A��

PGEBUF � end batch of output �bu�er� � � � � � � � � � � � � � � � A��

PGEND � terminate PGPLOT � � � � � � � � � � � � � � � � � � � A��

PGENV � set window and viewport and draw labeled frame � � � � � � A��

PGERRB � horizontal error bar � � � � � � � � � � � � � � � � � � A��

PGERRX � horizontal error bar � � � � � � � � � � � � � � � � � � A��

PGERRY � vertical error bar � � � � � � � � � � � � � � � � � � � � A��

PGETXT � erase text from graphics display � � � � � � � � � � � � � A��

PGFUNT � function de�ned by X � F�T�� Y � G�T� � � � � � � � � � A��

PGFUNX � function de�ned by Y � F�X� � � � � � � � � � � � � � � A��

PGFUNY � function de�ned by X � F�Y� � � � � � � � � � � � � � � A��

PGGRAY � gray�scale map of a �D data array � � � � � � � � � � � � A��

PGHI�D � cross�sections through a �D data array � � � � � � � � � � � A��

PGHIST � histogram of unbinned data � � � � � � � � � � � � � � � A��

PGIDEN � write username� date� and time at bottom of plot � � � � � � A��

PGLAB � write labels for x�axis� y�axis� and top of plot � � � � � � � � A��

PGLABEL � non�standard alias for PGLAB � � � � � � � � � � � � � A��

PGLCUR � draw a line using the cursor � � � � � � � � � � � � � � � A��

PGLDEV � list available device types � � � � � � � � � � � � � � � � A��

PGLEN � Find length of a string in a variety of units � � � � � � � � � A��

PGLINE � draw a polyline �curve de�ned by line�segments� � � � � � � A��

PGMOVE � move pen �change current pen position� � � � � � � � � � A��

PGMTEXT � non�standard alias for PGMTXT � � � � � � � � � � � � A��

PGMTXT � write text at position relative to viewport � � � � � � � � A��

PGNCUR � mark a set of points using the cursor � � � � � � � � � � � A��

PGNCURSE � non�standard alias for PGNCUR � � � � � � � � � � � A��

PGNUMB � convert a number into a plottable character string � � � � � A��

PGOLIN � mark a set of points using the cursor � � � � � � � � � � � A��

PGPAGE � advance to new page � � � � � � � � � � � � � � � � � � A��

PGPAP � change the size of the view surface ��paper size�� A��

PGPAPER � non�standard alias for PGPAP � � � � � � � � � � � � � A��

PGPIXL � draw pixels � � � � � � � � � � � � � � � � � � � � � � A��

PGPNTS � draw one or more graph markers � � � � � � � � � � � � � A��

PGPOINT � non�standard alias for PGPT � � � � � � � � � � � � � � A��

PGPOLY � �ll a polygonal area with shading � � � � � � � � � � � � A��

v

PGPT � draw one or more graph markers � � � � � � � � � � � � � � A��

PGPTEXT � non�standard alias for PGPTXT � � � � � � � � � � � � A��

PGPTXT � write text at arbitrary position and angle � � � � � � � � � A��

PGQCF � inquire character font � � � � � � � � � � � � � � � � � � A��

PGQCH � inquire character height � � � � � � � � � � � � � � � � � A��

PGQCI � inquire color index � � � � � � � � � � � � � � � � � � � � A��

PGQCOL � inquire color capability � � � � � � � � � � � � � � � � � A��

PGQCR � inquire color representation � � � � � � � � � � � � � � � � A��

PGQFS � inquire �ll�area style � � � � � � � � � � � � � � � � � � � A��

PGQINF � inquire PGPLOT general information � � � � � � � � � � � A��

PGQLS � inquire line style � � � � � � � � � � � � � � � � � � � � � A��

PGQLW � inquire line width � � � � � � � � � � � � � � � � � � � � A��

PGQPOS � inquire current pen position � � � � � � � � � � � � � � � A��

PGQVP � inquire viewport size and position � � � � � � � � � � � � � A��

PGQWIN � inquire window boundary coordinates � � � � � � � � � � A��

PGRECT � draw a rectangle� using �ll�area attributes � � � � � � � � � A��

PGRND � �nd the smallest �round� number greater than x � � � � � � A��

PGRNGE � choose axis limits � � � � � � � � � � � � � � � � � � � A��

PGSCF � set character font � � � � � � � � � � � � � � � � � � � � A��

PGSCH � set character height � � � � � � � � � � � � � � � � � � � A��

PGSCI � set color index � � � � � � � � � � � � � � � � � � � � � � A��

PGSCR � set color representation � � � � � � � � � � � � � � � � � � A��

PGSFS � set �ll�area style � � � � � � � � � � � � � � � � � � � � � A��

PGSHLS � set color representation using HLS system � � � � � � � � � A��

PGSLS � set line style � � � � � � � � � � � � � � � � � � � � � � � A��

PGSLW � set line width � � � � � � � � � � � � � � � � � � � � � � A��

PGSVP � set viewport �normalized device coordinates� � � � � � � � � A��

PGSWIN � set window � � � � � � � � � � � � � � � � � � � � � � A��

PGTBOX � Draw a box and optionally write HH MM SS labels � � � � A��

PGTEXT � write text �horizontal� left�justi�ed� � � � � � � � � � � � A��

PGUPDT � update display � � � � � � � � � � � � � � � � � � � � � A��

PGVPORT � non�standard alias for PGSVP � � � � � � � � � � � � � A��

PGVSIZ � set viewport �inches� � � � � � � � � � � � � � � � � � � A��

PGVSIZE � non�standard alias for PGVSIZ � � � � � � � � � � � � � A��

PGVSTAND � non�standard alias for PGVSTD � � � � � � � � � � � A��

PGVSTD � set standard �default� viewport � � � � � � � � � � � � � A��

PGWINDOW � non�standard alias for PGSWIN � � � � � � � � � � � A��

PGWNAD � set window and adjust viewport to same aspect ratio � � � A��

vi

B PGPLOT SYMBOLS � � � � � � � � � � � � � � � � � � � � � B��

C� INSTALLATION INSTRUCTIONS �VMS � � � � � � � � � C��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � C��

Restoring the Save Set � � � � � � � � � � � � � � � � � � � � � � C��

Logical Names � � � � � � � � � � � � � � � � � � � � � � � � � � C��

The Shareable Image � � � � � � � � � � � � � � � � � � � � � � � C��

Recompiling PGPLOT � � � � � � � � � � � � � � � � � � � � � � C��

Recompiling the Example Programs � � � � � � � � � � � � � � � � C��

Rebuilding the Documentation Files � � � � � � � � � � � � � � � � C��

Printing the Manual � � � � � � � � � � � � � � � � � � � � � � � C��

Adding a new PGPLOT routine � � � � � � � � � � � � � � � � � � C��

C� INSTALLATION INSTRUCTIONS �UNIX � � � � � � � � � C��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � C��

Basic Installation � � � � � � � � � � � � � � � � � � � � � � � � � C��

Advanced Installation � � � � � � � � � � � � � � � � � � � � � � � C��

Device Handlers � � � � � � � � � � � � � � � � � � � � � � � � � C��

Special Notes� Sun � � � � � � � � � � � � � � � � � � � � � � � � C��

Acknowledgments � � � � � � � � � � � � � � � � � � � � � � � � C��

D SUPPORTED DEVICES � � � � � � � � � � � � � � � � � � � D��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

Versatec � � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

PostScript printers � � � � � � � � � � � � � � � � � � � � � � � � D�

QMS Lasergra�x � � � � � � � � � � � � � � � � � � � � � � � � � D��

Printronix � � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

VT�� DEC REGIS terminals� � � � � � � � � � � � � � � � � � � D��

VAX Workstations � � � � � � � � � � � � � � � � � � � � � � � � D��

Sun Workstations � � � � � � � � � � � � � � � � � � � � � � � � D��

Grinnell � � � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

IVAS � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

Sigma ARGS � � � � � � � � � � � � � � � � � � � � � � � � � � D��

Tektronix �� D��

Tektronix �� D��

Retrographics � � � � � � � � � � � � � � � � � � � � � � � � � � D��

Null Device � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

Canon � � � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

Colorwriter �� Plotter � � � � � � � � � � � � � � � � � � � � � D��

Ikon � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

vii

Zeta � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � D��

E WRITING A DEVICE HANDLER � � � � � � � � � � � � � � E��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � E��

Device handler interface � � � � � � � � � � � � � � � � � � � � � � E��

Handler state � � � � � � � � � � � � � � � � � � � � � � � � � � E��

Summary of operations � � � � � � � � � � � � � � � � � � � � � � E��

Testing a new device handler � � � � � � � � � � � � � � � � � � � E��

F CALLING PGPLOT FROM A C PROGRAM � � � � � � � � F��

Introduction � � � � � � � � � � � � � � � � � � � � � � � � � � � F��

VMS � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � F��

Convex UNIX � � � � � � � � � � � � � � � � � � � � � � � � � � F��

viii

Chapter �

INTRODUCTION

�� PGPLOT

PGPLOT is a Fortran subroutine package for drawing simple scienti�cgraphs on various graphics display devices� It was originally developed foruse with astronomical data reduction programs in the Caltech Astronomydepartment�

This manual is intended for the Fortran programmer who wishes towrite a program generating graphical output� For most applications� theprogram can be device�independent� and the output can be directed to theappropriate device at run time� The output device is described by a �devicespeci�cation�� discussed below� The programmer can build a speci�c devicespeci�cation into the program� but it is better to make this a parameterwhich the user of the program can supply�

All the examples in this manual use standard Fortran�� PGPLOTitself is written mostly in standard Fortran�� with a few non�standard�system�dependent subroutines� At Caltech� it runs under the VAXVMS�Convex�UNIX� and Sun�UNIX operating systems�

�� This Manual

This manual is intended both as a tutorial introduction to PGPLOT andas a reference manual� The remainder of this chapter describes some fun�damentals how to include the PGPLOT library in your program� and thetypes of graphic devices that PGPLOT can use�

Chapter � is tutorial it presents a Fortran program for drawing a graphusing the minimum number of PGPLOT subroutines� and explains whateach of these subroutines does� After reading this chapter� you should beable to write your own PGPLOT program� although it may be helpful torefer to the individual subroutine descriptions in Appendix A�

The basic features of PGPLOT are introduced in Chapters �� and ��Chapter � explains the positioning and scaling of plots on the page� Chapter describes the basic ��primitive�� routines for drawing lines� writing text�drawing graph markers� and shading areas� and Chapter � describes the

�� INTRODUCTION

routines for changing the �attributes� of these primitives color� line�style�line�width� text font� etc�

Chapter � describes some �high level� routines that use the primitiveroutines to build up more complicated pictures e�g�� function plots� his�tograms� bar charts� and contour maps�

Chapter � describes PGPLOT�s capabilities for �interactive� graphics�whereby the user of the PGPLOT program can control its action with acursor� joystick� mouse� etc�

Chapter � describes the use of �meta�les�� A meta�le is a disk �le inwhich a device�independent representation of a graphics image can be stored�A translation program allows the image to be displayed on any supporteddevice�

There are six appendices� Appendix A is a list of all the PGPLOTroutines� with detailed instructions for their use� Appendix B shows thecomplete set of PGPLOT characters and symbols that can be used for an�notating graphs� Appendix C is intended for those who want to installPGPLOT on another machine� Appendix D gives details of the devicessupported by PGPLOT� Appendix E provides instructions for programmerswho want to extend PGPLOT to support other devices� Appendix F de�scribes how PGPLOT subroutines can be called from a program written inthe C language�

�� Using PGPLOT

In order to use PGPLOT subroutines� you will need to link your programwith the graphics subroutine library�

VAX�VMS On the Caltech Astronomy VAX computers� the graphicssubroutine library is scanned automatically by the LINK command� so thefollowing sequence of instructions su�ces to compile� link� and run a graphicsprogram EXAMPLE�FOR

� FORTRAN EXAMPLE

� LINK EXAMPLE

� RUN EXAMPLE

On other VMS computers� the automatic search of the graphics library maynot occur� You will then need to include the graphics library explicitly byusing a LINK commands like the following

� LINK EXAMPLE�PGPLOT�DIR�GRPSHR�LIB

INTRODUCTION ��

The PGPLOT subroutines are not included in your �EXE �le� but are fetchedfrom a shareable image when you execute the RUN command� This makesthe �EXE �le much smaller� and means that the program need not be re�linked when changes are made to the graphics subroutines� but the �EXE �lecan only be run on a machine that has a copy of the shareable image andis running a compatible version of VAXVMS� For more information� seeAppendix C�

Unix The following assumes that the PGPLOT library libpgplot�a hasbeen installed in a standard location where the loader can �nd it� To com�pile� link� and run a graphics program example�f

fc �o example example�f �lpgplot

example

Unlike the VMS version� the PGPLOT routines are included in the exe�cutable �le�

�� Graphics Devices

Graphics devices fall into two classes devices which produce a hardcopyoutput� usually on paper� and interactive devices� which usually display theplot on a TV monitor� Some of the interactive devices allow modi�cation tothe displayed picture� and some have a movable cursor which can be used asa graphical input device� There is also a �null device�� to which unwantedgraphical output can be directed� Hardcopy devices are not used interac�tively� One must �rst create a disk �le and then send it to the appropriatedevice with a print or copy command� Consult Appendix D �or your SystemManager� to determine the appropriate device�speci�c command�

A PGPLOT graphical output device is described by a �device speci�ca�tion� that consists of two parts� separated by a slash �� the device nameor �le name� and the device type�

Device name The device name or �le name is the name by which theoutput device is known to the operating system� For most hardcopy de�vices� this should be the name of a disk �le� while for interactive devices� itshould be the name of a device of the appropriate type� in both cases� thename should be speci�ed according to the syntax of the operating systemin use� If the device or �le name includes a slash �� enclose the name indouble quotation marks �� If the device name is omitted from the devicespeci�cation� a default device is used� the default depending on the devicetype �see Appendix D�� In Unix� device and �le names are case�sensitive�

�� INTRODUCTION

Device type The device type tells PGPLOT what sort of graphical de�vice it is� Appendix D lists the device types available at the time of writing�together with the names by which they are known to PGPLOT� If the de�vice type is omitted� a system�dependent default type is assumed �this isthe value of the �environment variable� PGPLOT�TYPE� and on Phobos andDeimos it is �Printronix�� The device type is not case�sensitive you canuse uppercase or lowercase letters� or a mixture of the two�

Examples �VMS�

Tektronix �� terminal TTA�TEK �device �TTA��

Grinnell image display �GRIN�

Disk �le� Printronix format SYS�SCRATCH�PLOT�DAT�PRIN�

Disk �le� Versatec format� with the output �le on a di�erent DECnet nodeDEIMOS��XPLOT�DAT�PRIN�

Disk �le in default format in default directory PGPLOT�LIS�

Examples �Unix�

Tektronix �� terminal �TEK �the logged�in terminal��

IVAS image display �IVAS�

Disk �le� Printronix format �scr�tjp�plot�dat�PRIN�

Disk �le in default format in default directory pgplot�lis�

�� Environment variables

The run�time behavior of PGPLOT can be modi�ed by de�ning one or moreenvironment variables� The variables have names which begin with PGPLOT��In VMS� they are logical names� in Unix� they are Unix environment vari�ables�

To set the value of a variable in VMS �DCL�

� DEFINE PGPLOT�ENVOPT VG

In Unix �csh�

setenv PGPLOT�ENVOPT VG

Quotation marks may be required around the value �double�quotes in VMS�single quotes in Unix� to prevent interpretation of special characters by thecommand interpreter�

To unset a variable in VMS or Unix

� DEASSIGN PGPLOT�ENVOPT

unsetenv PGPLOT�ENVOPT

INTRODUCTION ��

The following are some of the environment variables currently in use

� PGPLOT�ENVOPT this variable provides additional options for the PGENVsubroutine �see description in Appendix A��

� PGPLOT�FONT the name of the binary �le containing character font dig�itization� e�g�� PGPLOT�FONT � �usr�tjp�grfont�dat�

� PGPLOT�IDENT if this variable is de�ned �with any value�� the user nameand time are written at the lower right corner of the plot by routinePGEND �hardcopy devices only�� e�g�� PGPLOT�IDENT � YES�

� PGPLOT�TYPE the plot type to be used in PGPLOT when a device spec�i�cation omits the type� e�g�� PGPLOT�TYPE � QMS�

� PGPLOT�BUFFER controls bu�ering �see Chapter ��

Chapter �

SIMPLE USE OF PGPLOT

�� Introduction

This chapter introduces the basic subroutines needed to create a graph us�ing PGPLOT� by way of a concrete example� It does not describe all thecapabilities of PGPLOT� these are presented in later chapters�

A graph is composed of several elements a box or axes delineating thegraph and indicating the scale� labels if required� and one or more pointsor lines� To draw a graph you need to call at least four of the PGPLOTsubroutines

�� PGBEGIN� to start up PGPLOT and specify the device you want to ploton�

�� PGENV� to de�ne the range and scale of the graph� and draw labels� axesetc�

�� one or more calls to PGPOINT or PGLINE or both� or other drawing rou�tines� to draw points or lines�

� PGEND to close the plot�

To draw more than graph on the same device� repeat steps �� and �� Itis only necessary to call PGBEGIN and PGEND once each� unless you want toplot on more than one device�

This chapter presents a very simple example program to demonstratethe above four steps�

�� An Example

A typical application of PGPLOT is to draw a set of measured data pointsand a theoretical curve for comparison� This chapter describes a simpleprogram for drawing such a plot� in this case there are �ve data points

�� SIMPLE USE OF PGPLOT

and the theoretical curve is y � x�� Here is the complete Fortran code forthe program

PROGRAM SIMPLE

REAL XR�� YR��

REAL XS�� YS��

DATA XS��

DATA YS��

CALL PGBEGIN� ��

CALL PGENV� ��

CALL PGLABEL��x�� y�� A Simple Graph��

CALL PGPOINT��XS�YS��

DO � I��

XR�I� � ��I

YR�I� � XR�I��

� CONTINUE

CALL PGLINE�� XR�YR�

CALL PGEND

END

The following sections of this chapter describe how the program works� andthe resulting plot is shown in Figure ��

�� Data Initialization

We shall store the x and y coordinates of the �ve data points in arrays XSand YS� For convenience� this program de�nes the values in DATA statements�but a more realistic program might read them from a �le� Arrays XR andYR will be used later in the program for the theoretical curve�

REAL XR�� YR��

REAL XS�� YS��

DATA XS��

DATA YS��

SIMPLE USE OF PGPLOT ��

Figure �� Output from example program�

�� Starting PGPLOT

The �rst thing the program must do is to start up PGPLOT and select thegraphics device for output

CALL PGBEGIN� ��

Subroutine PGBEGIN has four arguments

�� The �rst argument is present for historical reasons� It should always beset to zero ��

�� The second argument is a character string which gives a �device spec�i�cation� for the interactive graphics device or disk �le for hardcopygraphics �see Chapter � and Appendix D�� This program makes use of aspecial shorthand feature of PGPLOT� however if this argument is setto �� the program will ask the user to supply the device speci�cationat run�time�

�� The last two arguments are described in x�� Usually they are bothset to �� as in this example�


�� De�ning Plot Scales and Drawing Axes

Subroutine PGENV starts a new picture and de�nes the range of variablesand the scale of the plot� PGENV also draws and labels the enclosing box andthe axes if requested� In this case� the x�axis of the plot will run from ��to �� and the y axis will run from �� to ��


PGENV has six arguments

�� the left and right limits for the x �horizontal� axis �real numbers� notintegers��

�� the bottom and top limits for the y �vertical� axis �also real numbers��

�� If this �integer� argument is �� the scales of the x�axis and y�axis �in unitsper inch� will be equal� otherwise the axes will be scaled independently�In this case we have not requested equal scales�

�� This argument controls whether an enclosing box� tick�marks� numericlabels� andor a grid will be put on the graph� The recommended valueis �� Some of the allowed values are

�� no annotation�

�� draw box only�

� draw box� and label it with coordinate values around the edge�

� in addition to the box and labels� draw the two axes �lines x � ��y � �� with tick marks�

� in addition to the box� labels� and axes� draw a grid at major in�crements of the x and y coordinates�

�� Labeling the Axes

Subroutine PGLABEL may �optionally� be called after PGENV to write identi�fying labels on the x and y axes� and at the top of the picture

CALL PGLABEL��x�� y�� A Simple Graph��

All three arguments are character variables or constants� any of them canbe blank ��

�� A label for the x�axis �bottom of picture��

�� A label for the y�axis �left�hand edge��

�� A label for the plot �top of picture��

SIMPLE USE OF PGPLOT ��

�� Drawing Graph Markers

Subroutine PGPOINT draws graph markers at one or more points on thegraph� Here we use it to mark the �ve data points

CALL PGPOINT��XS�YS��

If any of the speci�ed points fall outside the window de�ned in the call toPGENV� they will not be plotted� The arguments to PGPOINT are

�� The number of points to be marked �integer��

�� The x and y coordinates of the points �real arrays��

� The number of the symbol to be used to mark the points� In thisexample� we use symbol number � which is a circle with a central dot�The available symbols are shown in Chapter �

�� Drawing Lines

The following code draws the �theoretical curve� through the data points

DO � I��

XR�I� � ��I

YR�I� � XR�I��

� CONTINUE

CALL PGLINE�� XR�YR�

We compute the x and y coordinates at �� points on the theoretical curve�and use subroutine PGLINE to draw a curve through them� PGLINE joinsup the points with straight�line segments� so it is necessary to computecoordinates at fairly close intervals in order to get a smooth curve� Any lineswhich cross the boundary of the window de�ned in PGENV are �clipped� atthe boundary� and lines which lie outside the boundary are not drawn� Thearguments of PGLINE are like those of PGPOINT

�� The number of points de�ning the line �integer��

�� The x and y coordinates of the points �real arrays��

�� Ending the Plot

Subroutine PGEND must be called to complete the graph properly� otherwisesome pending output may not get sent to the device

CALL PGEND


�� Compiling and running the program

To compile the program and link it with the PGPLOT library� see Chapter ��For example� under VMS

� EDIT SIMPLE�FOR

��

� FORTRAN SIMPLE

� LINK SIMPLE

Under Unix

ed simple�f

��

fc �o simple simple�f �lpgplot

When you run the program� it will ask you to supply the graphics devicespeci�cation� Type in any allowed device speci�cation� or type a question�mark �� to get a list of the available device types� For example� if you areusing a VT�� terminal� type �VT the graph will appear on the terminalscreen�

If you want a hard copy� you can run the program again� and specify adi�erent device type� e�g�� SIMPLE�PLT�VERS to make a disk �le in Versatecformat� To obtain the hard copy� print the �le �but �rst check with yoursystem manager what the correct print command is� it is possible to wastea lot of paper by using the wrong command or sending a �le to the wrongsort of printer��

Chapter �

WINDOWS AND VIEWPORTS

�� Introduction

This chapter is concerned with positioning a graph on the screen or hardcopypage� and controlling its scale� In simple applications� the position and scaleof the graph are controlled more�or�less automatically by the routine PGENV�but in order to obtain complete control of positioning and scaling� it isnecessary to understand the concepts of the View Surface� theWindow� andthe Viewport� and two coordinate systems World Coordinates and DeviceCoordinates�

A simple PGPLOT picture might be a two�dimensional graph showingthe dependence of one variable on another� A typical graph has data points�represented by error bars or special markers such as dots or diamonds� possi�bly connected by lines� or perhaps plotted on the same scale as a theoreticalmodel drawn as a smooth curve� The graph must be labeled with two axesto indicate the coordinate scales�

The programmer must describe to PGPLOT the various elements of thegraph in terms of rectangular Cartesian coordinates� The only limitationon the coordinates is that they be represented as �oating�point �REAL��numbers� otherwise we are totally free to choose the meaning of the co�ordinates� For example� in a graph showing the temporal variation of aradio source� the abscissa �x�coordinate� might be Epoch �in years� and theordinate �y�coordinate� Flux Density �in Jy��

In accordance with common practice in graphics programming� thesecoordinates� chosen by the programmer� are termed world coordinates � PG�PLOT maps a selected rectangular region of the world�coordinate space�termed the window� onto a speci�ed rectangle �termed the viewport� onthe view surface �the screen of an interactive display or a sheet of paper ona hardcopy plotter�� The program must make calls to PGPLOT routines tode�ne both the window and the viewport� For complete descriptions of theroutines and their arguments� refer to Appendix A�

�� WINDOWS AND VIEWPORTS

�� Selecting a View Surface

The �rst thing a graphics program must do is to tell PGPLOT what deviceit is going to use� This is done by calling routine PGBEGIN� For example� tocreate a plot �le for the Versatec printer

CALL PGBEGIN � � �PLOTFILE�LIS�VERSATEC��

Equally important� when all plotting has been completed� it is necessary tocall PGEND to �ush any pending plot requests

CALL PGEND

Note that only one device can be used at a time� If PGBEGIN is called whilea plot is in progress� the old plot is closed and a new one is begun�

After calling PGBEGIN the program has access to a view surface� Forinteractive devices� this is the full screen of the device� For hardcopy devices�it is a standard page� usually ��x� � ��y� inches on a device used in�landscape� mode �e�g�� device types �VE and �QMS�� or ��x��y� inchesa device used in �portrait� mode �e�g�� device types �VV and �VQMS��

On some devices� it is possible to plot on a larger piece of paper thanthe standard page� see the description of routine PGPAPER� which must becalled immediately after PGBEGIN to change the size of the view surface� Thedi�erent devices di�er not only in the size of the view surface� but also inits aspect ratio �heightwidth�� PGPAPER can be called to ensure that a plothas the same aspect ratio no matter what device it is plotted on�

After completing a graph� it is possible to advance to a new page tostart a new graph �without closing the plot �le� by calling PGPAGE

CALL PGPAGE

This clears the screen on interactive devices� or gives a new piece of paperon hardcopy devices� It does not change the viewport or window�

The last two arguments of PGBEGIN �NX and NY� can be used to sub�divide the view surface into smaller pieces called sub�pages� each of whichcan then be used separately� The view�surface is divided into NX �hori�zontally� by NY �vertically� sub�pages� When the view surface has beensubdivided in this way� PGPAGE moves the plotter to the next sub�page� andonly clears the screen or loads a new piece of paper if there are no sub�pagesleft on the current page�

In addition to selecting the view surface� PGBEGIN also de�nes a defaultviewport and window� It is good practice� however� to de�ne the viewportand window explicitly as described below�

WINDOWS AND VIEWPORTS ��

�� De�ning the Viewport

A viewport is a rectangular portion of the plotting surface onto which thegraph is mapped� PGPLOT has a default viewport which is centered on theplotting surface and leaves su�cient space around it for annotation� Theapplication program can rede�ne the viewport by calling routine PGVPORT

or PGVSIZE�

PGVPORT de�nes the viewport in a device�independent manner� usinga coordinate system whose coordinates run from � to � in both x and y�This coordinate system is called normalized device coordinate space� Forexample� if we wish to divide the view surface into four quadrants and mapa di�erent plot onto each quadrant� we can de�ne a new viewport beforestarting each plot� PGVPORT has the format

CALL PGVPORT �XMIN� XMAX� YMIN� YMAX�

For example� to map the viewport onto the upper left quadrant of the viewsurface

CALL PGVPORT � � � ��

�Note that this does not leave room around the edge of the viewport forannotation��

PGVSIZE de�nes the viewport in absolute coordinates �inches�� it shouldonly be used when it is known how big the view surface is and a de�nite plotscale is required� The arguments are the same as for PGVPORT� but measuredin inches from the bottom left corner of the view surface� For example

CALL PGVSIZE ��

de�nes a rectangular viewport � by � inches� o�set �� inches from thebottom and left edges of the view surface�

PGVSTAND de�nes a standard viewport� the size of which depends on theparticular device being used� and on the current character size �it uses thewhole view surface excluding a margin of four character heights all around�

CALL PGVSTAND

This is the default viewport set up by PGBEGIN�

Note that the viewport must be de�ned before calling any routines thatwould actually generate a display� The viewport may� however� be changedat any time this will a�ect the appearance of objects drawn later in theprogram�

�� WINDOWS AND VIEWPORTS

�� De�ning the Window

The program de�nes the window by calling routine PGWINDOW� whose argu�ments specify the world�coordinate limits of the window along each coordi�nate axis� e�g�

CALL PGWINDOW ��

speci�es that the x�axis �epoch� is going to run �left to right� from �� to�� and the y�axis ��ux density� is going to run �bottom to top� from � to�� Jy� Note that the arguments are �oating�point numbers �Fortran REAL

variables or constants�� and require decimal points� If the order of eitherthe x pair or the y pair is reversed� the corresponding axis will point in theopposite sense� i�e�� right to left for x or top to bottom for y� PGPLOT usesthe window speci�cation to construct a mapping that causes the image ofthe window to coincide with the viewport on the view surface� Furthermore�PGPLOT �clips� lines so that only those portions of objects that lie withinthe window are displayed on the view surface�

Like the viewport� the window must be de�ned before drawing anyobjects� The window can be de�ned either before or after the viewport thee�ect will be the same� The default window� set up by PGBEGIN� has x limits�� and y limits ��

If the ratio of the sides of the window does not equal the ratio of thesides of the viewport� the mapping of the world coordinates onto the viewsurface results in an image whose shape is compressed in either x or y� Oneway to avoid this compression is to carefully choose the viewport to have thesame aspect ratio as the window� Routine PGWNAD can do this it de�nes thewindow and simultaneously adjusts the viewport to have the same aspectratio as the window� The new viewport is the largest that can �t inside theold one� and is centered in the old one�

�� Annotating the Viewport

For a simple graph� it is usually necessary to draw a frame around theviewport and label the frame with tick marks and numeric labels� This canbe done with the routine PGBOX� For our sample graph� the call might be

CALL PGBOX ��BCTN�� BCNST��

Another routine� PGLABEL� provides text labels for the bottom� left handside� and top of the viewport

CALL PGLABEL ��Epoch�� Flux Density �Jy��

�Variation of �C�� at � �� GHz��

WINDOWS AND VIEWPORTS ��

The �rst two arguments provide explanations for the two axes� the thirdprovides a title for the whole plot� Note that unlike all the other plottingroutines� the lines and characters drawn by PGBOX and PGLABEL are notclipped at the boundaries of the window� PGLABEL actually calls a moregeneral routine� PGMTEXT� which can be used for plotting labels at any pointrelative to the viewport�

The amount of space needed outside the viewport for annotation de�pends on the exact options speci�ed in PGBOX� usually four character heightswill be su�cient� and this is the amount allowed when the standard view�port �created by PGVSTAND� is used� The character height can be changedby using routine PGSCH�

�� Routine PGENV

Having to specify calls to PGPAGE� PGVPORT� PGWINDOW� and PGBOX is exces�sively cumbersome for drawing simple graphs� Routine PGENV �for PGplotENVironment� combines all four of these in one subroutine� using the stan�dard viewport� and a limited set of the capabilities of PGBOX� For example�the graph described above could be initiated by the following call

CALL PGENV ��

which is equivalent to the following series of calls

CALL PGPAGE

CALL PGVSTAND

CALL PGWINDOW ��

CALL PGBOX ��BCNST�� BCNST��

PGENV uses the standard viewport� The �rst four arguments de�ne theworld�coordinate limits of the window� The �fth argument can be � or ��it is �� PGENV calls PGWNAD instead of PGWINDOW so that the plot has equalscales in x and y� The sixth argument controls the amount of annotation�

Chapter �

PRIMITIVES

�� Introduction

Having selected a view surface and de�ned the viewport and the window�we are ready to draw the substance of the image that is to appear within theviewport� This chapter describes the most basic routines� called primitives�that can be used for drawing elements of the image� There are four di�erentsorts of primitive lines� graph�markers� text� and area �ll� Chapter � ex�plains how to change the attributes of these primitives� e�g�� color� line�style�text font� and Chapter � describes some higher�level routines that simplifythe composition of images that would require a large number of calls to theprimitive routines�

The primitive routines can be used in any combination and order afterthe viewport and window have been de�ned� They all indicate where theprimitive is to appear on the view surface by specifying world coordinates�See the subroutine descriptions in Appendix A for more details�

�� Clipping

The primitives are �clipped� at the edge of the viewport any parts of theimage that would appear outside the viewport are suppressed� The variousprimitives behave slightly di�erently� A line is clipped where it crossesthe edge of the viewport� A graph marker is plotted if the center �the pointmarked� lies within or on the edge of the viewport� otherwise it is suppressed�Text � which is usually used for annotation� is not clipped �except at the edgeof the view surface� A �lled area is clipped at the edge of the viewport�

�� PRIMITIVES

�� Lines

The primitive line�drawing routine is PGLINE� This draws one or more con�nected straight�line segments �generally called a polyline in computer graph�ics�� It has three arguments the number �N� of points de�ning the polyline�and two arrays �XPTS and YPTS� containing the world x and y�coordinates ofthe points� The polyline consists of N � � straight�line segments connectingpoints �� N � ��N

CALL PGLINE �N� XPTS� YPTS�

The two routines PGMOVE and PGDRAW are even more primitive than PG�

LINE� in the sense that any line graph can be produced by calling these tworoutines alone� In general� PGLINE should be preferred� as it is more modular�PGMOVE and PGDRAW are provided for those who are used to Calcomp�styleplotting packages� PGMOVEmoves the plotter �pen� to a speci�ed point� with�out drawing a line ��pen up�� It has two arguments the world�coordinatesof the required new pen position� PGDRAW moves the plotter �pen� from itscurrent position �de�ned by the last call of PGMOVE or PGDRAW� to a newpoint� drawing a straight line as it goes ��pen down�� The above call toPGLINE could be replaced by the following

CALL PGMOVE �XPTS�� YPTS��

DO I��N

CALL PGDRAW �XPTS�I�� YPTS�I��

END DO

�� Graph Markers

A Graph Marker is a symbol� such as a cross� dot� or circle� drawn on agraph to mark a speci�c point� Usually the symbol used will be chosento be symmetrical with a well�de�ned center� The routine PGPOINT drawsone or more graph markers �sometimes called a polymarker�� It has fourarguments the number �N� of points to mark� two arrays �XPTS and YPTS�containing the world x and y�coordinates of the points� and a number �NSYM�identifying the symbol to use

CALL PGPOINT �N� XPTS� YPTS� NSYM�

The symbol number can be �� to draw a dot of the smallest possible size�one pixel�� to draw any one of the symbols in Figure �� or ��to draw the corresponding ASCII character �the character is taken from thecurrently selected text font�� or � �� to draw one of the Hershey symbolsfrom Appendix B� The Fortran ICHAR function can be used to obtain theASCII value� e�g�� to use letter F

CALL PGPOINT �� ICHAR��F��

PRIMITIVES ��

Figure �� Standard Graph Markers�

�� PRIMITIVES

�� Text

The Text primitive routine is used for writing labels and titles on the im�age� It converts an internal computer representation of the text �ASCIIcodes� into readable text� The simplest routine for writing text is PGTEXT�which writes a horizontal character string starting at a speci�c �x� y� worldcoordinate position� e�g��

CALL PGTEXT �X� Y� �A text string��

PGTEXT is actually a simpli�ed interface to the more general primitive routinePGPTEXT� which allows one to change orientation and justi�cation of the text�e�g��

CALL PGPTEXT �X� Y� �� A text string��

writes the text at an angle of �� to the horizontal� centered at �x� y� �seeAppendix A��

Both PGTEXT and PGMTEXT require the position of the text string to bespeci�ed in world coordinates� When annotating a graph� it is usually moreconvenient to position the text relative to the edge of the viewport� ratherthan in world�coordinate space� The routine PGMTEXT �see Appendix A� isprovided for this� and PGLABEL provides a simple interface to PGMTEXT forthe normal job of annotating an �x� y� graph�

The appearance of text can be altered by specifying a number of at�tributes� described in the next chapter� In particular� the character size andcharacter font can be changed� Figure �� illustrates some of the possibili�ties�

To include one of the graph marker symbols in a text string� use theFortran CHAR function� e�g��

CALL PGTEXT �X� Y� �Points marked with ��CHAR��

The routine PGPTEXT �and all the PGPLOT routines which call it� e�g��PGTEXT� PGLABEL� allows one to include escape sequences in the text stringto be plotted� These are character�sequences that are not plotted� but areinterpreted as instructions to change font� draw superscripts or subscripts�draw non�ASCII characters �e�g�� Greek letters�� etc� All escape sequencesstart with a backslash character �� The following escape sequences arede�ned �the letter following the � may be either upper or lower case�

�u � start a superscript� or end a subscript�

�d � start a subscript� or end a superscript �note that �u and �dmust alwaysbe used in pairs��

PRIMITIVES ��

Figure �� Text examples�

�� PRIMITIVES

�b � backspace �i�e�� do not advance text pointer after plotting the previouscharacter��

�� backslash character ��

�A � �Angstr�om symbol ��A��

�gx � greek letter corresponding to roman letter x�

�fn � switch to Normal font ��

�fr � switch to Roman font ��

�fi � switch to Italic font ��

�fs � switch to Script font � ��

��n� � character number n �� to decimal digits�� the closing parenthesismay be omitted if the next character is neither a digit nor �� This makesa number of special characters �e�g�� mathematical� musical� astronomical�and cartographical symbols� available� See Appendix B for a list of availablecharacters�

Greek letters are obtained by �g followed by one of the following upper�case and lower�case letters

use A B G D E Z Y H I K L M N C O P R S T U F X Q W

for A B � � E Z H � I K � M N O P � T � X � �

or a b g d e z y h i k l m n c o p r s t u f x q w

for � � � � � � � � � � � � � � o � � ! " # $ % &

Use uppercase letters for uppercase Greek� lowercase for lowercase� Exam�ple �gh is �� lowercase �theta��

�� Area Fill

The Area Fill primitive allows the programmer to shade the interior of anarbitrary polygonal region� The appearance of the primitive is controlledby attributes �ll area style and color index �see Chapter �� An area isspeci�ed by the set of vertices of the polygon�

The routine PGPOLY is used to �ll an area� It has three arguments thenumber �N� of vertices de�ning the polygon� and two arrays �XPTS and YPTS�containing the world x and y�coordinates of the vertices

CALL PGPOLY �N� XPTS� YPTS�

If the polygon is not convex� it may not be obvious which points in theimage are inside the polygon� PGPLOT assumes that a point is inside thepolygon if a straight line drawn from the point to in�nity intersects an oddnumber of the polygon�s edges�

PRIMITIVES ��

For the special case of a rectangle with edges parallel to the coordinatesaxes� it is better to use routine PGRECT instead of PGPOLY� this routine willuse the hardware rectangle��ll capability if available� PGRECT has four argu�ments the �x� y� world coordinates of two opposite corners �note the orderof the arguments�

CALL PGRECT �X�� X�� Y�� Y��

Chapter �

ATTRIBUTES

�� Introduction

The appearance of the primitive elements of a graphical image �lines� graph�markers� text� and area��ll� can be changed by specifying primitive at�tributes� The attributes� and the corresponding routines for changing them�are

Color Index and Color Representation� PGSCI� PGSCR� and PGSHLS�

Line Style� PGSLS�

Line Width� PGSLW�

Character Height� PGSCH�

Character Font� PGSCF�

Fill�area Style� PGSFS�

The routines to change attributes can be freely intermixed with thePGPLOT drawing routines� Once an attribute has been changed by a callto the appropriate routine� it remains in e�ect for all subsequent plottinguntil it is changed again� In addition to the routines that set attributes�PGSxx� there are routines for determining the current value of each attribute�PGQxx�� These make it possible to write subroutines which change attributevalues temporarily but restore the old attributes before returning to thecalling program�

�� Color Index

This attribute a�ects all the primitives lines� graph�markers� text� andarea��ll� and is controlled by two subroutines PGSCI and PGSCR�

Devices di�er considerably in their ability to draw in more than onecolor� On most hardcopy devices� the default color is black on a whitebackground� while on most CRT devices� it is white �or green� on a blackbackground� Color is selected using an integer parameter called the colorindex� Color index � is the default color� and color index � is the backgroundcolor� The number of di�erent color indices available depends on the device�On most monochrome devices� only color indices � and � are available� while

�� ATTRIBUTES

some color CRT devices may permit color indices from � to �� On somemonochrome devices� color index can be used to select di�erent brightnesses�intensities��

Color index �� the background color� can be used to �erase� elementsfrom a picture by overwriting them with color index �� Note that not alldevices are capable of this e�g�� Tektronix storage�tube terminals and pen�plotters cannot erase part of a displayed picture�

To select a new color index for subsequent plotting� use routine PGSCI�Set Color Index��

Appendix D lists the capabilities of the devices for plotting in color andvariable intensity� The default color index is �� all devices accept this� Mostdevices also accept color index � �erase�� and several accept color index upto �� or more� The maximum color index is the number of di�erent colorsthat can be displayed at once� Some devices permit the assignment of colorsto color indices to be changed �by calling PGSCR� see below��

�� Color Representation

Each color index has an associated Color Representation� which de�nes theassociated color and intensity� Color Representation may be expressed bya set of three numbers� either the Hue� Lightness� and Saturation �H�L� S�components or the Red� Green� and Blue �R�G�B� components� �R�G�B�are quantities in the range �� with �� being maximum intensity� ifR � G � B the color is a shade of gray� In the �H�L� S� system� hue is acyclic quantity expressed as an angle in the range �� while L and S arein the range ��

Table �� shows how the color indices are de�ned when PGPLOT isstarted �not all are available on all devices�� The default assignments ofcolors to color indices can be changed with routine PGSCR� which permitsone to specify the �R�G�B� values for any color index� or PGSHLS� whichpermits one to specify the �H�L� S� values� Note that color�index �� thebackground color� can be rede�ned in this way�

The e�ect of PGSCR is device�dependent� One some devices� it will beignored� On others� �e�g�� Grinnell� VT�� it will change the color of lineswhich have already been drawn in the speci�ed color index� while on others�e�g�� pen plotters� it will only a�ect lines drawn after the call of PGSCR�

ATTRIBUTES ��

Table �� Default Color Representations

ColorIndex Color �H�L� S� �R�G�B�

� Black �background� �� White �default� �� Red �� Green � �� Blue �� Cyan �Green Blue� �� Magenta �Red Blue� �� Yellow �Red Green� �� Red Yellow �Orange� �� Green Yellow �� Green Cyan �� Blue Cyan �� Blue Magenta �� Red Magenta �� Dark Gray �� Light Gray ��

�� Unde�ned

�� Line Style

Line Style can be� e�g�� solid� dashed� or dotted� The attribute a�ects onlylines� not the other primitives� It is controlled by subroutine PGSLS� Thedefault line style is a full� unbroken line� To change the line style� use routinePGSLS� Line style is described by an integer code

� � full line�

� � long dashes�

� � dash�dot�dash�dot�

� dotted�

� � dash�dot�dot�dot�

�� Line Width

Line Width a�ects lines� graph�markers� and text� A thick�nibbed pen issimulated by tracing each line with multiple strokes o�set in the directionperpendicular to the line� The line width is speci�ed by the number ofstrokes� The default width is one stroke� and the maximum that may bespeci�ed is �� The exact appearance of thick lines is device�dependent!itdepends on the resolution of the device!but on hardcopy devices �e�g�� QMSLasergra�x� Versatec� PGPLOT attempts to make the line�width increment

�� ATTRIBUTES

equal to �� inches� Requesting a line�width of �� say� should give linesthat are approximately �� inch thick� To change the line width� useroutine PGSLW�

�� Character Height

Character Height a�ects graph�markers and text� Character height is speci��ed as a multiple of the default character height� the default character heightone�fortieth of the height or width of the view surface �whichever is less��To change the character height� use routine PGSCH�

�� Character Font

Character Font a�ects text only� Four fonts are available� The default font�� is simple and is the fastest to draw� the others should only be usedfor presentation plots on a high�resolution device �e�g�� Versatec or laserprinter�� To change the character font� use routine PGSCF� it is also possibleto change the font temporarily by using escape sequences �see x � �� Thefont is de�ned by an integer code

� � normal �simple� font �default��

� � roman font�

� � italic font�

� script font�

�� Fill Area Style

Fill�Area Style can be hollow �only the outline of the polygon is drawn�� orsolid� The attribute may be extended in future to allow hatching and otherpatterns� To change the �ll�are style� use routine PGSFS� The style is de�nedby an integer code

� � solid �ll �default��

� � hollow �outline only��

Chapter �

HIGHER�LEVEL ROUTINES

�� Introduction

This chapter describes a number of �high level� routines that simplify thecomposition of complicated graphical images� They include routines fordrawing graphs of one variable or function against another ��xy�plots��histograms� and display of two�dimensional data �functions of two variables��Rather than giving complete details of all the available routines� this chapterjust points out some of the ways that they can be used� See Appendix Afor details of the calling sequences�

�� XY plots

The basic technique for drawing xy�plots is described in Chapter �� whichshowed how to make scatter plots using graph markers produced by PGPOINTand line plots produced by PGLINE� Considerable variation in the appearanceof the graph can be achieved using the following techniques�

Attributes� Use di�erent attributes to distinguish di�erent datasets�Graph markers can be distinguished by choosing di�erent markers� di�erentcolors� or di�erent sizes �character height attribute�� Lines and curves canbe distinguished by line�style� color� or line�width�

Box parameters� If routine PGENV is replaced by calls to the more basicroutines �see x�� including PGBOX� considerable variety in the appearanceof the graph can be achieved� For example� one can suppress the tick marks�draw the tick marks projecting out of the box instead of into it� or draw agrid over the whole viewport� Note that PGBOX may be called many timesone might call it once to draw a grid using thin dotted lines� and again todraw the frame and tick marks using thick lines

CALL PGSLW��

CALL PGSLS��

CALL PGBOX��G�� G��

CALL PGSLW��

CALL PGSLS��

CALL PGBOX��ABCTSN�� ABCTSNV��

�� HIGHER�LEVEL ROUTINES

Note that in this example we have also speci�ed tick intervals explicitly� Ifthe horizontal axis is to represent an angle in degrees� it is convenient tochoose a tick interval that is a simple fraction of �� here we have a majortick interval of �� and a minor tick interval of ��

Steppedline plots� As an alternative to PGLINE� which �joins up thedots� using straight line segments� it is sometimes appropriate to use PG�BIN which produces a �stepped line plot� �sometimes misleadingly calleda histogram� with horizontal line segments at each data point and verticalline segments joining them� This is often used� for example� in displayingdigitized spectra�

Error bars� Graphs of real data often require the inclusion of error bars�The two routines PGERRX and PGERRY draw horizontal and vertical error bars�respectively� These routines are usually used in combination with PGPOINT�e�g�� to draw a set of points with �� error�bars

DO � I��YHI � YPTS�I� � �� ERR�I�

YLO � YPTS�I� � �� ERR�I�

CALL PGPOINT�� XPTS�I�� YPTS�I��

CALL PGERRY�� XPTS�I�� YLO� YHI� ��

� CONTINUE

Logarithmic axes� It is commonly required that the x�axis� the y�axis� or both� be logarithmic instead of linear� that is� one wishes to plotthe logarithm of the quantity instead of its actual value� PGPLOT doesn�tprovide any automatic mechanism to do this one has to adopt log� x andorlog� y instead of x and y as world�coordinates� i�e�� if the range of x is tobe � to �� choose as world�coordinate limits for the window log � � ��and log �� and supply the logarithms of x to PGPOINT and PGLINE�However� PGENV and PGBOX have options for labeling the axis logarithmically�if this option is used in our example� the axis will have labeled major tickmarks at �� and �� with logarithmically�spaced minor tick marksat �� etc�� An example may make this clearer

CALL PGENV��

CALL PGLABEL��Frequency� �gn �GHz��

� �Flux Density� S�d�gn�u �Jy��

DO � I��

XPTS�I� � ALOG� �FREQ�I��YPTS�I� � ALOG� �FLUX�I��

� CONTINUE

CALL PGPOINT�� XPTS� YPTS� ��

HIGHER�LEVEL ROUTINES ��

This is a fragment of a program to draw the spectrum of a radio source�which is usually plotted as a log�log plot of �ux density v� frequency� It�rst calls PGENV to initialize the viewport and window� the AXIS argumentis �� so both axes will be logarithmic� The x�axis �frequency� �� runs from�� to �� GHz� the y�axis ��ux density� S�� runs from �� to �� Jy� Notethat it is necessary to specify the logarithms of these limits in the call toPGENV� The penultimate argument requests equal scales in x and y so thatslopes will be correct� The program then marks �� data points� supplyingthe logarithms of frequency and �ux density to PGPOINT�

�� Histograms

The routine PGHIST draws a histogram� that is� the frequency distributionof measured values in a dataset� Suppose we have �� measurements of aquantity �the sky brightness temperature at �� GHz� say� in mK� stored inFortran array VALUES� The following program�fragment draws a histogramof the distribution of these values in the range �� to �� using �� bins �sothat each bin is �� K wide� the �rst running from �� to �� the secondfrom �� to �� etc��

DO � I��

VALUES�I� � ��

� CONTINUE

CALL PGHIST�� VALUES� � � ��

CALL PGLABEL��Temperature �K��

� �Number of measurements��

� �Sky Brightness at � GHz� �

The histogram does not depend on the order of the values within the array�

�� Functions of two variables

A function of two variables� f � f�x� y�� really needs a three�dimensionaldisplay� PGPLOT does not have any three�dimensional display capability� butit provides three methods for two�dimensional display of three�dimensionaldata�

�� HIGHER�LEVEL ROUTINES

Contour maps� In a contour map of f�x� y�� the world�coordinates arex and y and the contours are lines of constant f � The PGPLOT contouringroutines �PGCONT and PGCONS� require the input data to be stored in a two�dimensional Fortran array F� with element F�I�J� containing the value ofthe function f�x� y� for a point �xi� yj�� Furthermore� the function must besampled on a regular grid the �x� y� coordinates corresponding to �I�J�

must be related to I and J by

x � a bI cJ�

y � d eI fJ�

The constants a� b� c� d� e� f are supplied to PGCONT in a six�element Fortranarray� The other input required is an array containing the contour values�i�e�� the constant values of f corresponding to each contour to be drawn�In the following example� we assume that values have been assigned to theelements of array F� We �rst �nd the maximum and minimum values ofF� and choose �� contour levels evenly spaced between the maximum andminimum

REAL F�� ALEV�� TR��

FMIN � F��

FMAX � F��

DO � I��

DO � J��

FMIN � MIN�F�I�J��FMIN�

FMAX � MAX�F�I�J��FMAX�

� CONTINUE

� CONTINUE

DO I��

ALEV�I� � FMIN � �I��FMAX�FMIN��

CONTINUE

Next� we choose a window and viewport� and set up an array TR contain�ing the � constants in the transformation between array indices and worldcoordinates� In this case� the transformation is simple� as we want x � I�y � J


TR��

TR��

TR��

TR��

TR��

TR��

HIGHER�LEVEL ROUTINES ��

Finally� we call PGCONT� actually� we call it twice� to draw the �rst �vecontours in color index � �red� and the remaining � in color index � �green�

CALL PGSCI��

CALL PGCONT�F�� ALEV��TR�CALL PGSCI��

CALL PGCONT�F�� ALEV��TR�

Normally PGCONT is preferable to PGCONS� See the description in Appendix Afor suggestions as to when PGCONS should be used�

Grayscale plots� The routine PGGRAY is used in a similar way to PG�CONT� Instead of drawing contours� it shades the interior of the viewport�the intensity of shading representing the value of the function at each point�The exact appearance of the resulting �image� is device�dependent� Onsome devices� PGGRAY does the shading by drawing many dots� so it can bevery slow�

Cross sections� Routine PGHI�D draws a series of cross�sections througha two�dimensional data array� Each cross�section �hides� those that appearbehind it� giving a three�dimensional e�ect� See Appendix A for details�

Chapter �

INTERACTIVE GRAPHICS

�� Introduction

The previous chapters have described how to produce a static graphical im�age if the same program is run twice with the same input parameters� thesame image will result� An interactive program allows the user to controlthe behavior of the program with a graphical input device� PGPLOT sup�ports a limited interactive capability on devices with a cursor for graphicalinput �e�g�� Grinnell� VT�� terminal� some Tektronix terminals� VT� �Retrographics terminal�� The capabilities are necessarily limited by the aimto keep PGPLOT device�independent�

�� The Cursor

Some of the graphics devices supported by PGPLOT have a graphics cursor�This appears on the view surface as a plus sign� a cross�hair� or a diamond�and can be moved around the view surface with a joy�stick� mouse� or track�ball attached to the graphics device� If the hardware does not provide thismechanism� PGPLOT allows the user to move the cursor using the arrowkeys on his terminal� See Appendix D for instructions for using the cursoron a speci�c device�

�� Using the Cursor

The basic routine for cursor input is PGCURSE� This routine enables thecursor on the selected device� positions it at a speci�ed location within theviewport� and allows the user to move it� When the user has positioned thecursor� he types a key on his terminal� PGCURSE returns the cursor position�in world coordinates� and the character that was typed�

In addition� PGPLOT provides three higher�level routines for cursorinput PGOLIN� PGNCURSE� and PGLCUR� These three routines require thatthe device has erase capability�

�� INTERACTIVE GRAPHICS

PGOLIN allows the user to specify a set of points within the viewport�with the capability of correcting mistakes� Interactive commands �singlecharacters "A� D� or X# typed on the keyboard� allow the user to add a pointat the current cursor position� delete the last�entered point� or exit fromthe subroutine� The world�coordinates of the entered points are returned tothe calling program� The following program fragment illustrates the use ofPGOLIN� the user supplies NPT �up to �� points with world�coordinates X��and Y�� and the program then shades the polygon de�ned by these pointsby calling PGPOLY

INTEGER NPT

REAL X�� Y��

��

WRITE �� Use the cursor to draw a polygon�WRITE �� Type A to add point� D to delete� X to exit�

NPT �

CALL PGOLIN �� NPT� X� Y� �

IF �NPT�GE�� CALL PGPOLY �NPT� X� Y�

PGNCURSE is similar to PGOLIN� but the points are sorted into increasingorder of x before being returned to the calling program� In addition� thedelete command deletes the point nearest to the cursor� rather than thelast�entered point� It can be used� for example� to allow the user to supplya set of points to represent the continuum level on a spectrum�

PGLCUR is similar to PGOLIN but instead of using a graph marker to markeach entered point it draws a polyline through them�

�� Bu�ering

By default� PGPLOT ensures that the image seen on the view surface isup to date at all times� that is� each PGPLOT subroutine updates theimage before returning control to the calling program� To improve e�ciency�PGPLOT can save instructions for controlling the graphics device in a bu�er�and only send them to the device when the bu�er is �lled up� This meansthat at any given moment� the image displayed on the screen may not becompletely up to date� This can be a problem in an interactive program�where� for example� the user has to tell the program what to do next based onhis interpretation of the current display� Three PGPLOT routines �PGBBUF�PGEBUF� and PGUPDT� are provided for controlling the bu�ering of output�All three routines have no arguments�

The routine PGBBUF causes PGPLOT to begin saving graphical outputin a bu�er� The output is saved until �� a matching PGEBUF call is made�or �� the bu�er �lls up� or �� the bu�er is emptied by a call to PGUPDT�

INTERACTIVE GRAPHICS ��

or � � PGEND is called� The routine PGEBUF stops bu�ering and causes thebu�ered commands to be sent to the output device� Calls to PGBBUF andPGEBUF should always be paired� PGBBUF increments an internal counter�while PGEBUF decrements this counter and �ushes the bu�er to the outputdevice when the counter drops to zero� This allows a subroutine to turn onand turn o� bu�ering without disturbing any bu�ering that may have beenestablished by the calling program�

Routine PGUPDT empties the bu�er created by PGBBUF� but it does notalter the internal counter� The routine should be called when it is essentialthat the display be completely up�to�date �before interaction with the user�for example� but it is not known if output is being bu�ered�

Usually output is not bu�ered� this is the default state established byPGBEGIN� The default behavior can be changed� however� by de�ning anenvironment variable PGPLOT�BUFFER �see Chapter �� If this variable isde�ned� with any value� PGBEGIN will start bu�ering output �by callingPGBBUF��

The following example shows how routine PGLABEL might be imple�mented in terms of routine PGMTEXT

SUBROUTINE PGLABEL �XLBL� YLBL� TOPLBL�

CHARACTER�� XLBL� YLBL� TOPLBL

CALL PGBBUF

CALL PGMTEXT��T�� TOPLBL�

CALL PGMTEXT��B�� XLBL�

CALL PGMTEXT��L�� YLBL�

CALL PGEBUF

END

The calls to PGBBUF and PGEBUF ensure that the output generated by thethree calls to PGMTEXT is bu�ered �i�e�� sent to the output device as a singlecommand instead of three separate ones�� If bu�ering is already enabled bythe program which calls PGLABEL� the calls to PGBBUF and PGEBUF have noe�ect�

Chapter

METAFILES

�� Introduction

A graphics meta�le is a disk �le in which a device�independent represen�tation of a graphics image can be stored� Such a �le cannot be displayeddirectly on a graphics device� but must �rst be translated into the com�mands appropriate for the speci�c device using a meta�le translator� Thismay seem like an unnecessary complication� when PGPLOT can create thedevice�speci�c commands directly� but it has some advantages� Meta�lescan be used� for example� to transfer pictures between two computing sites�they are usually smaller than the corresponding device�speci�c �les� or forarchiving pictures� It is sometimes convenient to make a program generatea meta�le rather than a device�speci�c �le so that one can� for example�take a �quick look� at the picture on an interactive display before makinghard copies� One may not know what hard�copy devices will be availablewhen the program runs for example� if it turns out after your ��hour batchjob has �nished that the Versatec printer has broken� it is nice to be able tosend the plot to some other device without re�running the batch job�

The meta�les generated by PGPLOT follow the �GSPC Meta�le Pro�posal� described in Computer Graphics �A� C� M�� volume �� number ��August ��

At present� meta�les are available only in the VMS version of PGPLOT�not in the UNIX versions�

�� Creating Meta�les

Meta�les may be created using PGPLOT in the same way that any otherplot �le is created the device speci�cation consists of a disk �le nameand a device type �FILE� for example PLOT��GMF�FILE� The default �letype if none is speci�ed is �GMF �for Graphics Meta File�� Programs whichmight generate meta�le output should not make any assumptions about thephysical scale of the picture� the scale will vary depending on what devicethe picture is ultimately plotted on�

�� METAFILES

�� Translating Meta�les

In order to generate graphics output from a meta�le� one must use aMeta�leTranslator to interpret the device independent meta�le commands� TheMeta�le Translator �GMFPLOT� provided with PGPLOT uses the PG�PLOT subroutines to generate the device�speci�c output thus a meta�lemay be displayed on any of the devices supported by PGPLOT� �A meta�lemay even be translated into another meta�le� but this is not very useful�� Touse GMFPLOT� �rst de�ne a command PLOT� say� as follows� this de�nitionmay be included in your LOGIN�COM �le if you make extensive use of it

� PLOT �� PGPLOT�DIR�GMFPLOT

The PLOT command takes two arguments the name of the input meta�le�and the device speci�cation for the output� The following sample commandsdisplay a meta�le on a Grinnell and on a Versatec printer

� PLOT PLOT��GMF �GR

� PLOT PLOT�� DEIMOS��LVA ��VE

Again� the default �le type for the meta�le is �GMF�

At present� it is not possible to edit the meta�le before display� This isa facility which might be added one day� Nor is it possible to change thescale or aspect ratio �ratio of heightwidth of the display surface�� WhenPGPLOT generates a meta�le� it does not know the size or shape of thedisplay surface that it will ultimately be plotted on� as it has to makesome assumption� it assumes that the surface will be square� The meta�letranslator displays the meta�le in the largest square available on the outputdevice� Thus a plot which is sent directly to a terminal may not look exactlythe same as one that is stored in a meta�le and subsequently displayed onthe terminal� Future enhancements may allow one to specify the scale andaspect ratio of the meta�le when it is generated�

Appendix A

SUBROUTINE DESCRIPTIONS

A�� Introduction

This appendix includes a classi�ed list of all the PGPLOT subroutines�and then gives detailed instructions for the use of each routine in Fortranprograms� The subroutine descriptions are in alphabetical order�

A�� Arguments

The subroutine descriptions indicate the data type of each argument� Whenarguments are described as �input�� they may be replaced with constantsor expressions in the CALL statement� but make sure that the constant orexpression has the correct data type�

�� INTEGER arguments these should be declared INTEGER or INTEGER� inthe calling program� not INTEGER��

�� REAL arguments these should be declared REAL or REAL� in the callingprogram� not REAL�� or DOUBLE PRECISION�

�� CHARACTER arguments any valid Fortran CHARACTER variable may beused �declared CHARACTER�n for some integer n��

A�� Classi�ed List

Note all routine names begin with the letters �PG�� Most �but unfor�tunately not all� routine names are six characters or less� to conform toFortran�� standards�

A�� SUBROUTINE DESCRIPTIONS

Control routines

PGADVANCE � see PGPAGE

PGASK � control new page prompting

PGBBUF � begin batch of output �bu�er�

PGBEGIN � begin PGPLOT� open output device

PGEBUF � end batch of output �bu�er�

PGEND � terminate PGPLOT

PGPAGE � advance to a new page or clear screen

PGPAPER � change the size of the view surface

PGUPDT � update display

Windows and viewports

PGBOX � draw labeled frame around viewport

PGENV � set window and viewport and draw labeled frame

PGVPORT � set viewport �normalized device coordinates�

PGVSIZE � set viewport �inches�

PGVSTAND � set standard �default� viewport

PGWINDOW � set window

PGWNAD � set window and adjust viewport to same aspect ratio

Primitive drawing routines

PGDRAW � draw a line from the current pen position to a point

PGLINE � draw a polyline �curve de�ned by line�segments�

PGMOVE � move pen �change current pen position�

PGPOINT � draw one or more graph markers

PGPOLY � �ll a polygonal area with shading

PGRECT � draw a rectangle� using �ll�area attributes

Text

PGLABEL � write labels for x�axis� y�axis� and top of plot

PGMTEXT � write text at position relative to viewport

PGPTEXT � write text at arbitrary position and angle

PGTEXT � write text �horizontal� left�justi�ed�

SUBROUTINE DESCRIPTIONS A��

Attribute setting

PGSCF � set character font

PGSCH � set character height

PGSCI � set color index

PGSCR � set color representation

PGSFS � set �ll�area style

PGSHLS � set color representation using HLS system

PGSLS � set line style

PGSLW � set line width

Higherlevel drawing routines

PGBIN � histogram of binned data

PGCONS � contour map of a �D data array �fast algorithm�

PGCONT � contour map of a �D data array �contour�following�

PGCONX � contour map of a �D data array �non�rectangular�

PGERRX � horizontal error bar

PGERRY � vertical error bar

PGFUNT � function de�ned by X � F�T�� Y � G�T�

PGFUNX � function de�ned by Y � F�X�

PGFUNY � function de�ned by X � F�Y�

PGGRAY � gray�scale map of a �D data array

PGHI�D � cross�sections through a �D data array

PGHIST � histogram of unbinned data

Interactive graphics �cursor�

PGCURSE � read cursor position

PGLCUR � draw a line using the cursor

PGNCURSE � mark a set of points using the cursor

PGOLIN � mark a set of points using the cursor


Inquiry routines

PGQCF � inquire character font

PGQCH � inquire character height

PGQCI � inquire color index

PGQCR � inquire color representation

PGQFS � inquire �ll�area style

PGQINF � inquire PGPLOT general information

PGQLS � inquire line style

PGQLW � inquire line width

PGQVP � inquire viewport size and position

PGQWIN � inquire window boundary coordinates

Utility routines

PGETXT � erase text from graphics display

PGIDEN � write username� date� and time at bottom of plot

PGLDEV � list available device types

PGNUMB � convert a number into a plottable character string

PGRND � �nd the smallest �round� number greater than x

PGRNGE � choose axis limits

A�� Subroutine Synopses

The following pages give descriptions of all the PGPLOT subroutines inalphabetical order� These descriptions have been extracted from commentsin the Fortran source code� �For an up�to�date version of these decriptions�look at the �le PGPLOT�DOC in the PGPLOT directory��


A�� PGADVANCE � non standard alias for PGPAGE

SUBROUTINE PGADVANCE

A�� PGASK � control new page prompting

SUBROUTINE PGASK �FLAG�LOGICAL FLAG

Change the �prompt state� of PGPLOT� If the prompt state isON� PGPAGE will type �Type �RETURN� for next page� and will waitfor the user to type �CR� before starting a new page� The initialprompt state �after a call to PGBEG� is ON for interactive devices�Prompt state is always OFF for noninteractive devices�ArgumentsFLAG �input� if �TRUE�� and if the device is an interactive

device� the prompt state will be set to ON� If�FALSE�� the prompt state will be set to OFF�

A� PGBBUF � begin batch of output �bu�er�

SUBROUTINE PGBBUFBegin saving graphical output commands in an internal buffer� thecommands are held until a matching PGEBUF call �or until the bufferis emptied by PGUPDT�� This can greatly improve the efficiency ofPGPLOT� PGBBUF increments an internal counter� while PGEBUFdecrements this counter and flushes the buffer to the outputdevice when the counter drops to zero� PGBBUF and PGEBUF callsshould always be paired�Arguments none


A� PGBEG � begin PGPLOT� open output device

INTEGER FUNCTION PGBEG �UNIT� FILE� NXSUB� NYSUB�INTEGER UNITCHARACTER�� FILEINTEGER NXSUB� NYSUB

Begin PGPLOT� open the plot file� A call to PGBEG isrequired before any other calls to PGPLOT subroutines� If a plotfile is already open for PGPLOT output� it is closed before the newfile is opened�ReturnsPGBEG a status return value� A value of indicates

successful completion� any other value indicatesan error� In the event of error a message iswritten on the standard error unit�To test the return value� callPGBEG as a function� eg IER�PGBEG�� notethat PGBEG must be declared INTEGER in thecalling program�

ArgumentsUNIT �input� this argument is ignored by PGBEG �use zero��FILE �input� the �device specification� for the plot device�

Device specifications are installation dependent�but usually have the form �device�type� or�file�type�� If this argument is aquestion mark �� PGBEG will prompt the userto supply a string�

NXSUB �input� the number of subdivisions of the view surface inX�

NYSUB �input� the number of subdivisions of the view surface inY� PGPLOT puts NXSUB x NYSUB graphs on each plotpage or screen� when the view surface is subdivided in this way� PGPAGE moves to the nextsubpage� not the next physical page�

A�� PGBEGIN � non standard alias for PGBEG

INTEGER FUNCTION PGBEGIN �UNIT� FILE� NXSUB� NYSUB�INTEGER UNITCHARACTER�� FILEINTEGER NXSUB� NYSUB


A�� PGBIN � histogram of binned data

SUBROUTINE PGBIN �NBIN� X� DATA� CENTER�INTEGER NBINREAL X�� DATA��LOGICAL CENTER

Plot a histogram of NBIN values with X� ��NBIN� values alongthe ordinate� and DATA� ��NBIN� along the abscissa� Bin width isspacing between X values�ArgumentsNBIN �input� number of values�X �input� abscissae of bins�DATA �input� data values of bins�CENTER �input� if �TRUE�� the X values denote the center of the

bin� if �FALSE�� the X values denote the loweredge �in X� of the bin�

A� SUBROUTINE DESCRIPTIONS

A�� PGBOX � draw labeled frame around viewport

SUBROUTINE PGBOX �XOPT� XTICK� NXSUB� YOPT� YTICK� NYSUB�CHARACTER�� XOPT� YOPTREAL XTICK� YTICKINTEGER NXSUB� NYSUB

Annotate the viewport with frame� axes� numeric labels� etc�PGBOX is called by on the user�s behalf by PGENV� but may also becalled explicitly�ArgumentsXOPT �input� string of options for X �horizontal� axis of

plot� Options are single letters� and may be inany order �see below��

XTICK �input� world coordinate interval between major tick markson X axis� If XTICK�� the interval is chosen byPGBOX� so that there will be at least � major tickmarks along the axis�

NXSUB �input� the number of subintervals to divide the majorcoordinate interval into� If XTICK�� or NXSUB��the number is chosen by PGBOX�

YOPT �input� string of options for Y �vertical� axis of plot�Coding is the same as for XOPT�

YTICK �input� like XTICK for the Y axis�NYSUB �input� like NXSUB for the Y axis�Options �for parameters XOPT and YOPT�A draw Axis �X axis is horizontal line Y�� Y axis is vertical

line X��B draw bottom �X� or left �Y� edge of frame�C draw top �X� or right �Y� edge of frame�G draw Grid of vertical �X� or horizontal �Y� lines�I Invert the tick marks� ie draw them outside the viewport

instead of inside�L label axis Logarithmically �see below��N write Numeric labels in the conventional location below the

viewport �X� or to the left of the viewport �Y��P extend ��Project�� major tick marks outside the box �ignored if

option I is specified��M write numeric labels in the unconventional location above the

viewport �X� or to the right of the viewport �Y��T draw major Tick marks at the major coordinate interval�S draw minor tick marks �Subticks��V orient numeric labels Vertically� This is only applicable to Y�

The default is to write Ylabels parallel to the axisTo get a complete frame� specify BC in both XOPT and YOPT�Tick marks� if requested� are drawn on the axes or frameor both� depending which are requested� If none of ABC is specified�tick marks will not be drawn� When PGENV calls PGBOX� it sets bothXOPT and YOPT according to the value of its parameter AXIS �BC�� BCNST�� ABCNST�� ABCGNST��For a logarithmic axis� the major tick interval is always �� Thenumeric label is ��x� where x is the world coordinate at thetick mark� If subticks are requested� � subticks are drawn betweeneach major tick at equal logarithmic intervals�


A�� PGCONB � contour map of a �D data array� with blanking

SUBROUTINE PGCONB �A� IDIM� JDIM� I � I�� J � J�� C� NC� TR� BLANK�INTEGER IDIM� JDIM� I � I�� J � J�� NCREAL A�IDIM�JDIM�� C�� TR�� BLANK

Draw a contour map of an array� This routine is the same as PGCONS�except that array elements that have the �magic value� defined byargument BLANK are ignored� making gaps in the contour map� Theroutine may be useful for data measured on most but not all of thepoints of a grid�ArgumentsA �input� data array�IDIM �input� first dimension of A�JDIM �input� second dimension of A�I �I� �input� range of first index to be contoured �inclusive��J �J� �input� range of second index to be contoured �inclusive��C �input� array of contour levels �in the same units as the

data in array A�� dimension at least NC�NC �input� number of contour levels �less than or equal to

dimension of C�� The absolute value of thisargument is used �for compatibility with PGCONT�where the sign of NC is significant��

TR �input� array defining a transformation between the I�Jgrid of the array and the world coordinates� Theworld coordinates of the array point A�I�J� aregiven by

X � TR� � � TR��I � TR��JY � TR�� TR��I � TR��J

Usually TR�� and TR�� are zero unless thecoordinate transformation involves a rotationor shear�

BLANK �input� elements of array A that are exactly equal tothis value are ignored �blanked��


A�� PGCONS � contour map of a �D data array �fast algorithm�

SUBROUTINE PGCONS �A� IDIM� JDIM� I � I�� J � J�� C� NC� TR�INTEGER IDIM� JDIM� I � I�� J � J�� NCREAL A�IDIM�JDIM�� C�� TR��

Draw a contour map of an array� The map is truncated ifnecessary at the boundaries of the viewport� Each contour line isdrawn with the current line attributes �color index� style� andwidth�� This routine� unlike PGCONT� does not draw each contour as acontinuous line� but draws the straight line segments composing eachcontour in a random order� It is thus not suitable for use on penplotters� and it usually gives unsatisfactory results with dashed ordotted lines� It is� however� faster than PGCONT� especially ifseveral contour levels are drawn with one call of PGCONS�ArgumentsA �input� data array�IDIM �input� first dimension of A�JDIM �input� second dimension of A�I �I� �input� range of first index to be contoured �inclusive��J �J� �input� range of second index to be contoured �inclusive��C �input� array of contour levels �in the same units as the

data in array A�� dimension at least NC�NC �input� number of contour levels �less than or equal to

dimension of C�� The absolute value of thisargument is used �for compatibility with PGCONT�where the sign of NC is significant��

TR �input� array defining a transformation between the I�Jgrid of the array and the world coordinates� Theworld coordinates of the array point A�I�J� aregiven by


Usually TR�� and TR�� are zero unless thecoordinate transformation involves a rotationor shear�


A�� PGCONT � contour map of a �D data array �contour following�

SUBROUTINE PGCONT �A� IDIM� JDIM� I � I�� J � J�� C� NC� TR�INTEGER IDIM� JDIM� I � J � I�� J�� NCREAL A�IDIM�JDIM�� C�� TR��

Draw a contour map of an array� The map is truncated ifnecessary at the boundaries of the viewport� Each contour lineis drawn with the current line attributes �color index� style� andwidth�� except that if argument NC is positive �see below�� the linestyle is set by PGCONT to �solid� for positive contours or ��dashed� for negative contours�ArgumentsA �input� data array�IDIM �input� first dimension of A�JDIM �input� second dimension of A�I � I� �input� range of first index to be contoured �inclusive��J � J� �input� range of second index to be contoured �inclusive��C �input� array of NC contour levels� dimension at least NC�NC �input� �� number of contour levels �less than or equal

to dimension of C�� If NC is positive� it is thenumber of contour levels� and the linestyle ischosen automatically as described above� If NC isnegative� it is minus the number of contourlevels� and the current setting of linestyle isused for all the contours�

TR �input� array defining a transformation between the I�Jgrid of the array and the world coordinates�The world coordinates of the array point A�I�J�are given byX � TR� � � TR��I � TR��JY � TR�� TR��I � TR��J

Usually TR�� and TR�� are zero unless thecoordinate transformation involves a rotation orshear�


A�� PGCONX � contour map of a �D data array �non rectangular�

SUBROUTINE PGCONX �A� IDIM� JDIM� I � I�� J � J�� C� NC� PLOT�INTEGER IDIM� JDIM� I � J � I�� J�� NCREAL A�IDIM�JDIM�� C��EXTERNAL PLOT

Draw a contour map of an array using a usersupplied plottingroutine� This routine should be used instead of PGCONT when thedata are defined on a nonrectangular grid� PGCONT permits onlya linear transformation between the �I�J� grid of the arrayand the world coordinate system �x�y�� but PGCONX permits anytransformation to be used� the transformation being defined by ausersupplied subroutine� The nature of the contouring algorithm�however� dictates that the transformation should maintain therectangular topology of the grid� although gridpoints may beallowed to coalesce� As an example of a deformed rectangulargrid� consider data given on the polar grid theta�� n�pi��for n�� and r��m� for m�� This gridcontains �� points� of which are coincident at the origin�The input array for PGCONX should be dimensioned � �� anddata values should be provided for all �� elements� PGCONX canalso be used for special applications in which the height of thecontour affects its appearance� e�g�� stereoscopic views�The map is truncated if necessary at the boundaries of the viewport�Each contour line is drawn with the current line attributes �colorindex� style� and width�� except that if argument NC is positive�see below�� the line style is set by PGCONX to �solid� forpositive contours or � �dashed� for negative contours� Attributesfor the contour lines can also be set in the usersuppliedsubroutine� if desired�ArgumentsA �input� data array�IDIM �input� first dimension of A�JDIM �input� second dimension of A�I � I� �input� range of first index to be contoured �inclusive��J � J� �input� range of second index to be contoured �inclusive��C �input� array of NC contour levels� dimension at least NC�NC �input� �� number of contour levels �less than or equal

to dimension of C�� If NC is positive� it is thenumber of contour levels� and the linestyle ischosen automatically as described above� If NC isnegative� it is minus the number of contourlevels� and the current setting of linestyle isused for all the contours�

PLOT �input� the address �name� of a subroutine supplied bythe user� which will be called by PGCONX to dothe actual plotting� This must be declaredEXTERNAL in the program unit calling PGCONX�

The subroutine PLOT will be called with four argumentsCALL PLOT�VISBLE�X�Y�Z�

where X�Y �input� are real variables corresponding toI�J indices of the array A� If VISBLE �input� integer� is �PLOT should draw a visible line from the current penposition to the world coordinate point corresponding to �X�Y��if it is �� it should move the pen to �X�Y�� Z is the valueof the current contour level� and may be used by PLOT if desired�Example

SUBROUTINE PLOT �VISBLE�X�Y�Z�REAL X� Y� Z� XWORLD� YWORLDINTEGER VISBLEXWORLD � X�COS�Y� � this is the userdefinedYWORLD � X�SIN�Y� � transformationIF �VISBLE�EQ�� THEN

CALL PGMOVE �XWORLD� YWORLD�ELSE

CALL PGDRAW �XWORLD� YWORLD�END IFEND


A�� PGCURS � read cursor position

INTEGER FUNCTION PGCURS �X� Y� CH�REAL X� YCHARACTER� CH

Read the cursor position and a character typed by the user�The position is returned in world coordinates� PGCURS positionsthe cursor at the position specified� allows the user to move thecursor using the joystick or arrow keys or whatever is available onthe device� When he has positioned the cursor� the user types asingle character on the keyboard� PGCURS then returns thischaracter and the new cursor position �in world coordinates��ReturnsPGCURS if the call was successful� � if the device

has no cursor or some other error occurs�ArgumentsX �in�out� the world xcoordinate of the cursor�Y �in�out� the world ycoordinate of the cursor�CH �output� the character typed by the user� if the device has

no cursor or if some other error occurs� the valueCHAR�� ASCII NUL character� is returned�

Note The cursor coordinates �X�Y� may be changed by PGCURS even ifthe device has no cursor or if the user does not move the cursor�Under these circumstances� the position returned in �X�Y� is that ofthe pixel nearest to the requested position�

A�� PGCURSE � non standard alias for PGCURS

INTEGER FUNCTION PGCURSE �X� Y� CH�REAL X� YCHARACTER� CH

A�� PGDRAW � draw a line from the current pen position to a point

SUBROUTINE PGDRAW �X� Y�REAL X� Y

Draw a line from the current pen position to the pointwith worldcoordinates �X�Y�� The line is clipped at the edge of thecurrent window� The new pen position is �X�Y� in world coordinates�ArgumentsX �input� world xcoordinate of the end point of the line�Y �input� world ycoordinate of the end point of the line�


A�� PGEBUF � end batch of output �bu�er�

SUBROUTINE PGEBUFA call to PGEBUF marks the end of a batch of graphical output begunwith the last call of PGBBUF� PGBBUF and PGEBUF calls should alwaysbe paired� Each call to PGBBUF increments a counter� while each callto PGEBUF decrements the counter� When the counter reaches �� thebatch of output is written on the output device�Arguments none

A�� PGEND � terminate PGPLOT

SUBROUTINE PGENDTerminate PGPLOT� close the plot file� release the graphicsdevice� If the call to PGEND is omitted� some or all of the plotmay be lost� If the environment parameter PGPLOT�IDENT is defined�with any value�� and the device is a hardcopy device� anidentifying label is written on the plot �by calling PGIDEN q�v��Arguments none


A�� PGENV � set window and viewport and draw labeled frame

SUBROUTINE PGENV �XMIN� XMAX� YMIN� YMAX� JUST� AXIS�REAL XMIN� XMAX� YMIN� YMAXINTEGER JUST� AXIS

Set PGPLOT �Plotter Environment�� PGENV establishes the scalingfor subsequent calls to PGPT� PGLINE� etc� The plotter isadvanced to a new �sub�page� clearing the screen if necessary�If the �prompt state� is ON �see PGASK�� confirmationis requested from the user before clearing the screen�If requested� a box� axes� labels� etc� are drawn according tothe setting of argument AXIS�ArgumentsXMIN �input� the world xcoordinate at the bottom left corner

of the viewport�XMAX �input� the world xcoordinate at the top right corner

of the viewport �note XMAX may be less than XMIN��YMIN �input� the world ycoordinate at the bottom left corner

of the viewport�YMAX �input� the world ycoordinate at the top right corner

of the viewport �note YMAX may be less than YMIN��JUST �input� if JUST� � the scales of the x and y axes �in

world coordinates per inch� will be equal�otherwise they will be scaled independently�

AXIS �input� controls the plotting of axes� tick marks� etcAXIS � � draw no box� axes or labels�AXIS � draw box only�AXIS � � draw box and label it with coordinates�AXIS � same as AXIS�� but also draw the

coordinate axes �X�� Y��AXIS � � same as AXIS� � but also draw grid lines

at major increments of the coordinates�AXIS � � draw box and label Xaxis logarithmically�AXIS � �� draw box and label Yaxis logarithmically�AXIS � �� draw box and label both axes logarithmically�

For other axis options� use routine PGBOX� PGENV can be pursuaded tocall PGBOX with additional axis options by defining an environmentparameter PGPLOT�ENVOPT containing the required option codes�ExamplesPGPLOT�ENVOPT�P � draw Projecting tick marksPGPLOT�ENVOPT�I � Invert the tick marksPGPLOT�ENVOPT�IV � Invert tick marks and label y Vertically


A�� PGERRB � horizontal error bar

SUBROUTINE PGERRB �DIR� N� X� Y� E� T�INTEGER DIR� NREAL X�� Y�� E��REAL T

Plot error bars in the direction specified by DIR�This routine draws an error bar only� to mark the data point atthe start of the error bar� an additional call to PGPT is required�ArgumentsDIR �input� direction to plot the error bar relative to

the data point� DIR is for �X� � for �Y�� for X� and � for Y�

N �input� number of error bars to plot�X �input� world xcoordinates of the data�Y �input� world ycoordinates of the data�E �input� value of error bar distance to be added to the

data position in world coordinates�T �input� length of terminals to be drawn at the ends

of the error bar� as a multiple of the defaultlength� if T � �� no terminals will be drawn�

Note the dimension of arrays X� Y� and E must be greaterthan or equal to N� If N is � X� Y� and E may be scalarvariables� or expressions�

A�� PGERRX � horizontal error bar

SUBROUTINE PGERRX �N� X � X�� Y� T�INTEGER NREAL X �� X�� Y��REAL T

Plot horizontal error bars�This routine draws an error bar only� to mark the data point inthe middle of the error bar� an additional call to PGPT orPGERRY is required�ArgumentsN �input� number of error bars to plot�X �input� world xcoordinates of lower end of the

error bars�X� �input� world xcoordinates of upper end of the

error bars�Y �input� world ycoordinates of the data�T �input� length of terminals to be drawn at the ends


Note the dimension of arrays X � X�� and Y must be greaterthan or equal to N� If N is � X � X�� and Y may be scalarvariables� or expressions� eg

CALL PGERRX� �XSIGMA�X�SIGMA�Y�


A�� PGERRY � vertical error bar

SUBROUTINE PGERRY �N� X� Y � Y�� T�Plot vertical error bars�This routine draws an error bar only� to mark the data point inthe middle of the error bar� an additional call to PGPT orPGERRX is required�ArgumentsN �input� number of error bars to plot�X �input� world xcoordinates of the data�Y �input� world ycoordinates of top end of the

error bars�Y� �input� world ycoordinates of bottom end of the

error bars�T �input� length of terminals to be drawn at the ends


Note the dimension of arrays X� Y � and Y� must be greaterthan or equal to N� If N is � X� Y � and Y� may be scalarvariables or expressions� eg

CALL PGERRY� �X�Y�SIGMA�YSIGMA�

A�� PGETXT � erase text from graphics display

SUBROUTINE PGETXTSome graphics terminals display text �the normal interactive dialog�on the same screen as graphics� This routine erases the text from theview surface without affecting the graphics� It does nothing ondevices which do not display text on the graphics screen� and ondevices which do not have this capability�ArgumentsNone


A�� PGFUNT � function de�ned by X � F�T�� Y � G�T�

SUBROUTINE PGFUNT �FX� FY� N� TMIN� TMAX� PGFLAG�REAL FX� FYINTEGER NREAL TMIN� TMAXINTEGER PGFLAG

Draw a curve defined by parametric equations X � FX�T�� Y � FY�T��ArgumentsFX �external real function� supplied by the user� evaluates

Xcoordinate�FY �external real function� supplied by the user� evaluates

Ycoordinate�N �input� the number of points required to define the

curve� The functions FX and FY will each becalled N� times�

TMIN �input� the minimum value for the parameter T�TMAX �input� the maximum value for the parameter T�PGFLAG �input� if PGFLAG � � the curve is plotted in the

current window and viewport� if PGFLAG � ��PGENV is called automatically by PGFUNT tostart a new plot with automatic scaling�

Note The functions FX and FY must be declared EXTERNAL in theFortran program unit that calls PGFUNT�

A�� PGFUNX � function de�ned by Y � F�X�

SUBROUTINE PGFUNX �FY� N� XMIN� XMAX� PGFLAG�REAL FYINTEGER NREAL XMIN� XMAXINTEGER PGFLAG

Draw a curve defined by the equation Y � FY�X�� where FY is ausersupplied subroutine�ArgumentsFY �external real function� supplied by the user� evaluates

Y value at a given Xcoordinate�N �input� the number of points required to define the

curve� The function FY will be called N� times�If PGFLAG�� and N is greater than �� will be used instead� If N is less than �nothing will be drawn�

XMIN �input� the minimum value of X�XMAX �input� the maximum value of X�PGFLAG �input� if PGFLAG � � the curve is plotted in the

current window and viewport� if PGFLAG � ��PGENV is called automatically by PGFUNX tostart a new plot with X limits �XMIN� XMAX�and automatic scaling in Y�

Note The function FY must be declared EXTERNAL in the Fortranprogram unit that calls PGFUNX� It has one argument� thexcoordinate at which the y value is required� e�g�REAL FUNCTION FY�X�REAL XFY � ��END


A�� PGFUNY � function de�ned by X � F�Y�

SUBROUTINE PGFUNY �FX� N� YMIN� YMAX� PGFLAG�REAL FXINTEGER NREAL YMIN� YMAXINTEGER PGFLAG

Draw a curve defined by the equation X � FX�Y�� where FY is ausersupplied subroutine�ArgumentsFX �external real function� supplied by the user� evaluates

X value at a given Ycoordinate�N �input� the number of points required to define the

curve� The function FX will be called N� times�If PGFLAG�� and N is greater than �� will be used instead� If N is less than �nothing will be drawn�

YMIN �input� the minimum value of Y�YMAX �input� the maximum value of Y�PGFLAG �input� if PGFLAG � � the curve is plotted in the

current window and viewport� if PGFLAG � ��PGENV is called automatically by PGFUNY tostart a new plot with Y limits �YMIN� YMAX�and automatic scaling in X�

Note The function FX must be declared EXTERNAL in the Fortranprogram unit that calls PGFUNY� It has one argument� theycoordinate at which the x value is required� e�g�REAL FUNCTION FX�Y�REAL YFX � ��END


A�� PGGRAY � gray scale map of a �D data array

SUBROUTINE PGGRAY �A� IDIM� JDIM� I � I�� J � J�� FG� BG� TR�INTEGER IDIM� JDIM� I � I�� J � J�REAL A�IDIM�JDIM�REAL FG� BGREAL TR��

Draw grayscale map of an array in current window� The subsectionof the array A defined by indices �I I�� J J�� is mapped ontothe view surface worldcoordinate system by the transformationmatrix TR� The resulting quadrilateral region is clipped at the edgeof the window and shaded with the shade at each point determinedby the corresponding array value� The shade is a number in therange � to obtained by linear interpolation between the backgroundlevel �BG� and the foreground level �FG�� i�e��shade � �A�i�j� BG� � �FG BG�

The background level BG can be either less than or greater than theforeground level FG� Points in the array that are outside the rangeBG to FG are assigned shade � or as appropriate�The algorithm used by PGGRAY is devicedependent� On devicesthat have only two color indices �� and �� the background coloris the color assigned to color index �� the foreground coloris the color assigned to color index � and PGGRAY uses a�dithering� algorithm to fill in pixels in the two colors� withthe shade �computed as above� determining the faction of pixelsthat are assigned color index �On devices that have more than � color indices� PGGRAY may usecolor indices outside the range � � to provide more than twogray shades� Note that PGGRAY may change the color representationof these color indices� but it will not change the representationof indices � ��On most devices� the shaded region is �opaque�� i�e�� it obscuresall graphical elements previously drawn in the region� But ondevices that do not have erase capability� the background shadeis �transparent� and allows previouslydrawn graphics to showthrough�The transformation matrix TR is used to calculate the worldcoordinates of the center of the �cell� that represents eacharray element� The world coordinates of the center of the cellcorresponding to array element A�I�J� are given by


Usually TR�� and TR�� are zero unless the coordinatetransformation involves a rotation or shear� The corners of thequadrilateral region that is shaded by PGGRAY are given byapplying this transformation to �I ��J �� I�� J��ArgumentsA �input� the array to be plotted�IDIM �input� the first dimension of array A�JDIM �input� the second dimension of array A�I � I� �input� the inclusive range of the first index

�I� to be plotted�J � J� �input� the inclusive range of the second

index �J� to be plotted�FG �input� the array value which is to appear with shade

��foreground��BG �input� the array value which is to appear with shade

� ��background��TR �input� transformation matrix between array grid and

world coordinates�


A�� PGHI�D � cross sections through a �D data array

SUBROUTINE PGHI�D �DATA� NXV� NYV� IX � IX�� IY � IY�� X� IOFF� BIAS� CENTER� YLIMS�INTEGER NXV� NYV� IX � IX�� IY � IY�REAL DATA�NXV�NYV�REAL X�IX�IX � �� YLIMS�IX�IX � �INTEGER IOFFREAL BIASLOGICAL CENTER

Plot a series of crosssections through a �D data array�Each crosssection is plotted as a hidden line histogram� The plotcan be slanted to give a pseudo�D effect if this is done� thecall to PGENV may have to be changed to allow for the increased Xrange that will be needed�ArgumentsDATA �input� the data array to be plotted�NXV �input� the first dimension of DATA�NYV �input� the second dimension of DATA�IX �input�IX� �input�IY �input�IY� �input� PGHI�D plots a subset of the input array DATA�

This subset is delimited in the first �x�dimension by IX and IX� and the �nd �y� by IY and IY�� inclusively� Note IY� � IY ispermitted� resulting in a plot with thecrosssections plotted in reverse Y order�However� IX� must be �� IX �

X �input� the abscissae of the bins to be plotted� That is�X� � should be the X value for DATA�IX �IY �� andX should have �IX�IX � � elements� The programhas to assume that the X value for DATA�x�y� isthe same for all y�

IOFF �input� an offset in array elements applied to successivecrosssections to produce a slanted effect� Aplot with IOFF � � slants to the right� one withIOFF � � slants left�

BIAS �input� a bias value applied to each successive crosssection in order to raise it above the previouscrosssection� This is in the same units as thedata�

CENTER �input� if �true�� the X values denote the center of thebins� if �false� the X values denote the loweredges �in X� of the bins�

YLIMS �input� workspace� Should be an array of at least�IX�IX � � elements�


A�� PGHIST � histogram of unbinned data

SUBROUTINE PGHIST �N� DATA� DATMIN� DATMAX� NBIN� PGFLAG�INTEGER NREAL DATA��REAL DATMIN� DATMAXINTEGER NBIN� PGFLAG

Draw a histogram of N values of a variable in arrayDATA� ��N� in the range DATMIN to DATMAX using NBIN bins� Notethat array elements which fall exactly on the boundary betweentwo bins will be counted in the higher bin rather than thelower one� and array elements whose value is less than DATMIN orgreater than or equal to DATMAX will not be counted at all�ArgumentsN �input� the number of data values�DATA �input� the data values� Note the dimension of array

DATA must be greater than or equal to N� Thefirst N elements of the array are used�

DATMIN �input� the minimum data value for the histogram�DATMAX �input� the maximum data value for the histogram�NBIN �input� the number of bins to use the range DATMIN to

DATMAX is divided into NBIN equal bins andthe number of DATA values in each bin isdetermined by PGHIST� NBIN may not exceed ��

PGFLAG �input� if PGFLAG � � the histogram is plotted in thecurrent window and viewport� if PGFLAG � ��PGENV is called automatically by PGHIST to starta new plot �the xlimits of the window will beDATMIN and DATMAX� the ylimits will be chosenautomatically�

A�� PGIDEN � write username� date� and time at bottom of plot

SUBROUTINE PGIDENWrite username� date� and time at bottom of plot�Arguments none�

A�� PGLAB � write labels for x axis� y axis� and top of plot

SUBROUTINE PGLAB �XLBL� YLBL� TOPLBL�CHARACTER�� XLBL� YLBL� TOPLBL

Write labels outside the viewport� This routine is a simpleinterface to PGMTXT� which should be used if PGLAB is inadequate�ArgumentsXLBL �input� a label for the xaxis �centered below the

viewport��YLBL �input� a label for the yaxis �centered to the left

of the viewport� drawn vertically��TOPLBL �input� a label for the entire plot �centered above the

viewport��


A�� PGLABEL � non standard alias for PGLAB

SUBROUTINE PGLABEL �XLBL� YLBL� TOPLBL�CHARACTER�� XLBL� YLBL� TOPLBL

A�� PGLCUR � draw a line using the cursor

SUBROUTINE PGLCUR �MAXPT� NPT� X� Y�INTEGER MAXPT� NPTREAL X�� Y��

Interactive routine for user to enter a polyline by use ofthe cursor� Routine allows user to Add and Delete vertices�vertices are joined by straightline segments�ArgumentsMAXPT �input� maximum number of points that may be accepted�NPT �in�out� number of points entered� should be zero on

first call�X �in�out� array of xcoordinates �dimension at least MAXPT��Y �in�out� array of ycoordinates �dimension at least MAXPT��Notes� � On return from the program� cursor points are returned inthe order they were entered� Routine may be �re�called with pointsalready defined in X�Y �� in NPT�� and they will be plottedfirst� before editing�� User commands the user types singlecharacter commandsafter positioning the cursor the following are acceptedA �Add� add point at current cursor location�D �Delete� delete lastentered point�X �eXit� leave subroutine�

A�� PGLDEV � list available device types

SUBROUTINE PGLDEVWrites a list to the terminal of all device types known to thecurrent version of PGPLOT�Arguments none�


A�� PGLEN � Find length of a string in a variety of units

SUBROUTINE PGLEN �UNITS� STRING� XL� YL�REAL XL� YLINTEGER UNITSCHARACTER�� STRING

Work out length of a string in x and y directionsInputUNITS � �� answer in normalized device coordinates

�� answer in inches� �� answer in mm� �� answer in absolute device coordinates �dots�� answer in world coordinates� �� answer as a fraction of the current viewport size

STRING String of interestOutputXL Length of string in x directionYL Length of string in y direction

A�� PGLINE � draw a polyline �curve de�ned by line segments�

SUBROUTINE PGLINE �N� XPTS� YPTS�INTEGER NREAL XPTS�� YPTS��

Primitive routine to draw a Polyline� A polyline is one or moreconnected straightline segments� The polyline is drawn usingthe current setting of attributes colorindex� linestyle� andlinewidth� The polyline is clipped at the edge of the window�ArgumentsN �input� number of points defining the line� the line

consists of �N � straightline segments�N should be greater than �if it is or less�nothing will be drawn��

XPTS �input� world xcoordinates of the points�YPTS �input� world ycoordinates of the points�The dimension of arrays X and Y must be greater than or equal to N�The �pen position� is changed to �X�N��Y�N�� in world coordinates�if N � ��

A�� PGMOVE � move pen �change current pen position�

SUBROUTINE PGMOVE �X� Y�REAL X� Y

Primitive routine to move the �pen� to the point with worldcoordinates �X�Y�� No line is drawn�ArgumentsX �input� world xcoordinate of the new pen position�Y �input� world ycoordinate of the new pen position�


A�� PGMTEXT � non standard alias for PGMTXT

SUBROUTINE PGMTEXT �SIDE� DISP� COORD� FJUST� TEXT�CHARACTER�� SIDE� TEXTREAL DISP� COORD� FJUST

A�� PGMTXT � write text at position relative to viewport

SUBROUTINE PGMTXT �SIDE� DISP� COORD� FJUST� TEXT�CHARACTER�� SIDE� TEXTREAL DISP� COORD� FJUST

Write text at a position specified relative to the viewport �outsideor inside�� This routine is useful for annotating graphs� It is usedby routine PGLAB� The text is written using the current values ofattributes colorindex� linewidth� characterheight� andcharacterfont�ArgumentsSIDE �input� must include one of the characters �B�� L�� T��

or �R� signifying the Bottom� Left� Top� or Rightmargin of the viewport� If it includes �LV� or�RV�� the string is written perpendicular to theframe rather than parallel to it�

DISP �input� the displacement of the character string from thespecified edge of the viewport� measured outwardsfrom the viewport in units of the characterheight� Use a negative value to write inside theviewport� a positive value to write outside�

COORD �input� the location of the character string along thespecified edge of the viewport� as a fraction ofthe length of the edge�

FJUST �input� controls justification of the string parallel tothe specified edge of the viewport� IfFJUST � �� the lefthand end of the string willbe placed at COORD� if JUST � �� the center ofthe string will be placed at COORD� if JUST � ��the righthand end of the string will be placed atat COORD� Other values between � and give intermediate placing� but they are not very useful�

TEXT �input� the text string to be plotted� Trailing spaces areignored when justifying the string� but leadingspaces are significant�


A�� PGNCUR � mark a set of points using the cursor

SUBROUTINE PGNCUR �MAXPT� NPT� X� Y� SYMBOL�INTEGER MAXPT� NPTREAL X�� Y��INTEGER SYMBOL

Interactive routine for user to enter data points by use ofthe cursor� Routine allows user to Add and Delete points� Thepoints are returned in order of increasing xccordinate� not in theorder they were entered�ArgumentsMAXPT �input� maximum number of points that may be accepted�NPT �in�out� number of points entered� should be zero on

first call�X �in�out� array of xcoordinates�Y �in�out� array of ycoordinates�SYMBOL �input� code number of symbol to use for marking

entered points �see PGPT��Note � � The dimension of arrays X and Y must be greater than orequal to MAXPT�Note �� On return from the program� cursor points are returned inincreasing order of X� Routine may be �re�called with pointsalready defined in X�Y �number in NPT�� and they will be plottedfirst� before editing�Note �� User commands the user types singlecharacter commandsafter positioning the cursor the following are acceptedA �Add� add point at current cursor location�D �Delete� delete nearest point to cursor�X �eXit� leave subroutine�

A�� PGNCURSE � non standard alias for PGNCUR

SUBROUTINE PGNCURSE �MAXPT� NPT� X� Y� SYMBOL�INTEGER MAXPT� NPTREAL X�� Y��INTEGER SYMBOL


A�� PGNUMB � convert a number into a plottable character string

SUBROUTINE PGNUMB �MM� PP� FORM� STRING� NC�INTEGER MM� PP� FORMCHARACTER�� STRINGINTEGER NC

This routine converts a number into a decimal characterrepresentation� To avoid problems of floatingpoint roundoff� thenumber must be provided as an integer �MM� multiplied by a power of �� PP�� The output string retains only significant digits of MM�and will be in either integer format � �� decimal format �� or exponential format � ��x �� Standard escape sequences �u� �draise the exponent and �� is used for the multiplication sign�This routine is used by PGBOX to create numeric labels for a plot�Formatting rules�a� Decimal notation �FORM� �

Trailing zeros to the right of the decimal sign areomitted

The decimal sign is omitted if there are no digitsto the right of it

When the decimal sign is placed before the first digitof the number� a zero is placed before the decimal sign

The decimal sign is a period �� No spaces are placed between digits �ie digits are notgrouped in threes as they should be�

A leading minus �� is added if the number is negative�b� Exponential notation �FORM��

The exponent is adjusted to put just one �nonzero�digit before the decimal sign

The mantissa is formatted as in �a�� unless its value is in which case it and the multiplication sign are omitted

If the power of � is not zero and the mantissa is notzero� an exponent of the form �� u��nnn is appended�where �� is a multiplication sign �cross�� u is an escapesequence to raise the exponent� and as many digits nnnare used as needed

�c� Automatic choice �FORM��Decimal notation is used if the absolute value of thenumber is less than �� or greater than or equal to�� Otherwise exponential notation is used�

ArgumentsMM �input�PP �input� the value to be formatted is MM� ��PP�FORM �input� controls how the number is formatted

FORM � � use either decimal or exponentialFORM � use decimal notationFORM � � use exponential notation

STRING �output� the formatted character string� left justified�If the length of STRING is insufficient� a singleasterisk is returned� and NC� �

NC �output� the number of characters used in STRINGthe string to be printed is STRING� NC��


A�� PGOLIN � mark a set of points using the cursor

SUBROUTINE PGOLIN �MAXPT� NPT� X� Y� SYMBOL�INTEGER MAXPT� NPTREAL X�� Y��INTEGER SYMBOL

Interactive routine for user to enter data points by use ofthe cursor� Routine allows user to Add and Delete points� Thepoints are returned in the order that they were entered �unlikePGNCUR��ArgumentsMAXPT �input� maximum number of points that may be accepted�NPT �in�out� number of points entered� should be zero on

first call�X �in�out� array of xcoordinates�Y �in�out� array of ycoordinates�SYMBOL �input� code number of symbol to use for marking

entered points �see PGPT��Note � � The dimension of arrays X and Y must be greater than orequal to MAXPT�Note �� On return from the program� cursor points are returned inthe order they were entered� Routine may be �re�called with pointsalready defined in X�Y �number in NPT�� and they will be plottedfirst� before editing�Note �� User commands the user types singlecharacter commandsafter positioning the cursor the following are acceptedA �Add� add point at current cursor location�D �Delete� delete the last point entered�X �eXit� leave subroutine�

A�� PGPAGE � advance to new page

SUBROUTINE PGPAGEAdvance plotter to a new �sub�page� clearing the screen ifnecessary� If the �prompt state� is ON �see PGASK�� confirmation isrequested from the user before clearing the screen� For anexplanation of subpages� see PGBEG� PGPAGE does not change thewindow or the position of the viewport relative to the �sub�page�Arguments none


A�� PGPAP � change the size of the view surface ��paper size��

SUBROUTINE PGPAP �WIDTH� ASPECT�REAL WIDTH� ASPECT

This routine changes the size of the view surface to a specifiedwidth and aspect ratio �height�width�� in so far as this is possibleon the specific device� It is always possible to obtain a viewsurface smaller than the default size� on some devices �e�g��printers that print on roll or fanfeed paper� it is possibleto obtain a view surface larger than the default� If this routine isused� it must be called immediately after PGBEGIN�ArgumentsWIDTH �input� the requested width of the view surface in inches�

if WIDTH�� PGPAP will obtain the largest viewsurface available consistent with argument ASPECT�

ASPECT �input� the aspect ratio �height�width� of the viewsurface� e�g�� ASPECT� �� gives a square viewsurface� ASPECT�� gives a horizontalrectangle� ASPECT� �� gives a vertical rectangle�

A�� PGPAPER � non standard alias for PGPAP

SUBROUTINE PGPAPER �WIDTH� ASPECT�REAL WIDTH� ASPECT


A�� PGPIXL � draw pixels

SUBROUTINE PGPIXL �IA� IDIM� JDIM� I � I�� J � J�� X � X�� Y � Y��INTEGER IDIM� JDIM� I � I�� J � J�INTEGER IA�IDIM�JDIM�REAL X � X�� Y � Y�

Draw lots of solidfilled �tiny� rectangles alligned with thecoordinate axes� Best performance is achieved when output isdirected to a pixeloriented device and the rectangles coincidewith the pixels on the device� In other cases� pixel output isemulated�The subsection of the array IA defined by indices �I I�� J J��is mapped onto worldcoordinate rectangle defined by X � X�� Y and Y�� This rectangle is divided int �I� I � � � �J� J � �small rectangles� Each of these small rectangles is solidfilledwith the color index specified by the corresponding element ofIA�On most devices� the output region is �opaque�� i�e�� it obscuresall graphical elements previously drawn in the region� But ondevices that do not have erase capability� the background shadeis �transparent� and allows previouslydrawn graphics to showthrough�ArgumentsIA �input� the array to be plotted�IDIM �input� the first dimension of array A�JDIM �input� the second dimension of array A�I � I� �input� the inclusive range of the first index

�I� to be plotted�J � J� �input� the inclusive range of the second

index �J� to be plotted�X � Y �input� world coordinates of one corner of the output

regionX�� Y� �input� world coordinates of the opposite corner of the

output region


A�� PGPNTS � draw one or more graph markers

SUBROUTINE PGPNTS �N� X� Y� SYMBOL� NS�INTEGER N� NSREAL X�� Y��INTEGER SYMBOL��

Draw Graph Markers� Unlike PGPT� this routine can draw a differentsymbol at each point� The markersare drawn using the current values of attributes colorindex�linewidth� and characterheight �characterfont applies if the symbolnumber is �� If the point to be marked lies outside the window�no marker is drawn� The �pen position� is changed to�XPTS�N��YPTS�N�� in world coordinates �if N � ��ArgumentsN �input� number of points to mark�X �input� world xcoordinate of the points�Y �input� world ycoordinate of the points�SYMBOL �input� code number of the symbol to be plotted at each

point �see PGPT��NS �input� number of values in the SYMBOL array� If NS �� N�

then the first NS points are drawn using the valueof SYMBOL�I� at �X�I�� Y�I�� and SYMBOL� � for allthe values of �X�I�� Y�I�� where I � NS�

Note the dimension of arrays X and Y must be greater than or equalto N and the dimension of the array SYMBOL must be greater than orequal to NS� If N is � X and Y may be scalars �constants orvariables�� If NS is � then SYMBOL may be a scalar� If N isless than � nothing is drawn�

A�� PGPOINT � non standard alias for PGPT

SUBROUTINE PGPOINT �N� XPTS� YPTS� SYMBOL�INTEGER NREAL XPTS�� YPTS��INTEGER SYMBOL


A�� PGPOLY � �ll a polygonal area with shading

SUBROUTINE PGPOLY �N� XPTS� YPTS�INTEGER NREAL XPTS�� YPTS��

Fillarea primitive routine shade the interior of a closedpolygon in the current window� The action of this routine dependson the setting of the FillArea Style attribute� If FillArea Styleis SOLID �the default�� the interior of the polygon is solidfilledusing the current Color Index� If FillArea Style is HOLLOW� theoutline of the polygon is drwan using the current line attributes�color index� linestyle� and linewidth�� Other values of the FillArea attribute may be allowed in future� e�g�� for shading withpatterns or hatching� The polygon is clipped at the edge of thewindow� The pen position is changed to �XPTS� ��YPTS� �� in worldcoordinates �if N � �� If the polygon is not convex� a point isassumed to lie inside the polygon if a straight line drawn toinfinity intersects and odd number of the polygon�s edges�ArgumentsN �input� number of points defining the polygon� the

line consists of N straightline segments�joining points to �� to �� N to N� N to �N should be greater than � �if it is � or less�nothing will be drawn��

XPTS �input� world xcoordinates of the vertices�YPTS �input� world ycoordinates of the vertices�

Note the dimension of arrays XPTS and YPTS must begreater than or equal to N�


A�� PGPT � draw one or more graph markers

SUBROUTINE PGPT �N� XPTS� YPTS� SYMBOL�INTEGER NREAL XPTS�� YPTS��INTEGER SYMBOL

Primitive routine to draw Graph Markers �polymarker�� The markersare drawn using the current values of attributes colorindex�linewidth� and characterheight �characterfont applies if the symbolnumber is �� If the point to be marked lies outside the window�no marker is drawn� The �pen position� is changed to�XPTS�N��YPTS�N�� in world coordinates �if N � ��ArgumentsN �input� number of points to mark�XPTS �input� world xcoordinates of the points�YPTS �input� world ycoordinates of the points�SYMBOL �input� code number of the symbol to be drawn at each

point � � a single dot �diameter � current

line width�� a regular polygon with ABS�SYMBOL�

edges �style set by current fill style�� standard marker symbols�� ASCII characters �in current font��

e�g� to use letter F as a marker� letSYMBOL � ICHAR��F��

� � a Hershey symbol number�Note the dimension of arrays X and Y must be greater than or equalto N� If N is � X and Y may be scalars �constants or variables�� IfN is less than � nothing is drawn�

A�� PGPTEXT � non standard alias for PGPTXT

SUBROUTINE PGPTEXT �X� Y� ANGLE� FJUST� TEXT�REAL X� Y� ANGLE� FJUSTCHARACTER�� TEXT


A�� PGPTXT � write text at arbitrary position and angle

SUBROUTINE PGPTXT �X� Y� ANGLE� FJUST� TEXT�REAL X� Y� ANGLE� FJUSTCHARACTER�� TEXT

Primitive routine for drawing text� The text may be drawn at anyangle with the horizontal� and may be centered or left or rightjustified at a specified position� Routine PGTEXT provides asimple interface to PGPTXT for horizontal strings� Text is drawnusing the current values of attributes colorindex� linewidth�characterheight� and characterfont� Text is NOT subject toclipping at the edge of the window�ArgumentsX �input� world xcoordinate�Y �input� world ycoordinate� The string is drawn with the

baseline of all the characters passing throughpoint �X�Y�� the positioning of the string alongthis line is controlled by argument FJUST�

ANGLE �input� angle� in degrees� that the baseline is to makewith the horizontal� increasing counterclockwise�� is horizontal��

FJUST �input� controls horizontal justification of the string�If FJUST � �� the string will be leftjustifiedat the point �X�Y�� if FJUST � �� it will becentered� and if FJUST � �� it will be rightjustified� �Other values of FJUST give otherjustifications��

TEXT �input� the character string to be plotted�

A�� PGQCF � inquire character font

SUBROUTINE PGQCF �IF�INTEGER IF

Query the current Character Font �set by routine PGSCF��ArgumentIF �output� the current font number �in range ��

A�� PGQCH � inquire character height

SUBROUTINE PGQCH �SIZE�REAL SIZE

Query the Character Size attribute �set by routine PGSCH��ArgumentSIZE �output� current character size �dimensionless multiple of

the default size��


A�� PGQCI � inquire color index

SUBROUTINE PGQCI �CI�INTEGER CI

Query the Color Index attribute �set by routine PGSCI��ArgumentCI �output� the current color index �in range �max�� This is

the color index actually in use� and may differfrom the color index last requested by PGSCI ifthat index is not available on the output device�

A�� PGQCOL � inquire color capability

SUBROUTINE PGQCOL �CI � CI��INTEGER CI � CI�

Query the range of color indices available on the current device�ArgumentCI �output� the minimum available color index� This will be

either � if the device can write in thebackground color� or if not�

CI� �output� the maximum available color index� This will be if the device has no color capability� or alarger number �e�g��

A�� PGQCR � inquire color representation

PGQCR not yet available�

A�� PGQFS � inquire �ll area style

SUBROUTINE PGQFS �FS�INTEGER FS

Query the current FillArea Style attribute �set by routinePGSFS��ArgumentFS �output� the current fillarea style

FS � �� solid �default�FS � � �� hollow


A�� PGQINF � inquire PGPLOT general information

SUBROUTINE PGQINF �ITEM� VALUE� LENGTH�CHARACTER�� ITEM� VALUEINTEGER LENGTH

This routine can be used to obtain miscellaneous information aboutthe PGPLOT environment� Input is a character string defining theinformation required� and output is a character string containing therequested information�The following item codes are accepted �note that the strings mustmatch exactly� except for case� but only the first � characters aresignificant�� For items marked �� PGPLOT must be in the OPEN statefor the inquiry to succeed� If the inquiry is unsuccessful� eitherbecause the item code is not recognized or because the informationis not available� a question mark �� is returned��VERSION� version of PGPLOT software in use��STATE� status of PGPLOT ��OPEN� if a graphics device

is open for output� �CLOSED� otherwise��USER� the username associated with the calling program��NOW� current date and time �e�g�� FEB !�� DEVICE� � current PGPLOT device or file��FILE� � current PGPLOT device or file��TYPE� � devicetype of the current PGPLOT device��DEV�TYPE� � current PGPLOT device and type� in a form which

is acceptable as an argument for PGBEG��HARDCOPY� � is the current device a hardcopy device� ��YES� or

�NO��TERMINAL� � is the current device the user�s interactive

terminal� ��YES� or �NO��CURSOR� � does the current device have a graphics cursor�

��YES� or �NO��ArgumentsITEM �input� character string defining the information to

be returned� see above for a list of possiblevalues�

VALUE �output� returns a characterstring containing therequested information�

LENGTH �output� the number of characters returned in VALUE�VALUE is padded with spaces to the lengthsupplied��

A�� PGQLS � inquire line style

SUBROUTINE PGQLS �LS�INTEGER LS

Query the current Line Style attribute �set by routine PGSLS��ArgumentLS �output� the current linestyle attribute �in range ��


A�� PGQLW � inquire line width

SUBROUTINE PGQLW �LW�INTEGER LW

Query the current LineWidth attribute �set by routine PGSLW��ArgumentLW �output� the linewidth �in range � ��

A�� PGQPOS � inquire current pen position

SUBROUTINE PGQPOS �X� Y�REAL X� Y

Query the current �pen� position in world C coordinates �X�Y��ArgumentsX �output� world xcoordinate of the pen position�Y �output� world ycoordinate of the pen position�

A�� PGQVP � inquire viewport size and position

SUBROUTINE PGQVP �UNITS� X � X�� Y � Y��INTEGER UNITSREAL X � X�� Y � Y�

Inquiry routine to determine the current viewport setting�The values returned may be normalized device coordinates� inches� mm�or pixels� depending on the value of the input parameter CFLAG�ArgumentsUNITS �input� used to specify the units of the output parameters

UNITS � � normalized device coordinatesUNITS � inchesUNITS � � millimetersUNITS � � pixelsOther values give an error message� and aretreated as ��

X �output� the xcoordinate of the bottom left corner of theviewport�

X� �output� the xcoordinate of the top right corner of theviewport�

Y �output� the ycoordinate of the bottom left corner of theviewport�

Y� �output� the ycoordinate of the top right corner of theviewport�


A�� PGQWIN � inquire window boundary coordinates

SUBROUTINE PGQWIN �X � X�� Y � Y��REAL X � X�� Y � Y�

Inquiry routine to determine the current window setting�The values returned are world coordinates�ArgumentsX �output� the xcoordinate of the bottom left corner

of the window�X� �output� the xcoordinate of the top right corner

of the window�Y �output� the ycoordinate of the bottom left corner

of the window�Y� �output� the ycoordinate of the top right corner

of the window�

A�� PGRECT � draw a rectangle� using �ll area attributes

SUBROUTINE PGRECT �X � X�� Y � Y��REAL X � X�� Y � Y�

This routine can be used instead of PGPOLY for the special case ofdrawing a rectangle aligned with the coordinate axes� only twovertices need be specified instead of four� On most devices� it isfaster to use PGRECT than PGPOLY for drawing rectangles� Therectangle has vertices at �X �Y �� X �Y�� X��Y�� and �X �Y��ArgumentsX � X� �input� the horizontal range of the rectangle�Y � Y� �input� the vertical range of the rectangle�

A�� PGRND � �nd the smallest �round� number greater than x

REAL FUNCTION PGRND �X� NSUB�REAL XINTEGER NSUB

Rooutine to find the smallest �round� number larger than x� a�round� number being � � or � times a power of �� If X is negative�PGRND�X� � PGRND�ABS�X�� eg PGRND�� PGRND�� If X is zero� the value returned is zero�CThis routine is used by PGBOX for choosing tick intervals�ReturnsPGRND the �round� number�

ArgumentsX �input� the number to be rounded�NSUB �output� a suitable number of subdivisions for

subdividing the �nice� number � or ��


A�� PGRNGE � choose axis limits

SUBROUTINE PGRNGE �X � X�� XLO� XHI�REAL X � X�� XLO� XHI

Choose plotting limits XLO and XHI which encompass the datarange X to X��ArgumentsX � X� �input� the data range �X �X�� ie� the min and max values

to be plotted�XLOXHI �output� suitable values to use as the extremes of a graph

axis �XLO �� X � XHI �� X��

A�� PGSCF � set character font

SUBROUTINE PGSCF �IF�INTEGER IF

Set the Character Font for subsequent text plotting� Four differentfonts are available �default� a simple singlestroke font ��normal� font�� roman font� italic font� script font

This call determines which font is in effect at the beginning ofeach text string� The font can be changed �temporarily� within a textstring by using the escape sequences �fn� �fr� �fi� and �fs for fonts � �� and �� respectively�ArgumentIF �input� the font number to be used for subsequent text

plotting �in range ��

A�� PGSCH � set character height

SUBROUTINE PGSCH �SIZE�REAL SIZE

Set the character size attribute� The size affects all text and graphmarkers drawn later in the program� The default character size is �� corresponding to a character height about �� the height ofthe view surface� Changing the character size also scales the lengthof tick marks drawn by PGBOX and terminals drawn by PGERRX and PGERRY�ArgumentSIZE �input� new character size �dimensionless multiple of

the default size��


A�� PGSCI � set color index

SUBROUTINE PGSCI �CI�INTEGER CI

Set the Color Index for subsequent plotting� if the output devicepermits this� The default color index is � usually white on a blackbackground for video displays or black on a white background forprinter plots� The color index is an integer in the range � to adevicedependent maximum� Color index � corresponds to the backgroundcolor� lines may be �erased� by overwriting them with color index ��if the device permits this��If the requested color index is not available on the selected device�color index will be substituted�The assignment of colors to color indices can be changed withsubroutine PGSCR �set color representation�� Color indices � �have predefined color representations �see the PGPLOT manual�� butthese may be changed with PGSCR� Color indices above � have nopredefined representations if these indices are used� PGSCR mustbe called to define the representation�ArgumentCI �input� the color index to be used for subsequent plotting

on the current device �in range �max�� If theindex exceeds the devicedependent maximum� thedefault color index � � is used�

A�� PGSCR � set color representation

SUBROUTINE PGSCR �CI� CR� CG� CB�INTEGER CIREAL CR� CG� CB

Set color representation i�e�� define the color to beassociated with a color index� Ignored for devices which do notsupport variable color or intensity� Color indices � �have predefined color representations �see the PGPLOT manual�� butthese may be changed with PGSCR� Color indices �maximum have nopredefined representations if these indices are used� PGSCR mustbe called to define the representation� On monochrome outputdevices �e�g� VT �� terminals with monochrome monitors�� themonochrome intensity is computed from the specified Red� Green� Blueintensities as ��R � ��!�G � �� B� as in US color televisionsystems� NTSC encoding� Note that most devices do not have aninfinite range of colors or monochrome intensities available�the nearest available color is used� Examples for black�set CR�CG�CB�� for white� set CR�CG�CB� �� for medium gray�set CR�CG�CB�� for medium yellow� set CR�CG�� CB��ArgumentCI �input� the color index to be defined� in the range �max�

If the color index greater than the devicemaximum is specified� the call is ignored� Colorindex � applies to the background color�

CR �input� red� green� and blue intensities�CG �input� in range �� to ��CB �input�


A�� PGSFS � set �ll area style

SUBROUTINE PGSFS �FS�INTEGER FS

Set the FillArea Style attribute for subsequent areafill byPGPOLY� At present only two styles are available solid �fillpolygon with solid color of the current colorindex�� and hollow�draw outline of polygon only� using current line attributes��ArgumentFS �input� the fillarea style to be used for subsequent

plottingFS � �� solid �default�FS � � �� hollow

Other values give an error message and aretreated as ��

A�� PGSHLS � set color representation using HLS system

SUBROUTINE PGSHLS �CI� CH� CL� CS�INTEGER CIREAL CH� CL� CS

Set color representation i�e�� define the color to beassociated with a color index� This routine is equivalent toPGSCR� but the color is defined in the HueLightnessSaturationmodel instead of the RedGreenBlue model�Reference SIGGRAPH Status Report of the Graphic Standards PlanningCommittee� Computer Graphics� Vol� �� No�� Association forComputing Machinery� New York� NY� ! !�ArgumentCI �input� the color index to be defined� in the range �max�

If the color index greater than the devicemaximum is specified� the call is ignored� Colorindex � applies to the background color�

CH �input� hue� in range �� to ��CL �input� lightness� in range �� to ��CS �input� saturation� in range �� to ��

A� PGSLS � set line style

SUBROUTINE PGSLS �LS�INTEGER LS

Set the line style attribute for subsequent plotting� Thisattribute affects line primitives only� it does not affect graphmarkers� text� or area fill�Five different line styles are available� with the following codes �full line�� dashed�� dotdashdotdash�� dotted�� dashdotdotdot�� The default is �normal full line��ArgumentLS �input� the linestyle code for subsequent plotting

�in range ��


A� PGSLW � set line width

SUBROUTINE PGSLW �LW�INTEGER LW

Set the linewidth attribute� This attribute affects lines� graphmarkers� and text� Thick lines are generated by tracing each linewith multiple strokes offset in the direction perpendicular to theline� The line width is specified by the number of strokes to beused� which must be in the range �� The actual line widthobtained depends on the device resolution�ArgumentLW �input� the number of strokes to be used

�in range ��

A�� PGSVP � set viewport �normalized device coordinates�

SUBROUTINE PGSVP �XLEFT� XRIGHT� YBOT� YTOP�REAL XLEFT� XRIGHT� YBOT� YTOP

Change the size and position of the viewport� specifyingthe viewport in normalized device coordinates� Normalizeddevice coordinates run from � to in each dimension� Theviewport is the rectangle on the view surface �through�which one views the graph� All the PG routines which plot linesetc� plot them within the viewport� and lines are truncated atthe edge of the viewport �except for axes� labels etc drawn withPGBOX or PGLAB�� The region of world space �the coordinatespace of the graph� which is visible through the viewport isspecified by a call to PGSWIN� It is legal to request aviewport larger than the view surface� only the part whichappears on the view surface will be plotted�ArgumentsXLEFT �input� xcoordinate of left hand edge of viewport� in NDC�XRIGHT �input� xcoordinate of right hand edge of viewport�

in NDC�YBOT �input� ycoordinate of bottom edge of viewport� in NDC�YTOP �input� ycoordinate of top edge of viewport� in NDC�


A�� PGSWIN � set window

SUBROUTINE PGSWIN �X � X�� Y � Y��REAL X � X�� Y � Y�

Change the window in world coordinate space that is to be mapped onto the viewport� Usually PGSWIN is called automatically by PGENV�but it may be called directly by the user�ArgumentsX �input� the xcoordinate of the bottom left corner

of the viewport�X� �input� the xcoordinate of the top right corner

of the viewport �note X� may be less than X ��Y �input� the ycoordinate of the bottom left corner

of the viewport�Y� �input� the ycoordinate of the top right corner

of the viewport �note Y� may be less than Y ��

A�� PGTBOX � Draw a box and optionally write HH MM SS style numeric labelling�

SUBROUTINE PGTBOX �XOPT� XTICKD� NXSUBD� YOPT� YTICKD� NYSUBD�REAL XTICKD� YTICKDINTEGER NXSUBD� NYSUBDCHARACTER XOPT�� YOPT��

Draw a box and optionally label one or both axes with HH MM SS stylenumeric labels �useful for time or RA DEC plots�� Should deal withaxes that increase or decrease� and are positive or negative� or both�If the HH MM SS labelling is desired� then PGSWIN should have beenpreviously called with the extrema in SECONDS�InputsXOPT Xoptions for PGBOX� Same as for PGBOX plus �Z� for time

labelling� and �F� means write only the last part of thelabel for the first time tick on the axis� E�g�� ifthe full first label is �� then write only ��

YOPT Yoptions for PGBOX� Same as for PGBOX plus �Z� and �F�XTICKD Xaxis major tick increment� Use �� to get default�YTICKD Yaxis major tick increment� Use �� to get default�NXSUB Number of intervals for minor ticks on Xaxis� Use � for defaultNYSUB Number of intervals for minor ticks on Yaxis� Use � for default


A�� PGTEXT � write text �horizontal� left justi�ed�

SUBROUTINE PGTEXT �X� Y� TEXT�REAL X� YCHARACTER�� TEXT

Write text� The bottom left corner of the first character is placedat the specified position� and the text is written horizontally�This is a simplified interface to the primitive routine PGPTXT�For nonhorizontal text� use PGPTXT�ArgumentsX �input� world xcoordinate of start of string�Y �input� world ycoordinate of start of string�TEXT �input� the character string to be plotted�

A�� PGUPDT � update display

SUBROUTINE PGUPDTUpdate the graphics display flush any pending commands to theoutput device� This routine empties the buffer created by PGBBUF�but it does not alter the PGBBUF�PGEBUF counter� The routine shouldbe called when it is essential that the display be completely up todate �before interaction with the user� for example� but it is notknown if output is being buffered�Arguments none

A�� PGVPORT � non standard alias for PGSVP

SUBROUTINE PGVPORT �XLEFT� XRIGHT� YBOT� YTOP�REAL XLEFT� XRIGHT� YBOT� YTOP


A�� PGVSIZ � set viewport �inches�

SUBROUTINE PGVSIZ �XLEFT� XRIGHT� YBOT� YTOP�REAL XLEFT� XRIGHT� YBOT� YTOP

Change the size and position of the viewport� specifyingthe viewport in physical device coordinates �inches�� Theviewport is the rectangle on the view surface �through�which one views the graph� All the PG routines which plot linesetc� plot them within the viewport� and lines are truncated atthe edge of the viewport �except for axes� labels etc drawn withPGBOX or PGLAB�� The region of world space �the coordinatespace of the graph� which is visible through the viewport isspecified by a call to PGSWIN� It is legal to request aviewport larger than the view surface� only the part whichappears on the view surface will be plotted�ArgumentsXLEFT �input� xcoordinate of left hand edge of viewport� in

inches from left edge of view surface�XRIGHT �input� xcoordinate of right hand edge of viewport� in

inches from left edge of view surface�YBOT �input� ycoordinate of bottom edge of viewport� in

inches from bottom of view surface�YTOP �input� ycoordinate of top edge of viewport� in inches

from bottom of view surface�

A�� PGVSIZE � non standard alias for PGVSIZ

SUBROUTINE PGVSIZE �XLEFT� XRIGHT� YBOT� YTOP�REAL XLEFT� XRIGHT� YBOT� YTOP

A� PGVSTAND � non standard alias for PGVSTD

SUBROUTINE PGVSTAND

A� PGVSTD � set standard �default� viewport

SUBROUTINE PGVSTDDefine the viewport to be the standard viewport� The standardviewport is the full area of the view surface �or subpage��less a margin of � character heights all round for labelling�It thus depends on the current character size� set by PGSCH�Arguments none�


A�� PGWINDOW � non standard alias for PGSWIN

SUBROUTINE PGWINDOW �X � X�� Y � Y��REAL X � X�� Y � Y�

A�� PGWNAD � set window and adjust viewport to same aspect ratio

SUBROUTINE PGWNAD �X � X�� Y � Y��REAL X � X�� Y � Y�

Change the window in world coordinate space that is to be mapped onto the viewport� and simultaneously adjust the viewport so that theworldcoordinate scales are equal in x and y� The new viewport isthe largest one that can fit within the previously set viewportwhile retaining the required aspect ratio�ArgumentsX �input� the xcoordinate of the bottom left corner

of the viewport�X� �input� the xcoordinate of the top right corner

of the viewport �note X� may be less than X ��Y �input� the ycoordinate of the bottom left corner

of the viewport�Y� �input� the ycoordinate of the top right corner of the

viewport �note Y� may be less than Y ��

Appendix B

PGPLOT SYMBOLS

The PGPLOT primitive subroutines PGPOINT and PGPTEXT are usedfor drawing symbols �graph markers� and strings of symbols �text�� Theavailable symbols are listed in this appendix� The total number of di�erentsymbols available is about �� Each symbol is composed of a set of vectors�based on digitized type fonts devised by A� V� Hershey of the US NavalPostgraduate School� and each symbol is assigned a number in the range�� PGPLOT uses the ASCII code for representing graph markers andsymbols� ASCII codes �� are used for the graph markers� and codes�� are used for the standard ASCII printable characters� The font�switching and escape mechanisms described in Chapters and � can beused to enlarge the available character set�

Table B�� shows the graphical representation of all the available symbolsarranged according to Hershey�s numerical sequence� the blank spaces in thistable represent �space� characters of various widths� Note that not everynumber has an associated character� Any character can be inserted in atext string using an escape sequence of the form ��n�� where n is the �digitHershey number�

B�� PGPLOT SYMBOLS

Table B�� PGPLOT Character Set

PGPLOT SYMBOLS B��

Table B�� continued�

B� PGPLOT SYMBOLS


Appendix C�

INSTALLATION INSTRUCTIONS �VMS�

C�� Introduction

PGPLOT consists of four �layers� of subroutines� The subroutines in eachlayer call only subroutines in the same layer or in the next layer down

�� The top�level PGPLOT subroutines� these routines call only other PG�PLOT routines�

�� The �primitive� PGPLOT routines� these are used by the top�level rou�tines and can be called by users� programs� They call the routines atthe next level to perform graphical output�

�� Device�independent support routines� These are responsible for thingslike scaling� windowing� and character�generation�

� Device handler routines these generate graphical output for speci�cdevice types� There is one device handler subroutine for each supporteddevice type�

Routines at levels � and � are the only ones that should be referenceddirectly by a user�s program� They are all described fully in Appendix A�

C�� Restoring the Save Set

PGPLOT is usually distributed in the form of a VAXVMS BACKUP saveset on magnetic tape� This save set contains a directory tree the maindirectory� "PGPLOT#� and several subdirectories "PGPLOT�DRIVERS#�"PGPLOT�EXAMPLES#� "PGPLOT�FONTS#� "PGPLOT�MANUAL#� and"PGPLOT�SOURCE#� The save set should be restored to a similar directorytree� The following example indicates how the VMS BACKUP commandcan be used to copy the �les into directories called "USER�PGPLOT# and"USER�PGPLOT�$#� It is a good idea to make sure that these destinationdirectories either do not exist or are empty before beginning the BACKUPcommand�

� MOUNT�FOREIGN MTA � PGPLOT

� BACKUP�LOG�VERIFY MTA �PGPLOT�BCK�SELECT��PGPLOT��

DISK��USER�PGPLOT��

� DISMOUNT MTA �

C�� INSTALLATION INSTRUCTIONS �VMS

The main directory� "PGPLOT#� contains all the �les needed to linkand run PGPLOT programs� The subdirectories contain the source code�example programs� utility programs� and documentation�

The directory "PGPLOT# includes

�� Object code the object�module library GRPCKG�OLB� the shareableimage GRPSHR�EXE� and the shareable�image symbol�table libraryGRPSHR�OLB�

�� Command procedures LOGICAL�COM and MAKEHELP�COM� Theseprocedures are described below�

�� Documentation PGPLOT�DOC is the text of the subroutine synopsesin Appendix A� PGPLOT�HLB is a VMS�format HELP library contain�ing the same information�

� Miscellaneous DOCUMENT�FOR� DOCUMENT�EXE �used in creat�ing documentation�� GRFONT�DAT �binary representation of the PG�PLOT character set�� GMFPLOT�FOR and GMFPLOT�EXE �meta�letranslator�� PGATTRIB�FOR �a Fortran include �le de�ning symbolicnames for the various PGPLOT attribute codes��

The directory "PGPLOT�DRIVERS# contains source code for device�handler subroutines that are not included in the executable version of PG�PLOT as distributed� Instructions for incorporating these device handlersin the executable version are given below� Adding support for a new devicetype requires the addition of a new device handler subroutine� No otherchanges to PGPLOT are required� For details� consult Appendix E�

The directory "PGPLOT�EXAMPLES# contains a number of programsfor demonstrating and testing PGPLOT� The source code is in �les PGEX��FOR� PGEX��FOR� etc�� and executable code in PGEX��EXE� etc�� Thecommand procedure EXCOMP�COM can be used to recompile and link oneor all of the example programs�

The directory "PGPLOT�FONTS# contains some utility programs formanipulating the binary �le containing character de�nitions �font informa�tion�� This directory can be deleted if you do not want to edit the characterset�

The directory "PGPLOT�MANUAL# contains the text of this PGPLOTmanual �in TEX format� and Fortran programs for creating the �gures� Thisdirectory can be deleted if you do not wish to print copies of the manual� orif you do not have the TEX document formatting program�

The directory "PGPLOT�SOURCE# contains the complete source codefor PGPLOT� including the device handlers built in to the distribution ver�sion� PGPLOT�FOR contains the Fortran source code for routines in levels� and �� all these routines have names beginning with PG� GRPCKG�FOR�GRCHAR�FOR� GRSYMB�FOR� and GRVMS�FOR contain the source code

INSTALLATION INSTRUCTIONS �VMS C��

for routines in level �� The �le GRVMS�FOR contains system�dependent rou�tines which will have to be rewritten for a di�erent operating system� Thevarious �les $DRIVER�FOR contain the source code for the level� devicehandlers� All the routines in level � have names beginning with GR� The�les PGPLOT�INC and GRPCKG��INC are referenced by VAX FortranINCLUDE statements in PGPLOT�FOR and GRPCKG�FOR� respectively�The command procedures ADD�COM� BUILD�COM� COMPILE�COM� andNEWGE�COM are used to rebuild PGPLOT from the source code �see be�low��

C�� Logical Names

A number of VMS logical names must be de�ned before PGPLOT can beused� The procedure LOGICAL�COM will de�ne these logical names� but itmay be necessary to modify it slightly� A possible de�nition is the following

� DEFINE�SYSTEM PGPLOT�DIR SYS��PGPLOT�

� DEFINE�SYSTEM LNK�LIBRARY PGPLOT�DIR�GRPSHR�OLB

� DEFINE�SYSTEM PGPLOT�TYPE PRINTRONIX

� DEFINE�SYSTEM PGPLOT�FONT PGPLOT�DIR�GRFONT�DAT� DEFINE�SYSTEM GRPSHR PGPLOT�DIR�GRPSHR�EXE

It is not essential that they be �system� logical names�

�� PGPLOT�DIR� This is a logical name pointing to the directory contain�ing the PGPLOT �les� The name need not be PGPLOT�DIR� anothername can be chosen� so long as the other logical names are modi�edaccordingly�

�� LNK�LIBRARY� This is optional� It tells the VMS linker to automat�ically scan GRPSHR�OLB for subroutine references� If LNK�LIBRARYis already de�ned� choose another name like LNK�LIBRARY�� see theVAXVMS Linker manual��

�� PGPLOT�TYPE� This is optional� It provides a default device type for useby PGPLOT when no device type is provided explicitly by the user�

� PGPLOT�FONT� This is essential� Whenever a PGPLOT program is run�it attempts to read the character�set de�nition from the �le de�ned bythis logical name� �If it fails� the program will continue� but requests toplot text or graph markers will be ignored��

�� GRPSHR� This logical name must be de�ned at run�time if the shareable�image version of PGPLOT is used �see below��


C�� The Shareable Image

Programs using the PGPLOT library can be linked in two di�erent ways

� LINK EXAMPLE�PGPLOT�DIR�GRPSHR�LIB

� LINK EXAMPLE�PGPLOT�DIR�GRPCKG�LIB

Usually the �rst library �GRPSHR�OLB� should be used� When this library isused� the subroutines are not included in the �EXE �le� but are fetched froma shareable image when you execute the RUN command� This makes the �EXE�le much smaller� and means that the program need not be relinked whenchanges are made to the graphics subroutines� but the �EXE �le can only berun on a machine which has a copy of the shareable image� If the secondlibrary �GRPCKG�OLB� is used� the subroutines are included in the �EXE �leand the program can be run on any VAX computer running a compatibleversion of VMS� In general� the shareable image is to be preferred�

C�� Recompiling PGPLOT

To recompile PGPLOT� proceed as follows�

�� In directory �PGPLOT�SOURCE� make sure that the source code forall the device handlers you wish to include is in this directory ��les�DRIVER�FOR�� Device handlers that you do not wish to include shouldbe moved to directory �PGPLOT�DRIVERS��

�� Execute the DCL command procedure COMPILE�COM� This compiles allthe Fortran �les in the directory� and creates a new version of the object�module library GRPCKG�OLB� See the comments in the procedure for moreinformation�

�� The shareable image� GRPSHR�EXE� and shareable�image symbol�tablelibrary� GRPSHR�OLB� can be rebuilt from GRPCKG�OLB by executing thecommand procedure BUILD�COM� Again� see the comments in the pro�cedure for more information� �Note do not modify the symbol tablede�ned in BUILD�COM� if you do� the resulting programs will not beportable��

� You can now delete all the object module �les ��OBJ� if you wish�

�� The new version of PGPLOT consists of three �les GRPCKG�OLB� GRP�SHR�EXE� and GRPSHR�OLB� It is possible to test the new version byrede�ning logical name GRPSHR to point to the new GRPSHR�EXE� If youare satis�ed with the new version� rename �or copy� these three �lesinto the main directory� �PGPLOT�� superseding the old version�

INSTALLATION INSTRUCTIONS �VMS C��

C�� Recompiling the Example Programs

The procedure EXCOMP�COM in directory �PGPLOT�EXAMPLES� can be used tocompile and link any of the example programs

� �EXCOMP �

� �EXCOMP

The �rst command compiles PGEX�� The second compiles all the exampleprograms�

C�� Rebuilding the Documentation Files

The �les PGPLOT�DOC and PGPLOT�HLB contain documentation extractedfrom the PGPLOT source code� The �les can be rebuilt by executing theprocedure MAKEHELP�COM in directory �PGPLOT�� This procedure also up�dates the TEX version of the documentation included in Appendix A of themanual�

C�� Printing the Manual

The TEX source�code for the PGPLOT manual can be found in the subdi�rectory �PGPLOT�MANUAL� in a number of �les with type �TEX� These �lescan be used to make a printable copy of the manual if you have the TEXtext�formatting program

� TEX PGPLOT

The �le PGPLOT�TEX contains TEX �input commands that reference theother �TEX �les� Please do not modify the TEX �les send your commentsand bug reports to the author�

The �gures in the manual were generated using PGPLOT subroutines�The Fortran programs used to generate them can also be found in the �PG�PLOT�MANUAL� directory�


C�� Adding a new PGPLOT routine

The author is happy to receive contributions of new high�level routines forinclusion in PGPLOT� Some general guidelines should be observed whenpreparing such routines

�� The routine should be written �as far as possible� in standard Fortran��

�� The routine should call only other PGPLOT routines� or special supportroutines provided along with it� It should not use routines from otherlibraries �especially commercial ones�� Note that if it is to be installedin the shareable library� it cannot use common blocks for communicationwith the program that calls it� It may� if necessary� use common blocksto communicate with other PGPLOT routines� but this is discouraged�

�� It should be modular that is� it should avoid� as far as possible� makingassumptions about the environment it is to run in� or modifying thatenvironment� In particular if it changes any attribute �e�g�� color index�it should save the previous value of that attribute �obtained by callinga PGQ�� routine� and reset it before exiting� it should not change thewindow or viewport� but if it must� it should restore the old valuesbefore exiting� it should not call PGBEGIN or PGEND�

� It should call routine PGBBUF at the beginning� and PGEBUF before exit�ing� in order to bu�er its output�

�� It should provide a generally useful function rather than a highly speci�cone� with as many parameters as possible accessible to the user �e�g�� asarguments� rather than �xed in the program�

Appendix C�

INSTALLATION INSTRUCTIONS �UNIX�

C�� Introduction

All UNIX systems are di�erent� so the installation procedure described heremay not work on your system� and some editing and debugging may berequired� Please read all the installation instructions before attempting toinstall PGPLOT� I �rst describe the installation procedure which I have usedon our systems �Convex and Sun�� I hope it will work on other Berkeley�derived UNIX systems� If you have trouble with the installation� you shouldread Section C�� which is intended to provide su�cient background infor�mation for you to adapt PGPLOT to a di�erent system�

The UNIX version of PGPLOT is distributed in source form on a %tar�tape �usually a ��track� ��bpi tape��

C�� Basic Installation

The following installation procedure has been run on a Convex C�� runningVersion �� or �� of the Convex operating system with Fortran compilerFC Version �� or �� and on Sun�� and Sun� workstations running SunOSRelease �� with Sun Fortran Release �� It does not work with earlierversions of the Convex Fortran compiler� the Sun operating system� or theSun Fortran compiler�

�� Copy the �les from the distribution tape to your disk� The �les are orga�nized in three directories pgplot� pgplot�examples� and pgplot�fonts�To copy the �les from the %tar� tape� you should �rst change your defaultdirectory to the parent directory of pgplot� and use a command like thefollowing

tar xv pgplot

This will create a pgplot directory in your current directory and installthe PGPLOT �les in it� �If you already have a pgplot directory� removeit �rst�� If you are not using %tar� but are copying the �les from anothersystem� make sure that you put the �les in the correct directories�

C�� INSTALLATION INSTRUCTIONS �UNIX

�� Compile the PGPLOT subroutines and create the PGPLOT object li�brary� Change your default directory to PGPLOT and then use %make�to do the compilation� The distribution tape contains two %make�les�� onefor Convex �Makefile�CONVEX� and one for Sun �Makefile�SUN�� You canrename the appropriate �le to Makefile� or use the �f option of %make�

cd pgplot

make �f Makefile�SUN

If all goes well� you should get no error messages from the compilation� �TheSUN Fortran compiler issues an incorrect warning message that MOD is anunused variable when compiling grre and grte � you can ignore thismessage��

�� Build the binary font �le� The font �le �read at run time by PGPLOTprograms� is distributed in an ASCII text form in �le grfont�txt and mustbe converted to binary form before use� This is done using the %make�le� inthe fonts directory� again there are separate versions for Convex and Sun

cd fonts

make �f Makefile�SUN grfont�dat

This compiles a program pgpack to do the conversion and then runs it� Itshould display a message like the following

Characters defined� ��

Array cells used� ��

You now need to de�ne an environment variable that de�nes the location ofthe binary font �le� e�g�

setenv PGPLOT�FONT �usr�name�pgplot�fonts�grfont�dat

Substitute the appropriate path for �usr�name�pgplot� or while you are inthe fonts directory� type

setenv PGPLOT�FONT �pwd��grfont�dat

The fonts directory also contains utility programs pgunpack and pgdchar

that you will need only if you plan to modify the font �le �not recommended��

� Compile the test and demonstration programs in the examples directory�Again there there are separate %make�les� for Convex and Sun

cd ��examples

make �f Makefile�SUN

INSTALLATION INSTRUCTIONS �UNIX C��

At this point� you may run out of disk space �if you haven�t done already�as the executable programs are rather large� If necessary� you can compilethe programs one at a time� e�g�

make �f Makefile�SUN pgdemo�

to compile program pgdemo�� The two demonstration programs pgdemo�and pgdemo� each generate several screens �pages� illustrating the use of PG�PLOT subroutines� There is also a general test program� pgex�� describedin Appendix E� and two test programs for the cursor routines� pgex�� andpgex��

�� Run at least one of the test programs� e�g� pgdemo��

pgdemo�

The program will prompt for a device speci�cation� Type a question mark� to get a list of available device handlers� Read the PGPLOT manual fordetails of device speci�cations� and the remainder of this Appendix for noteson the available device handlers� Run the program once for each device thatyou wish to test� I hope that all will go well� if not� read the next section�The commonest problem is that you get graphs with no text� This impliesthat the program cannot read the font �le �you should also get a messageto this e�ect�� Check the de�nition of PGPLOT�FONT �see above��

�� If everything so far looks all right� you can move the �les to their ��nal destinations �this may require superuser privilege and the cooperationof your system manager�� You need to keep two �les the object librarypgplot�libpgplot�a and the binary font �le pgplot�fonts�grfont�dat�Everything else can be deleted if you want to conserve disk space� it canalways be recovered from the distribution tape� The object library should�ideally� be moved to the directory where the loader expects to �nd libraries�usually �usr�lib

cd pgplot

cp libpgplot�a �usr�lib

You can then use �lpgplot with ld or your Fortran compiler to link a pro�gram with the PGPLOT library� The location of the font �le is arbitrary� butas distributed� PGPLOT expects to �nd it in �usr�local�lib�grfont�dat

cd fontscp grfont�dat �usr�local�lib

If you want to put it in some other location� you can either de�ne PG�

PLOT�FONT every time you use a PGPLOT program �see above�� or modify


the default location by editing �le pgplot�grsy �f and recompiling �seestep �� Note that if you modify any PGPLOT routine� you will have toremodify it each time you install a new version of PGPLOT��

�� Finally� you should attempt to compile and link a PGPLOT program ofyour own� On Convex

fc �o program program�f �lpgplot

On Sun

f�� o program program�f �lpgplot �lsuntool �lcgi�� lcgi�

�lsunwindow �lpixrect �lm

Note that the Sun version requires all the above libraries to be included�in the order indicated �assuming that the SUNVIEW and CGI devicehandlers are included� as they are in the distribution tape��

C�� Advanced Installation

This section addresses problems that you may encounter trying to installPGPLOT on a di�erent UNIX system� and indicates what options are opento you to solve them�

Examine the %make�les� in the pgplot directory and make sure thatyou understand what they do� In particular� you may need to change thede�nitions of the Fortran compiler and compilation switches�

The subroutines are organized into several groups in the %make�le�

�� PG routines� These are the top level PGPLOT routines that can becalled by application programs� plus a few internal routines� They areidentical to the VMS version� and are written in standard Fortran��I believe� with two exceptions� the INCLUDE statement and the use ofsubroutines names longer than � characters� The former can be avoidedby use of a preprocessor or by hand�editing the code to replace eachINCLUDE statement with the text of the included �le� the latter is fun�damental to PGPLOT� but you might try truncating names to � char�acters�

�� GR routines� These are internal routines� They are also supposed tobe standard Fortran�� but there are a few problems� As in the PGroutines� some subroutine names are longer than � characters� and theINCLUDE statement is used� A large array BUFFER used in grsy �f

and grsyxd�f is declared INTEGER�� to save space both internally andin the binary font �le �the array is just a copy of the disk �le�� if youchange it to INTEGER� you must make the same change in the pgpack


program in the fonts directory� Routine grgrps�f uses a hexadecimalformat code �Z�� which is non�standard�

�� Drivers� Each device handler is a subroutine with a name like xxdriv�for device xx�� The %make�le� lists the additional subroutines requiredfor each handler� The DRIVERS macro lists all the device handlers tobe included in the �nal library� You customize PGPLOT by changingthe list assigned to DRIVERS� The device handlers are not written instandard Fortran�� although I have tried to adhere to the standardwhere possible� Please let me know what problems you have� Someof the handlers call on subroutines written in C rather than Fortran�The conventions for writing a C subroutine to be called from a Fortranprogram are di�erent on di�erent systems �it may not even be possible��Thus you may need to do a lot of work to get each handler going� Butnote that you don�t need to have all the handlers running in order totest PGPLOT� It is su�cient to include just the null device handler�which is written in standard Fortran�� See below for notes on eachhandler��

� Dispatch routine� The routine grexec must be modi�ed to include thelist of device handlers you wish to include in PGPLOT� Two di�erentversions are provided on the distribution tape� one for Convex and onefor Sun� It is a simple multi�way GOTO �CASE statement�� one branch foreach handler� Eventually this routine will be assembled automaticallyduring the installation procedure� but at present you must edit it byhand�

�� System routines� These routines� called from all levels of PGPLOT�encapsulate various operating�system dependent functions� If you havetrouble with these routines� you will need to write new versions� I hopethat the internal comments are su�cient to explain what each routineis supposed to do� The version distributed calls on a number of Fortranlibrary functions which are normally part of Berkeley�UNIX but whichmay not be present in other varieties �e�g�� getenv� getlog� hostnm��

�� Obsolete routines� This group includes a number of routines that areno longer an o�cial part of PGPLOT� but they may be called by someold PGPLOT application programs� If you have such programs� I rec�ommend you rewrite them� but if necessary you can compile an ad�ditional library containing these routines by the command make �f

Makefile�SUN libpgobs�a �


C�� Device Handlers

The UNIX version of PGPLOT is distributed with a much smaller set ofdevice handlers than the VMS version� If you modify any of the devicehandlers or write new ones� please �a� try to keep them as portable aspossible� and �b� send copies to me so that I can include them in futuredistributions� See Appendix E for instructions on writing a device handler�

Null device The null device handler is nudriv� Use device speci�cation�NULL� Output sent to the null device is discarded� i�e�� PGPLOT producesno output� This device handler is fully portable�

SunView �Sun only� File svdriv is a �rst attempt at a handler for Sunworkstations running SunView� from Brian M� Sutin �sutin&astro�umd�edu��It is written in C� Programs which use it must be linked with several libraries�in order�

�lsuntool �lsunwindow �lpixrect

Use device speci�cation �SUNVIEW� Please let me know if you have any prob�lems with this handler� or make improvements to it�

SunCGI �Sun only� File cgdriv is another handler for Sun workstationsrunning SunView� from Allyn Tennant� It only works with color worksta�tions� but could probably be easily modi�ed for monochrome workstations�It calls on the Sun CGI routines� and hence programs which use it must belinked with several libraries �in order�

�lcgi�� lcgi �lsunwindow �lpixrect �lm

Use device speci�cation �CGI� PGPLOT creates a window on the screen� oruses the whole screen if you are not running SunView� There is no cursoravailable with this handler� The window is closed when your program exits�so it is not possible to overlay one plot on top of another by using theundocumented �APPEND quali�er�

IVAS �Convex only� The handler for the IIS IVAS image display �ivdriv�device speci�cation �IVAS� calls C routines to do most of the work� It isself�contained �no other libraries are required�� but will require a compatibleversion of the Convex device driver for the interface board�


Imagraph �Convex only� This is a handler for the Imagraph image dis�play �tvdriv� device speci�cation �IMAGRAPH�� The board is an AGC SE�RIES VME�� board �IMAgraph Corporation� �� West CummingsPark� Woburn� Massachusetts �� and utilizes a Hitachi HD�� Ad�vanced CRT Controller �ACRTC� as graphics engine� It is con�gured with�� bit pixels �image frame memory� plus a ��bit pixel overlay�The device handler is self�contained �no other libraries are required�� but itwill require the Caltech Convex device driver for the interface board �contactJudy Cohen for more information��

Tektronix terminals and emulators The basic Tektronix� �� han�dler is tedriv ��TEK�� Extensions for use with Retrographics terminals andGraphOn terminals are provided in �les redriv ��RETRO� and gfdriv ��GF��respectively� The code for these handlers is fairly standard� with the excep�tion of C routines in gr�term�io�c for writing to the terminal� As controlcharacters must be output� the terminal is put in %cbreak� mode during out�put� The tedriv handler works with the Sun Tektronix emulator tektool�The cursor works with these device handlers on the Convex but not on SunsI would appreciate suggestions for �xing this problem�

PostScript printers The PostScript handlers �psdriv for landscapemode� vpdriv for portrait mode� adhere fairly closely to standard Fortran�� and so should be easily ported to di�erent systems� The �les that theycreate do not display correctly in the Sun psview PostScript preview pro�gram owing to what I assume is a bug in Sun�s implementation of PostScript�The PostScript handlers can optionally insert a control�D �end�of��le� char�acter at the beginning and end of the PostScript �le� which may be neededby some PostScript printers� To enable this option� de�ne the environmentvariable PGPLOT�PS�EOF �with any value��

REGIS terminals �e�g�� DEC VT�� The REGIS device handler isin �le vtdriv� specify a device type of �VT�� It is fairly close to standardFortran�� The default output device is the user�s terminal� but a disk�le can also be speci�ed� The display should be satisfactory on VT��terminals� later DEC terminals �like VT� �� VT� �� do not have separatememories for text and graphics� and this leads to problems with programsthat interleave text and graphical output� At present� the cursor is notimplemented�

Other devices �Convex only� The basic installation procedure installssome additional drivers in the Convex version of PGPLOT� but these havenot been tested in other versions� Imagen printers imdriv� Printronixprinters pxdriv� QMS printers qmdriv and vqdriv� Versatec printersvedriv and vvdriv�


C�� Special Notes� Sun

The Sun Fortran compiler treats the %backslash� character �� as a specialescape character in literal character strings� This means that any programsthat try to make use of the PGPLOT escape�character mechanism� whichalso uses backslash� will have problems� Until Sun provides a way to disablethis annoying behavior of the compiler� the solution is to replace each occur�rence of � by �� This does not cause problems within the PGPLOT library�there are no literal � characters�� but it does a�ect the example programsand many application programs� The %make�le� in the examples directorypasses the example programs through the Sun �lter f��cvt which performsthis substitution �among other things��

C�� Acknowledgments

I am grateful to Jon Danskin of Convex Computer Corporation for the ini�tial port of PGPLOT to Convex�UNIX� Allyn Tennant �NASA Marshall�for providing the Sun�CGI device handler� Brian Sutin �University of Mary�land� for the SunView device handler� Neil Killeen �University of Illinois�for comments on the Sun implementation� and Judy Cohen �Caltech� forproviding time on Sun�� and Sun� workstations�

T� J� Pearson�� May ��

Appendix D

SUPPORTED DEVICES

D�� Introduction

This Appendix presents device�speci�c information for some of the sup�ported devices� Table D�� shows the devices for which device handlers areavailable� together with the names by which they are known to PGPLOT�The names of the device types can be abbreviated so long as there is no am�biguity� in most cases� this means the �rst two letters are su�cient� Eachinstallation of PGPLOT is con�gured with the devices appropriate for thatinstallation� so not every device is available in every installation of PGPLOT�Some devices are available under VMS only� and others are available underUnix only�

The description of each device is organized under the following headings

Supported device description of device�

Device type code the code to be used �following the � in a PGPLOTdevice speci�cation� usually this can be abbreviated to two letters� Somedevices can be used in two modes landscape �long axis horizontal� andportrait �long axis vertical�� Di�erent device type codes are used for thetwo modes�

Default �le or device name the �le or device name that is used bydefault if none is included in the device speci�cation� �For example� if the de�vice speci�cation is given as �VERS� it is expanded to PGPLOT�VEPLOT�VERS�if it is given as UV�VERS� it is expanded to UV�VEPLOT�VERS��

Default view surface dimensions Most hardcopy devices print on�� inch paper� and the standard usable �view surface� is �� inches� The dimensions are meaningless for most CRT devices where theimage size depends on the size of the monitor�

Resolution The nominal resolution of the device in pixelsinch� Theexact resolution can be ill�de�ned� e�g�� on a pen plotter� it depends on thesize of the pen nib�

Color capability What color indices are available' Can the representa�tion of each color index be changed' Do changes to the representation a�ectprimitive elements that have already been drawn'

D�� SUPPORTED DEVICES

Table D�� Available Devices

Terminals

GraphOn GO�� terminal �GF

Tektronix �� storage�tube terminal �TEK �

Retrographics modi�ed VT�� terminal �VT� �� RETRO

DEC VT�� VT� �� or VT� � terminal �REGIS� �VT��

Tektronix ��series color terminal �TK�

ZSTEM � � �� terminal emulators �IBM PC� �ZSTEM

Highresolution Display Devices

DeAnza �Gould �� low resolution� �DEanza

Grinnell GMR�� Image Display System �GRINNELL

Digisolve Ikon Pixel Engine �IKon

Liacom Graphic Video Display �GVD�� LIacom

Peritek Corp� VCH�Q frame�bu�er video �PERITEK

Peritek Corp� VCK�Q frame�bu�er video �PK

Sigma Args� �� series �ARgs

Sigma� T�� terminal �GOC

Tektronix �� bit addressing� �TFILE

VAXVMS workstations �WS

Sun workstations �SunView mode� �SUNVIEW

Sun workstations �using CGI routines� �CGI

IIS IVAS image display �IVAS

Imagraph image display �IMA

Pen Plotters

Gould �now Bryans� Colourwriter �� CW��

HPGL Driver �tested on HP� ��A plotter� �HPGL

HPGL Driver �portrait mode� �VHPG

Hewlett Packard �� pen plotter �HP��

Houston Instruments HIDMP pen plotter �HIDMP

Bruning �fmr Nicolet� Zeta � Digital Plotter �ZEta

Laser Printers

Hewlett Packard LaserJet� LaserJet �II �LJ

PostScript device �landscape mode� �PS

PostScript device �portrait mode� �VPS

QUIC devices �QMS �� etc� �landscape mode� �QMS

QUIC devices �QMS �� etc� �portrait mode� �VQMS

Canon LBP��A� Laser printer �landscape mode� �BCanon

Canon LBP��A� Laser printer �landscape mode� �CAnon

Canon LBP��A� Laser printer �portrait mode� �VCanon

Impress �Imagen� device �landscape mode� �IMPRESS

Impress �Imagen� device �portrait mode� �VIMPRESS

SUPPORTED DEVICES D��

Table D�� continued�

Dotmatrix Printers

EPSON FX�� printer �EPSONEXCL �C�Itoh Megaserve� printer �EXCL

LA�� and other DEC sixel printers �LA�

Printronix P�� or P�� printer �PRINTRONIX

Toshiba ��in�on�� printer� model P�� TOSHIBA

Versatec V�� printer �landscape mode� �VERSATEC

Versatec V�� printer �portrait mode� �VVERSATEC

Other

Null device �no graphical output� �NULL

Meta�le �FILE


Input capability Instructions for the use of the graphics cursor� if oneis available�

File format Description of the �le in which the graphic commands arestored� For some devices� the commands are sent directly to the device andno intermediate �le is required�

Obtaining hardcopy When an intermediate �le is used� this sectiongives instructions for sending the graphic commands from the �le to thedevice� It is important to check the correct procedure with your SystemManager before attempting to generate a hardcopy plot� Attempting to printor plot a �le on the wrong sort of device will at best waste a large quantityof paper� and may damage the device or crash the VAX�

D�� Versatec

Supported device Versatec V�� printerplotter �and compatible mod�els��

Device type code �VErsatec �landscape mode�� VVersatec �portraitmode��

Default �le name PGPLOT�VEPLOT �landscape mode�� PGPLOT�VVPLOT�portrait mode��

Default view surface dimensions �� inches horizontal � �� inchesvertical �landscape mode�� inches horizontal � �� inches vertical �por�trait mode�� These are nominal values� the actual scale may vary� particu�larly in the dimension parallel to the paper motion�

Resolution �� pixelsinch �both dimensions��

Color capability Color indices � �erase� and � �black� are supported�Requests for other color indices are converted to �� It is not possible tochange color representation�

Input capability None�

File format The �le contains variable length records �up to �� bytes��one record corresponding to one horizontal dot row of the plot� The �le hasrecord attributes �No Carriage Control�� The �rst byte in each record iscontrol�D �hexadecimal � plot mode speci�er�� The remaining ��bit byteseach represent � dots� with the most signi�cant bit representing the left�mostdot� � implies the corresponding dot is to be �lled in� Thus the maximumnumber of dots per line is �� corresponding to �� inchesat �� dots per inch� The vertical spacing of dot rows is also �� per inch�Plot pages are separated by a record containing a form�feed character only ��byte� hexadecimal �C�� These �les are intended for use with a special driver


and printer symbiont which recognize the control�D and send the remainderof the record to the Versatec in plot mode instead of text mode� This is notthe format expected by the standard VMS driver provided by Versatec�

Obtaining hardcopy Use the VMS COPY command to send the �le to asuitable device or use the VMS PRINT command if a suitable printer queuehas been established� Examples

� COPY PGPLOT�VEPLOT LVA �

� PRINT�NOTIFY�QUEUE�VERSATEC PGPLOT�VEPLOT

On DEIMOS

� PRINT PGPLOT�VEPLOT

On PHOBOS

� VPRINT PGPLOT�VEPLOT

On Starlink

� PRINT�PASSALL�QUEUE�SYS�VERSATEC PGPLOT�VEPLOT

D�� PostScript printers

Supported device any printer that accepts the PostScript page descrip�tion language� e�g�� the LaserWriter �Apple Computer� Inc��

Device type code �PS �landscape mode�� VPS �portrait mode��

Default �le name PGPLOT�PSPLOT �landscape mode�� PGPLOT�VPPLOT�portrait mode��

Default view surface dimensions �� inches horizontal � �� inchesvertical �landscape mode�� inches horizontal � �� inches vertical �por�trait mode��

Resolution Commands sent to the device use coordinate increments of�� inch� giving an �apparent� resolution of �� pixelsinch� The trueresolution is device�dependent� e�g�� on an Apple LaserWriter it is �� pix�elsinch �in both dimensions��

Color capability Color indices � �erase�� black�� light grey��and �� dark grey� are supported� Requests for other color indices areconverted to �� It is not possible to change color representation�



File format The �le contains variable length records containing Post�Script commands� The commands use only printable ASCII characters� andthe �le can be examined or modi�ed with a text editor�

Obtaining hardcopy Use the VMS COPY command to send the �le to asuitable device or use the VMS PRINT command if a suitable printer queuehas been established� On DEIMOS

� PRINT PGPLOT�PSPLOT�QUEUE�LW

References �� Adobe Systems� Inc� PostScript Language ReferenceManual� Addison�Wesley� Reading� Massachusetts� �� Adobe Sys�tems� Inc� PostScript Language Tutorial and Cookbook� Addison�Wesley�Reading� Massachusetts� ��

D�� QMS Lasergra�x

Supported device QMS Lasergra�x �� laser printers and otherprinters accepting �QUIC� commands�

Device type code �QMs �landscape mode�� VQms �portrait mode��

Default �le name PGPLOT�QMPLOT �landscape mode�� PGPLOT�QEPLOT�portrait mode��

Default view surface dimensions �� inches horizontal � �� inchesvertical �landscape mode�� inches horizontal � �� inches vertical �por�trait mode�� These are nominal values� the actual scale may vary�

Resolution �� pixelsinch �both dimensions�� Commands sent to thedevice use coordinate increments of �� inch� giving an �apparent� reso�lution of �� pixelsinch�



File format The �le contains variable length records containing QUICcommands� The commands use only printable ASCII characters� and the�le can be examined or modi�ed with a text editor�


Obtaining hardcopy Use the VMS COPY command to send the �le to asuitable device or use the VMS PRINT command if a suitable printer queuehas been established� Examples

� COPY PGPLOT�QMPLOT TXA �

� PRINT�NOTIFY�QUEUE�LASER PGPLOT�QMPLOT

On XHMEIA

� LASER PGPLOT�QMPLOT

On CVAX

� PRINT�QUEUE�TXA PGPLOT�QMPLOT

D�� Printronix

Supported device Printronix P�� P�� and equivalent dot�matrixprinter�plotters�

Device type code �PRintronix �landscape mode only��

Default �le name PGPLOT�PRPLOT�

Default view surface dimensions �� inches horizontal � �� inchesvertical� on standard �� inch computer paper� These are nominalvalues� but the printer is usually quite accurately aligned�

Resolution �� pixelsinch horizontal � �� pixelsinch vertical�



File format A Printronix �le contains variable length records �up to ��bytes�� one record corresponding to one horizontal dot row of the plot� The�le has record attributes �No Carriage Control�� The last three bytes in eachrecord are control�E �hexadecimal �� plot mode speci�er�� carriage�return�line�feed� The remaining bytes each use the � lower�order bits to represent �dots� with the least signi�cant bit representing the left�most dot� � impliesthe corresponding dot is to be �lled in� The top two bits are always �� Thusthe maximum number of dots per line is �� corresponding to ��inches at �� dots per inch� If a plot covers more than one page� no form�feedcodes are inserted� rather a su�cient number of blank plot lines are insertedto advance to the top of the next page �� lines per ��inch page�� If these

D� SUPPORTED DEVICES

�les are to be printed on a Printronix printer using the standard VAXVMSline�printer driver �LPDRIVER or LCDRIVER�� the system manager mustset the characteristics of the printer and associated queue correctly� It isimportant to ensure that �� all ��bit characters� including non�printablecontrol characters� are passed to the printer� �� lines of �� bytes or lessare not truncated� and �� no extra formatting commands �e�g�� form�feeds�are sent to the printer� The following setup is used on Phobos

� SET PRINTER�LOWER�CR�PRINTALL LPA �

� SET DEVICE�SPOOLED��SYS�PRINT�SYS�� LPA �

� DEFINE�FORM�NOTRUNC�NOWRAP DEFAULT

� INITIALIZE�QUEUE�START�ON�LPA � SYS�PRINT �

�DEFAULT��FLAG�ONE��PROT��W�RW��SCHED�NOSIZE

Obtaining hardcopy On VAXVMS machines� Printronix plot �les canbe printed with a standard PRINT command� but the �PASSALL quali�ermust be included� �If the printer is setup as in the example above� �NOFEEDcan be substituted for �PASSALL� but this is not recommended�� Examples

� PRINT�NOTIFY�PASSALL PGPLOT�PRPLOT

On Phobos

� PRINT�PASSALL PGPLOT�PRPLOT

On Deimos

� PPRINT�PASSALL PGPLOT�PRPLOT

On Starlink

� PRINT�PASSALL�QUEUE�SYS�PRINTRONIX PGPLOT�PRPLOT

On Ikaros �Convex�Unix�

lpr �l PGPLOT�PRPLOT


D�� VT�� DEC REGIS terminals�

Supported device Digital Equipment Corporation VT�� VT� �� orVT� � terminal� other REGIS devices may also work�

Device type code �VT��

Default �le name �VMS� TT�PGPLOT�VTPLOT� This usually means theterminal you are logged in to �logical name TT�� but the plot can be sentto another terminal by giving the device name� e�g�� TTC ��VT� or it can besaved in a �le by specifying a �le name� e�g�� CITSCR��TJP�XPLOT�VT �inthis case a disk name must be included as part of the �le name��

Default �le name �Unix� �dev�tty� the terminal you are logged in to�the plot can be sent to another terminal by giving the device name� or itcan be saved in a �le by specifying a �le name�

Default view surface dimensions Depends on monitor�

Resolution The default view surface is �� horizontal�� vertical�pixels� On most Regis devices� the resolution is degraded in the verticaldirection giving only �� distinguishable raster lines� �There are actually� � raster lines� but �� are reserved for a line of text��

Color capability Color indices �� are supported� By default� colorindex � is black �the background color�� Color indices �� are white� red� andgreen on color monitors� or white� dark grey� and light grey on monochromemonitors� The color representation of all the color indices can be changed�although only a �nite number of di�erent colors can be obtained �see themanual for the terminal��

Input capability The graphics cursor is a blinking diamond�crosshair�The user positions the cursor using the arrow keys and PF��PF keys on hiskeyboard "Note NOT the keyboard of the terminal on which he is plotting�if that is di�erent�# The arrow keys move the cursor in the appropriatedirection� the size of the step for each keystroke is controlled by the PF��PF keys PF� � � pixel� PF� � pixels� PF� � �� pixels� PF � � pixels� "The VT� � terminal has a built�in capability to position the cursor�but PGPLOT does not use this as it is not available on the VT��# Theuser indicates that the cursor has been positioned by typing any characterother than an arrow or PF��PF key "control characters� e�g�� C� and otherspecial characters should be avoided� as they may be intercepted by theoperating system#�


File format A REGIS plot �le is formatted in records of �� charactersor less� and has no carriage�control attributes� The records are groupedinto �bu�ers�� each of which begins with hesciPp to put the terminal intographics mode and ends with hescin to put it back into text mode� Theterminal is in graphics mode only while a bu�er is being transmitted� so auser�s program can write to the terminal at any time �in text mode� withoutworrying if it might be in graphics mode� Everything between the escapesequences is REGIS see the VT�� or VT� � manual for an explanation�PGPLOT attempts to minimize the number of characters in the REGIScommands� but REGIS is not a very e�cient format� It does have the greatadvantage� though� that it can easily be examined with an editor� The �lemay also contain characters outside the hesciPp� � � hescin delimiters� e�g��escape sequences to erase the text screen and home the cursor�

The following escape sequences are used

hesci��J � Erase entire screen �text�hesci�H � Move cursor to home positionhesciPp � Enter REGIS graphics modehescin � Leave REGIS graphics mode

PGPLOT uses a very limited subset of the REGIS commands supportedby the VT�� and VT� �� The following list summarizes the REGIS com�mands presently used�

Initialization the following standard commands are used to initialize thedevice every time a new frame is started� most of these restore a VT�� orVT� � to its default state� but the screen addressing mode is nonstandard�

! � resynchronizeW�R� � replace mode writingW�I�� color index �W�F�� both bit planesW�M�� unit multiplierW�N � � negative o�W�P�� pattern �W�P�M�� pattern multiplier �W�S � � shading o�S�G�� select graphics plane "Rainbow REGIS#S�A� �� screen addressing� origin at bottom leftS�I � � background darkS�S�� scale �S�M �L ��AL �� output map section � �black�S�M��L� ��AH�� L� S� �� output map section � �reddim grey�S�M��L��AH� L� S� �� output map section � �greenlight grey�S�M��L� ��AL� �� output map section � �white�


Drawing lines the P and V commands are used with absolute coordinates�relative coordinates� and pixel vectors� The �B�� S�� E�� and �W�modi�ersare not used� Coordinates which do not change are omitted�

P�x�y� � move to position� e�g� P��

V�x�y� � draw vector to position� e�g� V��

Line attributes the line style and line color attributes are speci�ed with W

commands� e�g�

W�P�� line style �W�I�� intensity �color index� �

and S commands are used to change the output map� The PGPLOT colorindices �� correspond to output map sections ��

Obtaining hardcopy A hardcopy of the plot can be obtained using aprinter attached to the VT��VT� � terminal �see the instruction manualfor the terminal�� A plot stored in disk �le can be displayed by copying itto a suitable terminal� e�g�� use TYPE on VMS or cat on Unix�

D� VAX Workstations

Driver WSDRIVER� version �� Jun �� by S� C� Allendorf�

Supported device This driver should work with all VAXVMS work�stations running VWS software� it requires the UISSHR shareable imageprovided by DEC�

Device type code �WS�

Default device name PGPLOT� Output is always directed to deviceSYS�WORKSTATION� the �device name� provided by the user is used to la�bel the PGPLOT window�


Resolution Depends on monitor�

Color capability VAX workstations have �� or � bitplanes� On ��plane devices� there are only two colors �background � white� color index �� black�� On �plane devices� color indices �� are available � indices arereserved for text windows and pointers�� On ��plane systems� color indices�� are available �� indices are reserved for text windows and pointers��

Input capability The cursor is controlled by the mouse or the keypad�arrow keys and PF��PF � available on the controlling �DEC�like� keyboard�The user positions the cursor� and then types any key on the controllingkeyboard� The mouse buttons are not used�


Notes The displayed window is deleted when PGEND is executed or onprogram exit� PGPLOT requests con�rmation from the user before deletingthe window� Type a carriage�return at the prompt when you are ready tocontinue� This makes it impossible to overlay a plot created by one programon a plot created by another� �The �APPEND quali�er which allows this forother devices has no e�ect on device �WS�� PGPLOT uses a window which isnominally �� inches wide by �� inches tall� i�e�� the same size as you wouldget in a hardcopy� If you prefer a vertical orientation� execute the followingcommand before running the program

� DEFINE PGPLOT�WS�ASPECT PORTRAIT

Substitute LANDSCAPE for PORTRAIT to revert to horizontal orientation�

VAXstations can also be used in Tektronix emulation mode� If you runa process in a Tektronix emulation window� you can use device speci�cation�TEK to tell PGPLOT to plot in Tektronix mode within the same window�If you run in a VT�� window� you can tell PGPLOT to create a newTektronix window and plot in it by giving a device speci�cation TK��TEK��TK� is the VMS device name of the Tektronix emulator�� This has oneproblem the window will be deleted as soon as your program calls PGENDor exits� you may need to add a user�prompt in your program before thecall of PGEND�

D� Sun Workstations

Driver SVDRIV� by Brian M� Sutin �sutin&astro�umd�edu�� May��

Supported device This driver should work with all Sun workstationsrunning the SunView environment�

Device type code �SUNVIEW�

Default device name none� Output is always directed to the worksta�tion screen�


Resolution PGPLOT uses a square window with �� pixels�

Color capability �� colors� �� pre�de�ned� white background�

Input capability The cursor is controlled by the mouse� The user posi�tions the cursor� and then types any key on the controlling keyboard� Themouse buttons can be used instead of keystrokes�

Notes The displayed window is deleted when PGEND is executed or onprogram exit� PGPLOT requests con�rmation from the user before deletingthe window�


D�� Grinnell

Supported device Grinnell GMR�� Image Display System�

Device type code �GRinnell�

Default device name TV�DEVICE �a logical name� usually de�ned bythe system manager��


Resolution The full view surface is �� pixels�

Color capability Color indices �� are supported� The default colorrepresentation is as listed in Chapter �� The representation of all colorindices can be changed�

Input capability The graphics cursor is a white cross�hair� The userpositions the cursor using the arrow keys and PF��PF keys on his terminalkeyboard �SYS�COMMAND�� The arrow keys move the cursor in the appropriatedirection� the size of the step for each keystroke is controlled by the PF��PF keys PF� � � pixel� PF� � pixels� PF� � �� pixels� PF � � pixels� The user indicates that the cursor has been positioned by typing anycharacter other than an arrow or PF��PF key "control characters� e�g�� C�and other special characters should be avoided� as they may be interceptedby the operating system#�

File format It is not possible to send Grinnell plots to a disk �le�

Obtaining hardcopy Not possible�

D�� IVAS

Supported device International Imaging Systems IVAS Display Proces�sor�

Device type code �IVAS�

Default device name �dev�ga �Unix��





Input capability The graphics cursor is a yellow cross� The user po�sitions the cursor using the mouse� and indicates that the cursor has beenpositioned by typing any character other than an arrow or PF��PF key"control characters� e�g�� C� and other special characters should be avoided�as they may be intercepted by the operating system#�

File format It is not possible to send IVAS plots to a disk �le�


D�� Sigma ARGS

Supported device Sigma ARGS color graphic display�

Device type code �ARgs�

Default device name ARGS�DEVICE �a logical name��




Input capability maybe��

File format It is not possible to send ARGS plots to a disk �le�


D�� Tektronix ��

Supported device Tektronix �� and �� Series Storage Tube termi�nals� and �emulators��

Device type code �TEk � �

Default device name TT �a logical name� usually equivalent to thelogged�in terminal��


Resolution The full view surface is nominally �� horizontal�� vertical� pixels� but the actual resolution varies from device to device�

Color capability None� Only color index � is permitted� and requestsfor other color indices are ignored� It is not possible to change color repre�sentation� or to erase by using color index ��


Input capability Maybe��

File format It is not possible to send Tektronix plots to a disk �le�

Obtaining hardcopy A hardcopy of the plot can be obtained using aTektronix hardcopy unit attached to the terminal�

D�� Tektronix ��

Supported device Tektronix ��series terminals�

Device type code �TK� �

Default device name TT �a logical name� usually equivalent to thelogged�in terminal��


Resolution The view surface is nominally �� horizontal� � �� ver�tical� pixels� but the true resolution depends on which terminal is used� andis usually much less than this�


Input capability Not yet implemented�

File format It is not possible to send Tektronix plots to a disk �le�

Obtaining hardcopy It is possible to obtain a hardcopy of the plot �incolor� even� using a printer attached to the terminal�

D�� Retrographics

Supported device Digital Engineering� Inc�� Retrographics modi�edVT�� terminal �VT� ��

Device type code �REtro�

Default device name TT� �the logged�in terminal��


Resolution The full view surface is �� horizontal�� pixels�

Color capability Color indices � �erase� black� and � �bright usuallygreen� are supported� It is not possible to change color representation�


Input capability The graphics cursor is a crosshair across the entirescreen� The user positions the cursor using the four arrow keys on thekeyboard of the Retrographics terminal� �By striking the desired directionalarrow key� the crosshair will move across the display screen at the rate ofone dot per keystroke� Applying a constant pressure on an arrow key willcause the crosshair to move at a continuous rapid rate� releasing the key willstop the crosshair�s movement�� The user indicates that the cursor has beenpositioned by typing any printable ASCII character on the keyboard of theRetrographics terminal� Most control characters �e�g�� C� are interceptedby the operating system and cannot be used�

File format It is not possible to send Retro plots to a disk �le�


D�� Null Device

Supported device The �null� device can be used to suppress all graphicoutput from a program�

Device type code �Null�

Default device name None �the device name� if speci�ed� is ignored��

Default view surface dimensions Unde�ned�

Resolution Unde�ned�

Color capability Color indices �� are accepted�


File format None�


D�� Canon

Supported device Canon LBP��A� Laser printer� Conforms to ISO� �� and � �� speci�cations� VDM �graphics� conforms to pro�posed American National Standard VDM mode�

Device type code �CAnon �landscape mode�� VCanon �portrait mode�and �BCanon �bitmap in landscape mode only��

Default �le name PGPLOT�CAN

Default view surface dimensions � cm by �� cm�


Resolution �� pixels per inch in both directions�

Color capability Color indices � �erase� and � �black� are supported�Note� hardware polygon �ll is used and colors �� control the �ll pattern�


File format Variable length records with Carriage control of LIST�

Obtaining hardcopy If printer is connected to a terminal line �RS��option� then printing the �le on the corresponding queue should su�ce�If the printer is connected using the Centronics interface that appears theto VAX as an LP device then it is important to ensure that �� all � bitcharacters are passed to the printer �� lines longer than �� bytes are nottruncated� and �� no extra formatting commands �e�g� form�feeds� are sentto the printer� This can be done with the VMS command

� SET PRINT�PASSALL�LOWER�CR "device#

Note� some interface boards have a option to append a carriage return aftera formfeed or LF character� it is necessary that this be disabled� The �leshould be printed with the PASSALL quali�er i�e��

� PRINT�PASSALL "filename#

Note� SET PRINTPASSALL and PRINTPASSALL do not do the samethings and hence PASSALL is required in both locations�

Note� The BCDRIVER produces a bitmap that then can be printed onthe Canon� The default size is �� blocks and takes � min �parallel� or ��min �serial �� baud� to print� Thus for simple line graphs CADRIVERproduces much smaller �les �typically '�� blocks� that that plot in '�� sec�However� for complex graphs� for example those obtained with PGGRAY�BCDRIVER will produce the smaller �le and plot faster� Therefore� it issuggested that sites with Canon laser printers should support both drivers�

D�� Colorwriter �� Plotter

Supported device Gould �now Bryans� Colourwriter �� or any deviceobeying Gould Plotter Language�

Device type code �CW��

Default device name �PLOTTER� �De�ned system logical name�

Default view surface dimensions ��mm by ��mm �A��

Resolution ��mm


Colour Capability Up to �� pens�Default is pen � which is picked upon initialization without a call to PGSCI�Calls to PGSCI are interpreted asthe pen number and colours therefore depend on how the pens have beenloaded into the stalls�If a call is made for a pen higher than �� the selectedpen defaults to ��

Input Capability Possible but not supported�

File format Ascii character strings�It is possible to send the data to a�le which can then be copied to the plotter or examined on a terminal�

Obtaining hard copy PGPLOT has been �xed to send the plot directlyto the plotter without an intermediate �le�

D�� Ikon

Supported device Digisolve Ikon Pixel Engine

Device type code �IKon�

Default device name IKON�DEFAULT �a logical name��


Resolution The full view surface is �� by �� pixels�

Color capability Color indices �� are supported� The default repre�sentation is listed in Chapter � of the PGPLOT manual� The representationof all color indices can be changed�

Input capability

File format It is not possible to send IKON plots to a disk �le�


D�� Zeta

Supported device Zeta � Digital Plotter�

Device type code �ZEta

Default �le name PGPLOT�ZET

Default view surface dimensions �� inches by �� inches� Currentversion does not allow larger plots although the manual indicates plots upto � feet are possible�


Resolution This version is written for the case where the resolutionswitch is set to �� mm� Actual resolution depends on thickness of pen tip�

Color capability Color indices � to � are supported corresponding topens �� It is not possible to erase lines�


File format Variable length records with Carriage control of LIST�

Obtaining hardcopy On Starlink print the �le on the queue associatedwith the Zeta plotter� If the Plotter is attached to a terminal line� thenTYPEing the �le at the terminal will produce a plot� On Starlink

� PRINT�NOFEED�QUE�ZETA PGPLOT�ZET

To stop a Zeta plot job� once it has been started� use the buttons on theplotter� Press PAUSE� NEXT PLOT and CLEAR� Only after this sequenceis it safe to delete the job from the ZETA Queue� Failing to press theNEXT PLOT button will not correctly advance the paper� Failing to pressCLEAR but� deleting the current job can prevent the following plot frombeing plotted�

Appendix E

WRITING A DEVICE HANDLER

E�� Introduction

PGPLOT can be con�gured for a particular installation by adding or re�moving �device handlers�� A device handler is a subroutine which handlesall the device�speci�c aspects of graphical output for a particular device orclass of devices�

All graphical output is handled by a �device dispatch routine� in PG�PLOT� called GREXEC� This routine calls on the appropriate device han�dler to perform the output� Recon�guring PGPLOT involves modifying theGREXEC routine to use a di�erent set of device handlers� no other changesto PGPLOT are needed�$

To write a new device handler� it is simplest to start by modifying anexisting one� This Appendix explains what the device handler must do�but it does not explain how to do it!which is� of course� very hardware�dependent�

The supported device types fall into three classes� and when adding anew device you should determine which class it belongs to� and then addthe new device by copying and modifying the support routines for one ofthe existing devices in this class� The three classes are

�� Bit map devices �e�g�� Versatec�� The complete image is assembled inmemory as a bit map and then written in an output �le in a formatacceptable to the device� The existing devices in this class use one bitper pixel� but more bits could be allocated�

�� Instruction stream devices �e�g�� QMS� Graphical instructions are writ�ten sequentially in the output �le using Fortran IO� Usually the in�structions are composed of printable ASCII characters� but this is notessential�

$ In the VMS version of PGPLOT� the modi�cation of GREXEC can bedone automatically using the command procedure NEWEXEC�COM which �ndsall the device handlers currently installed in the �PGPLOT�SOURCE� directory�

E�� WRITING A DEVICE HANDLER

�� Direct IO devices �e�g�� Grinnell� devices that require special com�mands that cannot be encoded in text strings use the low�level oper�ating system IO routines �SYS(QIO in VMS� to directly control thedevice� It is not possible to store images in a disk �le for these devices�

E�� Device handler interface

A device handler is a Fortran subroutine� It is called by the GREXEC de�vice dispatch routine whenever PGPLOT needs to determine device�speci�cinformation or perform graphical output� The name of the subroutine mustbe of the form xxDRIV� where xx is a two�character code for the devicetype� usually the �rst two letters of the type� this code must �of course� bedi�erent for each di�erent device handler�

SUBROUTINE xxDRIV �OPCODE� RBUF� NBUF� CHR� LCHR�

INTEGER OPCODE

REAL RBUF��

INTEGER NBUF

CHARACTER�� CHR

INTEGER LCHR

The �rst argument �OPCODE� is an integer �operation code� which speci��es what operation the device handler is to perform� it is an input parameterto the subroutine �see Table E�� The other arguments are used for bothinput and output� and their meaning depends on the value of the operationcode� Not all arguments are used for every operation code� RBUF is a�oating�point array used to pass numerical data to or from the device han�dler� and NBUF indicates how many elements of the array are used� CHR isa character variable used to pass character data to or from the device han�dler� and LCHR indicates how many characters are used� NBUF or LCHRshould be set to zero if no data of the corresponding type are passed� If thefunction requested by the operation code �OPCODE� is not implemented inthe device handler� the subroutine should set NBUF � �� before returning�

The device handler subroutine can communicate with PGPLOT onlythrough the arguments� It should not attempt to reference the PGPLOTcommon blocks �this is because the internal structure of the PGPLOT com�mon blocks may change��

WRITING A DEVICE HANDLER E��

Table E�� Device Handler Operation Codes

Opcode Function

� Return device name� Return maximum dimensions of view surface�

and range of color index� Return device scale Return device capabilities� Return default device�le name� Return default size of view surface� Return miscellaneous defaults� Select device� Open workstation�� Close workstation�� Begin picture�� Draw line�� Draw dot� End picture�� Set color index�� Flush bu�er�� Read cursor�� Erase alpha screen�� Set line style�� Polygon �ll�� Set color representation�� Set line width�� Escape function� Rectangle �ll�� Set �ll pattern�� Line of pixels

E�� Handler state

PGPLOT will send commands to the device handler in a set sequence� In�quiry commands �opcodes �� may be sent at any time� whether or not adevice has been selected for output� The open workstation and close work�station commands are used to open and close a device� The begin pictureand end picture commands are used to start and �nish a �frame� �one pageon a hardcopy device�� Graphical output commands �opcodes �� are only used between begin picture and end picture� Thus the sequence of


commands for a plot consisting of two frames will be

open workstation

begin picture

�graphical output commands�

end picture

begin picture

�graphical output commands�

end picture

close workstation

Any violation of this sequence is due to a bug in PGPLOT�

E�� Summary of operations

OPCODE � �� Return device name� This is an inquiry function�the handler returns the name by which the the user will refer to the devicetype� e�g�� %PRINTRONIX� for a Printronix device handler� This namemust be di�erent for each device handler installed in PGPLOT� and shouldpreferably be unique in the �rst two or three characters�

CHR�LCHR� �returned� the device type supported by the handler�

OPCODE � �� Return maximum dimensions of view surface� andrange of color index� This is an inquiry function� the handler returnsthe maximum dimensions of the plot surface� and the range of color in�dices available� On interactive devices� these will usually be the same asthe default dimensions� On hardcopy devices which plot on roll or fanfoldpaper� the maximum dimensions may be larger� All dimensions are in de�vice coordinates� All devices should support color indices � and �� colorand gray�scale devices will allow color indices � � up to a device�dependentmaximum value �which should not exceed �� Color index � is the back�ground color and is used to erase� if it is not possible to erase by overwritingin the background color� then requests to write in color index � should beignored�

RBUF�� returned� Minimum physical x value �set to zero��

RBUF�� returned� Maximum physical x value �a value of �� indi�cates no e�ective maximum��

RBUF�� returned� Minimum physical y value �set to zero��

RBUF� � �returned� Maximum physical y value �a value of �� indi�cates no e�ective maximum��

RBUF�� returned� Minimum allowed color index �usually ��

RBUF�� returned� Maximum allowed color index �in range ��


OPCODE � �� Return device scale� This is an inquiry function� thehandler returns the device scale in device coordinate units per inch� Usually�the units of the device coordinates are pixels� so this also gives the physicalresolution in pixels per inch� For hardcopy devices� the values should beas accurate as possible� to ensure that an image has the correct scale� Forvideo display terminals and other devices where the scale is variable� nominalvalues should be returned�

RBUF�� returned� x scale in device coordinates per inch�

RBUF�� returned� y scale in device coordinates per inch�

RBUF�� returned� �pen diameter� in device coordinates �i�e�� thewidth of a hardware line�� this value is used by PGPLOT when emulatingthick lines and polygon �ll�

OPCODE � �� Return device capabilities� This is an inquiry func�tion which is used to inform PGPLOT of the device�s capabilities� If thedevice lacks a capability in hardware� PGPLOT will try to emulate it�

CHR�� returned� each character in this string de�nes whether acapability exists

CHR�� %H� if the device is a hardcopy device� %I� if it is an interactivedevice� On an interactive device� the image is visible as it is being drawn�while on a hardcopy device it cannot be viewed until the workstation isclosed�

CHR�� %C� if a cursor is available� %N� if not� PGPLOT cannotemulate a cursor if none is available�

CHR�� %D� if the hardware can draw dashed lines� %N� if it cannot�PGPLOT emulates dashed lines by drawing line segments� Software emula�tion is usually superior to hardware dashed lines� and not much slower� soCHR�� %N� is recommended�

CHR� � � %A� if the hardware can �ll arbitrary polygons with solidcolor� %N� if it cannot� PGPLOT emulates polygon �ll by drawing horizontalor vertical lines spaced by the pen diameter �see OPCODE � ��

CHR�� %T� if the hardware can draw lines of variable width� %N� ifit cannot� PGPLOT emulates thick lines by drawing multiple strokes spacedby the pen diameter� Note that thick lines are supposed to have roundedends� as if they had been drawn by a circular nib of the speci�ed diameter�

CHR�� %R� if the hardware can �ll rectangles with solid color� %N� ifit cannot� If this feature is not available� PGPLOT will treat the rectangleas an arbitrary polygon� In this context� a %rectangle� is assumed to have itsedges parallel to the device�coordinate axes�

CHR�� %P� if the driver understands the pixel primitives �opcode�� %N� otherwise�


CHR�� reserved for future use� the device handler should return%N� in all these positions�

OPCODE � � Return default device��le name� This is an inquiryroutine� The device handler returns the device or �le name to be used if thePGPLOT device speci�cation does not include one� �On VMS� the default�le name is also used to �ll in missing �elds of the supplied �le name� e�g��disk� directory� and �le type��

CHR�LCHR� �returned� default device�le name�

OPCODE � �� Return default size of view surface� This is aninquiry function� the handler returns the default dimensions of the plotsurface in device coordinates� At present� PGPLOT assumes that the devicecoordinates of the bottom left corner are ��

RBUF�� returned� default x�coordinate of bottom left corner �mustbe zero��

RBUF�� returned� default x�coordinate of top right corner�

RBUF�� returned� default y�coordinate of bottom left corner �mustbe zero��

RBUF� � �returned� default y�coordinate of top right corner�

OPCODE � �� Return miscellaneous defaults� This is an inquiryroutine� The handler returns a scale�factor to be used for the �obsoletecharacter set� used by old GRPCKG routines but not by PGPLOT�

RBUF�� returned� character scale factor �integer� � ��

OPCODE � �� Select device� This opcode is reserved for future use�At present� each device handler can handle only one open device at once�Future versions of PGPLOT will allow more than one device to be open atonce� and this opcode will be used to select the active device�

RBUF�� input� plot ID�

RBUF�� input� unit or channel number of selected device �as re�turned by open workstation �


OPCODE � �� Open workstation� Allocate an IO channel to therequested device and open the device� Any hardware resets that need to bedone once for a plot session �which could consist of several frames� shouldbe done here� Allocate bu�er� if its size is �xed for the device� No visibleIO should be performed on an interactive device e�g�� the screen shouldnot be cleared� this should be deferred until the begin picture call�

RBUF�� returned� identi�cation number of the IO channel opened�PGPLOT will use this number in subsequent select device calls for thisdevice �see OPCODE � ��

RBUF�� returned� error �ag� �� indicates that the workstation wasopened successfully� any other number indicates an error�

RBUF�� input� if �� the device speci�cation included the AP�PEND �ag� If this �ag is speci�ed� the device handler should suppress anyinitial screen erase so that the new image is superimposed on any previouslydisplayed image� The device handler may ignore this if it is inappropriate�e�g�� for a hardcopy device��

CHR�LCHR� �input� the �ledevice to be opened� On VMS� this willbe a physical device name� an RMS �le name� or a logical name�

OPCODE � �� Close workstation� Close the device opened by theopen workstation command� and deallocate any resources allocated for thedevice �e�g�� memory� IO channels��

OPCODE � �� Begin picture� Prepare the workstation for plotting�This command has two arguments which specify a size for the view surfaceoverriding the default size� if the device handler is unable to change the sizeof the view surface� it may ignore these arguments� On interactive devices�erase the screen�

RBUF�� input� maximum x coordinate�

RBUF�� input� maximum y coordinate�

OPCODE � �� Draw line� Draw a straight line from device coordi�nates �x�� y�� to �x�� y�� using the current line attributes �color index� linestyle� and line width�� The coordinates are �oating point� and may need tobe rounded to the nearest integer before they are passed to the hardware�

RBUF�� input� x��

RBUF�� input� y��

RBUF�� input� x��

RBUF� � �input� y��

E� WRITING A DEVICE HANDLER

OPCODE � �� Draw dot� Draw a dot at device coordinates �x� y�using the current line attributes �color index and line width�� The resultshould be an approximation to a �lled circle of diameter equal to the linewidth� or a dot of minimum size if line width is �� The coordinates are�oating point� and may need to be rounded to the nearest integer beforethey are passed to the hardware�

RBUF�� input� x�

RBUF�� input� y�

OPCODE � �� End picture� Terminate the current frame� Onhardcopy devices always advance the paper� On interactive devices� clearthe screen only if requested� Deallocate bu�ers that were created by beginpicture �OPCODE � ��

RBUF�� input� if �� clear screen�

OPCODE � �� Set color index� Set the color index for subsequentplotting� The default color index is ��

RBUF�� input� color index� in range de�ned by OPCODE � ��

OPCODE � �� Flush bu�er� If the handler is bu�ering output toan interactive device� it should �ush its bu�ers to ensure that the displayedimage is up to date� Hardcopy devices can ignore this opcode�

OPCODE � �� Read cursor� This function is not used if OPCODE� indicates that the device has no cursor� The handler should make thecursor visible at position �x� y�� allow the user to move the cursor� and waitfor a key stroke� It should then return the new cursor �x� y� position andthe character �key stroke� typed� �If it is not possible to make the cursorvisible at a particular position� the handler may ignore the requested �x� y�coordinates��

RBUF�� inputreturned� x position of cursor�

RBUF�� inputreturned� y position of cursor�

CHR�� returned� character typed by user�

OPCODE � �� Erase alpha screen� If graphics device is a terminalthat can display both graphics and text on the same screen� clear the textscreen� leaving graphics unchanged� All other devices should ignore thisopcode�

OPCODE � �� Set line style� This opcode is not used if OPCODE� indicates that the device does not support hardware dashing� PGPLOTwill use software�generated dashed lines�

RBUF�� input� requested line style �integer ��


OPCODE � �� Polygon �ll� This function is not used if OPCODE� indicates that the device does not support hardware polygon �ll� Thepolygon may be arbitrarily complex �concave or re�entrant�� if the hardwarecannot cope with this� the handler should set the OPCODE � response todisable hardware �ll� If hardware �ll is enabled� the handler should respondto this function by �lling the polygon with the current color index� To drawan N �sided polygon� PGPLOT uses this opcode N � times�

First call

RBUF�� input� number of points N in polygon�

For next N calls

RBUF�� input� x value�

RBUF�� input� y value�

OPCODE � �� Set color representation� Assign the speci�ed�R�G�B� color� or the best available approximation� to the speci�ed colorindex� If colors cannot be changed dynamically� ignore the request�

RBUF�� input� color index �integer� in range de�ned by OPCODE� ��

RBUF�� input� red component ��

RBUF�� input� green component ��

RBUF� � �input� blue component ��

OPCODE � �� Set line width� This function is not used if OP�CODE � indicates that the device does not support hardware thick lines�Subsequent lines and dots should be drawn with the requested width� or theclosest available approximation� The units of line�width are �� inches� Arequested line�width of zero should give the narrowest line available on thedevice ��hair line��

RBUF�� input� requested line width� in units of �� inch�

OPCODE � �� Escape function� This function allows an arbitrarycharacter string to be sent to the device handler� The interpretation is up tothe handler� usually� the string will be sent directly to the device or ignored�Use of this function should be avoided�

CHR�LCHR� �input� character string�

OPCODE � �� Rectangle �ll� This function is not used if OPCODE� indicates that the device does not support hardware rectangle �ll�

RBUF�� RBUF�� input� x� y coordinates of lower left corner ofrectangle�

RBUF�� RBUF� � �input� x� y coordinates of upper right corner ofrectangle�


OPCODE � �� Set �ll pattern� This function is not yet imple�mented�

OPCODE � �� Line of pixels� This function is not used if OPCODE� indicates that the device does not support this function� It is used towrite a horizontal line of pixels on the device screen with speci�ed colorindices� it should be more e�cient to do this with one device driver callrather than separate calls for each pixel� This operation is used for gray�scaleand color imaging �e�g�� routine PGGRAY�� If the device handler implementsthis operation� it is important that the device coordinates should be truepixel numbers�

RBUF�� RBUF�� input� x� y coordinates of the �rst pixel to bewritten� These should be integer pixel numbers in the device coordinatesystem �passed as REAL numbers��

RBUF��RBUF�NBUF� �input� color indices for n pixels to be �lledin� starting at �x� y� and ending at �x n�� y�� The values should be validinteger color indices for the device �passed as REAL numbers�� The numberof pixels is speci�ed by the argument NBUF n � NBUF� ��

E�� Testing a new device handler

Several of the example programs can be used to test that PGPLOT has beeninstalled correctly� or that a new device handler is working� For a completetest� I recommend running the following programs on each installed devicetype�

PGEX�� This tests most of the features of PGPLOT and will revealmost device�handler errors�

�� It draws a rectangle enclosing the entire view surface� All four sidesof this rectangle should be visible� It then draws the bisectors of thesides� which intersect in the center of the rectangle� and a concentriccircle� The circle should always be circular� not elliptical� independentof the aspect ratio of the view surface� The dimensions of the rectangleand circle are typed on the terminal before the program exits� these di�mensions should be checked against the actual dimensions for hardcopydevices �for TV�type devices the exact dimensions are not important��

�� It draws � vertical lines of width � in the �ve di�erent line�styles�

�� It draws � horizontal lines of width � through ��

� It draws �� dots� using pen�widths � through �� Check particularlythat the �rst �lowest� dot� of diameter �� is visible�


�� It draws �� vertical lines using color indices �� The �rst line� incolor index zero� overwrites the vertical bisector of the rectangle� Iferase�mode is implemented� this will erase the line drawn in step ��

�� It outlines and �lls four polygons �ducks� in color indices �� The inte�rior of the �rst polygon should be erased if erase�mode is implemented�

�� Finally it erases �or attempts to erase� a rectangle at the top of theimage� and writes the version number of PGPLOT and the name of thedevice type within the rectangle� If this text does not appear� probablythe environment variable PGPLOT�FONT is not de�ned correctly�

PGDEMO� This draws several simple graphs using the basic PGPLOTroutines� The main feature that this program tests that is not tested byPGEX�� is the ability to clear the screen or start a new page� On interactivedevices� the program should prompt for a carriage�return before starting thesecond and subsequent graphs� A large number of the PGPLOT routinesare tested by this program�

PGDEMO� The �rst image produced by PGDEMO� is mostly usefulfor testing TV�type displays which support many color�indices� It drawsan alignment grid in two shades of gray� and patches of color using indexes�� Subsequent images demonstrate the graph markers and text fonts�

PGEX� PGEX�� can be use to test the cursor �routine PGCURSE�� Itdraws a frame around the view surface and allows the user to position thecursor� The keystroke code typed by the user and the cursor position aredisplayed on the terminal� To exit from the program� type a slash ��

Appendix F

CALLING PGPLOT FROM A C PROGRAM

F�� Introduction

It is possible to call PGPLOT routines from a program written in C� Themethods for calling a Fortran subroutine from a C program are operating�system dependent� and indeed it is impossible in some systems� The detailsare rather complicated� and if there is a demand� we could create a C�callable library that hides these details from the user� Examples of thesame program written in Fortran�� VAXVMS C� and Convex UNIX Care included below�

F�� VMS

The following is a prescription for calling PGPLOT subroutines from a Cprogram on a VAX running VMS�

�� All arguments �except arrays and character strings� are passed by ad�dress using the $ operator� As you cannot take the address of a constant�constants must be passed in dummy variables�

�� INTEGER arguments correspond to C type long int or int�

�� REAL arguments correspond to C type float�

� CHARACTER arguments correspond to C character strings� but they mustbe passed by descriptor� The VAX�C manual explains how to do thisusing the �DESCRIPTOR macro for �xed strings� it is a little more com�plicated for variable strings�

�� Note that the backslash character �� must be escaped ��

F�� CALLING PGPLOT FROM A C PROGRAM

F�� Convex UNIX

The following is a prescription for calling PGPLOT subroutines from a Cprogram on the Convex� It may also work on other Berkeley UNIX systems�

�� The main program must be called MAIN�� instead of main�� I don�tknow why this is so� but it must have to do with the initialization ofthe Fortran library�

�� Use the C compiler to compile the program� but use fc to load it� Thisensures that the Fortran system libraries are scanned�

�� All PGPLOT subroutine names must be typed in lower case� with anunderscore appended� e�g�� pgbegin�� pgend��

� All arguments �except arrays and character strings� are passed by ad�dress using the $ operator� As you cannot take the address of a constant�constants must be passed in dummy variables�

�� INTEGER arguments correspond to C type long int�

�� REAL arguments correspond to C type float�

�� For CHARACTER arguments� pass a pointer to a C character string� andadd the length of the string �number of characters� as an extra long

int argument at the end of the argument list�

�� Note that the backslash character �� must be escaped ��

Example

cc �c example��c

fc �o example� example��o �lpgplotexample�

CALLING PGPLOT FROM A C PROGRAM F��

C C Demonstration program for PGPLOT �Fortran version��C C

PROGRAM PGDEMOC

INTEGER IREAL XS��YS�� XR� �� YR� ��DATA XS� ��DATA YS� ��!��

CC Call PGBEGIN to initiate PGPLOT and open the output device� PGBEGINC will prompt the user to supply the device name and type�C

CALL PGBEGIN�� CC Call PGENV to specify the range of the axes and to draw a box� andC PGLABEL to label it� The xaxis runs from � to �� and y from � to ��C

CALL PGENV�� CALL PGLABEL��x�� y�� PGPLOT Example y � x�u��

CC Mark five points �coordinates in arrays XS and YS�� using symbolC number !�C

CALL PGPOINT��XS�YS�!�CC Compute the function at �� points� and use PGLINE to draw it�C

DO � I� ��XR�I� � �� IYR�I� � XR�I��

� CONTINUECALL PGLINE��XR�YR�

CC Finally� call PGEND to terminate things properly�C

CALL PGENDC

END


�� Demonstration program for PGPLOT called from C �VMS��

�include descripmain��"

int i�static float xs�� " �� #�static float ys�� " �� !�� #�float xr� �� yr� ��long dummy� nx� ny�float xmin� xmax� ymin� ymax�long just� axis� n� symbol�$DESCRIPTOR�device� ��$DESCRIPTOR�xlabel� ��x��$DESCRIPTOR�ylabel� ��y��$DESCRIPTOR�toplabel� �PGPLOT Example y � x��u��

�� Call PGBEGIN to initiate PGPLOT and open the output device� PGBEGIN� will prompt the user to supply the device name and type��

dummy � ��nx � �ny � �pgbegin�%dummy� %device� %nx� %ny��

�� Call PGENV to specify the range of the axes and to draw a box� and� PGLABEL to label it� The xaxis runs from � to �� and y from � to ��

xmin � ��xmax � ��ymin � ��ymax � ��just � ��axis � �pgenv�%xmin� %xmax� %ymin� %ymax� %just� %axis��pglabel�%xlabel� %ylabel� %toplabel��

�� Mark five points �coordinates in arrays XS and YS�� using symbol� number !��

n � ��symbol � !�pgpoint�%n� xs� ys� %symbol��

�� Compute the function at �� points� and use PGLINE to draw it��

n � ��for �i�� i�n� i��

"xr�i� � �� i�yr�i� � xr�i��xr�i��#

pgline�%n� xr� yr�� Finally� call PGEND to terminate things properly��

pgend��#

CALLING PGPLOT FROM A C PROGRAM F��

�� Demonstration program for PGPLOT called from C �Convex UNIX��

MAIN��"

int i�static float xs�� " �� #�static float ys�� " �� !�� #�float xr� �� yr� ��long dummy� nx� ny� just� axis� n� symbol�float xmin� xmax� ymin� ymax�

�� Call PGBEGIN to initiate PGPLOT and open the output device� PGBEGIN� will prompt the user to supply the device name and type��

dummy � ��nx � �ny � �pgbegin��%dummy� �� %nx� %ny� L��

�� Call PGENV to specify the range of the axes and to draw a box� and� PGLABEL to label it� The xaxis runs from � to �� and y from � to ��

xmin � ��xmax � ��ymin � ��ymax � ��just � ��axis � �pgenv��%xmin� %xmax� %ymin� %ymax� %just� %axis��pglabel��x�� y�� PGPLOT Example y � x��u�� L� �L� � L��

�� Mark five points �coordinates in arrays XS and YS�� using symbol� number !��

n � ��symbol � !�pgpoint��%n� xs� ys� %symbol��

�� Compute the function at �� points� and use PGLINE to draw it��

n � ��for �i�� i�n� i��

"xr�i� � �� i�yr�i� � xr�i��xr�i��#

pgline��%n� xr� yr�� Finally� call PGEND to terminate things properly��

pgend��#

Pgplot Manual

Documents

Transcript of Pgplot Manual