forked from noirlab-iraf/iraf-docs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgio.txt
3717 lines (2545 loc) · 162 KB
/
gio.txt
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
GIO (Dec84) Graphics I/O GIO (Dec84)
GRAPHICS I/O DESIGN
Doug Tody
December 1984
(revised October 1987)
1. INTRODUCTION
The graphics i/o (GIO) interface is a library of SPP or Fortran
callable procedures for interactive vector graphics. The interface is
designed primarily for scientific applications (graphing 1-dimensional
data vectors). Limited support is also provided for displaying
2-dimensional image data. GIO is fully integrated into the IRAF system
and is not intended for use in systems other than IRAF. The principal
design objectives of GIO are outlined below.
o Simple and efficient interactive graphics. For interactive
data analysis applications speed is typically much more
important than the quality of the plot.
o Ease of use. The interface must be easy to use for scientific
data analysis applications. Ease of use for interactive
graphics in scientific applications is considered more
important than the flexibility required to produce publication
quality graphics.
o Compact size. That portion of the graphics system required for
interactive graphics must be small enough to be linked into
every process which performs interactive graphics.
o Device independence. The interface must be device independent
without compromising compactness and speed. True device
independence means that an applications program that normally
uses interactive graphics can be run noninteractively or from a
nongraphics workstation.
IRAF needs its own graphics interface partly because no existing
graphics interface meets all of the above requirements, and partly
because we do not want our applications to be dependent upon any
particular external graphics package. The existing large graphics
interfaces such as GKS and CORE are likely to make it easier to
interface GIO to new graphics devices, but to be completely and
directly dependent on any one such interface is unwise since
implementations are sometimes hard to come by. Furthermore, packages
such as GKS and CORE were designed to serve as the kernel of a graphics
system and are cumbersome to use directly in applications software.
GIO will serve as a front end to the graphics kernel, providing a
higher level interface for applications software and isolating the IRAF
applications from the kernel, making it possible to switch to a
different kernel without rewriting the applications packages.
-1-
GIO (Dec84) Graphics I/O GIO (Dec84)
2. CONCEPTUAL DESIGN
GIO is intended to be used either as a self contained interface to a
graphics device, with GIO writing device instructions directly to the
device, or as an interface to a more general device independent
graphics kernel. For maximum speed in interactive applications GIO
will use a special builtin kernel capable of driving only the
interactive graphics devices in use at a particular site (e.g.,
tektronix compatible graphics terminals). Other devices will be driven
by a device independent graphics kernel resident in a separate
process. GIO will select the data path to be used for a particular
device transparently to the calling program. Thus, the overhead of
process initiation and IPC will be eliminated in common interactive
applications without sacrificing device independence. The builtin
kernel will be table driven using a TERMCAP format graphics device
database, allowing maximum flexibility for adapting GIO to new graphics
devices.
The device independent graphics kernel may be GKS, CORE, NSPP, or any
other reasonably capable kernel. GIO will be designed to require only
a few simple graphics primitives at the bottom end, making it
straightforward to interface to different graphics kernels. Any
application which requires a more sophisticated graphics interface than
that provided by GIO may bypass GIO and talk directly to the underlying
graphics kernel, but doing so will render the application usable only
with that particular graphics kernel.
Placing the device independent graphics kernel in a separate process
makes it possible to use a large, sophisticated graphics kernel without
linking enormous libraries of subroutines into applications processes.
Bugs can be fixed and new features and devices added without relinking
applications processes. In principle it is even possible to interface
simultaneously to more than one graphics kernel, e.g., one might drive
some devices with an NSPP kernel and others with a GKS kernel. On a
different host CORE might be the only thing available and GIO would
have to be interfaced to CORE on such a host.
-2-
GIO (Dec84) Graphics I/O GIO (Dec84)
__________
/ \
| graphics |
| terminal |
\__________/
| ^
| |(device codes)
v | _________
+--------+ +-----------+ / \
| CL+ |<----| graphics |<----| |
| fast | | kernel | | gdevice |
| kernel |---->| task |---->| |
+--------+ +-----------+ \_________/
| ^ |
| |(gki metacode) | (core metacode)
v | +--------> (nspp metacode)
+--------+ (gks vdm)
| user |
| task |-----------------------> (gki metacode)
+--------+
simple plotters
|--- interactive ---|------ metafile ------|
graphics special devices
Figure 1. Graphics Task Structure
The IRAF command language (CL) is the user interface to IRAF programs
and as such moderates all interaction with the user, including
interaction via graphics devices. GIO is primarily a graphics OUTPUT
interface; graphics input (other than pixel readback) is decoupled from
graphics output and is controlled by the CL. Often the task requesting
cursor input will differ from that which produced the graphics. The
CL, under control of the user, may set the default graphics input and
output devices, redirect graphics input and/or output to devices other
than the default, and control whether a graphics task is used
interactively or in batch mode.
3. SPECIFICATIONS
The GIO graphics output procedures draw various flavors of vectors
and fill or color two dimensional areas. Cursor input is a way of
interacting with the user and is therefore handled by CLIO (the command
language interface). We first define important terms and define the
coordinate systems used by GIO. Next follows an overview of the input
and output procedures. Finally, we describe in detail the individual
procedures and the interface to the graphics kernel.
-3-
GIO (Dec84) Graphics I/O GIO (Dec84)
3.1 COORDINATE SYSTEMS
The full plotting surface of a device defines the domain of
definition of the coordinate systems used by GIO. GIO supports up to
sixteen user defined WORLD COORDINATE SYSTEMS (WCS) per open device,
numbered 1 through 16. One additional coordinate system (WCS 0) with
values ranging from 0 to 1 in either axis is predefined for every
device; this NORMALIZED DEVICE COORDINATE SYSTEM (NDC) spans the full
plotting surface of the device.
The mapping of world coordinates to device coordinates is defined by a
WINDOW into world space and a corresponding VIEWPORT into device
space. Each window-viewport pair defines one of the 16 world
coordinate systems. At GOPEN time GIO is initialized to WCS 1, which
has both window and viewport set to NDC coordinates. A subsequent call
to either GSWIND or GSCALE will set the window and a subsequent call to
GSVIEW will set the viewport. The WCS is not fixed to the device until
a plotting operation occurs which requires use of the WCS. Hence,
multiple calls to GSCALE to determine the range of data values in X and
Y for a family of curves are possible before fixing the WCS to the
device, e.g. in a call to GLABAX.
A VIEWPORT is any rectangular plotting area lying entirely within the
plotting area of the device. The viewport defines the area in which
data can be plotted, i.e., the boundary at which CLIPPING will occur if
enabled. The viewport is the area framed by GLABAX; the tick and axis
labels will be plotted in the area just outside the viewport. A square
viewport need not have the same resolution in both X and Y. Devices
with variable resolution, e.g. pen plotters, have a default resolution
in either axis which can be overridden when the plot is drawn. The
aspect ratio of the device is the ratio of the physical size of a
device pixel in Y to that in X. Most devices have an aspect ratio of
unity, but it is common for the resolution to be different in X and Y.
The aspect ratio of the device is available via a GGET inquiry, as is
the device resolution in either axis.
A WINDOW is the range of world coordinates which GIO will map to the
corresponding viewport. The world coordinates must be cartesian and
either linear or logarithmic (base 10) in either axis. There are no
restrictions on the range of world coordinates other than those imposed
by the single precision floating point hardware of the host computer,
provided that the WCS is not degenerate (zero range in either axis).
Most applications will use only a single WCS, hence the WCS number is
not included explicitly in the argument lists of the GIO procedures. A
call to GSET is required to change to a different WCS. Thereafter all
graphics output and cursor input will refer to the new WCS. Multiple
WCS are useful when plotting in several distinct (nonoverlapping)
viewports on a device, or when overplotting curves within the same
viewport but with different world coordinate windows.
-4-
GIO (Dec84) Graphics I/O GIO (Dec84)
3.2 GRAPHICS OUTPUT PROCEDURES
The GIO output procedures range from GPLOTV and GPLOTO, which can
draw an entire plot with autoscaling and axis labelling in one call, to
the polyline, polymarker, move, draw, and text drawing primitives at
the low end.
gplotv (v, npts, x1, x2, title)
gploto (gp, v, npts, x1, x2, title)
gpagefile (gp, fname, prompt)
gp = gopen (device, mode, fd)
gclose (gp)
gdeactivate (gp, flags)
greactivate (gp, flags)
gcancel (gp)
gflush (gp)
gclear (gp)
gframe (gp)
greset (gp, flags)
gmftitle (gp, metafile_title)
gscan (gp, text)
gset[irs] (gp, param, value)
val = gstat[irs] (gp, param[, outstr, maxch])
val = gget[birs] (gp, devcap[, outstr, maxch])
g[sg]view (gp, x1, x2, y1, y2)
g[sg]wind (gp, x1, x2, y1, y2)
g[ar]scale (gp, v, npts, axis)
ggscale (gp, x, y, dx, dy)
gctran (gp, x1, y1, x2, y2, wcs1, wcs2)
gcurpos (gp, x, y)
gescape (gp, fn, instruction, nwords)
glabax (gp, title, xlabel, ylabel)
gline (gp, x1, y1, x2, y2)
gpline (gp, x, y, npts)
gvline (gp, v, npts, x1, x2)
gmark (gp, x, y, marktype, xsize, ysize)
gpmark (gp, x, y, npts, marktype, xsize, ysize)
gvmark (gp, v, npts, x1, x2, marktype, xsize, ysize)
gumark (gp, x, y, npts, xcen, ycen, xsize, ysize, fill)
g[ar]move (gp, x, y)
g[ar]draw (gp, x, y)
gtext (gp, x, y, text, format)
gfill (gp, x, y, npts, style)
g[pg]cell (gp, m, nx, ny, x1, y1, x2, y2)
gscur (gp, x, y)
stat = ggcur (gp, x, y, key)
All coordinates are given in world coordinates (user coordinates)
except the viewport coordinates and the marker sizes, which are given in
-5-
GIO (Dec84) Graphics I/O GIO (Dec84)
device coordinates. Low level graphics i/o requires that the graphics
device first be opened with GOPEN and later closed with GCLOSE.
Several graphics devices may be open simultaneously.
When a graphics device is opened with GOPEN all internal parameters are
initialized to their default values, unless the device is opened in
APPEND mode. The default values of these internal parameters may be
changed via explicit GSET, GSWIND, GSCALE, or GSCAN calls. Most
powerful is GSCAN, which interprets graphics commands passed either as
an explicit string or in a text file.
Much of the flexibility of GIO derives from its parameter defaulting
mechanism. The interface may be expanded indefinitely by adding new
internal parameters accessed via GSET calls, without changing the basic
interface.
3.3 GRAPHICS INPUT PROCEDURES
The most commonly used type of graphics input is cursor readback.
Two forms of cursor input are supported: cursor input via the CLIO
procedure CLGCUR, and cursor input via the GIO procedure GGCUR. CLIO
based cursor input should be used whenever possible, i.e., when writing
to STDGRAPH or STDIMAGE. The advantage of cursor input via the CL is
that input may come from a list file or the terminal as well as from a
physical cursor read, allowing programs to be used either interactively
or in batch mode. Furthermore, WCS selection and conversion of NDC
cursor coordinates to WCS and cursor mode interaction are only
available with CLGCUR. Programs which do not produce any graphics
output may read the cursor via CLIO without using any part of the GIO
interface. The lower level GIO cursor read procedure always reads the
physical device cursor in NDC coordinates and is device dependent (it
is what is called by CLGCUR).
Cursors are implemented as abstract datatypes within the CL. A user
task accesses a cursor by reading the value of a CL parameter of type
GCUR (stdgraph cursor) or IMCUR (stdimage cursor). Multiple cursors may
be implemented using multiple cursor type parameters. A cursor
parameter is assumed to have a LIST of values; EOF is returned when the
end of the list is reached. Reading the cursor automatically causes
any graphics output to be flushed.
stat = clgcur (param, wx, wy, wcs, key, strval, maxch)
The CLIO function CLGCUR reads the next cursor value from the named
cursor parameter, returning as output arguments the cursor position in
world coordinates, the index of the referenced WCS, the keystroke value
(character typed) of the cursor event, and a string value if the key
was ':', the cursor mode set option escape character. A cursor read
sequence begins with a prompt, i.e., the cursor lights up or starts
blinking. The user is then free to move the cursor about; the cursor
position is not read until a key is typed on the user terminal. Using
a keystroke on the user terminal to terminate both STDGRAPH and
STDIMAGE cursor reads provides a rich and device independent set of
-6-
GIO (Dec84) Graphics I/O GIO (Dec84)
keystroke values for identifying the action to be performed (imaging
devices are typically very limited in this area).
GIO always returns the cursor position in world coordinates, along with
the index of the WCS selected. Typically there will be exactly one
world coordinate system (excluding WCS 0) and the WCS value may be
ignored. If no world coordinate systems are defined for the device the
cursor position will be returned in NDC coordinates with WCS=0.
If multiple world coordinate systems are defined GIO will select the WCS
closest to the position of the cursor, i.e., the cursor may lie outside
the viewport and GIO will still return WCS coordinates. If the cursor
lies within two or more overlapping viewports GIO will select the WCS
with the highest number. The cursor read protocol will allow the user
to force the selection of a particular viewport by first placing the
cursor on a nonoverlapping portion of the viewport and typing a special
code, e.g., W (see next section), and then continuing with the normal
cursor read. If the application wishes to override the automatic WCS
selection it may do so by calling GCTRAN to transform the cursor
coordinates returned by CLGCUR to a different world coordinate system.
3.3.1 CURSOR MODE
In cursor mode, i.e., after a call to CLGCUR or after typing
"=gcur", a number of special keystrokes shall be recognized for
interactive display control. All graphics output to stdgraph and
stdimage is routed through the CL on the way to the graphics kernel.
The CL will optionally spool in an internal buffer all graphics
instructions output to an interactive device. This internal buffer is
emptied whenever the device screen is cleared. In cursor mode, special
keystrokes may be used to redraw all or any portion of the spooled
graphics, e.g., one may zoom in on a portion of the plot and then roam
about on the plot at high magnification. Since the spooled graphics
vectors typically contain more information than can be displayed at
normal magnification, zooming in on a feature may bring out additional
detail (the maximum resolution is 32768 points in either axis).
Increasing the magnification will increase the precision of the cursor
by the same factor.
Cursor mode is implemented by performing coordinate transformation and
clipping on each GKI instruction in the frame buffer, passing the
transformed and clipped instructions on to the graphics kernel. The
cursor mode operations perform a simple geometric transformation on the
spooled graphics frame, mapping a rectangular window of the spooled
frame onto the device screen. The graphics frame itself is not
modified, hence zoom out or reset and redraw will restore the original
display.
If the graphics frame is a typical vector plot with drawn and labelled
axes, magnifying a portion of the plot may cause the axes to be lost.
If this is not what is desired a keystroke is provided to draw and label
the axes of the displayed window. The axes will be overplotted on the
current display and will not be saved in the frame buffer, hence they
-7-
GIO (Dec84) Graphics I/O GIO (Dec84)
will be lost when the frame is redrawn. In cursor mode the viewport is
the full display area of the output device, hence the tick mark labels
of the drawn axes will be drawn inside the viewport. This form of axes
labelling is used because it is simple and because it is appropriate for
both vector graphics and image display output devices (and cursor mode
must serve both).
A draw and label the axes of current viewport
B backup over last instruction in frame buffer
C print the cursor position as it moves
D draw a line by marking the endpoints
E expand plot by setting window corners
F set fast cursor (for HJKL)
H step cursor left
J step cursor down
K step cursor up
L step cursor right
M move point under cursor to center of screen
P zoom out (restore previous expansion)
R redraw the screen
T draw a text string
U undo last frame buffer edit
V set slow cursor (for HJKL)
W select WCS at current position of cursor
X zoom in, X only
Y zoom in, Y only
Z zoom in, both X and Y
< set lower limit of plot to the cursor y value
> set upper limit of plot to the cursor y value
\ escape next character
: set cursor mode options
:! send a command to the host system
= shorthand for :.snap (make graphics hardcopy)
0 reset and redraw
1-9 roam
Figure 2. Cursor Mode Keystrokes
By default the cursor mode keystrokes are all upper case letters,
reserving lower case for applications programs. The terminal shift
lock key may be used to simplify typing in lengthy interactive cursor
mode sessions. The cursor motions are decoupled from roam since zoom
and roam are often used merely to increase the precision of a cursor
read. Special keystrokes are provided for stepwise cursor motions to
increase the speed of cursor setting on terminals that do not have fast
cursor motions (e.g., the retro-graphics enhanced VT100). The
recognized keystrokes are shown in Figure 2.
If the character : is typed while in cursor mode the alpha cursor will
appear at the bottom of the screen, allowing a command line to be
entered. Commands which begin with a period, e.g., ":." are
interpreted by the graphics system; any other command will terminate
the cursor read, returning the character ':' as the key value, and the
command string as the string value of the cursor read. The commands
-8-
GIO (Dec84) Graphics I/O GIO (Dec84)
recognized by the graphics system are summarized in figure 3.
:.axes[+-] draw axes of viewport whenever screen is redr
awn
:.case[+-] enable case sensitivity for keystrokes
:.clear clear alpha memory (e.g, this text)
:.cursor n select cursor (0=normal,1=crosshair,2=lightpe
n)
:.gflush flush plotter output
:.help print help text for cursor mode
:.init initialize the graphics system
:.markcur[+-] mark cursor position after each cursor read
:.off [keys] disable selected cursor mode keys
:.on [keys] enable selected cursor mode keys
:.page[+-] enable screen clear before printing help text
:.read file fill frame buffer from a file
:.show print cursor mode and graphics kernel status
:.snap [device] make hardcopy of graphics display
:.txqual qual set character generator quality (normal,l,m,h
)
:.txset format set text drawing parameters (size,up,hj,vj,et
c)
:.xres=value set X resolution (stdgraph only)
:.yres=value set Y resolution (stdgraph only)
:.viewport x1 x2 y1 y2 set workstation viewport in world coordinates
:.write[!][+] file save frame buffer in a spool file
:.zero reset viewport and redraw frame
Figure 3. Cursor Mode Commands
Minimum match abbreviations are permitted for cursor mode command names.
Multiple commands may be given on one line, delimited by semicolons.
If the CL environment variable CMINIT is defined when cursor mode is
first entered, the string value will be interpreted as a cursor mode
command and used for initialization. For example, to disable the
numeric keys and set the graphics resolution to 200 points in X and 100
points in Y, one could add the following SET declaration to their
"login.cl" file:
set cminit = "xres=200; yres=150; off 0-9"
The numeric keypad of the terminal (if it has one) is used to roam about
when the zoom factor is greater than one. If the magnification is
normal the numeric keys are not recognized as special keystrokes, i.e.,
typing a numeric key will exit cursor mode, returning the character
typed to the applications program. In roam mode a numeric key must be
escaped to exit cursor mode. The directional significance of the
numeric keys in roam mode is obvious if the terminal has a keypad, and
is illustrated below.
-9-
GIO (Dec84) Graphics I/O GIO (Dec84)
7 8 9 135 090 045
4 5 6 180 000 000
1 2 3 225 -90 -45
There is a fixed upper limit on the size of the cursor mode frame
buffer. If the frame data overflows the frame buffer while plotting
the plot will still come out correctly, but only the final plotting
instructions will be retained in the buffer. Redisplay of the frame in
cursor mode will thus result in only a portion of the full frame being
drawn. If this is a problem the user can increase the upper limit on
the size of the frame buffer by setting the value of the environment
variable CMBUFLEN, e.g.,
gflush; set cmbuflen = 512000
would initialize the graphics system (freeing the old frame buffer) and
set the upper limit on the size of the frame buffer to 512K words or
1Mb.
3.4 EXAMPLE
At this point a brief example may help to illustrate the use of the
GIO procedures. The following procedure will plot a data vector (pixel
array) and then repeatedly read the cursor, drawing a mark at
successive positions of the cursor. The procedure exits if the user
types either the character 'q' or EOF, e.g., <ctrl/z> or carriage
return.
-10-
GIO (Dec84) Graphics I/O GIO (Dec84)
include <gset.h>
# MARKPLOT -- Plot a data array and then enter a loop, drawing
# circles at successive cursor positions.
procedure markplot (data, npts, x1, x2)
real data[npts] # data vector to be plotted
int npts # length of array
real x1, x2 # world X-coords of vector
pointer gp
int wcs, key
char str[32]
real wx, wy
pointer gopen()
int clgcur()
begin
gp = gopen ("stdgraph", NEW_FILE, STDGRAPH)
call gploto (gp, data, npts, x1, x2, "data")
while (clgcur ("points", wx, wy, wcs, key, str, 32) != EOF)
if (key == 'q')
break
else
call gmark (gp, wx, wy, GM_CIRCLE, 1., 1.)
call gclose (gp)
end
3.5 GRAPHICS OUTPUT DEVICES
While the graphics output device may be specified explicitly by
name, more often graphics output devices will be specified by one of
the logical device names shown below. Examples of the installation
dependent device name associated with each logical name are also shown.
stdgraph = "gterm"
stdimage = "deanza"
stdplot = "qms"
stdvdm = "uparm$vdm"
Interaction (via the CL) is supported only for STDGRAPH and STDIMAGE.
The standard batch plotter device is STDPLOT, and the standard metafile
(for spooling graphics output) is STDVDM.
The user should not normally set the value of STDGRAPH directly with
SET, rather they should set the terminal type with STTY and let the
latter specify the value of STDGRAPH. If the terminal specified is not
-11-
GIO (Dec84) Graphics I/O GIO (Dec84)
a graphics terminal (no ":gd" capability in the termcap entry for the
device) the value of STDGRAPH will be set to "none", otherwise STDGRAPH
will be set to the name of the stdgraph device entry for the graphics
terminal.
The device name associated with a logical graphics output device must
have an associated entry in the GRAPHCAP file, a text file used to
describe the characteristics of each device. New graphcap entries may
easily be added by the user to interface to special graphics devices.
System privledge is not required to modify graphcap, since the name of
the graphcap file is taken from a CL environment variable of the same
name (which can be redefined by the user to point to a file in a
private directory). The graphcap entries for the most commonly used
devices at a given site may be precompiled by the system manager to
eliminate the overhead of searching the graphcap file at GOPEN time.
The graphcap parameters (device CAPABILITIES) are too involved to be
presented here and will be described in a later section. Examples of
device capabilities are the device resolution, whether a frame advance
is required before or after a plot, indication of device capabilities
such as the ability to generate text, and the name of the executable
graphics kernel file associated with the device. Many additional
parameters are defined for interactive devices. The graphcap device
capabilities may be inspected with the GGET[BIRS] procedures, which
resolve into calls to the TTY interface, used to access both graphcap
and termcap files.
The sequence of actions taken by GIO to access the graphcap entry for a
device is summarized below.
if (standard graphics output device)
get device name from environment
if (device name is actually a filename) {
load graphics device descriptor using the first device entry
from the named graphcap format file
} else {
get filename of graphcap file from environment
load graphics device descriptor by searching the graphcap file
for the named device
}
3.6 GRAPHICS INPUT DEVICES
The technique used to associate an input source with a graphics
cursor is similar to that used for output devices. A CL environment
variable is associated with each cursor type. The names and default
values of the environment variables are shown below.
-12-
GIO (Dec84) Graphics I/O GIO (Dec84)
stdgcur = "stdgraph"
stdimcur = "stdimage"
The default input source for a cursor is the graphics output device
associated with the graphics output stream. If the cursor device is
"stdgraph" or "stdimage" the graphics kernel is called to read the
physical device cursor for STDGRAPH or STDIMAGE. If the cursor device
is "text" the cursor value is a line of text read from the user
terminal. In this mode the user enters at least two of the fields
defining a cursor value. Missing fields are assigned the value zero
(the user presumably will know that the program does not use the extra
fields).
cl> set stdgcur = "text"
cl> = gcur
gcur: 345.33 23.22 1 c
345.33 23.22 1 c
cl>
An example of a cursor read request entered interactively by the user,
taking input from the terminal and sending output to the terminal, is
shown above (the CL typed the "gcur: " query and the user entered the
remainder of that line). If the cursor device were "stdgraph" a real
cursor read would occur and the equivalent interaction might appear as
shown below. The cursor position is returned in world coordinates,
where the world coordinate system was defined by the last plot output to
the device. For an imaging device the world coordinates will typically
be the pixel coordinates of the image section being displayed.
cl> = gcur
345.33 23.22 1 c
cl>
Redirecting cursor input to the terminal is useful when working from a
nongraphics workstation and when debugging programs. ASCII cursor
queries are the only type supported when running an IRAF program
outside the CL. Cursor input may also be taken from a list file by
assigning a filename to a cursor parameter, i.e., by assigning a list
file to a list structured parameter and overriding query mode:
cl> gcur = filename
cl> = gcur
345.33 23.22 1 c
cl>
This last mechanism is a standard technique used with CL list structured
parameters and will not be discussed further here.
-13-
GIO (Dec84) Graphics I/O GIO (Dec84)
3.7 MIXED TERMINAL AND GRAPHICS I/O
Interactive graphics programs are normally (but not necessarily)
executed on a graphics terminal or workstation supporting both ordinary
terminal i/o and vector graphics. IRAF is designed to use a single
terminal for both text and graphics; text and graphics on separate
devices is also supported but is not the norm. By text we refer here
to ordinary line or screen oriented terminal i/o (e.g., for HELP or
EPARAM), not the use of text in the graphics plane to annotate plots.
3.7.1 TEXT AND GRAPHICS MODE
Most modern graphics terminals provide separate memory planes for
text and graphics. Depending upon the device, these planes may be
displayed simultaneously, displayed alternately, or only a single
memory plane may be available for both terminal modes, in which case a
mode switch is destructive. The graphics device model implemented by
GIO and the STDGRAPH kernel is flexible enough to deal with all or
nearly all such devices.
The normal mode for the terminal or workstation is text mode.
Activating the workstation causes a switch to graphics mode;
deactivating the workstation restores the terminal to text mode.
Activation is implied whenever a device is opened with GOPEN, unless
the AW_DEFER mode bit is set to defer the activate workstation until
graphics i/o is actually done to the device. Closing the workstation
automatically deactivates the workstation. The GIO procedures
GREACTIVATE and GDEACTIVATE are provided to simplify mode switching
while a device is open on a graphics stream.
Occasionally it is necessary to print out a large amount of text in
response to a user command entered in a cursor loop while in graphics
mode. If the text is in a file this is done most easily by calling
GPAGEFILE to page the file in text mode, restoring graphics mode when
the operation is completed. If the application generates the output
text dynamically then the workstation must be explicitly deactivated
and later reactivated before resuming graphics i/o, e.g.,
while (clgcur (gp, ...) != EOF) {
switch (key) {
case XXX:
call gdeactivate (gp, AW_CLEAR)
<write the text to STDOUT>
call greactivate (gp, AW_PAUSE)
case YYY:
...
}
}
The sequence shown will switch to text mode, clear the screen, output
the text, and pause for the user to read the text before restoring
graphics mode and initiating another cursor read.
-14-
GIO (Dec84) Graphics I/O GIO (Dec84)
3.7.2 STATUS LINE I/O
The deactivate/reactivate workstation technique is fine for
outputting large amounts of text, but is not well suited for small
amounts of text, e.g., single line commands to interactively set
internal parameters, output of single lines of text to prompt the user,
print the value of a calculation or some variable, and so on. The
so-called "status line" interface is provided for this purpose. Status
line i/o makes it possible to interact directly with the user without
interfering with the contents of the graphics frame, and without
leaving graphics mode.
What the status line actually is is determined by the graphcap entry
for the device and the characteristics or limitations of the actual
device. On most devices, the status line is a single line at the
bottom of the screen. This only works, however, if the device can
dynamically erase the status line; if this is not possible the status
"line" may actually be the entire screen, with successive output lines
being drawn on top of the graph.
To output text to the status line while in graphics mode one merely
writes to STDOUT or STDERR in the usual way, e.g., in a call to
PRINTF. When newline is seen a flag is set which causes the status
line to be cleared when the next output character is received. Output
lines may be built up in successive calls to output procedures,
outputting a single newline to terminate the line and start a new one.
After a newline delimited line of text has been output, output of a
single newline (blank line) will clear the status line.
It is also possible to read from the status line. This is most
commonly done after writing a prompt string to the status line. The
prompt should be terminated with a colon (e.g., "enter value: ") rather
than a newline, to signal to the user that input is expected, and to
avoid having the subsequent status line read clear the prompt string.
In many cases such explicit prompting and decoding of the return string
can be avoided by using the standard CLIO parameter prompting mechanism
for interactive input. CL parameter prompts are also permitted in
graphics mode, and will interact with the user on the status line in
the expected way, without interfering with the graphics state of the
device.
When mixing status line i/o and graphics i/o one must be careful to
flush any buffered graphics or textual output before switching modes.
In many cases the system will do this for you automatically, but there
are exceptions where explicitly flushing of buffered output is
necessary (e.g., STDOUT and STDERR are low level facilities with no
knowledge of GIO, and output to one of these streams will not
automatically cause any graphics output to be flushed).
3.8 USER INTERFACE CONVENTIONS
While different interactive (cursor driven) graphics programs will
differ in many ways, there are certain operations which are common to
-15-
GIO (Dec84) Graphics I/O GIO (Dec84)
all such programs. In order to present a more consistent interface to
the user, conventions have been defined for these common operations.
3.8.1 ON LINE HELP
All interactive graphics programs should respond to the key '?'
with a description of the keystrokes and colon commands recognized by
the program (or submenu, in the case of a menu structured interface).
This is normally done by calling GPAGEFILE to interactively page the
".key" keystrokes help file for the program. The keystroke files for
system programs are stored in the directory lib$scr; non-system
programs keep their keys files either in the package directory, or in a
global package library.
3.8.2 CURSOR AND DEVICE NAMES
In general, applications programs should not read directly from GCUR
or IMCUR (the global cursor parameters), nor should the open the
"stdgraph", "stdimage", or "stdplot" device directly by these explicit
string values. This works, but is inflexible. To make it easy for the
user to run an otherwise interactive program in batch mode, taking
input from a cursor list file, the task should include a cursor type
parameter in its parameter set. Likewise, to make it easy for the user
to temporarily redirect the output of the program to a device other
than the current stdgraph, stdplot, etc., device, the device name
should be parameterized as a string type CL parameter.
For example, if task PLOTIT has cursor and device parameters named
"cursor" and "device", the command
cl> plotit cursor=listfile device=qms
would run the task taking cursor input from the text file "listfile",
with stdgraph graphics output directed to the plotter device "qms".
3.8.3 EXITING AN INTERACTIVE CURSOR LOOP
The following standards have been defined for dealing with EOF/quit
in interactive cursor loops.
EOF
End of file is indicated for a cursor list either by an actual
end of file in the case of a true cursor list, or by typing the
EOF character (e.g., <ctrl/z>, <ctrl/d>, or the interrupt
character) in an interactive cursor read. EOF on the cursor
list should be taken seriously by the applications program, and
not treated as just another key, hence it should not be
something that the user is expected to type routinely to exit a
cursor loop. If a program gets EOF back as the value of CLGCUR
-16-
GIO (Dec84) Graphics I/O GIO (Dec84)