aboutsummaryrefslogtreecommitdiff
path: root/plotlib/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'plotlib/Doc')
-rw-r--r--plotlib/Doc1004
1 files changed, 1004 insertions, 0 deletions
diff --git a/plotlib/Doc b/plotlib/Doc
new file mode 100644
index 0000000..26bed6a
--- /dev/null
+++ b/plotlib/Doc
@@ -0,0 +1,1004 @@
+/***********************************************************************
+ Module: Doc
+
+ Copyright (C) 1996 Harold Youngren, Mark Drela
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public
+ License along with this library; if not, write to the Free
+ Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+ Report problems to: guppy@maine.com
+ or drela@mit.edu
+***********************************************************************/
+
+
+Xplot11 Graphics Package "Documentation"
+
+C Version 4.46 11/28/01
+
+(submitted in partial fullfillment of the
+ necessity of documenting this package)
+
+
+History
+-------
+This plot package is an "extension" of the ancient Versatec graphics
+routines which are in turn descended from the even more ancient
+Plot10 package that ran Tektronics vector graphics tubes. This
+particular package started off life as a severely hacked version of
+the Versatec software that supported a wide range of graphics
+equipment at MIT's Gas Turbine Lab. At this point the package has
+been hacked and extended to the point where no trace of the original
+source code remains (that is definitely for the best...). Note that
+this package is not PLOT10 compatible, it is closer to a Versatec
+graphics library.
+
+The basic philosophy of page-by-page plotting for both the screen
+window and hardcopy output has been retained. At the device level,
+the major changes have been the use of X-Windows for screen display output,
+and PostScript for hardcopy output, neither of which existed when
+the original Versatec software was developed. Also, both B&W and Color
+output is supported. On the retro-technology side, vector fonts are still
+used to completely sidestep the headaches associated with using bitmaps for
+both X-graphics and PostScript.
+
+
+Intent
+------
+Xplot11 is a collection of routines intended for use in custom applications
+which require more flexibility and power than simple X-versus-Y line plot
+packages, but don't require the complexity of full event-driven screen
+graphics interaction. It has the following key features:
+
++ Direct move-to, draw-to
++ Polyline plot, polygon fill
++ Terminal-type WYSIWYG vector font
++ LaTex-like Greek and math symbol vector font
++ Automatic offset/scaling
++ Automatic zooming
++ Automatic clipping against arbitrary "box"
++ Automatic plot primitive storage in display list for X-window replot
+ and/or PostScript hardcopy.
++ Color X-graphics and color PostScript support (or black & white)
++ Cursor location query via mouse click
+
+Recently added do-dahs include
++ Double buffering
++ limited 3D support
+
+The last item represents the only capability for "interactive" graphics.
+The following features are NOT provided by design:
+
+- Bitmap constructs
+- Continuous X-event recognition
+- Read/Write Colormaps
+- Multiple X windows
+- full 3D support (you really ought to be using OpenGL at that point)
+
+
+
+Implementation
+--------------
+Xplot11 is implemented at three basic levels of routines, but only
+the first, user-level group is called in applications.
+
++ user level routines - these are in the files:
+ plt_base.f
+ plt_font.f
+ plt_color.f
+ plt_util.f
+ plt_3D.f ("3D" support routines for passive display of x,y,z objects)
+
+ plt_old.f (old Versatec-style graphics interface)
+
++ an intermediate level that scales between user and plot, clips and zooms,
+ and handles replotting - these are in the file:
+ set_subs.f
+
++ a hardware support level that interfaces to the postscript and X-windows
+ plotting devices - these are in the files:
+ ps_subs.f
+ gw_subs.f
+ Xwin.c
+
+One major purpose of the intermediate level is to permit the automatic
+generation of a logging list as a side-effect of the user-level calls.
+This list allows the entire current plot to be regenerated by a
+simple call, e.g.
+
+ CALL REPLOT(2)
+
+if the user wants to make a hardcopy of what's visible on the screen, say.
+This call to REPLOT simply takes the calls from the logging list, and calls
+the support-level routines again, but now with PostScript output enabled.
+
+
+Plot Devices
+------------
+
+As mentioned above the plot library only supports two devices, the X-window
+display and hardcopy in the form of output files in postscript. The plot
+device is selected for each plot in the PLOPEN statement which has the
+form:
+ CALL PLOPEN(relsize,lpsunit,idev)
+
+where idev selects the plotting destination as follows:
+
+ idev X-window PostScript
+ ---- -------- ----------
+ 1 x
+ 2 B & W
+ 3 x B & W
+ 4 Color
+ 5 x Color
+
+Note that odd idev's include plotting to the X-window, even values select
+postscript only and can be used with REPLOT to get a hardcopy of the
+current plot.
+
+The lpsunit input specifies the logical unit to use for the postscript output.
+If lpsunit=0 Xplot11 writes to unit 80 and to a file called "plot.ps". If
+lpsunit>0 the plot will be written to unit #lpsunit with the filename
+"plotunitNNN.ps" where NNN=lpsunit. If an open file is found on unit #lpsunit
+Xplot11 will assume the unit is under external program control and will only
+write postscript data to it, no OPENs, CLOSEs or REWINDs will be done. If
+lpsunit<0 is specified separate "plotNNN.ps" files are generated for each
+plot, written to logical unit 80. Separate plot files are numbered starting
+with NNN=000 (i.e. "plot000.ps") and file names are incremented for each plot.
+
+The first parameter, relsize, gives the relative window size and orientation
+to use for the graphics page. A relsize=0.6 gives a graphics window that is
+0.6 of the size of the root X-window. If relsize+>0 the page is in Landscape
+mode (11x8.5), if relsize<0 the page is in Portrait mode (8.5x11). Note that
+relsize does not specify the size for hardcopy, only the screen fraction to
+use to display the page on the screen (more on this below...).
+
+
+Automatic Replot
+----------------
+
+A call to REPLOT(idev) uses the same plotting destinations used in the
+PLOPEN call discussed above. Normally REPLOT is used for either zooming
+a previous plot (with REPLOT(1)) or to make a hardcopy of the current plot
+(with REPLOT(2) or REPLOT(4)).
+
+This automatic logging and replot capability means that the user program
+does not need to be structured to regenerate the plot on demand. This is
+well suited to the kind of program structure used for simple Fortran
+analysis codes (more casual than event-driven programming).
+
+Note that the current logging is done to an array (in memory) until the
+number of plot primitives hits the array limit (set in the parameters in
+pltlib.inc, normally 100,000 or more primitives are stored) then the array
+is paged out to a logging file "xplot11_logfile" that holds the overflow.
+This ensures that a replot can recreate any plot, no matter how complex.
+The log file is currently created on logical unit 81 (which is not available
+to the user as a postscript file unit) and is deleted automatically when the
+user closes plotting.
+
+
+Plotting coordinate systems
+----------------------------
+
+The Xplot11 user interface works with two plotting coordinate systems:
+
+* User units x,y (arbitrary units)
+* Absolute units X,Y (inches for PostScript, pseudo_inches for X-graphics)
+
+1 pseudo_inch on the X-window will show up as 1 inch on PostScript.
+For brevity, a pseudo_inch will be referred to simply as "Inch" henceforth.
+
+
+
+*************************************************************************
+******** Achtung Europeans and Un-American metric zealots !!! ********
+
+If you prefer doing all your plotting in centimeters rather than inches,
+you can make the following source code changes...
+
+In subroutine ps_init (in ps_subs.f):
+
+ccc if(P_SCALE.EQ.0.) P_SCALE = 72.
+ if(P_SCALE.EQ.0.) P_SCALE = 72. / 2.54
+
+
+In subroutine gw_init (in gw_subs.f):
+
+ccc DATA iwdefsize, w1size, w2size / 1000, 11.00, 8.50 /
+ DATA iwdefsize, w1size, w2size / 1000, 27.94, 21.59 /
+
+
+...and then translate "inch" to "centimeter" in this file.
+
+
+While you're at it, you might as well change w1size, w2size above
+to match your strange and unnatural paper dimensions in cm.
+
+*************************************************************************
+
+
+
+
+The absolute (X,Y) axes always span the X-window and PostScript page as
+shown below. The user (x,y) axes are relocatable within the screen or page,
+and are provided mainly for programming convenience:
+
+
+ Y_PAGE -------------------------------
+ | |
+ | |
+ | |
+ | | |
+ | | |
+ | y | |
+ Y | | user system |
+ | | |
+ | +------------- |
+ | x |
+ | |
+ | ABSOLUTE SYSTEM |
+ | |
+ 0 +-------------------------------
+
+ 0 X X_PAGE
+
+
+The transformation (x,y) -> (X,Y) is defined as
+
+ X = X_SCALE*x + X_ORG
+ Y = Y_SCALE*y + Y_ORG
+
+with the start-up values of the offset/scaling transformation parameters being
+
+ X_SCALE = 1.
+ Y_SCALE = 1.
+ X_ORG = 0.
+ Y_ORG = 0.
+
+so that (x,y) is initially the same as (X,Y) when a plot page is started.
+Different offsets and/or scaling factor can be set at any time by
+
+ CALL NEWORIGIN(X_ORG,Y_ORG)
+ CALL NEWFACTORS(X_SCALE,Y_SCALE)
+
+Alternatively one could use the "move-to & re-origin" PLOTABS call.
+
+ CALL PLOTABS(X_ORG,Y_ORG,-3)
+ CALL NEWFACTORS(X_SCALE,Y_SCALE)
+
+The effect of these specifications persists until these parameters are
+changed again or a new plot page is opened with CALL PLOPEN.
+
+
+Alternatively (and confusingly), one can also change the absolute
+transformation offsets X_ORG,Y_ORG via the current user coordinates by
+
+ CALL PLOT(x_org,y_org,-3)
+
+which derives the new absolute offsets directly from the current
+transformation:
+
+ (X_ORG)_new = X_SCALE*x_org + X_ORG
+ (Y_ORG)_new = Y_SCALE*y_org + Y_ORG
+
+In general, PLOT is affected by the current transformation parameters
+whereas PLOTABS is not, so the use of PLOTABS for origin-changing is
+conceptually much simpler.
+
+
+Another alternative way, rather than independently setting origins
+and scale factors, is to set the complete user-absolute
+transformation (offsets and scaling factors) at any time by
+
+ CALL NEWUSERTRANS(X_ORG,Y_ORG,X_SCALE,Y_SCALE)
+
+For convenience, transformation function routines for direct evaluation
+of x(X), y(Y), X(x), Y(y) are provided:
+
+ FUNCTION XABS2usr(X)
+ FUNCTION YABS2usr(Y)
+ FUNCTION xusr2ABS(x)
+ FUNCTION yusr2ABS(y)
+
+It is rarely necessary to use these in applications, however.
+
+Note that the user-to-absolute tranformation can be queried with
+
+ CALL GETUSERTRANS(X_ORG,Y_ORG,X_SCALE,Y_SCALE)
+
+or
+ CALL GETORIGIN(X_ORG,Y_ORG) and
+ CALL GETFACTORS(X_SCALE,Y_SCALE)
+
+
+* * *
+
+The default X-window size is (X_PAGE,Y_PAGE) = ( 11.0 , 8.5 ),
+and can be resized with the mouse via the Window Manager.
+
+For PostScript hardcopy, (X,Y) are inches, so that anything visible
+in the default X-window will just fit on a standard 8.5"x11.0" sheet
+in Landscape orientation.
+
+For the X-window, (X,Y) are "pseudo_inches", whose size depends
+on the physical size of the screen, and on the specified fraction
+of the screen taken up by the window. No matter what size the
+default X-window appears to be on the terminal, its contents
+will fit within a 11.0"x8.5" PostScript page. See "Window Resizing"
+section below.
+
+The alternative 8.5"x11.0" Portrait orientation for both the X-window
+and Postscript is specified via the PLOPEN call list when a new plot
+page is started.
+
+
+* * *
+
+Most Xplot11 routines come in two versions:
+
+ * User-coordinate routines, which receive the user coordinates (x,y)
+
+ * Absolute-coordinate routines, which receive the absolute coordinates (X,Y)
+
+These are essentially the same, except that the user-coordinate routines
+initially perform the transformation (x,y) --> (X,Y) using the current
+transformation parameters X_SCALE, Y_SCALE, X_ORG, YORG, previously
+set as described above.
+
+The absolute-coordinate plot-command routines are:
+
+ PLOTABS
+ POLYLINEABS
+ PLNUMBABS
+ PLCHARABS
+ PLSLANABS
+ PLMATHABS
+ PLSYMBABS
+ PLGRIDABS
+ NEWCLIPABS
+ NEWZOOMABS
+
+The following routines return information in absolute coordinates:
+
+ GETLASTXYABS
+ GETCURSORXYABS
+ GETCLIPABS
+ GETZOOMABS
+
+ GETORIGIN
+ GETWINSIZE
+ GETPAGESIZE
+
+
+Most of the above routines have user-coordinate counterparts,
+typically without the "ABS" name ending.
+
+
+Plot units, Sizing and Zooming
+------------------------------
+
+It should be mentioned that there are two additional coordinate
+systems used inside Xplot11,
+
+- (GX,GY) X-window pixel coordinates
+- (PX,PY) PostScript point coordinates
+
+which actually drive the screen and hardcopy output routines.
+The application does not need to be concerned with these, however.
+
+To further add to the confusion, there is another intermediate
+set of coordinates associated with the built-in zooming feature,
+which "pre-processes" the absolute (X,Y) coordinates before the
+actual X-window and PostScript coordinates are generated.
+The overall data stream is as follows:
+
+ User --> Absolute --> Zoomed-absolute --> X-window,PostScript
+
+ any --> Inches --> Magnified Inches --> pixels , points
+
+ (x,y) --> (X,Y) --> (X',Y') --> (GX,GY), (PX,PY)
+
+ X' = XFAC*(X + XOFF)
+ Y' = YFAC*(Y + YOFF)
+
+
+The interactive zoom routine
+
+ CALL USETZOOM(LXYsame,Lcursor)
+
+asks the user to specify two corners of a "zoom box" on the X-window,
+either by the cursor (if Lcursor = T), or by typing their x,y user coordinates
+or X,Y absolute coordinates (if Lcursor = F). This establishes the
+intermediate coordinate system (X',Y') which results in the selected zoom
+region taking up as much of the output plot page as possible.
+
+When the window is first opened, the zoom parameters are initialized to
+ XOFF = 0.
+ YOFF = 0.
+ XFAC = 1.
+ YFAC = 1.
+
+so that (X',Y') = (X,Y) and there is no zooming. Zooming differs
+from the usual re-origin and scale change in two key ways:
+
+1) It will distort the vector fonts (unless LXYsame = T)
+2) The zoom parameters are NOT reset if a new plot page is started
+ with PLOPEN
+
+The zoom offsets and factors can be directly specified with
+
+ CALL NEWZOOMABS(XOFF,YOFF,XFAC,YFAC)
+
+which explicitly sets the zoom parameters in absolute coordinate offsets and
+zoom factors from absolute->zoomed coordinates. These can be queried with
+
+ CALL GETZOOMABS(XOFF,YOFF,XFAC,YFAC)
+
+The zooming can be reset with
+
+ CALL CLRZOOM
+
+which just resets the zoom parameters to their default initial values.
+
+The simplest way to treat zooming is as a magnifying lens in front of the
+screen and/or hardcopy paper, to be placed and removed interactively at
+the whim of the user. NEWZOOMABS should not be used to do axis scaling,
+shifting, etc, in normal plot operations. That's what NEWFACTORS and
+PLOTABS are for.
+
+
+Window Resizing
+---------------
+
+The window dimensions in absolute units are X_WIND,Y_WIND. These are
+initialized to be the same as X_PAGE,Y_PAGE, these in turn having default
+values set in the parameter statements in pltlib.inc.
+
+If the window is resized with the mouse, then X_WIND,Y_WIND are reset
+appropriately on the next PLOPEN or REPLOT call. This resetting is done
+so that
+
+a) Y_WIND/X_WIND matches the window aspect ratio in pixels.
+b) X_WIND,Y_WIND do not exceed X_PAGE,Y_PAGE, respectively.
+
+The latter requirement ensures that whatever is visible in the window
+will fall within the X_PAGE,Y_PAGE limits, and hence will fall on the
+hardcopy page. Not all of the page will be "covered" by the graphics
+window if the window aspect ratio doesn't match the page aspect ratio.
+Two such possible situations are shown below.
+
+
+ Y_PAGE+---------------------+ Y_PAGE+---------------------+
+ Y_WIND|.............. | | |
+ |. . | | |
+ |. . | Y_WIND|.....................|
+ |. . | |. .|
+ |. . | |. .|
+ |. . | |. .|
+ |. . | |. .|
+ |.............. | |.....................|
+ 0 +---------------------+ 0 +---------------------+
+ 0 X_WIND 0 X_WIND
+ X_PAGE X_PAGE
+
+
+In general, interactively resizing the window has no effect on what
+comes out on hardcopy, but it obviously does affect what is visible
+on the screen. Adjusting of the plot aspect ratio to fit a resized
+window must be done by the application itself. The current window
+size can be interrogated with
+
+ CALL GETWINSIZE(X_WIND,Y_WIND)
+
+at any time.
+
+
+
+Color and Colormaps
+-------------------
+
+The original Versatec hardware (back when I was a lad...) supported
+only black and white plots. This is the 90's however and color
+graphics have become ubiquitous (and useful!).
+
+The two graphics output devices used for Xplot11, the Xwindows screen
+and the postscript output, both support color graphics. In the
+interests of portability, the color support for Xplot11 has been aimed
+primarily at a modern minimal configuration, an 8-bitplane color
+graphics system. In worst case, if the Xserver does not support at
+least 16 colors the package degrades gracefully to provide B&W screen
+graphics. Xplot11 can also generate either B&W postscript or color
+postscript output, as selected by the user.
+
+Colors in Xplot11 are manipulated by the use of a COLORMAP which contains up
+to 256 entries, each of which has an associated color value (red,green,blue).
+Unfortunately not all of these 256 may be available at all times. This
+limitation arises because Xplot11 uses a read-only Xwindow colormap where
+colors are allocated and shared with other applications. This limits the
+number of colors that an application may use but has the advantage that
+colors will not change as the input focus (mouse) moves through various
+windows that each try to reload the graphics hardware with their own private
+colormap. The extent of the X colormap used by other Xwindow applications is
+typically less than 30-40 colormap entries, depending on what other windows
+are displaying. For an 8-bit color depth, this leaves around 220 or so
+available for use by Xplot11. Note that this may not be true for your system
+if other color-hogging applications are running (such as a window manager with
+lots of pretty colored icons). You can monitor the number of colors used in
+the read-only colormap with the xcmap command (part of the X distribution, at
+least one of the X contributed programs that is typically available with X).
+
+Note that the number of colors available in postscript output is unlimited
+but Xplot11 has a 256 color limit.
+
+
+
+The default color setting for Xplot11 is to plot white lines on a black
+background to reduce glare and enhance color saturation. Some people prefer
+to use non-reverse video (black foreground on white background). Black
+plotting on white can be selected for Xplot11 plots by setting an environment
+variable:
+
+using the csh or tcsh shell
+ % setenv XPLOT11_BACKGROUND white
+using the sh or bash shell
+ % export XPLOT11_BACKGROUND=white
+
+To restore white-on-black video:
+
+using the csh or tcsh shell
+ % unsetenv XPLOT11_BACKGROUND
+or % setenv XPLOT11_BACKGROUND black
+using the sh or bash shell
+ % export XPLOT11_BACKGROUND=black
+
+Note that, even though this reverses black and white in the video,
+PostScript plots will still be done as black-on-white to save toner.
+Note that, internally, Xplot11 always assumes that "white" is the
+background color. In reverse-video mode the roles of black and white
+are reversed only to the X window, where the color "black" plots to the
+screen as white and the color "white" plots as black, all other colors
+are unaffected. This may be a little confusing if you are looking at a
+reverse video plot with white lines that are selected with the color "black".
+
+
+
+Colors can be allocated to the colormap in several ways.
+
+- A default map with 10 basic colors is set up by the package with
+ the corresponding colormap indices. These are set as parameters
+ in the convenient include file colors.inc .
+
+ BLACK = 1
+ WHITE = 2
+ RED = 3
+ ORANGE = 4
+ YELLOW = 5
+ GREEN = 6
+ CYAN = 7
+ BLUE = 8
+ MAGENTA = 9
+ VIOLET = 10
+
+Their RGB color components are defined in SUBR. COLORMAPDEFAULT,
+and can be easily tuned to personal preference. They can be displayed
+with the simple program defmap:
+
+ % make defmap
+ % defmap
+
+The default 8 RED...VIOLET colors are not fully saturated, but
+are darkened somewhat to be adequately visible on black and on white
+backgrounds alike (i.e. in both normal and reverse-video modes).
+They are well-suited for use with the 8 line styles implemented
+in SUBROUTINE XYLINE.
+
+
+- A color can be allocated or selected by name (like BLACK, ORANGE,
+ tan, steelblue,RED...) where the color names must be known to the Xwindows
+ server (look in the file /usr/lib/X11/rgb.txt for a complete definition)
+
+- A color can be allocated or selected by its red,green,blue components
+ e.g. R,G,B = (0-255,0-255,0-255)
+
+- A continuous range of colors can be allocated at once with a "spectrum"
+ colormap, by calling one of the following routines:
+
+ subroutine COLORSPECTRUMHUES(ncols,HUESTR)
+ subroutine COLORSPECTRUMTRP(ncols,NBASE,IRGBBASE,COLWIDTH)
+ subroutine COLORSPECTRUMRGB(NRGB,IRGB)
+
+ These create additional colors, and append them as a "Spectrum" to the
+ end of the current colormap. The spectrum colors are intended mainly
+ for use in color contouring, etc.
+
+ The three routines above have three different ways to specify the
+ "spectrum", with increasing levels of input detail, ranging from
+ a simple rainbow hue string "RYGB" to an array of r,g,b components
+ for each color in the "spectrum" (see their comment headers).
+
+Different hue strings can be tried out with program spectrum:
+
+ % make spectrum
+ % spectrum
+
+
+
+Once allocated, colors in the Xplot11 colormap may be selected, as mentioned
+above, with a color name
+
+ CALL NEWCOLORNAME('cyan')
+
+or the r,g,b components
+
+ CALL NEWCOLORRGB(0,255,255)
+
+or by an absolute color index,
+
+ CALL NEWCOLOR(7)
+
+or by a "Spectrum" color index.
+
+ CALL NEWCOLOR(-48)
+
+
+A positive color index can run from 1 to N_color (# of all colors allocated),
+although this is typically used to access the first 10 or so default colors
+for simple line plots, etc.
+
+A negative color index can only run from -1 to -N_spectrum (# of Spectrum
+colors allocated via one of the COLORSPECTRUMxxx routines). These colors
+are a subset of the full colormap, and are typically used to do orderly
+shading with the closely-spaced Spectrum colors.
+
+
+ _ _____
+ 1 |_rgb_|
+ | 2 |_____|
+ | 3 |_____|
+ 4 |_____|
+default 5 |_____|
+colors 6 |_____|
+ 7 |_____|
+ | 8 |_____|
+ | 9 |_____|
+ _ 10 |_____|
+ 11 |_____| -1 <- note that the first spectrum color may be
+ 12 |_____| -2 located at an index > 11 since the user may
+ 13 |_____| -3 allocate colors (named or RGB) before
+ . . . allocating the spectrum
+ . . .
+ _____
+ N_color |_____| -N_spectrum
+
+
+
+Double Buffering
+-----------------
+
+Xplot11 now supports double buffering (although this is getting kind of
+overly exotic for a simple plot package, it was so simple we added it).
+The double buffering can be used to do primitive animation without the screen
+flickering that would otherwise spoil the effect. You open a plot as usual
+but now you can redirect drawing to a pixmap buffer rather than to the X
+window. This done with a DRAWTOBUFFER call before you do any plotting.
+This will cause a redirection of the plot so that none of the buffer drawing
+will appear until a SHOWBUFFER or PLFLUSH is called. At this point the
+buffer pixmap is copied to the X window. Double buffering can be stopped
+with a DRAWTOSCREEN to change the plot destination back to the X window.
+
+The new double-buffering functions are
+
+ SUBROUTINE DRAWTOSCREEN Sets plotting destination to screen
+ SUBROUTINE DRAWTOBUFFER Sets plotting destination to background buffer
+ SUBROUTINE SHOWBUFFER Displays contents of background buffer to screen
+
+
+
+Fonts and Symbols
+-----------------
+
+Xplot11 supports only vector fonts as a matter of policy. Currently
+there are three fonts available, implemented in three routines which
+take character strings to be plotted as arguments:
+
+ SUBROUTINE PLCHAR Keyboard-style WYSIWYG ASCII characters
+ SUBROUTINE PLSLAN Slanted version of PLCHAR
+ SUBROUTINE PLMATH LaTex-like Greek letters and math symbols
+
+There is also a plotting symbol routine which plots simple geometric
+shape "characters" one at a time, indexed by an integer argument.
+
+ SUBROUTINE PLSYMB
+
+All font routines come in absolute-coordinate and user-coordinate
+versions, e.g.
+
+ CALL PLCHAR (x,y,ch,'ABCdef',0.0,6)
+ or CALL PLCHARABS(X,Y,CH,'ABCdef',0.0,6)
+
+The location x,y or X,Y positions the lower-left corner of the first
+character. The user-coordinate character width parameter ch passed
+to PLCHAR is converted to an absolute width by using X_SCALE (not Y_SCALE).
+Having different X_SCALE and Y_SCALE will not distort the fonts,
+since only X_SCALE is used to plot them.
+
+
+The font routines have their vector fonts encoded in DATA statements
+in four separate include files CHAR.INC, SLAN.INC, etc. New fonts
+can be created or the existing ones modified by the interactive program
+symgen in the sym/ directory. File sym/Readme has more information.
+
+To display the four available fonts and some sample character
+strings, run program test in the sym/ directory:
+
+ % cd sym
+ % make test
+ % test
+
+This will generate a screen display and the corresponding PostScript
+file plot.ps which can be printed as a handy programming reference.
+
+
+In addition to the basic vector font routines above, there is
+also a higher-level SUBROUTINE PLNUMB which takes a real argument
+and plots the corresponding numeral. This routine does not have
+an associated font, but instead calls PLCHAR to plot the individual
+digits, decimal point, etc. Like with the other font routines,
+an absolute-coordinate version PLNUMBABS is also available.
+
+
+
+Utility Routines
+----------------
+
+The source files plt_util.f and plt_3D.f contain frequently-used
+higher-level routines which are convenient for building applications.
+For example, a plain x-y plot can be made with three simple calls
+
+ CALL XAXIS(...)
+ CALL YAXIS(...)
+ CALL XYLINE(...)
+
+although a few preparatory calls to AXIS_ADJ or other scaling routines
+might be necessary to set up the appropriate call list parameters.
+Additional calls to PLCHAR, PLGRID, might also be desirable for
+annotation and grid overlay.
+
+
+The annotation routine is useful for interactive annotation,
+and is simply invoked with:
+
+ CALL ANNOT(char_size)
+
+Anything the user places on the screen while in ANNOT will be
+automatically logged and can be echoed to PostScript with
+
+ CALL REPLOT(2)
+
+as described earlier.
+
+
+
+==================================================================
+
+
+Typical application calling sequences are illustrated below.
+
+c==== This comment lead indicates a required call. All others are optional.
+
+
+
+c==== Initialize plot routines, sets up default (10 color) colormap
+ CALL PLINITIALIZE
+c
+c---- Additional "Spectrum" colormap with hardwired definitions
+c (1..64 colors ranging from Blue to Cyan to Green to Yellow)
+ CALL COLORSPECTRUMHUES(64,'BCGY')
+c
+c---- Alternative Spectrum-setup call are given below...
+c- (these are more general, but more awkward to set up)
+c
+c---- User-supplied "Spectrum" interpolated from base color RGB components
+c (in lieu of COLORSPECTRUMHUES call above)
+CCC CALL COLORSPECTRUMTRP(64,NBASE,IRGB,COLWIDTH)
+c
+c---- User-supplied "Spectrum" defined by RGB components
+c (in lieu of COLORSPECTRUMHUES or COLORSPECTRUMTRP call above)
+CCC CALL COLORSPECTRUMRGB(NRGB,IRGB)
+c
+c
+c==== start new X-window plot, Postscript output to default unit and file
+c normally "plot.ps" and logical unit 80, no PostScript yet
+ CALL PLOPEN(0.8,0,1)
+c
+c---- move origin +0.1,+0.1 Inches
+ CALL PLOT(0.1,0.1,-3)
+c
+c---- blow up everything 5x in both directions
+ CALL NEWFACTOR(5.0)
+c
+c---- draw some lines
+ CALL NEWPEN(3)
+
+ CALL PLOT(x,y,...
+
+ CALL PLOT(x,y,...
+c
+c---- select color #4 in colormap
+ CALL NEWCOLOR(4)
+c
+c---- alternative to NEWCOLOR call above (will add color if not defined)
+CCC CALL NEWCOLORNAME('orange')
+c
+c---- another alternative to NEWCOLOR call (will also add color if necessary)
+CCC ired = 250
+CCC igrn = 150
+CCC iblu = 0
+CCC CALL NEWCOLORRGB(ired,igrn,iblu)
+c
+c---- plot a number
+ CALL PLNUMB(x,y,...
+c
+c---- flush X buffer so everything is on screen
+ CALL PLFLUSH
+c
+c==== finish plot page
+ CALL PLEND
+c
+c
+c---- replot everything (since last PLOPEN call) to PostScript file "plot.ps"
+ CALL REPLOT(2)
+c
+c
+c---- query window size (might have been changed by user via mouse)
+ CALL GETWINSIZE(Xmax,Ymax)
+c
+c
+c
+c==== start another plot page in Portrait orientation, with simultaneous PS
+c (this resets all re-origins, scaling)
+ CALL PLOPEN(-0.8,0,3)
+c
+c---- blow up everything 10x, 5x
+ CALL NEWFACTORS(10.0,5.0)
+c
+c---- plot x,y axes
+ CALL XAXIS(x0,y0,xlen,dxlen,xann0,dxann,csize,-2)
+ CALL YAXIS(x0,y0,ylen,dylen,yann0,dyann,csize,-2)
+c
+c---- label x axis
+ CALL PLCHAR(x0+0.5*xlen,y0-3.0*csize,csize,'X_variable',0.0,10)
+c
+c---- select Spectrum color #33 and plot a grid
+ CALL NEWCOLOR(-33)
+ CALL PLGRID(x0,y0,...
+c
+c---- plot x(y) line with line pattern 3
+ CALL XYLINE(n,x,y,xoff,xwt,yoff,ywt,3)
+c
+c---- replot everything since last PLOPEN call, in case window got resized
+ CALL REPLOT(1)
+c
+ CALL PLOT(x,y,...
+ CALL PLOT(x,y,...
+ CALL PLFLUSH
+c
+c---- get cursor location in user coordinates x,y
+ CALL GETCURSORXY(x,y,chkey)
+c
+c---- get cursor location in absolute coordinates x,y
+ CALL GETCURSORXYABS(x,y,chkey)
+c
+ CALL NEWPEN(4)
+c
+c---- plot character(s) at cursor location in absolute coordinates
+ CALL PLCHARABS(X,Y,ch,'Test',0.0,4)
+c
+ CALL PLOT(x,y,...
+ CALL PLOT(x,y,...
+ CALL PLFLUSH
+c
+c---- ask user to specify zoom area (distortion OK, using cursor)
+ CALL USETZOOM(.FALSE.,.TRUE.)
+c
+ CALL PLOT(x,y,...
+ CALL PLOT(x,y,...
+c
+c---- clear zoom if next plot page is not to be zoomed
+ CALL CLRZOOM
+c
+c==== finish plot page
+ CALL PLEND
+c
+c---- same as PLEND call above
+ccc CALL PLOT(0.0,0.0,-999)
+c
+c
+c---- end of all plotting, close window, close PostScript file
+ CALL PLCLOSE
+c
+c---- same as PLCLOSE call above
+ccc CALL PLOT(0.0,0.0,+999)
+
+
+
+==================================================================
+
+To make a list of user interface routines, do the following...
+
+ % grep " subroutine" plt*.f
+
+
+The source file plt_old.f contains the equivalent of the old Versatec
+user interface routines (this set includes some of the basic routines
+that were retained in the extended package) provided for backwards
+compatibility. These routines should not be used in new applications,
+since the intent is to phase them out sometime in the 21st Century:-)
+
+
+The other source files set_subs.f, ps_subs.f, gw_subs.f, Xwin.c
+contain internal support routines. These are not intended to be
+called by applications (there's no reason to do so in any case).
+
+
+====================================================================
+
+
+Sample and test programs
+-------------------------
+
+volts.f - demo program that draws a simple, labeled plot with axes.
+
+volts_old.f - demo program that draws a simple, labeled plot with axes.
+ (uses old "Versatec" plot calls)
+
+squares.f - draws a sine wave in colored boxes with colored labels
+
+squaresdoublebuff.f - tests the double buffering with a sine wave with
+ dynamic color sequence in the colored boxes
+
+gridtest.f - tests the grid routines (obvious, aren't we...)
+
+symbols.f - display and test the basic vector fonts
+
+symbolsall.f - display and test all the vector fonts and symbols, has option
+ to test the separate plot file or external plot file options
+
+cmap2.f
+cmap3.f - used for interactive viewing of RGB color components:
+
+zoomtest.f - test of zooming, enter T T to prompt to keep scale, use cursor
+
+contest.f - test of contoured, filled plots
+
+defmap.f - displays the default colormap produced by CALL COLORMAPDEFAULT
+
+spectrum.f - displays the "Spectrum" produced by
+ CALL COLORSPECTRUMHUES(ncols, RYGCBM_string)
+ in pie and bar form.
+
+ Typical values for RYGCBM_string might be
+ 'RYG'
+ 'GYR'
+ 'MCY'
+ 'BMRY'
+ 'BCGYR', etc.
+
+ Choosing strongly non-contiguous sequences like 'RCB' is OK,
+ but will make a horrid-looking Spectrum.
+
+sym/test.f - display current vector fonts
+
+====================================================================
+
+