Chapter 3: Writing a graphics program

  Previous chapter          LLUs Home          Next chapter          Index

Before we can talk about the structure of a graphics program, we need to discuss the structure of NCAR Graphics. Once you understand the structure of NCAR Graphics, we will discuss writing a program in Fortran. Finally we'll show you how to apply those concepts to a C program.

The structure of NCAR Graphics

The NCAR Graphics utilities are built in layers, the lowest of which is GKS. GKS is a specification of how to implement basic functions for computer graphics programming, such as points, lines, text, fill areas, and portable raster images. The GKS standard has been adopted by both ANSI and ISO, and can be implemented at one of 12 levels, depending on graphical input and output capabilities. NCAR has implemented the 0A level, and a few extensions from the 2B level. The GKS standard also specifies the Fortran and C interfaces for its graphics functionality. Because GKS is a standard, and all NCAR Graphics utilities rely on GKS to do the plotting, you can run NCAR Graphics with GKS packages from other vendors, or with the GKS package included in NCAR Graphics.

GKS is not invisible in NCAR Graphics. Things like setting up color tables and doing solid color fill are best done using GKS, so you will call GKS routines directly.

The next layer of NCAR Graphics is the SPPS utility. This utility was designed to do some of the things that GKS does with fewer calls. Other utilities, such as Conpack, Autograph, and Ezmap, frequently rely on you to make the right GKS and SPPS calls to work correctly. In Version 3.2, these other utilities are the highest layer of NCAR Graphics, and will do the most work with the fewest number of calls. In general, knowing which utility a particular routine belongs to is only necessary when you need to look up its documentation in one of the manuals. We've tried to alleviate this difficulty by listing routine names in the index.

Structure of a Fortran program

Every NCAR Graphics program has generally the same structure. Before you can do anything else, you must open GKS, and when you are finished plotting, you must close GKS. Once GKS is open, you, or the utility you are using, need to define a transformation between the user coordinate system (the coordinate system of your data), and the Normalized Device Coordinate (NDC) system. Then it is time to call the various routines needed to get your plot. When you are finished drawing a plot, you must close that plot or frame. Finally, you need to close GKS. In summary, your program contains:

Calls for opening GKS and activating workstations

GKS settings

Normalization transformations

Graphics code

Calls for ending the plot or frame

Calls for deactivating workstations and closing GKS

Example graphics program

In the following example, we discuss a way to do each of these steps, and point you to the chapter of this guide where you can find more detailed information.

1      PARAMETER (M=21,N=25)
2      REAL U(M,N), V(M,N), WRK(2*M*N)
3      INTEGER IDM
   C Generate some data.
4      CALL MKDAT(U,V,M,N)
   C Open GKS, open NCGM type workstation, activate workstation.
5      CALL GOPKS (6,IDUM)
6      CALL GOPWK (1, 2, 1)
7      CALL GACWK (1)
   C Select normalization transformation 0 (user coordinates are the
   C same as NDC coordinates), so that title is drawn at top of plot.
8      CALL GSELNT (0)
   C Call PLCHLQ to write the plot title.
9      CALL PLCHLQ (.5,.9765,'Example Streamlines Plot',16.,1 0.,0.)
   C Define normalization transformation 1, and set up linear scaling.
10     CALL SET(0.1, 0.9, 0.1, 0.9,1.0, 21., 1.0, 25.,1)
   C Tell Streamlines that SET has been called, and
   C set spacing of stream lines.
11     CALL STSETI('SET---Set Call Flag', 0)
12     CALL STSETR('SSP---Stream Spacing', 0.015)
   C Initialize Streamlines, and draw stream lines
13     CALL STINIT(U,M,V,M,IDM,IDM,M,N,WRK,2*M*N)
14     CALL STREAM(U,V,IDM,IDM,IDM,WRK)
   C Close Frame
15     CALL FRAME
   C Deactivate workstation, close workstation, and close GKS.
16     CALL GDAWK (1)
17     CALL GCLWK (1)
18     CALL GCLKS

Opening GKS and activating workstations

There are three calls necessary to open GKS and activate a workstation: GOPKS to open GKS; GOPWK to open a GKS workstation, which for the NCAR Graphics GKS must be either an X window or an NCGM file; and GACWK to activate the workstation.

      CALL GOPKS (IER,ISZ)
      CALL GOPWK (ID,IC,IT)
      CALL GACWK (ID)

IER is the logical unit to receive GKS error messages, ISZ is a dummy variable, ID is a GKS workstation identifier, IC is a logical unit to receive the NCGM output, and IT is the workstation type. As shown in lines 5, 6, and 7 of the example code, we recommend that you set IER=6, ID=1, and IC=2 for NCGM output. IT must equal 1 to produce NCGM output. This does assume that you aren't using unit 2 elsewhere in your program for some other purpose.

   C Open GKS, open NCGM type workstation, activate workstation.
