Cambridge University Engineering Department

GraSP

Graphics Subroutine Package

D. N. Harris November 9, 1993

Contents

1 Introduction 4

2 Feedback 4

3 Example programs 4

4 Using GraSP 7

5 Procedure specifications 8

5.1 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.1.1 int grerrt(int mode)—Set default or user error handling . . . . . . . . . 8 5.1.2 int grqerr(void)—Query error code . . . . . . . . . . . . . . . . . . . . . 9

5.2 Initialisation, device control, plotting . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.2.1 int grinit(int device)—Initialise the GraSP package . . . . . . . . . . 10 5.2.2 void grterm(void)—Terminate graphics . . . . . . . . . . . . . . . . . . . 10

5.2.3 void grplon(char *name, int length)—Start plotting . . . . . . . . . . 10

5.2.4 void grplof(void)—Turn off plotting . . . . . . . . . . . . . . . . . . . . 11 5.2.5 int grctrl(int stream)—Switch screen/plotter output . . . . . . . . . . 11

5.2.6 void grqdev(int select,real *val1,real *val2)—Query device . . . 11

5.2.7 int grqcde(void)—Get device type . . . . . . . . . . . . . . . . . . . . . . 11 5.2.8 void grwinname(char *name)—Set X11 window title . . . . . . . . . . . . 12

5.3 Coordinate systems, windows, viewports . . . . . . . . . . . . . . . . . . . . . . . . 12

5.3.1 void grwind(real umin,real umax,real vmin,real vmax)—Define win-

dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5.3.2 void grqwin(real *u1,real *u2,real *v1,real *v2)—Get current win-

dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5.3.3 void grview(real x1,real x2,real y1,real y2)—Define viewport . . . 13
5.3.4 void grqvie(real *x1,real *x2,real *y1,real *y2)—Get current view-

port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5.3.5 void grutod(real u,real v,real *x,real *y)—User to device coords . 13
5.3.6 void grdtou(real u,real v,real *x,real *y)—Device to user coords . 14

5.3.7 void grclr(int flag)—Clear screen or viewport . . . . . . . . . . . . . . 14 5.3.8 int grseen(real x,real y)—Test if point is in viewport . . . . . . . . . 14

5.4 Attribute setting: colours, line, fill and marker types . . . . . . . . . . . . . . . . . 14 5.4.1 int grcol(int colour)—Set colour . . . . . . . . . . . . . . . . . . . . . 14 5.4.2 int grX11col(char* colour)—Set colour by name . . . . . . . . . . . . . 15 5.4.3 int grbcol(int col)—Set background colour . . . . . . . . . . . . . . . . 15 5.4.4 void grinvt(void)—Swap foreground and background colours . . . . . . . 15 5.4.5 int grmode(int mode)—Set drawing mode . . . . . . . . . . . . . . . . . . 15 5.4.6 int grlt(int type)—Set line type . . . . . . . . . . . . . . . . . . . . . . 16 5.4.7 int grlw(int width)—Set line width . . . . . . . . . . . . . . . . . . . . . 16 5.4.8 int grft(int pattern)—Set polygon fill pattern . . . . . . . . . . . . . . 16 5.4.9 real grms(real size)—Set marker size . . . . . . . . . . . . . . . . . . . 16 5.4.10 void grmwh(real width, real height)—Set marker width and height . 16 5.4.11 int grmt(int type)—Set marker type . . . . . . . . . . . . . . . . . . . . 16 5.4.12 int grct(int type)—Set cursor type . . . . . . . . . . . . . . . . . . . . . 17 5.4.13 void grdflt(void)—Set default attributes . . . . . . . . . . . . . . . . . . 17 5.4.14 void grclip(int flag)—Set/Unset clipping . . . . . . . . . . . . . . . . 17

5.5 Drawing operations: lines, markers, arcs . . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.1 void grmove(real u, real v)—Move to (user coordinates) . . . . . . . . 17 5.5.2 void grdraw(real u, real v)—Draw to (user coordinates) . . . . . . . . 18 5.5.3 void grmvby(real du, real dv)—Move by . . . . . . . . . . . . . . . . . 18 5.5.4 void grdrby(real du, real dv)—Move by . . . . . . . . . . . . . . . . . 18 5.5.5 void grmvxy(real x, real y)—Move to (device coordinates) . . . . . . . 18 5.5.6 void grdrxy(real x, real y)—Draw to (device coordinates) . . . . . . . 18 5.5.7 void grmvch(int col, int row)—Move to (character coordinates) …. 18 5.5.8 void grmark(void)—Draw a marker symbol . . . . . . . . . . . . . . . . . 18

5.5.9 void grarc(real u, real v, real angle)—Draw a circular arc . . . . . 19
5.5.10 void grpie(real u, real v, real angle)—Draw a filled wedge . . . . . 19
5.5.11 void grpoly(int n, real u[], real v[])—Draw a polyline . . . . . . . 19
5.5.12 void grfill(int n, real u[], real v[])—Draw a filled polygon . . . 19

5.6 Character output and font selection . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.6.1 int grfont(int font)—Select character font . . . . . . . . . . . . . . . . 19 5.6.2 int grX11font(char *font)—Select font by name . . . . . . . . . . . . . 20

5.6.3 void grchar(char *message, int length)—Draw a character string . . 20

5.6.4 void grtext(char *message)—Draw a null-terminated character string . 20 5.6.5 void grputi(int value, int width)—Draw an integer value . . . . . . . 21

5.6.6 void grputr(real value, int width)—Draw a real value . . . . . . . . 21

5.6.7 real grchs(real size)—Set character size . . . . . . . . . . . . . . . . . 21 5.6.8 real grcha(real angle)—Set character orientation . . . . . . . . . . . . 21 5.6.9 int grtfbg(int mode)—Set transparency of font background . . . . . . . 21

5.7 Interactive procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 5.7.1 int grrqch(void)—Request choice . . . . . . . . . . . . . . . . . . . . . . 22 5.7.2 void grwait(void)—Wait for input . . . . . . . . . . . . . . . . . . . . . . 22

5.7.3 void grrqlc(int *choice, real *x, real *y)—Request locator . . . . 22

5.7.4 void grwarp(real *u, real *v)—Warp cursor . . . . . . . . . . . . . . . 22

5.7.5 int grrqst(char *reply, int *length)—Request string . . . . . . . . . 23

5.7.6 int grrqi(void)—Request an integer . . . . . . . . . . . . . . . . . . . . . 23 5.7.7 real grrqr(void)—Request a real . . . . . . . . . . . . . . . . . . . . . . 23 5.7.8 int grtime(int timeout)—Set timeout interval . . . . . . . . . . . . . . 23

