Contact us Heritage collections Image license terms
HOME ACL ACD ICF SUS DCS G&A STARLINK Literature
Further reading □ OverviewContentsPrefaceNotation1. Introduction2. Graphical output3. Coordinates4. Segments and Attributes5. Input devices6. Interaction styles7. Workstations8. Environment9. Input control10. Segment storage11. Metafiles12. Further facilities13. Individual attributesA. AbbreviationsB. Language bindingC. Complete programIndex
C&A INF CCD CISD Archives Contact us Heritage archives Image license terms

Search

   
ACDLiteratureBooksGKS
ACDLiteratureBooksGKS
ACL ACD C&A INF CCD CISD Archives
Further reading

OverviewContentsPrefaceNotation1. Introduction2. Graphical output3. Coordinates4. Segments and Attributes5. Input devices6. Interaction styles7. Workstations8. Environment9. Input control10. Segment storage11. Metafiles12. Further facilities13. Individual attributesA. AbbreviationsB. Language bindingC. Complete programIndex

Chapter 8: GKS Environment

8.1 INITIALISATION

Chapters 2 to 7 have given an overview of most of the input and output facilities within GKS. However, nothing has been said as to how the user initialises GKS at the start of the program. In fact, none of the GKS functions so far described may be called before GKS is initialised and this is done by the function:

OPEN GKS(EF, SU)

The function OPEN GKS is only called once for an invocation of GKS. The parameter EF specifies the name of a file that will be used by GKS to return error information to the application program. Section 8.5 discusses how GKS handles errors and the use made of the error file. The parameter SU allows the user to specify the size of the internal workspace to be used by GKS if this is meaningful in a particular implementation.

Opening GKS initialises a number of variables to default values, some of which are dependent on the specific implementation. For example the maximum number of workstations that may be open simultaneously may vary from installation to installation. Others are defined as standard for all implementations. For example, GKS always sets the current POLYLINE INDEX and other similar indices to 1. The current normalization transformation is set to 0 and all normalization transformations are initialised so that the window is the unit square and so is the viewport. For example:

     OPEN GKS(EF, SU)
     OPEN WORKSTATION(1, 6, 3) 
     ACTIVATE WORKSTATION(1) 
     X(l)=0.0 
     X(2)=1.0 
     Y(1)=0.0 
     Y(2)=1.0
     POLYLINE(1, X, Y)

This will draw a single line from the lower left to the top right of the NDC unit square. The line will be drawn in the style specified by polyline index 1.

However, it is important to note that GKS has an alternative attribute handling mechanism, to that used in the earlier chapters, which will be described in Chapter 13. Not all GKS implementations will choose the same default mechanism and it may be necessary to change the mechanism, to that assumed so far by this book, after GKS is opened. How this is done is described in Section 13.4. This is particularly important for readers in the USA.

Just as GKS needs to be initialised before any calls can be made to GKS functions, it is also necessary to close GKS down at the end of the session. This is achieved by calling the function:

CLOSE GKS

The error file is closed and any other housekeeping functions required by the implementation are performed. The program above would be completed by:

      DEACTIVATE WORKSTATION(1) 
      CLOSE WORKSTATION(1) 
      CLOSE GKS

Note that it is necessary to deactivate and close all workstations that are open prior to closing GKS down.

8.2 GKS OPERATING STATES

To aid error handling in GKS, a number of operating states are identified. When GKS is in a specified state, certain GKS functions can be called while others are invalid. Before GKS is opened, it is in the state GKS CLOSED. As soon as the function OPEN GKS has been called, GKS is in the state GKS OPEN. The main states of GKS are:

  1. GKS OPEN: the function OPEN GKS has been called. GKS leaves this state when CLOSE GKS is called or a workstation is opened.
  2. WORKSTATION OPEN: at least one workstation has been opened. In this state, certain attribute setting functions can be called.
  3. WORKSTATION ACTIVE: at least one of the open workstations is active. In this state, GKS output primitives can be created and certain segment manipulation functions can be performed.
  4. SEGMENT OPEN: a segment is open. Calling CLOSE SEGMENT causes GKS to revert to the state WORKSTATION ACTIVE.

There is a strict ordering to the states. For example, the state WORKSTATION OPEN cannot be changed to SEGMENT OPEN directly but GKS has first to go through the state WORKSTATION ACTIVE. Effectively, this ensures that a segment cannot be opened unless at least one workstation is active. Similarly, GKS cannot revert directly from the state WORKSTATION ACTIVE to GKS OPEN. This prevents a workstation from being closed if it is still active; the program must first deactivate it.

