Previous chapter LLUs Home Next chapter IndexBefore 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 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.
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
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 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."
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 filenamewhere 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.
C Close Frame 15 CALL FRAME
C Deactivate workstation, close workstation, and close GKS. 16 CALL GDAWK (1) 17 CALL GCLWK (1) 18 CALL GCLKSFor 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."
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_gtxpacFor 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