5.7.9 void grdeff(int field, int mode, char *prompt, int length, real u,

real v)—Define input field . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.7.10 int grread(void)—Request field input . . . . . . . . . . . . . . . . . . . . 24 5.7.11 void grgetf(int field, char *reply)—Fetch field contents . . . . . . . 24

1 Introduction

The GraSP package was first developed as part of the preparation for the changeover from the previous teaching system (an IBM 4341 mainframe) to the new system of networked workstations. A wide range of Computer-Based Teaching programs had been written for the 4341 using the proprietary IBM GDDM graphics library. In order to make an early start with the conversion of the teaching software, it was decided to define a set of graphics subroutines necessary and sufficient to support the graphical requirements of the programs, and to implement the library on currently available hardware—the IBM PS/2 microcomputer. This allowed conversion of teaching programs to be started in advance of any final decision about the type of new hardware. When the new Hewlett-Packard system was installed in June, 1989, the GraSP library was implemented for the X Windows environment and final conversion of the teaching programs was completed ready for the start of Michaelmas term in October, 1989.

GraSP provides the following graphical facilities:

• user-defined coordinate system and viewports

• routines for drawing lines, markers, arcs and characters

• interactive graphics (keyboard or mouse input)

• hard copy output on graphics printer or plotter

Although GraSP was designed for implementing sophisticated interactive graphics in teaching programs, it is easy to use and is suitable for general graphics programming as an alternative to standard graphics packages such as GKS.

GraSP is implemented on X Workstations and Personal Computers. The package is written in C and can be called from Fortran and C programs.

2 Feedback

Please send comments about the GraSP library, including any suggestions for additional procedures which you would find useful, to T. P. Love (email tpl@uk.ac.cam.eng).

3 Example programs

The following FORTRAN program draws graphs of sin(x^{n}) for 0 ≤ x ≤ 2 and n = 1, 2, 3, 4. Numbers at the left refer to notes following the example. If the file’s called prog.f it can be compiled using

         f77gr prog.f
(1) $INCLUDE '/usr/local/include/grasp.def'
(2) $INCLUDE '/usr/local/include/grasp.inc'
(3)       IDUM = GRINIT(X11)
(4)       CALL GRWIND( 0.0, 2.0, -1.0, 1.0 )
(5)       CALL GRQVIE(XMIN, XMAX, YMIN, YMAX)
(6)       CALL GRVIEW(0., XMAX/2., YMAX/2., YMAX)
          CALL SINXN(1)
(7)       CALL GRVIEW(XMAX/2., XMAX, YMAX/2., YMAX)
          CALL SINXN(2)
          CALL GRVIEW(0., XMAX/2., 0., YMAX/2.)
          CALL SINXN(3)
          CALL GRVIEW(XMAX/2., XMAX, 0., YMAX/2.)
          CALL SINXN(4)
(8)       CALL GRWAIT

(9)       CALL GRTERM
          END
          SUBROUTINE SINXN(N)
(2) $INCLUDE '/usr/local/include/grasp.inc'
          NSTEPS = 150
          DELX = 2.0 / NSTEPS
(10)      CALL GRMOVE(0.5, -1.0)
(11)      CALL GRCHAR('sin(x**', 7)
(12)      ICOL = GRCOL(RED)
(13)      CALL GRPUTI(N, 1)
(14)      IDUM = GRCOL(ICOL)
          CALL GRCHAR(')', 1)
(15)      CALL GRMOVE(0., 0.)
          DO 10 I =1, NSTEPS
            X = I * DELX
(16)        CALL GRDRAW(X, SIN(X**N))
     10   CONTINUE
          RETURN
          END

(1) Each source file must contain this statement once at the beginning.

(2) This statement should be included in every routine which calls a GraSP function or uses a GraSP attribute such as RED (see (12)). Note that the $INCLUDE must start in column 1.

(3) GRINIT initialises the package and opens an X window to display graphical output.

(4) GRWIND defines a user coordinate system suitable for drawing graphs with 0 ≤ x ≤ 2 and −1 ≤ y ≤ 1.

(5) GRQVIE returns the coordinates of opposite corners of the viewport— the area where output will appear on the screen. The initial viewport occupies the whole of the graphics region and has coordinates (0, 0) and (XMAX, YMAX), where XMAX and YMAX are hardware dependent. On the Hewlett-Packard system XMAX=1.0 and YMAX=0.75.

(6) redefines the viewport to be the top-left quarter of the initial viewport.

(7) The following statements define three more viewports and draw the remaining graphs.

(8) GRWAIT waits until a key is pressed on the keyboard. Without this statement the program would end immediately after drawing the graphs and the graphical output would disappear before it could be admired.

(9) terminates use of the GraSP package and closes the output window.

Lines (10) to (14) write a title on the graph. (10) moves the current position (or ‘pen’) to (.5, -1) and (11) writes the first part of the title.

(12) changes colour using a symbolic value, RED, which is defined by including ‘grasp.inc’. GRCOL returns the previous colour which is saved in ICOL and used in line (14) to restore the original colour. (13) outputs the value of N using 1 significant figure (i.e. no leading spaces).

(15) moves the current position to the origin and (16) draws the line segments which make up the graph.

The following C program demonstates some of the more sophisticated facilities. If the file’s called prog.c it can be compiled using

c89 -D_HPUX_SOURCE -I/usr/include/X11R4 -I/usr/local/include \
 -L/usr/local/lib -L/usr/lib/X11R4 -DANSI -o prog prog.c\
 -lgrasp -lgipsubb -lXhp11 -lX11 -lm -lI77 -lF77
#include <grsys.h>
#include <grasp.h>
main()
{
#define NUMBER_OF_FONTS 15

char *fonts[NUMBER_OF_FONTS]={
 "Standard",
 "Font8",
 "Simplex",
 "Triplex",
 "Font14",
 "Font19",
 "Font16",
 "Maths",
 "Vertical",
 "Font24",
 "Micro",
 "X11Simplex",
 "X11Duplex",
 "X11Complex",
 "X11Italic" };

int i;
real x_values[4];
real y_values[4];
x_values[0] = .0;
y_values[0] = .01;
x_values[1] = .0;
y_values[1] = .75;
x_values[2] = .2;
y_values[2] = .75;
x_values[3] = .2;
y_values[3] = .01;
grinit(0);
grwinname("Font Demo");
grbcol(White);
grclr(0);
grcol(Black);
grfill(4,x_values,y_values);
grcol(Red);
grchs(.02);
for (i = 1; i<NUMBER_OF_FONTS+1 ; i++){
   grfont(i);
   grmvxy(.0, .01 + i*0.05);
   grtext(fonts[i]);
}
grfont(X11Simplex);
for (i = 1; i<360 ; i+=60){
   grmvxy(.75,.21);
   grcha(i);
   grtext("test string");
}
grfont(X11Italic);
grcol(Black);

grmvxy(.65,.4);
for (i = 359; i>0 ; i-=60){
   grcha(i);
   grtext("testing more");
}
   grX11col("purple");
   grmvxy(.3,.2);
   grX11font("micro");
   grtext("a little bit of text");
   grmvxy(.3, .1);
   grX11font("chs-s50");
   grtext("rnbkqbnr");
sleep(300);
}

