An Athena Guide to Using the Penplot Graphics Library James L. Fulton Project Athena 22 September 1987 Revision 2.0 Abstract Penplot is a device independent graphics system that was originally developed at the MIT Joint Computer Facility under the VAX/VMS operating system. This library of routines is now available as part of the Athena environment. This document _______ ________ _______ ______ _________ ______ supplements the Penplot_Graphics_Control_System_Reference_Manual, describing Penplot under the Athena/Berkeley 4.2 Unix environment. Copyright (C) 1984, MIT Project Athena 1 __ ____________ __ ____________ __ ____________ 1. Introduction 1. Introduction 1._Introduction _______ _________ ______ This document supplements the Penplot_Reference_Manual written at the MIT Joint Computer Facility (JCF). It describes Penplot as used in the Athena Unix environment. In porting Penplot from VMS to Unix, as few modifications as possible have been made. There will be a new release of the Penplot library in June, 1984 that will contain a number of enhancements that will bring Unix Penplot closer to VMS Penplot. Below is a list of the major differences that currently exist between the two versions of Penplot: _________ ______ o The devices described in the Reference_Manual are for the JCF only. Athena will be using a different set of terminals and plotters. Currently, plots may be displayed on the VT125 and the PRO 350 (when emulating a VT125). _______ o There is currently no general mechanism for saving graphic output to be plotted later. This should be available in the June, 1984 release. o In addition, there are no devices capable of producing printed graphics output; all graphics must be examined interactively. For the moment, files produced by the HDCPY pseudo-device (for storing graphics in files) and calls to the HARDCOPY routine cannot be used. o The higher-level subroutines QPICTR and PICTR, and the routines that draw and annotate axes are not yet available. They will be included in the June, 1984 release. o The TWRITE subroutine used to associate a Fortran logical unit number with the plotting screen has been removed. Users should use internal WRITE statements to character variables to format data and then call the LABEL subroutine. o Unix does not have version numbers on files. Therefore, hardcopy files that are generated will not _________ have different versions as described in the Reference ______ Manual. The June, 1984 release will provide version numbers for files. o Several new routines, ILORG, DRAW3, MOVE3, TERMINAL, and QPICTRTITLE have been added to handle commonly- performed actions. o The command to link programs with the Penplot library under Unix is different than what is described in the Reference Manual. 2 o Penplot is written in Fortran 77, which has a specific CHARACTER data type. Thus, the sections of the _________ ______ Reference_Manual that describe byte arrays (used on PDP-11's) should be ignored. __ _______ ________ _______ __ _______ ________ _______ __ _______ ________ _______ 2. Penplot Graphics Devices 2. Penplot Graphics Devices 2._Penplot_Graphics_Devices The VT125 and the PRO350 are medium resolution graphics devices that are capable of plotting four different colors. Penplot divides the screen into a graphics region and a text region. The text portion uses the bottom four lines of the screen and may be used by programs to input and output normal text (i.e. using READ and WRITE statements). The graphics portion occupies the remaining twenty lines of the screen and is accessed through calls to Penplot routines. Below is a list of the various colors that the VT125 and the PRO350 can display. The first column contains the arguments that can be used in a call to the PEN subroutine to set the pen color. ___ ________ ___ _____ _____ _____ PEN_Argument PRO_color VT125_color 0 Black black 1 Blue dim gray 2 Red light gray 3 Green white Penplot now supports the new VS100 monitor from Digital. The VS100 is a fast, high resolution, monochrome graphics device which is capable of plotting up to about 800 x 1000 points on a screen. At the moment, although these devices do have keyboards and mice they are used by Penplot for output only. In addition, they are not terminals. You do not log into a VS100 to use it with Penplot; the plotting package handles the task of allocating one of the VS100's attached to each machine. To use a VS100 with Penplot, simply put a CALL VS100 statement at the start of your program. This routine will try to allocate one of the VS100's attached to your machine and will do the necessary initialization. Because the VS100 is a resource that must be shared among all of the users of a particular machine, there will be times when Penplot will not be allocate a VS100 on the first try. When this happens, Penplot will wait for 10 seconds and try again. By default it will go through 10 'retries' before giving up and calling HDCPY instead. This can be changed at run time by setting the environment variable VS100_RETRIES. For example, to have Penplot not wait for a VS100 to become available, 3 % setenv VS100_RETRIES 0 The advantage in using Penplot instead of a lower level package (especially sending escape sequences directly from a program) is that any program written now can later be made to work with the VS100. A good rule of thumb is: let Penplot do as much of the work as possible. __ ______ ______________ __ ______ ______________ __ ______ ______________ 3. Device Initialization 3. Device Initialization 3._Device_Initialization Although Penplot is device independent (i.e. you don't need to call different routines to plot on different devices), you do need to tell it what devices you wish to use. To do this you must include a call to one of the supported device initialization routines before you call any other Penplot routines. If you do not initialize at least one of the devices your program will not produce any graphics output. Worse yet, your program may abort. If an error is signaled from within a Penplot routine, check to make sure that you have called a device initialization routine at the top of your program. The PLTSEL routine is used to selectively turn on and off various devices. Because of the nature of most Athena applications this will not be very useful and should probably be ignored. __ ___________ ________ ______ __ ___________ ________ ______ __ ___________ ________ ______ 4. Redirecting Graphics Output 4. Redirecting Graphics Output 4._Redirecting_Graphics_Output Providing the ability to change where a program sends its output without having to recompile the program is one of the more important elements of the Unix operating system. In keeping with this philosophy, Penplot has built into it a mechanism that __ ________ allows you to redirect, at_run-time, graphics output being sent to any device. When a device initialization procedure is called (e.g. CALL VT125 in Fortran), Penplot looks into your environment for an environment variable named PLOT_x where 'x' is the CAPITALIZED name of the initialization routine that was called. If there is a variable of that name (e.g. PLOT_VT125), Penplot will send any output for that type of device to the file specified by the environment variable. The examples below assume that the VT125 is the only device that is being used; thus, all of the environment variables in these examples are named PLOT_VT125. 4 ______ ________ Environment variables are manipulated using the setenv, unsetenv, ________ and printenv commands. Your .login file contains several examples of how environment variables are defined. Further information on environment variables can be found by looking in ____ ________ ___ ________ the Athena Unix_Commands manual, or by typing the man__printenv ___ ___ and man_csh commands at the shell. Once an environment variable has been defined it stays defined throughout the rest of your terminal session. The general syntax for defining the PLOT_x variable is: % setenv PLOT_VT125 output-file _______ ________ _______ The section on Penplot_Graphics__Devices mentioned how Penplot divides the screen into two sections: one for graphics and one for normal text (written on the standard output, logical unit 6 in Fortran). The following diagram illustrates the two different sections of the screen and their relationship to the graphics and text streams. +--------------+ | Screen | +---------+ | | | Penplot |---- Graphics output stream -------> | | program |--+ | | +---------+ | |- - - - - - - | +- Textual output stream --------> | +--------------+ By defining the PLOT_x environment variable, you have the ability to manipulate the graphics stream. You can direct it to somewhere else (e.g. send plot to a graphics terminal) or merge it with the text stream so that the two can be manipulated using the shell redirection mechanisms. This is especially helpful in debugging graphics programs and using terminals that can emulate one of the Athena supported devices. In debugging graphics programs, it is often hard to work when the screen is being overwritten by the program you are trying to fix. Penplot Redirection allows you to send all of the graphics to another device (e.g. another terminal or the bit-sink, /dev/null) so that the screen is left clear for diagnostic messages. For example, if you are working with the VT125, you can throw away all of the graphics information by typing the following line before running your program: 5 % setenv PLOT_VT125 /dev/null You can now examine textual output or use the debugger without having to change a single line of code! The most important use of redirection comes when using terminals can emulate supported Athena graphics terminals. If you sit down at a PRO350 and try run a program designed for a VT125 you will not get any graphics output. This happens because Penplot thinks that you are not sitting at a VT125, so it does not generate any graphics. To force Penplot to send all VT125 output to your terminal (the PRO350 does understand VT125 graphics commands), define PLOT_VT125 to be /dev/tty as in the example below. When the VT125 routine is called from your program, Penplot will find the PLOT_VT125 environment variable and send all VT125 output to ________ /dev/tty, the Unix name for your terminal. % setenv PLOT_VT125 /dev/tty When you are sitting at plotting terminal that is supported by Penplot, /dev/tty is the default for the corresponding PLOT_x environment variable. Starting with the June, 1984 release this will change so that the default is to write graphics onto the standard output (see next paragraph). In addition to forcing Penplot to send graphics and text to different places, the PLOT_x variable can be used to send graphics to the standard output stream so that the normal shell redirection mechanism can be used on the graphics and the text together. Since the standard output stream is attached to your terminal by default, this is another good way of forcing Penplot to plot on your screen, even if you are using a terminal that isn't supported in Penplot. To tell Penplot to send graphics to the standard output stream, define the PLOT_x environment variable to be '(stdout)' (note, the quotes and the parentheses are required). The following example shows how you can use this form of Penplot Redirection to send both graphics and text to another terminal. In this case we assume that terminal tty01 is a VT125 or a PRO350. 6 % setenv PLOT_VT125 /dev/tty01 % myprog ... textual output # oops, I want to send the text to the ... # the other terminal also... % setenv PLOT_VT125 '(stdout)' % myprog >/dev/tty01 # send EVERYTHING to another terminal % myprog >myprog.output # save ALL output in a file # to be cat'ed later. In the first example, by defining PLOT_VT125 to be /dev/tty01 instead of '(stdout)', only the graphics will to the other terminal. To get the text to go there also we need to redirect the output from the program using the shell redirection. We could have just typed 'myprog >/dev/tty01', but we really want to redirect the graphics and text together. Thus, we redefine PLOT_VT125 to be '(stdout)' so that we can redirect both streams at the same time (which is, intuitively, what we want to have happen). _____________ In the last example, the file myprog.output can only be displayed on a VT125-compatible terminal. A more general method of storing plots will be part of the June, 1984 release. This is mentioned only as a quick solution to storing graphics output so that long graphics programs need not be rerun wastefully. If you frequently use terminals that can emulate a supported Athena graphics device (such as the PRO350), you might want to ______ put this setenv line into your .cshrc file. The only disadvantage in doing this is that Penplot will no longer prevent you from sending VT125 plots to non-VT125 terminals. __ _______ ________ ____ _______ __ _______ ________ ____ _______ __ _______ ________ ____ _______ 5. Linking Programs with Penplot 5. Linking Programs with Penplot 5._Linking_Programs_with_Penplot To use the Penplot library you must load the library in with your programs whenever you want to create an executable program. This is done by adding the -lpenplot option to command that you would otherwise use to link your program. For example, if you had a program myprog.f which called routines in subs.f and in Penplot, you could use the following commands to compile, link, and test your program: 7 % f77 -c myprog.f subs.f # compile .f Fortran files # to make .o object files % f77 myprog.o subs.o -lpenplot # link % a.out # run the program! To link with other libraries (for example, the NAG library), simply add the appropriate -llibraryname option to the link command: % f77 myprog.o subs.o -lpenplot -lnag The Fortran, C, and Pascal compilers all take the -llibraryname option to specify libraries to be used in linking. In general, __ do not try to use the ld command to load your programs; each language requires a particular set of libraries which the individual compilers understand how to find. __ _______ _______ ____ _____ _________ __ _______ _______ ____ _____ _________ __ _______ _______ ____ _____ _________ 6. Calling Penplot from Other Languages 6. Calling Penplot from Other Languages 6._Calling_Penplot_from_Other_Languages Penplot was designed to be called from Fortran. It can be called from C and probably Pascal if the programmer follows the Inter-Procedure Interface described on Page 7 of the article "A _______ Portable Fortran 77 Compiler" found in the Project Athena Fortran manual. You will need to append an underscore to all of the Penplot subroutine names and you must understand about passing pointers to everything instead of the objects themselves (Fortran uses call by reference whereas C uses call by value). To link a C program that calls Penplot, you must tell it to include the libraries that Fortran uses. The following example shows how to call Penplot routines and how to link the library with your program. % cat myprog.c # look at the program main() { double x,y; /* these are 'real's */ vt125_(); x = 0.; y = 0.; move_(&x, &y); /* must pass addresses */ endplt_(); /* of variables to Fortran */ } % cc -c myprog.c # compile it % cc myprog.o -lpenplot -l{F,I,U}77 -lm # load it % a.out # run it! 8 Calling Penplot from Pascal has not been tried, however it should be fairly similar to what is required above. Calling Penplot from LISP is currently being looked into by a member of the Athena staff. __ _______ __ ___ _______ _______ __ _______ __ ___ _______ _______ __ _______ __ ___ _______ _______ 7. Changes in the Penplot Library 7. Changes in the Penplot Library 7._Changes_in_the_Penplot_Library o The TWRITE subroutine has been removed from Penplot. It was originally developed when Fortran did not have the internal READ or WRITE statements. Users should first use an internal WRITE statement to store formatted data into a character variable, and then call LABEL. For example, CHARACTER*20 BUFFER CALL VT125 WRITE (BUFFER, 10) I,J 10 FORMAT ('I is ',I6,' and J is ',I6) CALL LABEL (BUFFER) CALL ENDPLT END o A new routine, ILORG, has been added. It is used to find out what value was used in the most recent call LORG. For example, C doing some plotting CALL ILORG(ILABORG) CALL LORG (6) C do something special, then restore LORG CALL LORG(ILABORG) o Appendix A of the Penplot Reference Manual contains a list of identifiers that are reserved to Penplot. You may ignore all of the routine names that begin with GR, MG, TK, TP, and VN. However, you should not begin any routine names with VT, HD, or SBCAL. If you create a routine that has the same name as one in the Penplot library your program will NOT run properly. If something is behaving very strangely or gets in a recursive loop and you can't spot the problem, try checking the names of your routines to see if they clash with any of the names in the library. This is a good rule of thumb when you use any library. 9 o There are a number of routines for plotting and annotating axes that are not documented and have not been fully tested. They will be available in the June, 1984 release. In addition, a set of routines that are very similar to the QPICTR and PICTR packages will also be in the June, 1984 release. __ ________ ___ ______ _____ _ ____ __ ________ ___ ______ _____ _ ____ __ ________ ___ ______ _____ _ ____ 8. Clearing the Screen After a Plot 8. Clearing the Screen After a Plot 8._Clearing_the_Screen_After_a_Plot If your program dies in the middle of running, it is possible that your screen will be left in graphics mode (this is the case when the blinking cross-hairs cursor is left on the screen). To fix the screen on a VT125 just push SET-UP and then the 0 (zero) key on the top row of the keyboard. These two keys are often referred to together as SET-UP RESET. To fix a PRO350, push the SET-UP (F4) key at the top of the keyboard. This will put you into the Terminal Emulator Menu. Now, just press the RESUME key (F7) at the top to get back. You will see a message instructing you how to get back to the Terminal Emulator. The screen should now be clear and you can press return to see where you are. If your program has run to completion you notice that the cursor is down at the bottom of the screen. Text in this region will not scroll up into the plot. To clear the screen of text and _____ graphics and to reset the scrolling region, use the clear command. __ _____ __ _____ _______ __ _____ __ _____ _______ __ _____ __ _____ _______ 9. Hints on Using Penplot 9. Hints on Using Penplot 9._Hints_on_Using_Penplot Here some hints on how to avoid some of the more common errors that people have when using Penplot. o If the tail end of a plot is not being displayed, make sure that you have called ENDPLT. This flushes all of the output buffers and closes the devices. If you just want to flush the buffers without ending the plot, put a CALL TSEND line in your program. o Try to stay away from the LIMIT subroutine. Each initialization routine calls LIMIT with the proper values to ensure that plots come out in the same proportions on every device. You can probably do what you want better with the LOCATE, SHOW, or AREA subroutines. o Make sure that you are calling all routines with the 10 right number and type of arguments. Some procedures expect real numbers; some procedures expect integers. A common source of underflow and overflow errors is the mismatching types in procedure calls. Calling a routine with the wrong number of arguments is likely to cause a segmentation fault. o Don't try to ship files generated by Penplot (HDCOPY or HARDCOPY) to Athena's LN01 laser printers, the JCF's Imagen, or LCS's Dover. The hardcopy files are a binary representation of the plot and are not designed to be sent directly to printers. You will get nothing but garbage and run the risk of hopelessly confusing the unsuspecting printer. o Always be careful in chosing names for your routines. A name conflict will probably be one of the last things you'll think of, making you waste a lot of time trying to debug your program. ___ ______ ___________ ___ ______ ___________ ___ ______ ___________ 10. Coming Attractions 10. Coming Attractions 10._Coming_Attractions As mentioned frequently above, there will be another Athena software release in June, 1984. At this time, a number of new features will be added to the Penplot library. Some of the major projects that are currently scheduled for this release are: o Penplot will support the VS100, Digital's new VAXstation, and the PRO350. o High level routines, similar to QPICTR and PICTR, will be provided. o Programs will be able to generate graphic output that can be stored and later plotted on any graphics device. This will be a more general method of creating plot files than the redirection scheme described above. The Project Athena is interested in any comments or suggestions that you may have about Penplot. Please feel free to talk to the Consultant; he or she will pass your thoughts on to the appropriate people. i Table of Contents Table of Contents Table of Contents 1. Introduction 1 2. Penplot Graphics Devices 2 3. Device Initialization 3 4. Redirecting Graphics Output 3 5. Linking Programs with Penplot 6 6. Calling Penplot from Other Languages 7 7. Changes in the Penplot Library 8 8. Clearing the Screen After a Plot 9 9. Hints on Using Penplot 9 10. Coming Attractions 10