Chapter 6: What you need to know about GKS workstations

Previous Chapter          LLUs Home          Next Chapter          Index
NCAR Graphics is based on GKS, the Graphical Kernel System. GKS is an ANSI standard that standardizes graphics functionality at a fairly low level. GKS is based on the concept of abstract graphical workstations. These workstations provide the logical interface through which an application program controls physical devices.

All GKS workstations are conceptualized as having a single display surface of fixed resolution allowing only rectangular display spaces. These workstations support drawing lines, plotting text, filling polygons, and so on. GKS workstations fall into several types depending on whether they support graphical output or graphical input, or store graphical instructions.

This section presents those parts of GKS that you should know in order to use workstations within the context of NCAR Graphics. This section discusses what types of physical workstations are available in the NCAR GKS package and shows how to associate an abstract GKS workstation with a physical workstation. This section also covers how to direct output to specific workstations and how to store graphics instructions, either in a metafile for permanent storage, or in a segment for temporary storage and subsequent copying to other workstations.

The basic reference for this section is the User's guide for NCAR GKS-0A Graphics programmer document; check with your site installer for the online PostScript version. Appendix C of that document also gives several references where complete presentations can be found for the entire GKS standard.

Because of the nature of this section, several of the modules do not contain accompanying graphics. Also, some of the modules have no sample codes since many of the functions are best illustrated in the context of a complete program. To this end, a program illustrating most of the functions covered in this section is presented as the final module.

Table of GKS workstation-related user entry points

This section discusses functions related to manipulating GKS workstations. These functions come from the GKS, Gflash, and SPPS utilities.

GKS

GACWK
Activates a GKS workstation.

GCLKS
Closes the GKS package.

GCLRWK
Clears a GKS workstation.

GCLWK
Closes a GKS workstation.

GDAWK
Deactivates a GKS workstation.

GESC
GKS ESCAPE function used for changing the name of an output metafile.

GOPKS
Opens the GKS package.

GOPWK
Opens a GKS workstation.

GUWK
Updates a GKS workstation

Gflash

GFLAS1
Initiates the creation of a segment for storing graphics instructions.

GFLAS2
Terminates a segment of stored graphics instructions.

GFLAS3
Copies segments of stored graphics instructions to active GKS workstations.

GFLAS4
Processes a previously created segment of stored graphics instructions for use with GFLAS3.

SPPS

FRAME
Updates all open workstations, creates a picture break for NCGM workstations, and pauses in the X11 window of most recent creation if such a window exists.

NGPICT
Combines several workstation control functions.

PLOTIF
Flushes the SPPS polyline buffer.

SFLUSH
Updates all open workstations and flushes all possible buffers.

Opening GKS, opening and activating workstations

This module describes the workstation types that are available to NCAR Graphics and shows how to put them in the proper states to receive graphics instructions.

Before any GKS functions can be called, or before any NCAR Graphics calls can be made, GKS must be opened. Opening GKS initializes all default settings such as character height and marker type. Most GKS functions that are not workstation specific can be called after GKS is open; this includes things like setting line color and thickness, setting fill area interior style and color, setting marker type and size, and so on.

GKS functions that are workstation specific, such as defining color indices, require that the workstation involved be open. In addition, if the GKS output primitives for drawing lines, text, filled areas, markers, and cell arrays are to be sent to a workstation, that workstation must be active.

GOPKS opens the GKS package. GOPWK opens a workstation and is the GKS function that establishes the association between the GKS logical workstation and a physical workstation. GACWK activates a workstation.

Code segment 1 from fgke01.f

1       CALL GOPKS(6,0)
2       CALL GOPWK(1,2,1)
3       CALL GOPWK(2,0,8)
4       CALL GACWK(1)
5       CALL GACWK(2)

Synopsis

      CALL GOPKS (ERRFIL, BUFA)
      CALL GOPWK (WKID, CONID, WKTYPE)
      CALL GACWK (WKID)

Arguments

ERRFIL
Integer, Input ---The Fortran logical unit number to which error messages are to be written. Typically this would be unit 6 (standard out).

BUFA
Integer, Input---The dimension of an internal buffer to be used by GKS. Currently in NCAR GKS, this is ignored and can be set to zero.

WKID
Integer, Input---A number assigned to a workstation as an identifier that can be used in all subsequent calls to GKS functions that require a workstation identifier. In NCAR GKS, WKID can be any non-negative integer.

CONID
Integer, Input---A connection identifier that has different meanings for different workstation types (see the description of WKTYPE and the "Discussion" section below).