4 Using GraSP

Each subroutine specification includes a C procedure prototype which defines the number and types of parameters needed by the routine, and a example of how the routine should be called from Fortran. The procedure prototype is included in the ‘Contents’ pages and provides a concise specification of how a procedure should be invoked.

For example:

       void grmove(real u, real v)
       REAL U, V
       CALL GRMOVE(U, V)

‘void’ indicates that the routine does not return a result and therefore should be CALLed as a subroutine in FORTRAN. In the specification of GRRQI:

       int grrqi(void)
       INTEGER GRRQI
       IR = GRRQI(IDUM)

‘int’ shows that an integer-value is returned. ‘void’ indicates that the routine does not require any parameters when called from a C program. However, in FORTRAN it is necessary to supply a dummy parameter IDUM as FORTRAN functions calls must always have at least one parameter.

Note: some routines return values via parameters. Such parameters are preceded by ‘*’ in the procedure prototype and must be variables, not expressions. For example:

       void grqwin(real *umin,real *umax,real *vmin,real *umax)
       CALL GRQWIN(0.0, 1.0, 0.0, 1.0)   !!! Wrong !!!
       CALL GRQWIN(U1, U2, V1, V2)       !!! Right !!!

Each Fortran source file must include the statement

$INCLUDE '/usr/local/include/grasp.def'

once at the beginning of each source file. File grasp.def contains ALIAS statements which ensure that GraSP routines are called correctly.

Symbolic definitions for many GraSP parameter values are contained in the include file grasp.inc. For example, an integer symbol RED is defined such that GRCOL(RED) produces red output (the actual value of RED is hardware dependent). Symbolic values should always be used to ensure that the program will work correctly on any hardware and, more importantly, make the program more readable. The statement

$INCLUDE '/usr/local/include/grasp.inc'

should be included at the start of every routine in which a symbolic parameter value is used.

grasp.inc also contains type statements for those GraSP functions which return an integer value, e.g. INTEGER GRRQST, and should be included whenever an integer-valued function is called. If grasp.inc is not included, the function should be declared explicitly as INTEGER or, alternatively, called as a subroutine (routines which set graphical attributes such as colour or line type return the old value of the attribute and may safely be CALLed if the old value is not needed).

Fortran 77 variable length strings are implemented in a way which is quite different from the representation used in C. The GraSP library contains interface routines which allow variable or fixed length strings to be passed to GraSP routines, but the maximum length of a string is limited to 100 characters.

To compile and load a program prog.f with the GraSP library use the following command:

   fort77 -I/usr/local/include -L/usr/local/lib -L/usr/lib/X11R4 \
   -o prog prog.f -U -w -lgipsubb -lgrasp -lXhp11 -lX11 -lm

Alternatively you could use the f77gr script to do the same thing.

   f77gr prog.f

C programs should #include <grasp.h> which contains prototypes for GraSP routines and symbolic definitions for many parameter values. grasp.h also contains a type definition ‘real’ for the type of floating-point parameters used in GraSP (on the Hewlett-Packard X version of GraSP real is float, i.e. single precision). Note that GraSP procedure names are in lower case in the C binding.

To compile and load a C program on the HP 300 series machines, use the following command:

c89 -D_HPUX_SOURCE -I/usr/include/X11R4 -I/usr/local/include \
 -L/usr/local/lib -L/usr/lib/X11R4 -DANSI -o prog prog.c\
 -lgipsubb -lgrasp -lXhp11 -lX11 -lm -lI77 -lF77

For the 700 series machines use

c89 -D_HPUX_SOURCE -I/usr/include/X11R4 -I/usr/local/include \
 -L/usr/local/lib -L/usr/lib/X11R4 -DANSI -o prog prog.c\
 /usr/local/lib/gipsubb.o -lgrasp -lcl -lXhp11 -lX11 -lm

5 Procedure specifications

5.1 Error handling

(This section may be skipped on an initial reading).

5.1.1 int grerrt(int mode)—Set default or user error handling

      INTEGER MODE
      IR = GRERRT(MODE)

Set the mode of error handling and return the previous value.

MODE:  OFF  default handling—terminate execution

ON enable GRQERR reporting of fatal errors FATAL treat all errors as fatal

A number of errors are possible when using GraSP, for example when:

• a viewport larger than the screen is specified

• an attempt is made to scale a fixed-size font

• an illegal plotfile name is specified

Some errors, for example failing to open a plot file, are potentially fatal—the program should not continue without taking action to correct the error. Other errors, for example attempting to specify a colour which is not available, are not disastrous and subsequent output may be acceptable even if the error is ignored.

The default action for fatal errors is to display a diagnostic message and terminate program execution. The default action for non-fatal errors is:

• correct the error in the procedure call by performing a sensible alternate action, or ignore the procedure call completely

• store an error code (normally ERRNA) for use by function GRQERR

• return to the user program

The user program can take over control of all errors by calling GRERRT(ON). This causes control to be returned to the user program after a fatal error in the same way that non-fatal errors are handled.

The default mode of handling errors is restored by GRERRT(OFF). A third mode of handling errors is set by GRERRT(FATAL). This causes all errors to be treated as fatal, and is provided for debugging purposes.

5.1.2 int grqerr(void)—Query error code

      IERR = GRQERR(IDUM)

Returns the current error code and resets the error state register to 0 (ERROK).

Note that if a procedure completes without error the error state remains unchanged. This means that a non-zero return from GRQERR may refer to an error condition in any of the procedures called since the previous use of GRQERR. In order to be certain that an error has occurred in a particular routine, the error state should be cleared (using GRQERR) immediately before calling the routine.

The user program may choose to ignore the error and continue as normal. This might produce acceptable output, or provoke additional errors which lead to a fatal system execution error and cause the program to be aborted.

