Workstation Functions


Although the NCAR GKS package is a full implementation of the GKS standard at level 0A, only a subset of the functions it contains is commonly used. This documentation module describes the Fortran and C bindings of this subset. It is strictly at the user's discretion which binding to use. In documention the GKS functions, the Fortran binding name will be used in general. In the descriptions of the user entry points in the Fortran and C bindings, the Fortran interface is fully described and a brief synopsis of the C interface is presented. For a full understanding of the GKS standard, or more thorough discussions, consult the references in Appendix E. All of the references cited are available in the NCAR book libraries. The routines described in this section have been grouped according to the order they might appear in a typical GKS application.

Definition of a GKS Workstation

GKS is based on the concept of an abstract graphical workstation. Such a workstation is conceptualized as a rectangular display space of fixed dimension being capable of drawing lines, text, markers, and filled polygons. The connection between the abstract GKS workstations and physical devices is made using the GKS function GOPWK described below.

Workstation Types

Each GKS workstation has a type. Different GKS implementations will support different workstation types. In NCAR GKS, a workstation of type 1 is a private binary encoding conforming to the ANSI Computer Graphics Metafile ( CGM ) Standard. SCD provides filters, ncgm2cgm and cgm2ncgm, for converting from the NCAR private encoding of the CGM to and from a generic binary encoding. SCD also supplies a CGM interpreter, ctrans, with NCAR Graphics that converts CGM files and plots them on many devices. For information on the filters or ctrans, consult the appropriate man page. See Viewing and editing your CGMs and raster images for details on CGM conversion and supported output devices.

In NCAR GKS, a workstation of type 3 is a WISS (Workstation Independent Segment Storage) workstation used for storing picture segments. Workstations of types 7 and 8 are X11 workstations. Workstations of type 10 are ASCII text dumps of graphics instructions. Workstations of types 20-31 are PostScript output workstations.

Workstation Categories

Each GKS workstation type has a unique category that must be one of:
OUTPUT
Output only
INPUT
Input only
OUTIN
Both output and input
WISS
Workstation independent segment storage (storage for parts of a plot)
MO
Metafile output
MI
Metafile input
For NCAR GKS, workstations of type 1 (CGM) are MO workstations. A workstation of type 3 is of category WISS. The only thing you need to know about a WISS workstation (GKS allows only one workstation of category WISS) is that it can be used to store picture segments. WISS is not officially part of GKS at level 0A, but it has been added to NCAR GKS in order to support the Gflash package. For details on Gflash, see NCAR Graphics Fundamentals, UNIX Version and the SCD UserDoc GFLASH - A Graphics Instruction and Manipulation Package. Workstations of type 7 and 8 are of category OUTIN and workstations of types 10 and 20-31 are of category MO.

For more details on GKS workstations, see What you need to know about GKS workstations.

Open and Close GKS

Opening GKS, opening and activating workstations

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.

The call to open GKS is GOPKS. The call to open a workstation is GOPWK. The call to activate a workstation is GACWK.

The following calls are usually the first GKS calls to appear in a GKS program:

-------------------------------------------------------
           Argument  |  Type   | Mode  | Dimension
-------------------------------------------------------
CALL GOPKS (ERFILE,  | Integer | Input |          
            BUFA)    | Integer | Input |          
-------------------------------------------------------
CALL GOPWK (WKID,    | Integer | Input |          
            CONID,   | Integer | Input |          
            WKTYPE)  | Integer | Input |          
-------------------------------------------------------
CALL GACWK (WKID)    | Integer | Input |          
-------------------------------------------------------
The arguments for the above subroutines are:
ERFILE
The Fortran unit number to which error messages will be written. Typically this will be unit 6 (standard output).
BUFA
The dimension of a dynamically managed internal buffer. In NCAR GKS, BUFA is ignored and most people simply specify a zero as its value.
WKID
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 positive integer.
CONID
A connection identifier that has different meanings for different workstation types (see WKTYPE below).
WKTYPE
An identifier specifying the type of output device targeted. Each GKS package has an implementation-dependent set of workstation types that the package supports. The workstation types supported in NCAR GKS follow. In NCAR GKS, workstation types 20-31 refer to PostScript output. The connection ID is irrelevant for the PostScript output workstations. For complete details on the PostScript workstation types, see the PostScript Output module.
1 -- CGM.
The output device will be a metafile whose default name is "gmeta". See the module "Changing a CGM filename" in NCAR Graphics Fundamentals to see how to change metafile output names. Also, Appendix A. discusses how to obtain a copy of the example code number 21 that shows how to create two metafiles with different, non-default, names from the same job. There can be at most one open workstation of type 1 at any time. For workstations of type 1, the connection ID is the Fortran logical unit number to be used for the writes to the metafile.
3 -- WISS
This stands for "Workstation Independent Segment Storage" and should be opened (using GOPWK) before storing graphics in segments. See GFLASH - A Graphics Instruction and Manipulation Package. for more details. For workstations of type 3, the connection ID is the Fortran logical unit number to be used for the writes to the metfile. It is permissible to have workstations of types 1 and 3 open simultaneously, but they must have different connection identifiers.
7 -- Pre-existing X11 window
Directs graphics output to a pre-existing X11 window. The X11 window ID should be be specified as connection ID in the GOPWK call.
8 -- New X11 window.
A new X11 window will appear on your screen when this call is executed. The connection ID is irrelevant for workstations of type 8.
10 -- Text dump of graphics output.
Writes a human-readable ASCII dump of the output. Since output is directed to standard out, the connection identifier is irrelevant for workstations of type 10.
20 -- Color PostScript, portrait mode.
21 -- Color Encapsulated PostScript (EPS), portrait mode.
22 -- Color Encapuslated PostScript Interchange (EPSI) format, portrait mode.
23 -- Monochrome PostScript, portrait mode.
24 -- Monochrome Encapsulated PostScript (EPS), portrait mode.
25 -- Monochrome Encapuslated PostScript Interchange (EPSI) format, portrait mode.
26 -- Color PostScript output in landscape mode.
27 -- Color Encapsulated PostScript (EPS), landscape mode.
28 -- Color Encapuslated PostScript Interchange (EPSI) format,
29 -- Monochrome PostScript output in landscape mode.
30 -- Monochrome Encapsulated PostScript (EPS), landscape mode.
31 -- Monochrome Encapuslated PostScript Interchange (EPSI) format, landscape.
Errors:
1, 8, 20, 21, 22, 23, 24, 25, 26, 29, 33, 35
-------------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gopen_gks( 
               const char  *err_file,  /*   name of error file     */  
               size_t      mem_unit    /*   units of memory        */  
);