5      CALL GOPKS (6,IDUM)
6      CALL GOPWK (1, 2, 1)
7      CALL GACWK (1)

For complete discussions on opening and closing GKS, and on workstation types, please see Chapter 6 "What you need to know about GKS workstations."

GKS settings

GKS has numerous options that you can set using various GKS routines. Some of the most common options that you may need to set are values for a color table, line width and color, and the fill style for areas that you wnat to fill. The routines that do this are GSCR, GSLWSC, GSPLCI, and GSFAIS, respectively. Although we don't set any GKS options in this example, it is best to set up a color table right after activating your workstation. In other words, you would put your calls to GSCR right after line 7 in the example. Please refer to Chapter 7 "Color tables and color mapping systems" for more information on setting up color tables, Chapter 10 "Drawing lines and curves" for more information on setting line color and width options, and Chapter 13 "Area filling with GKS and Softfill" for more information on filling areas.

Normalization transformations (SET)

It is necessary to set up a transformation between the coordinate system of your data and the Normalized Device Coordinate (NDC) system before attempting to plot your data. The Normalized Device Coordinate system defines the lower left corner of your device to be (0.0, 0.0) and the upper right corner of the device to be (1.0, 1.0). All plots will be drawn in the largest square that can be defined on your device, unless you specify something smaller.

GKS also defines a coordinate system for your data called World Coordinates. This is a Cartesian coordinate system. Because many of our users require non-Cartesian options such as log scaling and mirror imaging, NCAR Graphics uses "user coordinates." These coordinates are the coordinates of your data, and can be ordered from largest value to smallest, smallest to largest, or put on a logarithmic scale. Since GKS does not offer a transformation between NDC coordinates and user coordinates, we recommend that you use the NCAR Graphics call SET to define the transformation.

SET has nine arguments. The first four are the left, right, bottom, and top of the viewport, or your graphics output device. Since these coordinates are in NDCs, they must be between 0.0 and 1.0. Also, the value for the right of the viewport must be larger than the value for the left of the viewport, and the value for the top of the viewport must be larger than the value for the bottom of the viewport. The next four arguments are the left, right, bottom, and top coordinates of your data. If you were plotting something like a pressure function on the Y axis, then you would simply set your largest value at the bottom, and your lowest value at the top. The final argument determines whether any log scaling will be done, as follows:


   C Select normalization transformation 0 (user coordinates are the
   C same as NDC coordinates), so that title is drawn at top of plot.
8      CALL GSELNT (0)
   C Call PLCHLQ to write the plot title.
9      CALL PLCHLQ (.5,.9765,'Example Streamlines Plot',16.,1 0.,0.)
   C Define normalization transformation 1, and set up linear scaling.
10      CALL SET(0.1, 0.9, 0.1, 0.9,1.0, 21., 1.0, 25.,1)

In line 8, we call GSELNT with a value of zero. This is a shortcut for calling SET as follows:

      CALL SET (0., 1., 0., 1., 0., 1., 0., 1., 1)

This sets the world coordinate system and the NDC system to be the same, and sets the viewport to be the largest square that your graphics output device can handle. It also sets log/linear scaling to be linear in both directions.

In this case, we use GSELNT so that we can draw our title, with line 9, in a known location on the plot, rather than figuring out where the title should go relative to the coordinates of our data.

In line 10, we draw our plot on a slightly smaller square (0.1, 0.9, 0.1, 0.9) than is allowed by GKS. This leaves us room in the viewport to put a title at the top of the plot. Our data have values in the X direction from 1.0 to 21.0, and values in the Y direction from 1.0 to 25.0, as we have defined in the second set of four arguments. Also, this is a linear coordinate system in both directions, so we have set the log scaling value to 1.

More complete discussions of coordinate systems, normalization transformations, and SET appear in Chapter 8 "Coordinate systems in NCAR Graphics," and in Appendix A "The Use of X/Y Coordinates in NCAR Graphics."

Graphics code

At this point, you need to decide what utility or utilities you plan to use to plot your data. Because all NCAR Graphics utilities will draw over what has already been drawn, it is usually necessary to draw and fill in background areas first and to draw text, points, and lines last.

Carefully check the utilities you plan to use. Many of them, especially the easy or do-it-all-in-one-call routines call SET and FRAME for you. If you are overlaying more than one utility, you need to make sure that the SET routine is called only by the first utility. Also, if you want to set parameters special to any utilities, it is generally best to do that before calling the routine that initializes, or initializes and draws for that utility.

   C Tell Streamlines that SET has been called, and
   C set spacing of stream lines.