The following codes are currently defined:

Non-fatal errors (control returns to the user program):

ERROK no errors occurred since the last call of GRQERR ERRVAL VALue error: a parameter was specified incorrectly ERRNA the requested facility is Not Available

The following errors are potentially fatal and control returns to the user program only if GRERRT(ON) has been specified.

ERROPN Open error on font or plot file ERRWRT Write error on plot file ERRHW Hardware failure, or hardware not installed ERRMEM Insufficient free memory

Many procedures are capable of generating ERRVAL or ERRNA errors and these common cases are not always explicitly noted in the descriptions of procedures below. All procedures which generate graphical output can fail with ERRWRT if plotting is enabled and a write error occurs.

Example:

   CALL GRERRT(ON)          ... turn on user error processing
   CALL GRFONT(GREEK)                    ... load Greek font
   IF (GRQERR(IDUM) .NE. ERROK) RETURN   ... cannot speak Greek

5.2 Initialisation, device control, plotting

5.2.1 int grinit(int device)—Initialise the GraSP package

      INTEGER DEVICE
      IDEV = GRINIT(DEVICE)

GRINIT initialises the graphics package to drive the specified device.

DEVICE:  X11  (4) open a 640x480 pixel X window

X11B (5) open a 960x720 pixel X window DEFAULT (0) same as X11

The device type selected can be overridden by setting variable GRT in the shell environment to one of the numeric values in the above table. For example:

      GRT=5 graspprog

forces graspprog to use a large window. If GR BIG is set in the shell environment, X11B is used. The size and position of the grasp window is also affected by the value of the environmental variable

GRGEOM.
      GRGEOM=150x300-0-0 graspprog

will create a window 150 pixels by 300 in the bottom right corner of the screen. See the X man page for more details.

When invoked as a function GRINIT returns the device type selected (which may not be the same as the type specified by DEVICE if GRT is set).

This procedure must be called once (and only once) before any other Grasp procedure except GRERRT. GRINIT sets up initial values for graphical attributes as described under GRDFLT.

Errors: ERRHW hardware error or hardware not installed

5.2.2 void grterm(void)—Terminate graphics

      CALL GRTERM

Terminate use of the graphics package, close the graphics X window and close the plotter file (if open).

5.2.3 void grplon(char *name, int length)—Start plotting
      CHARACTER*n NAME
      INTEGER LENGTH
      CALL GRPLON(NAME, LENGTH)

Following a call to GRPLON all subsequent output is drawn on the screen and written to the specified plot file on disk (in coded form). An existing file is overwritten. The plot file may subsequently be viewed or copied to a pen plotter or laser printer using the PlotView program. Output on the hard copy device is drawn in a rectangle with the same aspect ratio as the graphics region.