void gopen_ws(
               Gint        ws_id,      /*  workstation identifier  */
               const char  *conn_id,   /*  connection identifier   */
               Gint        ws_type     /*  workstation type        */  
);

void gactivate_ws(
               Gint        ws_id       /*  workstation identifier  */  
);

-------------------------------------------------------------------------------

Closing GKS, deactivating and closing workstations

Three GKS calls are required to gracefully exit GKS. They deactivate the workstations (GDAWK), close the workstations (GCLWK), and close the GKS package (GCLKS).

--------------------------------------------------------
           Argument |  Type   |  Mode |  Dimension  
--------------------------------------------------------
CALL GDAWK (WKID)   | Integer | Input |             
CALL GCLWK (WKID)   | Integer | Input |             
CALL GCLKS          |         |       |             
--------------------------------------------------------

The argument for the above subroutines is:

WKID
The WKID identifier must be the same as that used in the opening sets of calls.
Errors:
2, 3, 7, 20, 25, 29, 30, 33, 35

--------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gdeactivate_ws(
                Gint  ws_id  /*   workstation identifier  */  
);                                                                          
void gclose_ws(
                Gint  ws_id  /*  workstation identifier   */  
);                                                                          
void gclose_gks(
                void                                          
);                                                                          
--------------------------------------------------------------------------

Updating a Workstation

For the sake of efficiency, NCAR GKS maintains output buffers for all of its workstations. Unless these buffers are flushed, the current state of the picture may not reflect all graphics instructions that have been issued to a workstation. To ensure that a workstation is current with regard to the GKS buffers one needs to update that workstation. Other buffers are maintained in the higher levels of NCAR Graphics that may need to be flushed if you are making NCAR Graphics calls in addition to GKS calls. For more details on how to insure that all graphics instructions are flushed, see the section "Making sure things are current" in the NCAR Graphics Fundamentals module.
------------------------------------------------------
          Argument |   Type  |  Mode  |   Dimension  
------------------------------------------------------
CALL GUWK (WKID,   | Integer | Input  |            
           REGFL)  | Integer | Input  |           
------------------------------------------------------
The arguments for the above subroutines are:
WKID
A number identifying the workstation to be updated. WKID must be the same as that used in some previous call to GOPWK.
REGFL
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 Graphics, this flag should always be set to 1.
-------------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gupd_ws(
             Gint             ws_id,          /*   workstation identifier   */
             Gupd_regen_flag  upd_regen_flag  /*  update regeneration flag  */
);                                                                                               
-------------------------------------------------------------------------------

Clearing a Workstation

In order to clear a workstation plotting surface use:

--------------------------------------------------------
            Argument |  Type   |  Mode  |  Dimension  
--------------------------------------------------------
CALL GCLRWK (WKID,   | Integer |  Input |             
             COFL)   | Integer |  Input |             
--------------------------------------------------------
The arguments for the above subroutine are:
WKID
A number identifying a workstation to be cleared. This number must be the same as that used in some previous call to GOPWK.
COFL
Clear the workstation display surface. Options are:
0 - Check if the display has been written. If not, do not issue a clear surface command.
1 - Issue a clear surface command whether the surface has been written to or not.

For CGM generation, GCLRWK is interpreted as a picture termination. If COFL=0 and no output primitives have been called in the current picture, then a call to GCLRWK is a "do nothing"; otherwise, it generates an END PICTURE as well as a BEGIN PICTURE element (as well as other picture initializing elements). If COFL=1, then a call to GCLRWK generates an END PICTURE and a BEGIN PICTURE.

For X11 windows, clearing a workstation erases all graphics primitives that appear on the screen in the specified window; for PostScript workstations a clear workstation will terminate the current picture (by inserting a "showpage" operator).
Errors:
6, 20, 25, 33, 35
-------------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gclear_ws(
               Gint        ws_id,     /*   workstation identifier  */  
               Gctrl_flag  ctrl_flag  /*  control flag             */  
);
-------------------------------------------------------------------------------

Inquiry Functions

Get the Open Status of GKS

GKS maintains an internal status flag to indicate what state it is in with regard to workstation activity. A call to GQOPS can be made to determine this status:

-----------------------------------------------------
           Argument |  Type   |  Mode  |  Dimension  
-----------------------------------------------------
CALL GQOPS (OPSTA)  | Integer | Output |            
-----------------------------------------------------
The argument for the above subroutine is:
OPSTA
Returns GKS, workstation, and segment status as per:
0 - GKS is closed
1 - GKS is open
2 - at least one workstation is open
3 - at least one workstation is active
4 - a segment is open
Default:
none
Errors:
none

---------------------------------------------------------------------------
C Synopsis
                                                                             
#include <ncarg/gks.h>

void ginq_op_st(
                Gop_st  *op_st  /*  operating state value  */  
);                                                                           
---------------------------------------------------------------------------


Links: GKS Index, GKS Home