WKTYPE
Integer, Input---An identifier specifying the type of output device targeted. Each GKS package has an implementation-dependent set of workstation types that the package supports. There are five legal workstation types in NCAR GKS:

1
NCGM. The output device will be a metafile whose default name is "gmeta". See the module later in this chapter, "Changing an NCGM filename" to change metafile output names. Only one NCGM output file can be open at a time.
3
WISS. This stands for "Workstation Independent Segment Storage" and should be opened before storing graphics in segments. See the module "Using GKS segments, the Gflash utility" later in this section. Only one WISS workstation can be open at a time.
7
Pre-existing X11 window. Directs graphics output to the pre-existing X11 window whose window ID is given as the connection ID.
8
Non-existing X11 window. Opens up a new X11 window.
10
Text dump of graphics output. Writes a human-readable ASCII dump of the output.

Discussion

For workstation types 1 (NCGM) or 3 (WISS), the connection ID is used as a Fortran logical unit number. It is permissible to have workstations of types 1 and 3 open simultaneously, but they must have distinct connection IDs. For workstations of type 7, the connection ID is the X11 window ID for an existing window (an ID as obtained from xwininfo for example). For workstations of type 8, an X11 window will be created at open workstation time. The connection ID is irrelevant for workstations of type 8. For workstations of type 10, the ASCII text is written to standard output and the connection ID is irrelevant. There can be a maximum of fifteen simultaneously open workstations of all types.

Line 1 of code segment 1 from fgke01.f opens the GKS package and establishes standard output as the error unit. Many GKS calls can be made after GKS has been opened and before any workstation has been opened. For example, you can make calls to set the text alignment, change the character height, and change the marker type. Line 2 opens an NCGM workstation and specifies Fortran logical unit 2 in the connection ID. After the NCGM workstation has been opened, it is legal to make calls to the GKS function GSCR to specify a color table for that workstation. Line 3 opens a new X11 window. After it has been opened, any calls to produce GKS primitives (such as polylines) will not produce any output on workstations 1 or 2, since they are not active. Line 4 activates the NCGM workstation. Calls to produce GKS primitives after this point will be sent to workstation 1, but not to workstation 2, since it is not yet active. Line 5 activates the X11 workstation. All GKS output primitives will now be sent to both workstations.

Deactivating and closing workstations, closing GKS

This module describes how to reverse the operations in the previous module. It describes how to deactivate and close a workstation and how to close GKS.

GDAWK deactivates a workstation, GCLWK closes a workstation, and GCLKS closes GKS.

Code segment 2 from fgke01.f

1       CALL GDAWK(1)
2       CALL GDAWK(2)
3       CALL GCLWK(1)
4       CALL GCLWK(2)
5       CALL GCLKS

Synopsis

      CALL GDAWK (WKID)
      CALL GCLWK (WKID)
      CALL GCLKS

Arguments

WKID
Integer, Input---A number identifying the workstation to be deactivated or closed. WKID must be the same number that was used in some previous GOPWK call.

Discussion

Line 1 of the fgke01.f code segment calls GDAWK to deactivate the NCGM workstation. After this call, the state of this workstation is exactly as it was immediately after the call to GOPWK that opened it. Unless the NCGM workstation is reactivated, no further GKS primitives will be sent to it. If the NCGM workstation is reactivated before being closed, then GKS output primitives will be once again be sent to it and appended to the file.

Line 2 deactivates the X11 window. The window will stay visible, but subsequent output primitives will not be sent to it unless it is reactivated.

Line 3 closes the NCGM file. The metafile is terminated with the appropriate NCGM elements and no new elements can be appended to it. If another NCGM file were now to be opened with the default name, it would overwrite the previously generated file. If an NCGM were opened with a new name (see "Changing an NCGM filename" later in this section) an entirely new file would be originated and the previous file would remain unchanged.

Line 4 closes the X11 window. The window will be erased from the screen, and that particular window cannot be reopened. Closing workstations removes the workstation identifiers from the set of open workstations and frees the connection identifiers. These numbers can be reused in future calls if desired.

Line 5 closes GKS. This call ensures that the graphics package is properly terminated. No graphics calls (with the exception of GOPKS) are legal while GKS is closed.

Making sure things are current