Parameter LENGTH specifies the number of characters in the file name. If LENGTH is zero the standard name ‘PLOTFILE’ is used. If LENGTH is negative the string in NAME should be terminated with a null character. For example:

      CALL GRPLON('PIX'//CHAR(0), -1)

The name of the plot file can be overridden by setting GRPF in the environment. For example:

      GRPF=TEST22.PLT grasprog

runs program grasprog sending plotter output to file TEST22.PLT, regardless of what may be specified within the program.

Plotter output for any GraSP program, including ones which do not normally create a plot file, may be obtained by setting GRP in the environment. This captures all graphical output in ‘PLOTFILE’, or in a file whose name is specifed by GRPF.

Errors: ERROPN cannot open plotfile ERRWRT (subsequently) error writing to plot file

5.2.4 void grplof(void)—Turn off plotting

      CALL GRPLOFF

Turns off plotting and closes the plot file.

5.2.5 int grctrl(int stream)—Switch screen/plotter output

      INTEGER STREAM
      IR = GRCTRL(STREAM)

GRCTRL allows additional control over graphical output. It may be used to generate a plot file without drawing to the screen, or to suspend plotting temporarily (for example while writing user prompts to the screen).

STREAM: 1 output to screen only 2 output to plotter only 3 output to both screen and plotter 4 output to stdout

Returns: the previous value of STREAM.

Errors: ERRVAL—attempt to route output to a plot file before calling GRPLON.

5.2.6 void grqdev(int select,real *val1,real *val2)—Query device
      INTEGER SELECT
      REAL VAL1, VAL2
      CALL GRQDEV(SELECT, VAL1, VAL2)

Returns the current pen position or device-specific information about screen size, character size and plotter scales. ‘SELECT’ specifies which items of information are required:

SELECT:  CURPOS  Current pen position in device coordinates

ASPECT Width and height of graphics region in device units CHSIZE Character width and height in device units PLSIZE Size of plotting area in mm. MKSIZE Marker width and height in device units

Screen dimensions are returned in normalised form (at least one of width and height is set to 1.0).

Error: ERRVAL—SELECT out of range.

5.2.7 int grqcde(void)—Get device type

      IDEV = GRQCDE(IDUM)

Returns the device type as reported by GRINIT.

5.2.8 void grwinname(char *name)—Set X11 window title
      CHARACTER*n NAME
      CALL GRWINNAME(NAME)

Sets the title for the X11 window. NAME should be terminated with a null character.

5.3 Coordinate systems, windows, viewports

Drawing takes place in a rectangular graphics region. On a PC the graphics region occupies the entire screen. On an X workstation the graphics region is an X window occupying part of the screen. The aspect ratio of the graphics region (the ratio of width to height) depends on the type of display being used. Aspect ratios are specified in a normalised form where the longer dimension has unit length. Most displays have a ‘landscape’ format with width > height so that in normalised form width is 1.0 and height is typically between 0.7 and 0.8. The graphics region on the Hewlett-Packard X implementation of GraSP has width=1 and height=0.75.

A cartesian system of device coordinates, (x, y), is defined over the graphics region such that the origin (0, 0) is at the lower-left corner of the graphics region. The opposite, top-right corner of the region has coordinates (w, h), where 0 < w, h ≤ 1 and max(w, h) = 1. Device coordinates are used to specify the position of the viewport (see below) and are used to define the size of text or marker symbols.

A user coordinate system, (u, v), is defined using the GRWIND procedure:

      CALL GRWIND(UMIN, UMAX, VMIN, VMAX)

This defines a graphics window in the user coordinate system. The bottom-left corner of the window corresponds to point (UMIN, VMIN) in user coordinates and the top-right corner corresponds to (UMAX, VMAX).

The view through the graphics window is drawn in a rectangular viewport which by default covers the whole of the graphics region. The size of the viewport and its position on the screen may be determined by calling the GRQVIE routine:

      CALL GRQVIE(XMIN, XMAX, YMIN, YMAX)

and its position and size may be redefined by calling the GRVIEW procedure:

      CALL GRVIEW(XLO, XHI, YLO, YHI)

where 0 ≤ XLO < XHI ≤ w and 0 ≤ Y LO < Y HI ≤ h (w and h are the dimensions of the graphics region in device coordinates).

When the package is initialised (by GRINIT) the default viewport coincides with the graphics region (i.e. the whole of the X window) and the default user coordinate system coincides with the device coordinate system: 0 ≤ x ≤ w, 0 ≤ y ≤ h and 0 ≤ u ≤ w, 0 ≤ v ≤ h.

Note that GRWIND in general will produce a coordinate system with different scale factors in the u and v directions. For example, given a viewport of aspect ratio 2:1 in the lower part of the graphics region and a window 0 ≤ u, v ≤ 1 defined by

      CALL GRVIEW( 0.0, 1.0, 0.0, 0.5 )
      CALL GRWIND( 0.0, 1.0, 0.0, 1.0 )

This defines a user coordinate system with a scale factor of 1 user unit/device coordinate in the u-direction, but a scale factor of 2 user units/device coordinate in the v-direction. If regular geometrical figures (for example) are to be drawn it is best to define uniform user coordinates with equal scale factors in each direction, by specifying a window and viewport with identical aspect ratios in the device and user coordinate systems. For example:

      CALL GRQVIE(XMIN, XMAX, YMIN, YMAX)
      ASPECT = (XMAX-XMIN)/(YMAX-YMIN)
      CALL GRWIND(UMIN, UMAX, VMIN, VMIN+(UMAX-UMIN)/ASPECT)

Note that window and viewport changes are independent—if the viewport is redefined the window remains unchanged.

5.3.1 void grwind(real umin,real umax,real vmin,real vmax)—Define window
      REAL UMIN, UMAX, VMIN, VMAX
      CALL GRWIND(UMIN, UMAX, VMIN, VMAX)

Defines a user coordinate system (u, v) by specifying a rectangular window in user space

UMIN ≤ u ≤ UMAX, V MIN ≤ v ≤ V MAX,

which is displayed in the viewport. The current viewport remains unchanged.

Drawing operations convert user coordinates (u, v) into device coordinates (x, y) using the transformation defined by GRWIND and GRVIEW (see also GRUTOD).

It is possible to specify UMIN>UMAX or VMIN>VMAX to define an inverted or reflected coordinate system.

Error: ErrVAL—UMIN=UMAX or VMIN=VMAX.

5.3.2 void grqwin(real *u1,real *u2,real *v1,real *v2)—Get current window
      REAL UMIN, UMAX, VMIN, VMAX
      CALL GRQWIN(UMIN, UMAX, VMIN, VMAX)

Returns the current window setting. This procedure is often used prior to redefining the window so that the previous setting can be restored later.

5.3.3 void grview(real x1,real x2,real y1,real y2)—Define viewport
      REAL XMIN, XMAX, YMIN, YMAX
      CALL GRVIEW(XMIN, XMAX, YMIN, YMAX)

Sets up a new viewport. Parameters are specified in device coordinates:

0 ≤ XMIN < XMAX ≤ width

and

0 ≤ Y MIN < Y MAX ≤ height

The graphics window is not changed. This allows multiple views of the same window to be displayed easily.

Error: ERRVAL—viewport off the screen (e.g. XMIN < 0) or null (e.g. XMIN ≥ XMAX).

5.3.4 void grqvie(real *x1,real *x2,real *y1,real *y2)—Get current viewport
      REAL XMIN, XMAX, YMIN, YMAX
      CALL GRQVIE(XMIN, XMAX, YMIN, YMAX)

Returns the current viewport setting. GRQVIE is often used to get the initial viewport setting prior to changing the viewport.

5.3.5 void grutod(real u,real v,real *x,real *y)—User to device coords
      REAL U, V, X, Y
      CALL GRUTOD(U, V, X, Y)

Converts user coordinates to device coordinates using the transformation defined by GRWIND and

GRVIEW.

5.3.6 void grdtou(real u,real v,real *x,real *y)—Device to user coords
      REAL U, V, X, Y
      CALL GRDTOU(X, Y, U, V)

Converts device coordinates to user coordinates using the transformation defined by GRWIND and

GRVIEW.

5.3.7 void grclr(int flag)—Clear screen or viewport

      INTEGER FLAG
      CALL GRCLR(FLAG)

Clears a viewport or the entire graphics region to the background colour.

FLAG : 0 clear the whole graphics region 1 clear the current viewport only

5.3.8 int grseen(real x,real y)—Test if point is in viewport

      REAL X, Y
      I = GRSEEN(X, Y)

Returns 1 if point (x, y) in device coordinates lies within the current viewport, otherwise 0.

5.4 Attribute setting: colours, line, fill and marker types

The functions in this section are used to change graphics attributes such as line type and colour. Each function takes a single parameter, the new value of the attribute, and returns the old setting of the attribute. The following example draws a green line and then restores the colour to its previous value:

       IOLD = GRCOL(GREEN)
       CALL GRDRAW(X, Y)
       IDUM = GRCOL(IOLD)

Mnemonics for each attribute value are defined in an include file, grasp.inc. Mnemonics should always be used as the resulting code is portable and easier to understand. Include the statement

$INCLUDE '/usr/local/include/grasp.inc'

in each Fortran subroutine which calls functions in this section.

All the routines may generate ERRNA or ERRVAL.

5.4.1 int grcol(int colour)—Set colour
       INTEGER COLOUR
       IOLD = GRCOL(COLOUR)

Defines the colour of lines, markers, character strings, arcs and polygon fills. On plotter output a new pen is selected. COLOUR is one of:

BLACK  BLUE  GREEN  CYAN
RED  MAGENTA  BROWN  GREY
DGREY  LBLUE  LGREEN  LCYAN
LRED  LMAGENTA YELLOW  WHITE

CYAN is green-blue (turquoise), MAGENTA is a red-blue (purple). DGREY is dark grey. LBLUE is light blue. The default colour is white. ‘BLACK’ means ‘draw in the background colour’, and may be used to erase an existing line. On hard copy devices black and white are interchanged— lines with the default colour (white) are drawn with black ink and the background (paper) colour is normally white.

‘Black’ output on a plotter is drawn with no pen.

5.4.2 int grX11col(char* colour)—Set colour by name
      CHARACTER*n COLOUR
      IOLD = GRX11COL(COLOUR)

Selects a colour using its actual X11 name or an RGB specification (see the X man page for details). COLOUR should be terminated with a null character. The user can have up to 16 of these named colours.

5.4.3 int grbcol(int col)—Set background colour

       INTEGER COL
       IOLD = GRBCOL(COL)

Sets the display background colour (the default is Black). Background colour is used by GRCLR to clear the graphics region, and forms the background to ‘opaque’ fonts (see GRTFBG).

5.4.4 void grinvt(void)—Swap foreground and background colours

       CALL GRINVT

Exchanges the foreground and background colours to provide a simple way to highlight text output.

5.4.5 int grmode(int mode)—Set drawing mode

       INTEGER MODE
       IOLD = GRMODE(MODE)

Defines how coloured objects (including text) are drawn on top of existing colours on the display. In the following P is the previous screen colour, N is the new screen colour and O is the colour of the object being drawn. The third column gives alternative names for some of the modes.

Mode  Operation  Alternate name
NORMAL  N := O  DEFAULT
XOR  N := O XOR P  INVERT

OR N := O OR P

NAND  N := (NOT O) AND P  ERASE
NOT  N := NOT O  REVERSE
NOR  N := (NOT O) OR P  INVERSE

Hard copy devices support only NORMAL mode. Mixing modes (XOR, OR, NAND, NOR) are used for special display effects. When different colours are mixed the effect depends on hardware palette codes.

XOR mode is useful in animation because

      ((O XOR P) XOR P) = O)