GKS precisely defines which states each GKS function can be called in and which GKS functions cause the state to change. Most of these are quite obvious as can be seen by the examples above.

8.3 GKS STATE LISTS

Internal to GKS and hidden from the application programmer are a number of state lists (COMMON blocks in a FORTRAN implementation) which contain relevant information about the current state of GKS. We will not go into these in great detail as, to first order, the application programmer does not really need to know that they exist. However, it is useful to get some feel for the underlying structure.

The main state lists are:

  1. Operating State: this is a single value giving the state of GKS.
  2. GKS Description Table: a table which gives information about the particular implementation of GKS. For example, it contains information as to how many workstations can be open together, the number of different normalization transformations allowed, and the types of workstation available.
  3. GKS State List: the main list for the virtual side of GKS. It contains information about all the current settings of attributes, normalization transformations, which segment is open, etc. The input queue is part of this list.
  4. Workstation Description Table: these are set up by the installation manager for the site and contain information about the characteristics of the workstations available. There is one table for each workstation type available.
  5. Workstation State List: these contain information about the workstations that are open. Each workstation that is open has its own state list and it is initialised to certain values (screen size, for example) from the Workstation Description Table. The Workstation State List contains information concerning the device specific side of GKS. It includes the workstation window and viewport settings and the various tables described in Chapter 7, which control how a particular primitive appears on this workstation.

These tables contain all the current relevant knowledge of GKS and are accessed by the application program via a set of inquiry functions.

8.4 INQUIRY FUNCTIONS

Inquiry functions in GKS allow the application programmer to access the information in the various GKS State Lists (see Section 8.3). They are used for a variety of purposes. The major ones are:

  1. To achieve precise results on a specific workstation.
  2. To tailor the application for particular environments.
  3. To produce library functions.
  4. To recover from error.

A typical inquiry function has the form:

INQUIRE NAME OF OPEN SEGMENT(IND, SEGNAME)

The inquiry functions in GKS have been organized so that it is not possible to get a GKS error when calling them. This allows inquiry functions to be called in an error condition without resulting in further GKS errors which could obscure the original error. Also, it allows inquiry functions to be called with no likelihood of them having any impact on the state of GKS.

This is achieved by the inquiry functions all having their initial output parameter as an indication as to whether the information returned by the inquiry is correct or not.

If IND has the value 0 on return, the SEGNAME parameter does contain the name of the open segment. If IND contains a value other than zero, it indicates what error situation has occurred. In the example above, IND could be set to a non-zero value indicating that there is no open segment and, therefore, it is not possible to give the name of the open segment.

The purpose of some inquiry functions is to return a complete list or set from GKS, which can be of unknown size. For example the application may need to scan all the segments so that it can find out if a particular segment exists. In a FORTRAN implementation, the inquiry returns the list one item at a time. Thus the function to return a segment is:

INQUIRE SET MEMBER OF SEGMENT NAMES IN USE(IX, IND, NM, SEG)

Here IX identifies which segment name is to be returned in SEG, IND is the indication of an error as before and NM is the total number of segment names in use.

Suppose we want to discover if segment 62 is in use. We can inquire each segment name and test it in turn. We emerge with a .TRUE. or .FALSE. in the logical variable EXISTS.

      EXISTS = .FALSE.
      IX=1
 100  CONTINUE 
      INQUIRE SET MEMBER OF SEGMENT NAMES IN USE(IX, IND, NM, SEG) 
      IF(IND .NE. 0) GOTO 300 
      IF(SEG .EQ. 62) GOTO 200 
      IX=IX+1 
      IF(IX .GT. NM) GOTO 300 
      GOTO 100
 200  EXISTS = TRUE.
 300  CONTINUE

As there are around 75 different inquiry functions in GKS, it is not possible to list these all here. It is more sensible for these to be looked up when they are required in the relevant GKS manual for the particular implementation being used.

8.4.1 Precise Results on a Workstation

An application program may require precise alignment with the characteristics of a particular workstation to achieve its aims. For example, the application may require to output to a plotter a scale drawing which will later be used on the assumption that the measurements on the output are precise. Suppose the application defines the picture in NDC space so that the range 0 to 0.5 in the X and Y directions correspond to 400 centimetres on the plotter output. If the application is to be used in a number of different environments, it will be unaware of the sizes of the plotters available or the device coordinates that they use. The inquiry function:

INQUIRE DISPLAY SPACE SIZE(WSTYP, IND, UNITS, RX, RY, IX, IY)

