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.
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.
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.
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.
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 */
);
-------------------------------------------------------------------------------
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
);
--------------------------------------------------------------------------
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 */
);
-------------------------------------------------------------------------------
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 */
);
-------------------------------------------------------------------------------
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