so that an object drawn in XOR mode may be erased by drawing it a second time. This process leaves the screen image unchanged.

NAND mode may be used to erase an object drawn in NORMAL mode, but this process may leave ‘black holes’ where the erased object crossed other lines.

5.4.6 int grlt(int type)—Set line type

       INTEGER LTYPE
       IOLD = GRLT(LTYPE)

Specifies the type of line produced by GRDRAW, GRDRBY and GRPOLY to be solid, dotted etc. LTYPE is one of:

SOLID (default) DASHED - - - - DOTTED ….

5.4.7 int grlw(int width)—Set line width

       INTEGER WIDTH
       IOLD = GRLW(WIDTH)

The default WIDTH is 0 (this produces lines much more quickly than WIDTH=1 for some reason).

5.4.8 int grft(int pattern)—Set polygon fill pattern

       INTEGER PATTERN
       IOLD = GRFT(PATTERN)

Specifies the pattern to be used in polygon area fills (see GRFILL). PATTERN is one of:

EMPTY current background colour

FULL (default) block fill with the current line colour HATCH1 Horizontal lines HATCH2 45 degree lines HATCH3 Vertical lines HATCH4 135 degree lines HATCH5 1 and 3 (+++) HATCH6 2 and 4 (xxx)

5.4.9 real grms(real size)—Set marker size

       REAL SIZE
       OLD = GRMS(SIZE)

Specifies the marker size in device units. Default size is .02 (i.e. 2% of the longer side of the graphics region). Marks are drawn by GRMARK.

5.4.10 void grmwh(real width, real height)—Set marker width and height
       REAL WIDTH, HEIGHT
       CALL GRMWH(WIDTH, HEIGHT)

Allows the width and height of a marker to be set independently. Parameters WIDTH and HEIGHT specify the dimensions in device units of a rectangle which just encloses the marker. The current marker size can be determined by GRQDEV.

5.4.11 int grmt(int type)—Set marker type

       INTEGER TYPE
       IOLD = GRMT(TYPE)

Sets the marker symbol type (see GRMARK). TYPE is one of:

PLUS (default)

CROSS SQUARE DIAMOND ARROW X11ARROW X11PLUS X11CROSS

The last 3 types use X11 cursors.

5.4.12 int grct(int type)—Set cursor type

       INTEGER TYPE
       IOLD = GRCT(TYPE)

Sets the type of cursor to be used by GRRQLC.

TYPE:  PLUS  (default) small +, size 0.02 device units

MARK current marker symbol (size and shape can be altered) RUBAND Rubber band RUBREC Rubber rectangle

Specify a cursor type of MARK and a marker size of 2. to get a cross-hair cursor.

For rubber band and rubber rectangle cursors the fixed point is located at the current point and the initial position of the moveable end or corner is given by the parameters X and Y of GRRQLC. Note that these values are updated when input is complete.

5.4.13 void grdflt(void)—Set default attributes

       CALL GRDFLT

Sets all the graphics attribute to the default settings which are in effect when the package is initialised.

    GRCOL(WHITE)  GRBCOL(BLACK) GRMODE(NORMAL)
    GRLT(SOLID)   GRLW(0)       GRMT(PLUS);
    GRMS(0.02)    GRFT(FULL)    GRCT(PLUS)

GRDFLT also selects STANDARD font, character size 1.0 and character angle 0.

5.4.14 void grclip(int flag)—Set/Unset clipping

       CALL GRCLIP(ON)

Clips output to screen and plotfile so that only the graphics in the viewport is drawn. CALL GRCLIP(OFF) restores the default.

5.5 Drawing operations: lines, markers, arcs

Basic drawing actions are defined in terms of a current point or ‘pen position’. The GRDRAW procedure draws a line from the current point to a new position (in user coordinate space), and moves the position of the current point to the end of the line. The initial position of the current point is at the centre of the rectangular graphics region.

5.5.1 void grmove(real u, real v)—Move to (user coordinates)

      REAL U, V
      CALL GRMOVE(U, V)

Moves the current point to (U, V) in user coordinates (no line is drawn).

5.5.2 void grdraw(real u, real v)—Draw to (user coordinates)

      REAL U, V
      CALL GRDRAW(U, V)

Draws a line from the current point to a point (U, V) in user coordinates. The colour, width and type of the line are specified by GRCOL, GRLW and GRLT. The new current point is set to (U, V).

5.5.3 void grmvby(real du, real dv)—Move by
      REAL DU, DV
      CALL GRMVBY(DU, DV)

Moves the current point (without drawing) through a displacement (DU, DV) in user coordinates.

5.5.4 void grdrby(real du, real dv)—Move by
      REAL DU, DV
      CALL GRDRBY(DU, DV)

Draws a line from the current point to a point displaced a distance (DU, DV) in user coordinates. The current point is moved to the end of the line.

5.5.5 void grmvxy(real x, real y)—Move to (device coordinates)

      REAL X, Y
      CALL GRMVXY(X, Y)

Moves the current point to (X, Y) in device coordinates. This procedure, and GRDRXY below, are provided to facilitate frame drawing and the positioning of labels on the screen, independently of current viewport and window definitions.