There are several buffers in the output viewing pipeline of NCAR Graphics. There is the SPPS polyline buffer; there is an output buffer in the metafile generation software; and there are system level I/O buffers. If any of these buffers is only partially filled, it may be that an output workstation does not reflect all of the requests that have been made. There are several functions that can be called to insure that workstations reflect all requests that have been made. This module discuss three such functions. Most of the functionality discussed here is subsumed under the functions discussed in the next module, but in certain circumstances that will be pointed out, you may want to call these lower-level functions directly. GUWK updates a workstation. PLOTIF draws lines and flushes the SPPS polyline buffer. SFLUSH flushes the SPPS polyline buffer and updates all workstations.

Synopsis

      CALL GUWK (WKID, REGFL)
      CALL PLOTIF (X, Y, IPEN)
      CALL SFLUSH

Arguments

WKID
Integer, Input---A number identifying the workstation to be updated. WKID must be the same as that used in some previous call to GOPWK.

REGFL
Integer, Input---A flag to specify if the current picture should be regenerated. The possible values are "0" for postpone and "1" for perform. For the workstation types supported in NCAR GKS, this flag should always be set to "0".

X,Y
Real, Input---A coordinate pair in normalized device coordinates. For the purposes of this discussion (using PLOTIF to flush the SPPS pen-move buffer) these values are not relevant and can be set to "0.".

IPEN
Integer, Input---A parameter that, for the purposes of this discussion (using PLOTIF to flush the SPPS pen-move buffer), should be set to "2".

Discussion

The function GUWK (update workstation) is a GKS entry point. You would call it if you were interested in writing an application that depended exclusively on GKS. For a metafile, GUWK forces a write of the most current requests and flushes the system I/O buffers. For an X11 workstation, GUWK forces the current picture to reflect all requests that have been made. GUWK does not flush the SPPS polyline buffer.

PLOTIF is an SPPS entry point and is used primarily for drawing lines, but it has the additional use of flushing the SPPS polyline buffer if it is called with the arguments "0., 0., 2". (See the man page for PLOTIF for complete details on that function). The polyline buffer in SPPS is designed to reduce metafile sizes by buffering pen-moves in order to call the GKS polyline function with as many points as possible. Without the buffering, GPL would need to be called with only two points in all cases.

The SPSS polyline buffer can produce some unwanted side effects. For example, if you change the line thickness before flushing the SPPS polyline buffer, then the line thickness request can actually be issued before the polyline call that is being buffered, so that the setting of line thickness can appear to have a retroactive effect. Whenever line attributes are being changed, you should flush the SPPS polyline buffer first. Calling PLOTIF is the most direct way of doing this, although other functions will flush this buffer as well, such as SFLUSH, discussed below, and the functions discussed in the next module. If you are using NCAR Graphics calls and want to update a workstation, it is advisable to flush the SPPS polyline buffer first. Thus, calling PLOTIF to flush the SPPS polyline buffer followed by calling GUWK is a logical sequence of calls.

SFLUSH is an SPPS entry. SFLUSH flushes the SPPS polyline buffer and then calls GUWK on all open workstations. The intent of SFLUSH is to flush all possible buffers relating to all open workstations.

There are certain circumstances where it would be more efficient to call PLOTIF rather than SFLUSH. For example, if you were creating dozens of objects with line draws and changing line attributes between the creation of each object, then it would be most efficient to call PLOTIF to flush the SPPS polyline buffer after drawing each object, rather than calling SFLUSH, since SFLUSH would add the overhead of updating all open workstations.

If you don't want to worry about the subtleties discussed in this module, but you want to ensure that your workstations are current, call SFLUSH and go on your merry way.

Controlling pictures

This module discusses various ways of updating and terminating pictures. For metafiles, this module shows how to insert an "END PICTURE" element into the metafile; for X11 windows, it shows how to pause in a window, how to clear the window, and how to issue a prompt waiting for keyboard or mouse input. GCLRWK clears a workstation.

Synopsis

      CALL GCLRWK (WKID, COFL)
      CALL FRAME
      CALL NGPICT (WKID, ACTION)

Arguments

WKID
Integer, Input---A number specifying a GKS logical workstation. This number must be the same as that used in some previous GOPWK call.

COFL
Integer, Input---Flag for clearing the display surface. COFL can have two possible values:

0
Checks to see if the display surface is empty. If it is, nothing is done; if not, the display surface is cleared.
1
Issues a clear display surface command whether the surface is empty or not.

ACTION
Integer, Input---Specifies an action to be taken on WKID. Legal values are:

0
Executes an update workstation on WKID (see GUWK in the previous module).
1
Executes an update workstation on WKID followed by a clear workstation.
2
Executes an update workstation on WKID followed by a pause waiting for any keyboard or mouse click. The picture is not cleared after the click has been issued.
3
Same as 2 above, except the picture is cleared after the click has been issued.
4
Same as 3 above, except a "<READY>" prompt is issued in the lower left corner of the window, after the update of the workstation, to indicate a mouse click is being awaited.

