Introduction to NCAR GKS


What is GKS?

GKS (the Graphical Kernel System) is an ANSI and ISO standard. GKS standardizes two-dimensional graphics functionality at a relatively low level. The primary purposes of the standard are: The GKS Standard (as described in the actual standard document: Computer Graphics - Graphical Kernel System (GKS) Functional Description, ANSI X3.124-1985) consists of three basic parts:

  1. An informal exposition of the contents of the standard which includes such things as how text is positioned, how polygonal areas are to be filled, and so forth.
  2. A formalization of the expository material in 1. by way of abstracting the ideas into discrete functional descriptions. These functional descriptions contain such information as descriptions of input and output parameters, precise descriptions of the effect each function should have, references into the expository material in 1., and a description of error conditions. The functional descriptions in this section are language independent.
  3. Language bindings. These bindings are an implementation of the abstract functions described in 2. in a specific computer language such as Fortran or Ada or C.
GKS stratifies its functionality into twelve functional levels, depending on the complexity of the graphical input and output. There are four levels of output (m, 0, 1, 2) and three levels of input (A, B, C). NCAR GKS contains a full implementation of the GKS Fortran and C bindings at level 0A.

Figure 1 - A plot generated with a GKS program

NCAR Graphics and GKS

NCAR Graphics is designed to facilitate organizing large amounts of numerical data and producing concise visual representations of those data. With the release of Version 4.0 of NCAR Graphics there are three programming interfaces to the NCAR Graphics package: NCL ( NCAR Command Language); Fortran; and C. The programming interfaces provide access to complex graphics utilities like contouring, world map projections, and velocity vectors. For the most part, the C interface is built on top of the Fortran interface.

The complex utilities of the NCAR Graphics package sit on top of GKS-0A. This level of GKS affords more than the minimum level (level m) of output functions, but allows for no graphical input; it cannot, for example, be used to read a point off your screen, but you can output almost any 2D picture to your screen. The NCAR Graphics Low Level Utilities (LLUs) can use the NCAR GKS package that is distributed with the package, or any other GKS package at level 0A or higher. It is possible to use NCAR Graphics without having but a brief knowledge of GKS. However, if you intend to use features of GKS directly, you will need to know more about GKS. In NCAR Graphics version 4.0 and later, direct GKS calls are viewed as LLU calls. For details on mixing LLUs with the HLUs, see the module Mixing HLUs and LLUs. For a discussion of the pros and cons of using LLUs versus the High Level Utilities (HLUs), consult the module HLUs vs. LLUs.

The GKS Documentation Modules

The NCAR GKS documentation modules (of which you are currently reading the "Introduction" module) are all accessible from the " GKS Home Page " module. The NCAR GKS documentation modules contain some site-specific details of NCAR's implementation of GKS-0A. The modules are meant to be used in conjunction with the other on-line documentation for NCAR Graphics. For the purposes of explication, as well as for historical reasons, the NCAR GKS documentation modules focus most heavily on the Fortran binding, although complete details on the C binding are presented.

Described in the NCAR GKS documentation modules are the most commonly used GKS functions of the NCAR Graphics package. GKS at level 0A contains 117 standardized Fortran user entry points and only about half of those are described. If you would like a full understanding of the GKS standard, or more thorough discussions, you should consult the references in Appendix E. All of the references cited are available in the NCAR book libraries.

GKS Output Primitives

GKS at level 0A standardizes a reasonably complete set of functions for displaying 2D images. Users of pre-GKS versions of NCAR Graphics will recognize GKS at level 0A as being a functional extension of what was called the NCAR System Plot Package ( NSPP ), although with a significantly different user interface. (NSPP contained lower-level graphics calls and was written at NCAR. It did not adhere to any graphics standard and was replaced with GKS in the mid 1980s.) At level 0A, GKS contains functions for drawing lines, markers, filled areas, text, and a function for representing rasterlike images in a device-independent manner. In addition to these basic functions, GKS contains many functions for changing the appearance of the output primitives, such as changing colors, changing line thicknesses, changing marker types and sizes, etc. The functions for changing the appearance of the fundamental drawing functions (output primitives) are called attribute setting functions.

Here is a brief description of the output primitives and their attribute functions. A utility function (that is not part of the GKS Standard) that can be used to save, restore, or set all attribute values in a single call is described in the documentation for NGSRAT. Detailed descriptions of these functions appear in the Output Primitives module.

Polylines

The GKS function for drawing line segments is called polyline. The polyline function takes an array of X-Y coordinates and draws line segments connecting them. The attributes that control the appearance of a polyline are:

Polymarkers

The GKS polymarker function allows you to draw marker symbols centered at coordinate points that you specify. The attributes that control the appearance of polymarkers are:

Text

The GKS text function allows you to draw a text string at a specified coordinate position. The attributes that control the appearance of text are:

Fill Area

The GKS fill area function allows you to specify a polygonal shape of an area to be filled with various interior styles. The attributes that control the appearance of fill areas are:

Cell Array

The GKS cell array function displays rasterlike images in a device-independent manner. The cell array function takes the two corner points of a rectangle that you specify, a number of divisions (M) in the X direction and a number of divisions (N) in the Y direction. It then partitions the rectangle into M x N subrectangles called cells. You assign each cell a color and create the final cell array by coloring each individual cell with its assigned color. At level 0A, cell array has no associated attributes.

Figure 2 - example illustrating the GKS output primitives.

Inquiry Functions

GKS provides a set of inquiry functions that return the current values of GKS variables. Included are variables related to GKS operating states, workstation status, transformations, output attributes, and others. For example, you can inquire about the current value of any GKS output attribute such as the fill area style index, polyline color, polymarker type, and so forth.

Inquiry functions are useful when it is desired to isolate a code so that it can work independently from attribute settings elsewhere. In this case, you can inquire about the value of a variable, save this value, set the value to what the immediate code requires, then reset it to the original value before exiting. In this way, one module will not change the values of variables which are assumed by another module.

Figure 3 - results of code using inquiry functions to isolate drawing text.

GKS Errors

Calls to non-inquiry GKS functions can generate errors. When an error is encountered in such a non-inquiry function, GKS enters an error state, an error handler is called to print the error message, GKS exits the error state, and control is passed back to the calling program. The error handler can be replaced by a user-supplied function, but that is an advanced topic that will not be discussed in the GKS documentation modules. For details on the error handler, consult one of the references in Appendix E.

The inquiry functions of GKS are designed in such a way that the inquiry call will not itself generate an error condition, that is to say GKS never enters an error state and nothing is printed. If the parameter values requested are not available (they do not exist for some reason), an output error indicator is passed back in one of the arguments of the inquiry function. This error parameter indicates whether or not the returned values are valid. If all values are available, the error indicator value is zero. If all state variable values are not available, the error indicator returns an error number which identifies the GKS error condition. These numbers are the same as those used for non-inquiry functions.

An error message list appears in Appendix D.


Links: GKS Index, GKS Home