5.5.6 void grdrxy(real x, real y)—Draw to (device coordinates)

      REAL X, Y
      CALL GRDRXY(X, Y)

Draws a line from the current point to a point (X, Y) in device coordinates. The current point is moved to the end of the line.

5.5.7 void grmvch(int col, int row)—Move to (character coordinates)

      INT ROW, COL
      CALL GRMVCH(ROW, COL)

Moves the current point relative to the top-left corner of the graphics region in units of the current character size. GRMVCH is useful for aligning blocks of text written with GRCHAR. GRMVCH(1, 1) positions the current point near the top-left corner of the graphics region. The coordinates of the bottom-right corner depend on the aspect ratio of the graphics region and the current character size.

5.5.8 void grmark(void)—Draw a marker symbol

      CALL GRMARK

Draws a centred marker symbol in the current colour at the current point (see GRMT).

5.5.9 void grarc(real u, real v, real angle)—Draw a circular arc
      REAL U, V, ANGLE
      CALL GRARC(U, V, ANGLE)

Draws a circular arc with centre at (U, V) in user coordinates. The radius and initial point of the curve are determined by the current point. ANGLE specifies the angle in degrees subtended by the arc. If ANGLE>0 the arc is drawn counterclockwise from the current point, otherwise it is drawn clockwise. After drawing, the current point is left at the end of the arc.

5.5.10 void grpie(real u, real v, real angle)—Draw a filled wedge
      REAL U, V, ANGLE
      CALL GRPIE(U, V, ANGLE)

Draws a circular arc and fills the wedge shape formed by the arc and the two radii joining the centre to the end-points. See GRARC for a description of U, V and ANGLE. The pattern used for filling the wedge is set by GRFT.

5.5.11 void grpoly(int n, real u[], real v[])—Draw a polyline
      INTEGER N
      REAL U(N), V(N)
      CALL GRPOLY(N, U, V)

Draws a polyline (a sequence of joined lines) by connecting N points with straight lines in the current colour and line type. U and V are arrays specifying the points in user coordinates. If a closed polygon is required the last point must equal the first.

5.5.12 void grfill(int n, real u[], real v[])—Draw a filled polygon
      INTEGER N
      REAL U(N), V(N)
      CALL GRPOLY(N, U, V)

Draws an N-sided polygon filled with solid colour or hatching. The colour and fill type are set by GRCOL and GRFT. U and V are arrays specifying the N vertices of the polygon in user coordinates. The last vertex is automatically linked to the first to produce a closed polygon. Note that the vertices are not joined by connecting lines - this allows the sides of the polygon to be drawn in a different colour using GRPOLY.

5.6 Character output and font selection

GraSP provides a number of character fonts for displaying text. ‘Bitmap’ fonts are fixed in size, and character orientation can be only horizontal or vertical, but these fonts are carefully designed to suit the display hardware and give uniformly good output. ‘Stroke’ fonts are formed from vectors and can be scaled and rotated arbitrarily, but these fonts do not always produce good results as numerical rounding can produce distorted text, especially for small characters.

5.6.1 int grfont(int font)—Select character font

      INTEGER FONT
      IOLD = GRFONT(FONT)

Selects the font to be used for drawing characters.

Bitmap fonts

STANDARD (default) SIMPLEX * TRIPLEX * FONT16 * FONT19 * MATHS VERTICAL FONT24 (default for X11B device) MICRO

(*) These fonts have transparent background (see GRTFBG).

Vector fonts

X11SIMPLEX X11DUPLEX X11COMPLEX X11ITALIC

All these fonts have transparent background. A separate handout ‘Scalable character routine for use with GraSP’ by Peter Clarkson describes the vector fonts in more detail.

Errors: ERRNA font not available ERROPN unable to open font definition file ERRMEM no memory to load font tables

5.6.2 int grX11font(char *font)—Select font by name
CHARACTER*n FONT
IOLD = GRX11FONT(FONT)

Selects a font using its actual X11 name. NAME should be terminated with a null character. The user can have up to 16 named X11 fonts.

5.6.3 void grchar(char *message, int length)—Draw a character string
CHARACTER*n MESSAGE
INTEGER LENGTH
CALL GRCHAR(MESSAGE, LENGTH)
or  CALL GRCHAR('...message...', LENGTH)

Draws a character string at the current point. After drawing the string, the current point is moved to the right of the last character drawn so that another call to GRCHAR will produce correctly aligned text. Colour, size and direction are specified by, respectively, GRCOL, GRCHS and GRCHA.

5.6.4 void grtext(char *message)—Draw a null-terminated character string