Discussion

GCLRWK is a GKS routine. For workstations of type 1 (NCGM), GCLRWK is interpreted as a picture termination in NCGM generation. If COFL = 0 and no output primitives have been written in the current picture, then a call to GCLRWK is a "do nothing"; otherwise, it generates an END PICTURE element (as well as other picture initializing elements). If COFL = 1, then a call to GCLRWK generates an END PICTURE. When ctrans encounters an END PICTURE in NCGM interpretation, it pauses waiting for a mouse click.

For workstations of types 7 or 8 (see the module "Opening GKS, opening and activating workstations" earlier in this section), clear workstation erases all primitives that appear on the screen. For all other workstation types, clear workstation updates the workstation. Clear workstation does not flush the SPPS polyline buffer.

If an NCGM workstation is active, a call to FRAME causes an END PICTURE CGM element to be generated. If there are active X windows, FRAME updates all workstations and pauses in the window of most recent creation. After a mouse click or a key click in the window on pause, all workstations are cleared and execution continues. FRAME flushes the SPPS polyline buffer.

FRAME is most applicable to an environment with a single active workstation. When multiple workstations are used, the more versatile NGPICT may be more useful.

In a call to NGPICT, if WKID designates a metafile, then a clear workstation is done. This inserts an END PICTURE into the metafile. The result produced in this case would be the same as that resulting from a call to FRAME. The only valid values for ACTION in a call to NGPICT that apply to metafile workstations are 0 and 1.

NGPICT is designed to be used when more precise control over individual workstations is desired than that offered by FRAME. This might be desirable, for example, when an application is controlling several simultaneously active workstations. NGPICT flushes the SPPS polyline buffer. To use NGPICT open GKS workstations with GOPWK rather than with OPNGKS.

For examples of usage of the functions described in this module, see the final code example at the end of this section.

Using GKS segments, the Gflash utility

This module describes how to store graphics instructions in independent buffers for later plotting. The buffers may be plotted repeatedly in as many pictures as desired, thus saving the time required to regenerate the instructions. This is accomplished by using the functions in the Gflash utility. Gflash offers a limited picture segmentation capability. A full segmentation capability is a part of all GKS packages at level 2A (or higher). NCAR GKS is at level 0A.

If you are using a level 2A GKS package, then you may want to use the segmentation capabilities in that package directly instead of using Gflash. GFLAS1 starts the storage of plotting instructions into a GKS segment; GFLAS2 stops the storage of plotting instructions. GFLAS3 inserts saved plotting instructions into the output stream. GFLAS4 associates plotting instructions stored on a disk file with an identifier that can be used later with GFLAS3.

Gflash usage

Code segment from fgke02.f

1       CALL GOPKS (6,IDUM) 
2       CALL GOPWK (1, 2, 1)
3       CALL GACWK (1) 
4       CALL GOPWK(9,1,3)
5       CALL GFLAS1(1)
6       CALL GPL(2,RLIN1X,RLIN1Y)
7       CALL GFLAS2
8       CALL GFLAS1(2)
9       CALL GPL(2,RLIN2X,RLIN2Y)
10      CALL GFLAS2
11      CALL GPL(5,PERIMX,PERIMY)
12      CALL GFLAS3(1)
13      CALL GFLAS3(2)
14      CALL FRAME
15      CALL GCLWK(9)
16      CALL GDAWK (1)
17      CALL GCLWK (1)
18      CALL GCLKS

Synopsis

      CALL GFLAS1 (IB)
      CALL GFLAS2
      CALL GFLAS3 (IB)
      CALL GFLAS4 (IB, 'buf_name')

Arguments

IB
Integer, Input---A number between 0 and 99 (inclusive) used as an identifier for the file of stored instructions. GFLAS1 automatically assigns the name GNFBxx to the file that will receive subsequent plotting instructions. These files may be reused in subsequent job steps by using GFLAS4.

buf_name
Character, Input---A filename of a buffer previously created using a GFLAS1/GFLAS2 sequence.

Discussion

A call to GFLAS1 initiates storage of subsequent plotting instructions in a disk file. A call to GFLAS2 terminates storage of plotting instructions to the disk file originated by GFLAS1. All plotting instructions that occur between a GFLAS1 call and a GFLAS2 call are captured in the buffer identified by the argument to GFLAS1. Between the calls to GFLAS1 and GFLAS2, all output to any other workstation is suspended.

