Previous Chapter LLUs Home Next Chapter IndexNCAR 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.
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.
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)
CALL GOPKS (ERRFIL, BUFA)
CALL GOPWK (WKID, CONID, WKTYPE)
CALL GACWK (WKID)
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.
GDAWK deactivates a workstation, GCLWK closes a workstation, and GCLKS closes GKS.
1 CALL GDAWK(1) 2 CALL GDAWK(2) 3 CALL GCLWK(1) 4 CALL GCLWK(2) 5 CALL GCLKS
CALL GDAWK (WKID)
CALL GCLWK (WKID)
CALL GCLKS
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.
CALL GUWK (WKID, REGFL)
CALL PLOTIF (X, Y, IPEN)
CALL SFLUSH
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.
CALL GCLRWK (WKID, COFL)
CALL FRAME
CALL NGPICT (WKID, ACTION)
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.
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.
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
CALL GFLAS1 (IB)
CALL GFLAS2
CALL GFLAS3 (IB)
CALL GFLAS4 (IB, 'buf_name')
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.
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
CALL GESC (FCTID, LIDR, IDR, MXODR, LODR, ODR)
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.
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
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