/*********************************************************************** 
    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

====================================================================