After graphics instructions have been captured in a file with a GFLAS1/GFLAS2 sequence, a call to GFLAS3 will plot the set of saved instructions on all active workstations. If you do not want the instructions of a particular flash buffer plotted to a particular workstation, you will need to deactivate that workstation before calling GFLAS3.

GFLAS4 is used to associate a file of stored instructions (created with a previous GFLAS1/GFLAS2 sequence) with an identifier for subsequent use with GFLAS3. The purpose of GFLAS4 is to allow instructions stored in a file in one job to be used in another job.

NCAR GKS stores the flash buffers on a special GKS workstation called WISS (Workstation Independent Segment Storage). You don't need to understand what WISS is, but the consequence is that WISS needs to be opened before accessing entries in the Gflash package and closed after Gflash usage. WISS is opened with a call to GOPWK, just like any other GKS workstation. Its workstation type is 3 and the connection identifier is a Fortran logical unit number used for the disk file writes.

In the code segment from fgke02.f, lines 1 through 3 open GKS and open and activate an NCGM workstation. Line 4 opens WISS. Line 5 initiates the storage of subsequent instructions in a disk file with the name GNFB01; the local identifier of that file is "1". Line 6 draws a line with positive slope in buffer 1 and line 7 terminates the storage of instructions in buffer 1. Output to active workstations is suspended during the time a GFLAS1/GFLAS2 sequence is under way so that the graphics instructions go to the buffer but not to the active workstations. This represents a difference between the way GKS segments behave and the way that Gflash buffers are created.

Lines 8 through 10 result in the storage of a line of negative slope in buffer 2. Line 11 draws a perimeter around the current picture. This call is outside of any flash buffer and will be sent to the currently active NCGM workstation. Line 12 plots the instructions stored in buffer 1 on all active workstations (only one in this case). Line 13 plots the instructions stored in buffer 2 on all active workstations. Line 14 terminates the picture in the metafile. Line 15 closes the WISS workstation and lines 16 through 18 deactivate and close the NCGM workstation and close GKS.

Color table settings are not stored in Gflash buffers. The color table in effect at the time of a GFLAS3 call will be inherited by the primitives in the buffer being inserted by GFLAS3.

There can be at most 100 segments created in a single job and the legal segment names run from 0 to 99 inclusive. It is not legal to call FRAME, or to clear a workstation, while a segment is open.

GFLAS4 is available only if you are using NCAR GKS. It uses a locally-defined GKS ESCAPE function that is unique to NCAR GKS.

Changing an NCGM filename

This section shows two ways to change the name of NCGM output files from the default value of "gmeta". The first way involves setting a UNIX environment variable that allows you to change the filename for the entire job. The second way is via a call to the GKS ESCAPE function GESC. This way allows for dynamically changing the NCGM name from within your Fortran code, a method that can be used to create several different metafiles from within the same job.

Code segment from fgke03.f

1       CHARACTER*80 FNAME,CDUM
2       CALL GOPKS (6,IDUM)
3       FNAME = 'META01'
4       CALL GESC(-1391,1,FNAME,1,1,CDUM)
5       CALL GOPWK (1, 2, 1)
6       CALL GACWK (1)
7       CALL GPM(1,.5,.5)
8       CALL FRAME
9       CALL GDAWK (1)
10      CALL GCLWK (1)
11      FNAME = 'META02'
12      CALL GESC(-1391,1,FNAME,1,1,CDUM)
13      CALL GOPWK (1, 2, 1)
14      CALL GACWK (1)
15      CALL GPM(1,.5,.75)
16      CALL FRAME
17      CALL GDAWK (1)
18      CALL GCLWK (1)
19      CALL GCLKS

Synopsis

      CALL GESC (FCTID, LIDR, IDR, MXODR, LODR, ODR)

Arguments

FCTID
Integer, Input---A function identifier specifying the requested activity. For changing the metafile name, this is "-1391".

LIDR
Integer, Input---Dimension of the IDR data record array.

IDR
Character*80 array, Input---An input data record. For calls to change a metafile name, IDR should be dimensioned as "1" and should contain the desired metafile name left justified with blank fill.

MXODR
Integer, Input---Maximum length of the ODR output data record array.

LODR
Integer, Input---Dimension of the ODR output data record array.

ODR
Character*80 array, Input---An output data record. For changing a metafile name, nothing is returned in ODR, so set MXODR and LODR to "1" and define ODR to be a CHARACTER*80 array dimensioned as "1".