11      CALL STSETI('SET---Set Call Flag', 0)
12      CALL STSETR('SSP---Stream Spacing', 0.015)
   C Initialize Streamlines, and draw stream lines
13      CALL STINIT(U,M,V,M,IDM,IDM,M,N,WRK,2*M*N)
14      CALL STREAM(U,V,IDM,IDM,IDM,WRK)

The example code illustrates many of these points. Line 11 tells Streamlines that SET has been called previously, and line 12 sets a parameter that controls the minimum distance between stream lines. We set the Streamlines parameters before initializing Streamlines in line 13. Line 14 draws the stream lines. If we wanted to draw stream lines over a color-filled contour plot, it would be best to call STREAM after the last call to draw the contours.

An easy way to figure out which routines you need to plot your data is to look through Appendix D "Pictorial index to ncargex" and find a plot that looks like what you want to do. Then, in the directory where you want to work, execute:

ncargex filename

where filename is the name printed under the plot of your choice in Appendix D. ncargex will put several files in your current working directory. The file filename.f will contain the graphics program to draw that plot. To help you make the modifications you need to plot your data, see the tutorial chapters of this guide, the NCAR Graphics Contouring and Mapping Tutorial, and the man pages.

Ending the plot or frame

There are two ways to end a plot or a frame so that you can either draw another plot in the same program, or so that you can quit. The easiest way is to call the SPPS routine FRAME. As mentioned above, some of the do-it-all-in-one-call routines will call FRAME for you. We called FRAME in line 15 of the example. Depending on your workstation type, FRAME will do different things. Please see Chapter 6 "What you need to know about GKS workstations" for more information on ending a frame.

   C Close Frame
15      CALL FRAME

Deactivating workstations and closing GKS

Just as it took three routines to open GKS and activate a workstation, it takes three to deactivate a workstation and close GKS. GDAWK deactivates the workstation, GCLWK closes the workstation, and GCLKS closes GKS. The argument that GDAWK and GCLWK require is the workstation identifier, ID, above. It is important for you to make sure that you activate and deactivate the same workstation if you are only working with one workstation, and that you deactivate all workstations before closing GKS. Since we open workstation 1 in line 6, and activate it in line 7, we must deactivate workstation 1 in line 16, and close it in line 17.

   C Deactivate workstation, close workstation, and close GKS.
16      CALL GDAWK (1)
17      CALL GCLWK (1)
18      CALL GCLKS

For a complete discussion on opening and closing GKS, as well as workstation types, please see Chapter 6 "What you need to know about GKS workstations."

Writing a C program

Writing an NCAR Graphics program in C requires the same elements as writing an NCAR Graphics program in Fortran. Please study the first part of this chapter, "Structure of a Fortran program" for complete details about how to organize an NCAR Graphics program.

This section describes how to use the NCAR Graphics C-binding. The NCAR Graphics GKS C-binding adheres to the ISO/IEC standard, which specifies that the names for the C-bindings are more descriptive than the Fortran names. Hence, the C-binding for setting the color-fill index is gset_fill_colr_ind, and the Fortran binding, which can only be 6 characters long, is GSFACI. To get the name and usage of the C-binding, please see the man page for the corresponding Fortran routine or the ncarg_gks_cbind man page for a complete list of the supported GKS C-bindings. In an effort to make it easy to find the C-bindings for NCAR Graphics routines, all C-bindings for NCAR Graphics routines are of the form c_rname where rname is the Fortran name of the routine in lowercase.

The argument list of each GKS C-binding closely corresponds to the argument list of the Fortran routine, but in many cases, the arguments are represented in the form of a C structure. These structures are defined in the include file <ncarg/gks.h>. The argument list of each NCAR Graphics C-binding also closely corresponds to the argument list of the Fortran routine, except when arguments include character strings or multidimensional arrays.

The NCAR Graphics C-bindings are intended to be ANSI C compliant. To get the correct function prototypes you can include <ncarg/ncargC.h> and <ncarg/gks.h> in your program.

To compile your NCAR Graphics C program with the GKS C-bindings, use the application ncargcc. ncargcc will take care of loading in the necessary C/Fortran interface libraries as well as the NCAR Graphics C and Fortran libraries.

An example of a C program that calls some of the NCAR Graphics GKS C-bindings has been provided. To copy this C program into your directory, and then compile, link, and run it, type:

ncargex c_gtxpac

For more information on how to use the C-bindings for the NCAR Graphics utilities, please see ncarg_cbind(3NCARG) or the man page for any of the NCAR Graphics routines. If you intend to use the GKS C-bindings heavily, you may want to get a copy of the American National Standard's Computer Graphics---Graphical Kernel System (GKS)---Functional Description.

  Previous chapter          LLUs Home          Next chapter          Index