returns the characteristics of the workstation WSTYP. UNITS indicates whether precise measuring is possible on the device or not. The next two parameters give the maximum size of the display either in metres, if precise measurements are possible, or the device coordinates used by the device. The last two parameters give the display space size in terms of addressable positions. To achieve the desired effect above would require:

      INQUIRE DISPLAY SPACE SIZE(WSTYP, IND, UNITS, RX, RY, IX, IY) 
      IF(UNITS .NE. METRES) GOTO 100 
      IF(MIN(RX, RY) .LT. 0.4) GOTO 100 
      OPEN WORKSTATION(WS, 5, WSTYP) 
      ACTIVATE WORKSTATION(WS) 
      SET WORKSTATION WINDOW(WS, 0, 0.5, 0, 0.5) 
      SET WORKSTATION VIEWPORT(WS, 0, 0.4, 0, 0.4)

The code at label 100 will indicate that a precise drawing cannot be obtained with a workstation of this type either because the device does not have precise scaling or is too small.

8.4.2 Tailoring Applications to Particular Environments

An application may expect the device to have a range of representations for a particular primitive. If these are unavailable on a particular device, it may decide to take a different approach to achieve the same results. For example, suppose two sets of points are to be marked by:

      SET POLYMARKER INDEX(1) 
      POLYMARKER(N, XA, YA) 
      SET POLYMARKER INDEX(2) 
      POLYMARKER(M, XB, YB)

At this installation, the five standard markers have been augmented by a sixth marker which outputs ellipses. This particular installation has set representations 1 and 2 to be a dot and ellipse for those devices that can produce markers. However, one device type at the installation only has the ability to output the five standard markers.

In this case, the application could define a function which outputs an ellipse centred at the position specified. The relevant inquiry is:

INQUIRE POLYMARKER FACILITIES(WSTYP, ..., IND, NMK, ...)

This function returns in NMK the number of available marker types. The other parameters give more information concerning the sizes available and the initial settings to particular representations. To achieve similar results on the limited workstation would require the following:

      SET POLYMARKER INDEX(1) 
      POLYMARKER(N, XA, YA) 
      INQUIRE POLYMARKER FACILITIES(WSTYP, 1, IND, NMK, ...) 
      IF (NMK .GT. 5) THEN 
      SET POLYMARKER INDEX(2) 
      POLYMARKER(M, XB, YB) 
      ELSE
      DO 100 I = 1, M 
      ELLlPSE(XB(I), YB(I)) 
 100  CONTINUE
      ENDIF

There are a large number of attributes of the workstation which an application may wish to inquire. The workstation description table indicates whether the device is a vector or raster display, which output functions require an implicit regeneration of the output, whether the display is monochrome or colour and many other facts. An application can use this information to change its approach. However, significant use of this information may cause the application to be less portable.

8.4.3 Library Functions

In Section 3.6, an example was given of a program which output the New York temperature given by the array MAXPR. It uses normalization transformations 1 to 3 to specify the position of the graph in NDC space and the associated annotations. To achieve its results, it resets a number of text and marker attributes.

If this was to be defined as a function, NEW YORK, it should be defined in such a way that the application using it is unaware that it has changed any attributes. To do this, the values need to be stored on entry to the function and reset before exit:

      SUBROUTINE NEW YORK(MAXPR)
      INQUIRE CURRENT NORMALIZATION TRANSFORMATION NUMBER(IND, CURRENT) 
      INQUIRE NORMALIZATION TRANSFORMATION(1, IND, WIND1, VIEW1) 
      INQUIRE NORMALIZATION TRANSFORMATION(2, IND, WIND2, VIEW2) 
      INQUIRE NORMALIZATION TRANSFORMATION(3, IND, WIND3, VIEW3) 
      INQUIRE CURRENT POLYMARKER INDEX(IND, PMKINDX) 
      INQUIRE CURRENT CHARACTER HEIGHT(IND, CHRHT) 
      INQUIRE CURRENT CHARACTER UP VECTOR(IND, CHARUPX, CHARUPY)
      (Program as in Section 3.6)
      SET WINDOW(1, WIND1(1), WIND1(2), WIND1(3), WIND1(4)) 
      SET VIEWPORT(1, VIEW1(1), VIEW1(2), VIEW1(3), VIEW1(4))
      SET WINDOW(2, WIND2(1), WIND2(2), WIND2(3), WIND2(4)) 
      SET VIEWPORT(2, VIEW2(1), VIEW2(2), VIEW2(3), VIEW2(4))
      SET WINDOW(3, WIND3(1), WIND3(2), WIND3(3), WIND3(4)) 
      SET VIEWPORT(3, VIEW3(1), VIEW3(2), VIEW3(3), VIEW3(4)) 
      SELECT NORMALIZATION TRANSFORMATION(CURRENT) 
      SET POLYMARKER INDEX(PMKINDX) 
      SET CHARACTER HEIGHT(CHRHT) 
      SET CHARACTER UP VECTOR(CHARUPX, CHARUPY)