Discussion

First, consider the example code in fgke03.f that shows how to create two metafiles with different names in the same job. After this, we will look at changing the NCGM name using a UNIX environment variable.

Line 1 of the fgke03.f code segment establishes two CHARACTER*80 variables used as the input and output data records for the GESC call. Line2 opens GKS and line 3 establishes the name for the first metafile. The specification of the metafile name must occur after GKS has been opened, but always before the NCGM workstation is opened. Line 4 informs NCAR GKS of the metafile name setting. Lines 5 and 6 open and activate an NCGM workstation. Line 7 plots a default marker in the center of the plot and line 8 terminates the picture. Lines 9 and 10 deactivate and close the NCGM file. This output NCGM has name "META01" and cannot now be changed. Lines 11 through 18 create a second metafile with name "META02". Line 19 closes GKS.

You can have only one NCGM workstation open at a time in NCAR Graphics, so it is not possible to simultaneously create two metafiles. Also, this call to GESC works only with NCAR GKS; the GESC function identifier is unique to NCAR Graphics and will not have a meaning in another GKS package.

If you do not need to create more than one NCGM file in a single job, then specifying the NCGM output file name via the UNIX environment variable NCARG_GKS_OUTPUT is easier than making the GESC call. Just set the NCARG_GKS_OUTPUT environment variable to the name you desire. This method also has the advantage of allowing you to specify different names without having to make any code changes. Also, there are a couple of special settings for NCARG_GKS_OUTPUT that may be of use to you. One is the setting of "|ctrans". To make this setting in the C-shell, issue the command:

setenv NCARG_GKS_OUTPUT "|ctrans"

This has the effect of piping the output CGM to the CGM interpreter ctrans without creating the metafile in one job step and then invoking ctrans in an another job step.

Another special setting of NCARG_GKS_OUTPUT is "|". This pipes the metafile output to a default CGM interpreter whose name is specified in the code wks.h.sed that is contained in the GKS code that is distributed with the NCAR Graphics package. In the default case, "|" is the same as "|ctrans".

When using either of these special settings for NCARG_GKS_OUTPUT, you will need to make sure that your graphcap setting for ctrans is what you want. This can be done by setting the UNIX environment variable GRAPHCAP appropriately.

Any setting for NCARG_GKS_OUTPUT takes precedence over any settings of metafile output names via the GESC calls.

Putting it all together

This module illustrates many of the concepts in this section with an example code. The example manipulates several workstations in the course of the execution and shows how you must be careful to consider the state of each workstation independently.

Code for fgke04.f