CHARACTER*n MESSAGE
CALL GRTEXT(MESSAGE//CHAR(0))

Draws a character string (terminated by a null character) at the current point. This is similar to GRCHAR, but more suitable for use in a C program.

5.6.5 void grputi(int value, int width)—Draw an integer value
      INTEGER VALUE, WIDTH
      CALL GRPUTI(VALUE, WIDTH)

Writes the value of the integer parameter VALUE as a character string starting at the current point. WIDTH specifies the the number of characters to be drawn, including any leading spaces. If WIDTH=0 the value is written with no leading spaces. After drawing the string, the current point is positioned to the right of the last character drawn.

5.6.6 void grputr(real value, int width)—Draw a real value
      REAL VALUE
      INTEGER WIDTH
      CALL GRPUTR(VALUE, WIDTH)

Writes the value of the real parameter VALUE as a character string starting at the current point. WIDTH specifies the the number of characters to be drawn, including any leading spaces. If WIDTH=0 the value is written with no leading spaces. Vary large or small numbers are written using fraction plus exponent format. After drawing the string, the current point is positioned to the right of the last character drawn.

5.6.7 real grchs(real size)—Set character size

      REAL SIZE
      OLD = GRCHS(SIZE)

Defines character size relative to a standard size (which may be different for each font). For example:

      OLD = GRCHS(2.0)

produces characters twice as large as normal.

Current character size in device coordinate units may be obtained by calling GRQDEV:

      CALL GRQDEV(CHSIZE, CWIDTH, CHEIGHT)

The values returned include sufficient space to separate characters and lines.

5.6.8 real grcha(real angle)—Set character orientation

      REAL ANGLE
      OLD = GRCHA(ANGLE)

Defines the angle between the horizontal u-direction and the baseline of character strings drawn by GRCHAR. ANGLE is measured in degrees anti-clockwise from the horizontal.

Vector fonts can be rotated in any direction. For bitmap fonts only two orientations are available: horizontal (ANGLE=0.) and vertical (ANGLE=90.). In the latter case characters are always written using the VERTICAL font.

5.6.9 int grtfbg(int mode)—Set transparency of font background

      INT MODE
      IOLD = GRTFBG(MODE)

Stroke fonts and some bitmap fonts, by default, have ‘transparent’ backgrounds—when a character is drawn only those pixels which make up the shape of the character are changed to the current colour. Other bitmap fonts (including the default STANDARD font) have ‘opaque’ backgrounds— when a character is drawn all pixels in a rectangular cell surrounding the character are changed.

Pixels which make up the shape of the character are set to the current colour, and all other pixels in the cell are set to the current background colour.

GRTFBG may be used to alter this default behaviour:

MODE:  TRANSPARENT  force transparent background

OPAQUE force opaque background DEFAULT restore default behaviour

5.7 Interactive procedures

The routines in this section obtain choice, locator or string input from the user.

A choice input is specified by pressing a single key on the keyboard. A locator input allows the user to position a cross-hair cursor by means of the mouse. The required position is signalled by pressing a key or mouse button.

A string input causes a character string to be read from the keyboard. The input characters are displayed on the screen at the current point.

In each case the display is updated, plotting is suspended, and the program waits until the user supplies the requested information.

5.7.1 int grrqch(void)—Request choice

      ICHAR = GRRQCH(IDUM)

Requests choice input. The value returned is:

0 Request timed out (see GRTIME -1 to -8 Function key 1 to 8 pressed >0 ASCII code of the key pressed (13=Return or mouse button)

5.7.2 void grwait(void)—Wait for input

      CALL GRWAIT

GRWAIT reads a single character. It is used to hold output on the screen until the user presses a key and is simpler to use than GRRQCH—it does not require grasp.inc to be included in any routine where it is invoked.

5.7.3 void grrqlc(int *choice, real *x, real *y)—Request locator
      INTEGER CHOICE
      REAL X, Y
      CALL GRRQLC(CHOICE, X, Y)

Requests locator input. A cursor is displayed at the current point. The cursor is moved using the mouse and input is signalled by pressing a mouse button or key. GRRQLC returns in variable CHOICE the code of the key or button used to signal input, as described under GRRQCH above. The current location of the cursor (in device coordinates) is returned in variables X and Y.

Note that the cursor may not necessarily be within the viewport when input is signalled. GRDTOU can be used to convert (X, Y) to user coordinates if required.

The default cursor is a ‘+’ mark of size 0.02 (in device units). The cursor style and size can be changed using GRCT, GRMT and GRMS.

5.7.4 void grwarp(real *u, real *v)—Warp cursor
      REAL U, V
      CALL GRWARP(U, V)

GRWARP jumps the X11 mouse pointer to the new position specified by (U, V) in user coordinates. This routine should be used with caution—pointer warping is considered to be bad practice by many X devotees.

5.7.5 int grrqst(char *reply, int *length)—Request string
      CHARACTER*n REPLY
      INTEGER LENGTH
      KEY = GRRQST(REPLY, LENGTH)

Requests string input. The string is typed at the current point. Characters may be erased using the ‘backspace’ or ‘left arrow’ keys. Input is terminated by pressing the Return key or a mouse button.

The maximum length of the string which can be entered is specified by the LENGTH parameter (which must be a variable). On completion, the length of the input string is returned in LENGTH.

The value returned by GRRQST is the code of the key or button used to terminate input:

0 Request timed out

-1 to -8 Function key 1 to 8 pressed 13 Return or mouse button pressed

5.7.6 int grrqi(void)—Request an integer

      INT = GRRQI(IDUM)

Reads a string using GRRQST and converts it to an integer result.

5.7.7 real grrqr(void)—Request a real

      REAL = GRRQR(IDUM)

Reads a string using GRRQST and converts it to a real result.

5.7.8 int grtime(int timeout)—Set timeout interval

      INTEGER TIMEOUT
      IOLD =  GRTIME(TIMEOUT)

Sets a limit on the time spent waiting for input in interactive routines GRRQCH, GRRQLC, GRRQST,

GRRQI, GRRQR and GRREAD.

TIMEOUT specifies the timeout period in seconds:

0 return immediately, even if input is not available >0 set timeout period in seconds <0 set infinite timeout period (default)

If input is not completed within the specified period the input routine returns a value of 0. If a timeout period of 0 is specified, an input routine exits immediately, returning a non-zero value if input is available, 0 otherwise. This may be used to achieve special effects including asynchronous interrupts. The default setting means that a program always waits until the user responds.

Example:

      CALL GRTIME(0)
  10  CALL ANIMATE
      IF (GRRQCH(IDUM) .EQ. 0) GO TO 10
      CALL GRTIME(-1)

This code repeatedly calls subroutine ANIMATE until a key is pressed.

5.7.9 void grdeff(int field, int mode, char *prompt, int length, real u, real v)—

Define input field

      CHARACTER*n PROMPT
      INTEGER FIELD, MODE, LENGTH
      REAL U, V
      CALL GRDEFF(FIELD, MODE, PROMPT, LENGTH, U, V)

GRREAD defines the position, length and initial contents of an alphanumeric input field. Up to thirteen fields may be defined. FIELD specifies which field is to be defined (1 <FIELD< 13).

MODE controls input to the field: MODE=1 enables input so that the user can type characters into the field. MODE=0 disables input and makes the field ‘write protected’.

PROMPT specifies the initial contents of the field (must be null-terminated).

LENGTH specifies the length of the field. PROMPT is padded at the right with spaces if necessary to fill out the field. U, V specify the position in user coordinates of the bottom-left corner of the first character in the field.

This routine together with GRREAD and GRGETF provide an emulation of the alphanumeric input facility of IBM’s GDDM graphics package.

5.7.10 int grread(void)—Request field input

      INT = GRREAD(IDUM)

Displays all defined fields and requests input from the keyboard. Input may be typed into any of the enabled (MODE=1) input fields. Editing keys are defined as follows:

<— move left —> move right Insert toggle insert/overstrike mode Delete delete character above the cursor and close up text tab move to next enabled field up arrow move to start of previous field down arrow move to start of next field Return terminate input

The value returned by GRREAD is the code of the key or button used to terminate input, as described

under GRRQST.
5.7.11 void grgetf(int field, char *reply)—Fetch field contents
      INTEGER FIELD
      CHARACTER*n REPLY
      CALL GRGETF(FIELD, REPLY)

Fetches the contents of an alphanumeric input field. GRGETF is called after GRREAD to retrieve input fields typed by the user.