All the attributes reset by the function are returned to their original values before exiting. If there was any danger that the inquiry functions would generate errors, the values of IND returned by the individual inquiries would also need to be checked.

Inquiry functions may differ from language to language as the style of the language differs. The functions given here correspond to the ones available in the FORTRAN binding.

8.5 ERROR HANDLING

GKS has a well defined set of errors which will be reported back to the application program. The philosophy adopted is that all errors are reported by putting details of the error in the error file which was specified when GKS was opened. A typical error will record the following information:

  1. Error Number: a number indicating which error has occurred.
  2. GKS Function: the name of the GKS function that was being obeyed when the error was detected.

There is a full set of error numbers so that a particular error can be precisely identified. What happens when an error has been recognized depends on the application program. If no special action has been specified, G KS calls the installation supplied error handling procedure:

ERROR HANDLING(NMBR, FCTID, EF)

The parameters supplied to it are the error number (NMBR), function name in which the error was detected (FCTID) and the name of the error file (EF). The action of this procedure is to record the error information in the error file by calling the procedure:

ERROR LOGGING(NMBR, FCTID, EF)

and then return to the GKS function where the error has been detected. Normally a GKS function causing an error has no effect on GKS. On return from the GKS function, the state of GKS is as if the function had not been called. In some cases, GKS may not be able to take the clean up action to achieve this and then the effects are unpredictable.

This rather cumbersome way of organizing the error handling has been set up to allow the application program to specify its own error handling procedure which takes a specific action. For example:

      OPEN GKS(ERRFLE, SU) 
      OPEN WORKSTATION(1, 6, 3) 
      ACTIVATE WORKSTATION(1) 
      CLOSE SEGMENT                ILLEGAL!!

This program would cause an error as the GKS State would be WORKSTATION ACTIVE (see Section 8.2) when CLOSE SEGMENT was called rather than SEGMENT OPEN. As a result, the installation supplied error handling procedure would be called. If the application program required to know whether any workstations were active when the error occurred, it could substitute its own error handling procedure as follows:

      SUBROUTINE ERROR HANDLING(NMBR, FCTID, ERRFLE)
      IF(NMBR .EQ. 4) THEN 
      INQUIRE OPERATING STATE VALUE(OP) 
      IF(OP .EQ. WSAC) WRITE(6,*) 'GKS is in the state WORKSTATION ACTIVE"
      - - -
      - - -
      ENDIF 
      ERROR LOGGING(NMBR, FCTID, ERRFLE) 
      RETURN 
      END

The main point to note is that the user supplied error handling routine should still call ERROR LOGGING before returning. In this example, error number 4 is one indicating that a segment was not open. It has been singled out for special treatment. The inquiry function returns the current value of the GKS Operating State in OP. A suitable message is put out if the Operating State is WORKSTATION ACTIVE. The user supplied error handling procedure could inquire other information and might write this information to the error file or it might store the information in a COMMON block for use by the application program.

The only GKS functions which can be invoked in the error handling procedure are:

      ERROR LOGGING 
      Inquiry functions 
      EMERGENCY CLOSE GKS

There will be occasions when it is not possible to recover from an error and then the requirement is to save as much of the graphical information produced as possible, for example ensuring that any output information buffered within GKS is transmitted to the device. GKS provides the function:

EMERGENCY CLOSE GKS

for this purpose. GKS itself will invoke this function in response to some classes of error. This function may be invoked by a user supplied error handling procedure.

8.6 LEVELS

It is clear from the previous sections that GKS is a comprehensive graphics system containing most of the features required by the application programmer. This in itself will mean that GKS is quite large and, for simple applications, it is feasible that a great deal of unnecessary complexity is available in GKS. In this case, the user would like to use only a subset of the facilities available in GKS. This is achieved in GKS through the level structure.

GKS has nine valid levels defined by three different choices on each of two axes. The two axes are approximately input and all the other functions.

The definitions of the input choices are:

The definitions of the choices on the other axis are:

The simplest GKS implementation is, therefore, Level Oa which only allows output to a single workstation at a time. Level 1b gives most of the functions described in Chapters 2 to 7 excluding Chapter 6. Level 1c adds approximately the input facilities described in Chapter 6.

⇑ Top of page
© Chilton Computing and UKRI Science and Technology Facilities Council webmaster@chilton-computing.org.uk
Our thanks to UKRI Science and Technology Facilities Council for hosting this site