1          PROGRAM TEST
2       C
3       C Illustrate workstation control functions by intermixing plotting to
4       C a metafile with plotting to X window workstations.
5       C
6       C
7       C Open GKS
8       C
9          CALL GOPKS(6,0)
10      C
11      C Open a CGM workstation and define color index 6 as red on that
12      C workstation.
13      C
14         CALL GOPWK(1,2,1)
15         CALL GSCR(1,6,1.,0.,0.)
16      C
17      C Set character height and set the text alignment to (center, half).
18      C
19         CALL GSCHH(.04)
20         CALL GSTXAL(2,3)
21      C
22      C Activate the CGM workstation.
23      C
24         CALL GACWK(1)
25      C
26      C Create picture 1 in the metafile and call FRAME to terminate 
27      C the first picture.
28      C
29         CALL GSTXCI(6)
30         CALL GTX(.5,.5,'Picture 1')
31         CALL FRAME
32      C
33      C Put another picture in the metafile.
34      C
35         CALL GTX(.5,.5,'Picture 2')
36         CALL FRAME
37      C
38      C Open and activate an X11 workstation and define color index 6
39      C to be cyan on that workstation (this workstation will be referred 
40      C to as "The first window".
41      C
42         CALL GOPWK(5,0,8)
43         CALL GACWK(5)
44         CALL GSCR(5,6,0.,1.,1.)
45      C
46      C Create picture 3. This will be plotted to the CGM workstation as
47      C well as to the X11 window since they are both active.
48      C
49         CALL GTX(.5,.5,'Picture 3')
50      C
51      C Terminate the metafile picture.
52      C
53         CALL NGPICT(1,1)
54      C
55      C Pause in the X window with a "<READY>" prompt and wait for a 
56      C mouse click. The window will be cleared after the mouse click.
57      C
58         CALL NGPICT(5,4)
59      C
60      C Open and activate another X workstation (to be referred to as "The
61      C second window") and define color index 6 to be green on that 
62      C workstation.
63      C
64         CALL GOPWK(7,0,8)
65         CALL GACWK(7)
66         CALL GSCR(7,6,0.,1.,0.)
67      C
68      C Plot picture 4. This will be sent to the CGM workstation and the
69      C two X window workstations since they are all active.
70      C
71         CALL GTX(.5,.5,'Picture 4')
72      C
73      C Terminate picture 4 in the metafile.
74      C
75         CALL NGPICT(1,1)
76      C
77      C Make the second window current.
78      C
79         CALL NGPICT(7,0)
80      C
81      C Pause in the first window with a "<READY>" prompt and wait for a
82      C mouse click. The window will be cleared after the click.
83      C
84         CALL NGPICT(5,4)
85      C
86      C Clear the second window.
87      C
88         CALL NGPICT(7,1)
89      C
90      C Deactivate the metafile (but do not close it) and draw picture 5.
91      C This will go to the two active X11 workstations, but not the CGM.
92      C
93         CALL GDAWK(1)
94         CALL GTX(.5,.5,'Picture 5')
95      C
96      C Make the second window current.
97      C
98         CALL NGPICT(7,0)
99      C
100     C Pause in the first window waiting or a mouse click.
101     C
102        CALL NGPICT(5,4)
103     C
104     C Re-activate the metafile and deactivate the second window.
105     C
106        CALL GACWK(1)
107        CALL GDAWK(7)
108     C
109     C Plot picture 6. This will go to the first window and to the
110     C metafile.
111     C
112        CALL GTX(.5,.5,'Picture 6')
113     C
114     C Terminate the picture in the CGM.
115     C
116        CALL NGPICT(1,1)
117     C
118     C Pause in the first window waiting for a mouse click.
119     C
120        CALL NGPICT(5,4)
121     
122     C Reactivate the second window and clear it.
123     C
124        CALL GACWK(7)
125        CALL NGPICT(7,1)
126     C
127     C Put out picture 7. This will go to the all active workstations.
128     C
129        CALL GTX(.5,.5,'Picture 7')
130     C
131     C Terminate the picture in the CGM.
132     C
133        CALL NGPICT(1,1)
134     C
135     C Make the first window current.
136     C
137        CALL NGPICT(5,0)
138     C
139     C Pause in the second window waiting for a mouse click.
140     C
141        CALL NGPICT(7,4)
142     C
143     C Deactivate and close the first window; deactivate and close the CGM.
144     C 
145        CALL GDAWK(5)
146        CALL GDAWK(1)
147        CALL GCLWK(5)
148        CALL GCLWK(1)
149     C
150     C Put out picture 8. This will go to the second window, the only 
151     C active workstation.
152     C
153        CALL GTX(.5,.5,'Picture 8')
154     C
155     C Pause in the second window with a "<READY>" prompt.
156     C
157        CALL NGPICT(7,4)
158     C
159     C Deactivate and close the second window.
160     C
161        CALL GDAWK(7)
162        CALL GCLWK(7)
163     C
164     C Close GKS.
165     C
166        CALL GCLKS
167     C
168        STOP
169        END

Discussion

Line 9 of the fgke04.f code segment opens GKS. Standard output is specified for the error file.

Line 14 opens an NCGM workstation. The NCGM workstation is given the identifier "1" and it uses "2" as the connection identifier.

Line 15 associates the color red with color index 6 on the NCGM workstation; this association has no bearing on how color indices are defined on other workstations. Note that the NCGM workstation does not have to be active to define color values for it.

Lines 19 and 20 establish some text attributes for drawing subsequent text strings. Notice that no workstations need to be active to make these calls; they will remain in effect for all subsequent calls, since they are never changed.

Line 29 sets color index 6 as the text color. Color index 6 may mean different things for different workstations.

Line 30 draws the text string 'Picture 1'. This will be sent to the only active workstation, which is the NCGM workstation.

Line 31 calls FRAME to terminate the first picture in the metafile. This call to FRAME is the equivalent of making the two calls GUWK(1,0) and GCLRWK(1,1).

Lines 35 and 36 plot another picture to the NCGM file.

Line 42 opens an X11 workstation. After this call has been executed, a window should appear on your X window workstation. You will need to position this window where you want it and then click on it.

Line 43 activates the new window. This window will now receive all GKS output primitives until it is deactivated.

Line 44 associates color index 6 with the color cyan on the X11 window. Notice that this setting for color index 6 is different from the setting for the same index on the NCGM workstation.

Line 49 plots another text string. This will be sent to the two active workstations. The string will be red in the NCGM and will be cyan in the X11 window.

Line 53 terminates picture 3 in the NCGM. NGPICT will be used to control the actions on each individual workstation from now on. If we were to have called FRAME here, FRAME would first update all open workstations (this means that the NCGM and the first window would be updated) and then FRAME would pause in the window of most recent creation waiting for a mouse click. This means that FRAME would be waiting in the X11 window for mouse input. However, after the call to NGPICT in line 53, the NCGM is updated and cleared, but the X11 window is not necessarily even current.

The NCPICT call in line 58 makes the X11 window current and pauses in that window waiting for a mouse click. A "<READY>" prompt appears in the lower left part of the screen, indicating that the window is waiting for a click. If we were to have called FRAME, this prompt would not appear, although we would still be waiting for a mouse click in that window. After the mouse input is supplied, the window will be cleared, since we have called NGPICT with a second argument of "4".

Lines 64 and 65 of the fgke04.f code segment open and activate a second X11 window. There are now three simultaneously active workstations, the NCGM workstation and the two X11 windows. The second X11 window has identifier number 7.

Line 67 associates the color green with color index 6 on the second X11 window. This association applies only to this workstation and is different from the setting of this index for the other two currently active workstations.

Line 71 plots another text string. This will be sent to all three currently active workstations.

Line 75 terminates the picture in the NCGM. This call updates the workstation and clears it. (Remember that a clear workstation on a NCGM terminates the current picture.)

Line 79 brings the second window up to date.

Line 84 makes the first window current and pauses in the window with a "<READY>" prompt, indicating input is being awaited. It was important to bring the second window up to date before executing the pause in the first window, since otherwise that window might not reflect all graphics requests made to it. In this case, it is possible that the text string 'Picture 4' would not be in the second window unless it had been updated. If we had called FRAME in line 79, all workstations would have been updated and we would be paused in the second window (the window of most recent creation) instead of being paused in the first window as we are. Also, there would be no prompt in the window indicating it is waiting for input. It is for these reasons that using NGPICT can be helpful, although using FRAME can certainly make coding easier if you can keep in mind exactly what it is doing.

Line 88 clears the second window. Without this, the next output primitives would overwrite what is currently there.

Line 93 deactivates the NCGM workstation. This means that output primitives will not be sent to it until it is reactivated. At this point, we have two active workstations, the two X windows.

Line 94 plots another text string. This will appear in the two active X windows.

Line 98 brings the second window up to date and line 102 brings the first window up to date and causes a pause with a prompt.

Line 106 reactivates the NCGM workstation. Line 107 deactivates the second X window. There are now two active workstations: the first X window and the NCGM. Deactivating the second X window means that it will not receive output primitives until reactivated. The window still stays on the screen in the state it was in at the time it was deactivated.

Line 112 plots another text string. It is sent to the two active workstations, but not to the inactive first window, which continues to display what was on it.

Line 116 terminates the picture in the NCGM and line 120 causes a pause in the currently active X window (the first window).

Line 124 of the fgke04.f code segment reactivates the second X11 workstation; line 125 clears it. All three workstations are now active again.

Line 129 plots another text string. This will be sent to all workstations.

Line 133 terminates the picture in the NCGM.

Line 137 brings the first window up to date.

Line 141 causes a pause in the second window with a "<READY>" prompt, indicating that window is waiting for input. Notice that we have now switched the window wanting input. Previously, we were using the first window for pausing. Now it is necessary to click in the second window to continue execution and only the second window will be automatically cleared after the pause.

Lines 145 through 148 deactivate and close the NCGM workstation and the first X window. The closing of the NCGM makes that file complete. It cannot be changed after the close. The close of the first X window causes it to disappear from the screen. No further commands can be issued to that window.

Line 153 plots one final text string. It will be sent to the only currently active window.

Line 157 causes a pause in the currently active window with a "<READY>" prompt.

Lines 161 and 162 deactivate and close the final workstation. It disappears from the screen.

Line 166 closes GKS.

After the execution of this job, the NCGM will contain six pictures, the ones numbered 1, 2, 3, 4, 6, and 7. All pictures in the CGM will be red.

During the execution of this job the first X11 window will have plotted five pictures, the ones numbered 3, 4, 5, 6, and 7. All pictures in the first X11 window will be cyan.

During the execution of this job, the second X11 window will have plotted four pictures, the ones numbered 4, 5, 7, and 8. All pictures in the second X11 window will be green.

Previous Chapter          LLUs Home          Next Chapter          Index