aboutsummaryrefslogtreecommitdiff
path: root/plotlib/Doc
blob: 26bed6a7b3648f91aa31e448451364e6771acb0b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
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

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