GraphiC Library |
0 - before initialization of GraphiCThese levels indicate the order in which the calls should be made; the lower a function's level, the earlier in the program it should be called. These levels should be used as guides so that parameter setting routines will be called before the outines that use those parameters.
1 - after initialization
2 - after the page layout and options have been defined<R>
3 - after the axes are defined
Each program containing GraphiC routines must be initialized and terminated using the routines bgnplot() and stopplot(). Generally each of these routines is called only once in the program.
Each GraphiC screen (a screen on the PC may contain several individual pictures) must also be initialized and terminated using the routines startplot() and endplot(), respectively. These obligatory routines put the color defaults, screen erasures, and other necessary information into the file containing the plot information.
We have provided a collection of sample programs to help you get started. These programs can be found in the chapter Example Programs. We always use one of the example programs as boiler plate for a new one.
To indicate functions that have changed or are new since the last version
of GraphiC, or that are obsolete, we use different color backgrounds for
the function name as follows:
| NormalFunction (void) |
|
|
| ChangedFunction (void) |
|
|
| ObsoleteFunction (void) |
|
|
The same color conventions are used for changed or for obsolete text
so that it will be easy for you to see.
An exception to this rule occurs in OS/2, a multithreaded environment. GraphiC/OS2 allows you to call GraphiC from different threads in your program, and in this case, each thread should have its own initialization/termination sequence.
In order to make simultaneous plots on one page, you need to call simuplot(num_of_plots) to specify the number of plots on a page. Then you call context() for each individual plot. You should make one call to page() for each context, and the area should be large enough to accommodate all of the subplots. Put this call in the first subplot.
The subplots are defined by calls to context(plot_number). The
first time context() is called for a subplot, there should be a
call to area2d() (if needed), and you should make all of the other
calls needed to set up the axes
before making another call to context().
Then, each time you want to plot data points in a subplot, make a call to context(plot_num) and thenmake your usual call to curve() or other plotting function.
When you complete all of the subplots, make a call to simuplot(0) and then a single call to endplot() and stopplot(). This call to simuplot(0) is essential in order to free all of GraphiC's internally allocated memory.
GraphiC uses a temporary file for each context's TKF data, and these are combined sequentially into the actual .TKF file when simuplot(0) is called. If you abort a GraphiC simultaneous plot without cleaning up via a call to simuplot(0), the temporary files will be left on your PC. The name and location of the temporary files depends on your compiler and the version of GraphiC. For example, with Microsoft C in DOS, the files are in the root directory and are called 1, 2, 3, . . .
The simultaneous plotting mechanism can also be used any time you need to plot graphs with different attributes on the same space. For example you can set up a plot with several x and y axes, then change among the coordinate systems as needed. The example MULTI_Y.C shows how this is done.
In GUI environments, the context feature can be used to have simultaneous plots running in separate windows within a single thread. Each window will have its own menus and if desired, a separate TKF file pointer. If you use separate TKF file pointers, you will be able to print each window individually. To use this feature, call NewFile() and GPCWINCreate() inside of each context definition. The window for the first context should be the window created by bgnplot().
GraphiC provides two types of axis routines:
The routines that make the decisions about the labels use floats (as opposed to doubles) to calculate the step sizes and the rounded values given to the labels. Because floating-point precision is used, the range of your data cannot be too small compared with the size of your data. For example, if your data values range from 1,000,000. to 1,000,001. and you are taking 5 steps, the step size would be .2. With floating-point precision this step size would be too small to show when printing the labels. IfUser-scaled routines allow you to have full control over all aspects of the axis tick marks and number formats. Self-scaling routines do most of the work for you, but you must present them with all of the data so that they can determine the proper scales and axis labels. Because GraphiC has a sophisticated algorithm to choose nice axis labels, it may change the number of axis divisions from the number you requested.
(max_value - min_value)/max_value < 0.00004then your data cannot be autoscaled.
If this situation exists you will get an error message to this effect and you will need to offset your data (by subtracting 1,000,000 in the above example). The same problem will occur using manual scaling [e.g., using graf()] since the above inequality also must pertain.
Another problem will arise if all the values are the same in one of
your axis arrays. (This can happen due to roundoff and precision problems.)
In this case, GraphiC will set the minimum value to the constant value
-1.0 and set the maximum value to the constant value + 1.0 A warning message
will also be placed in the file GRAPHIC.ERR.
In addition to drawing a contour plot in a plane of the 3-D workbox, you can draw contour plots as elevated or stacked contours. This can be done by establishing a 3-D workbox, calling plane3d(), and calling stack(1). This feature can be used to superimpose a contour plot on a 3-D surface. Stacked contours do not have hidden line removal activated.
The following method of specifying line styles and colors will handle
only the 16 basic IBM colors and is retained for compatibility purposes.
It will be eliminated in the next major revision of GraphiC. Instead, set
the lnstyle arrays to NULL and use a call to contcolor() before
calling the contour-plotting function.
| All of the contouring routines use an array of three-digit coded numbers
to set the line style and color for each contour ring. The first two digits
of the number are 10 + the color number. The
third digit is the line style number. For
example, 233 sets the color to 13 and the line style to 3:
(int)(233/10) - 10 = color 233 - ((color + 10)*10) = line style. |
GraphiC can also be used to create triangle plots. Triangle plots are a special kind of contour plot. They provide for the graphic display of an attribute of a three-component mixture. Each component is associated with a vertex. The fraction of that component is plotted on a line parallel to the opposite side. The position of the line is proportionally closer to the vertex depending on the relative amount of the component. Any two components determine the position of a point. GraphiC draws constant-value contours of the attribute.
The user has two options for triangle plots. You can specify a functional relationship between the attribute and two of the parameters or you can provide a table of values. The contours cannot be labeled automatically because of the mapping scheme used to generate them. They can, however, have different colors and/or line styles, which can be displayed and identified in a legend box.
Polar contour plots are created by setting up polar axes and making
a call to polar() before your call to any contour-plotting routines.
The x array in the contour plot corresponds to the radial direction
in polar coordinates, and
the y array corresponds to the angular direction in polar coordinates.
Setting z-values in a user-supplied matrix or in a function return value to a special value (called Not A Number, or NAN for short) will tell the contour plotter that data is missing, and contours will not be drawn through the cells so marked.
GraphiC allows you to define several types of NANs to allow you to represent
data values that are missing,
bad, or undefined. GraphiC ignores these values when doing contour
plots and 3-D surface plots. As a result, your data can be defined on a
non-rectangular domain.
The various types of defined NANs are shown in the listing of MISSINGS.H.
If you set data to NAN values, you must be sure that you do not compute
using the NAN values or else a run-time error will result. Since the NAN
macros are complicated, it is safest to test only simple variables to see
if they are NANs. An example of the use of NANs is given in the Introduction.
 |
| Triangle plots provide for the graphic display of an attribute of a three-component mixture. Each component is associated with a vertex. The fraction of that component is plotted on a line parallel to the opposite side. The position of the line is proportionally closer to the vertex depending on the relative amount of the component. Any two components determine the position of a point. This example is in the file TRITEST.C |
Because these routines use the GraphiC symbol() function, the colored patch can be represented by any of the GraphiC symbols, and these functions can be used with any of the two-dimensional axes (i.e., linear, logarithmic, polar, error function).
A subsequent call to ColorKeyL()
or ColorKeyN() should be used to plot
the color key legend as shown below. Depending upon where you wish to place
the legend, you might want to move the axes via a call to physor().
 |
| This example uses PlumePlotN() and ColorKeyN() to provide more resolution in the higher pollution areas. In this example, data exists with z < -2.2, and the maximum value is less than z = +2.2. The vector of color demarcation values was selected to yield even values for the color key labels. The code for this example is in PLUME.C. |
Begin by defining the three sides of a workbox in 3-D space using volm3d(),
thus determining the relative lengths
of the three axes. Only the ratios of these lengths are important.
Next, you must define the position of the viewer in the units of your workbox
[vuabs() or vuangl()]
or in user units [view()]. The view point
must be outside the workbox. Picking a viewpoint which is closer to the
plot will NOT make the plot larger; it will only increase the perspective
distortion unless you have called sclfix().
Finally, you must specify the variable ranges for the three axes. GraphiC does not have a self-scaling 3-D routine; instead, it rounds off the steps you specify to minimize the complication of the axis numbers. This process is done in graf3d().
Curves may be plotted in the 3-D space with curv3d(), and surfaces may be displayed with surfun(), surmat(), surmatc(), or surmat2c(). Hidden line removal will not work with curv3d(), or stacked contours.
Hidden line removal works by establishing upper and lower horizons for each pixel column. As a surface is being plotted, the horizons are updated so that for each column the upper horizon is set to the highest point of the surface and the lower horizon is set to the lowest. When the surface is finished, the horizons define the outline of the surface.
The 3-D surface-plotting routine can be restricted to a portion of the rectangular x-y plane by replacing the matrix values with NANs or returning a NAN from the surface-defining function. NANs are defined in MISSINGS.H and discussed in more detail in the section on contour plots; their use is illustrated in the example in the Introduction.
Waterfall plots can be produced two ways. You can call the WaterfallCurve()
function to draw individual curves on the plot or you can pass all of the
data in a matrix to WaterfallPlot().
The length of the edges of the rectangular volume are proportional to
the cube root of the volume. The normalization of this volume is determined
by the user specifying vmax, the maximum volume expected. The cube root
of this value will yield an edge that is 1/10 the length of the three axes.
Therefore, the rectangular volume will have the same aspect ratio as the
3-D work box.
 |
| The rectangular volume plotted at each point, v, represents the function v(x, y, z). The code to create this example is D4TEST,C. |
 |
 |
| This example of an error
function plot shows that the head sizes of boys form a normal distribution.
The code for this example is in ERFTEST.C. |
We recommend using the new GraphiC RGB colors unless you need to retain
IBM or Tektronix compatibility. The GraphiC RGB colors include the standard
IBM colors (200–215) and a 16-level gray scale (216–231).
The next 216 colors correspond to all combinations of six steps each
in Red, Green, and Blue.
The GraphiC colors may be viewed by PLAYing PATRN256.TKF, and the Tektronix dithered colors may be viewed using PATTERN.TKF.
When specifying color for panels, to retain compatibility with the Tektronix 4105 protocol, the IBM colors are negative, and the range 1–16 contains patterned fill choices. If you specify the IBM colors between 200 and 215, you need not worry about this distinction.
When output devices cannot support extended colors, GraphiC uses dither
patterns to approximate the color.
In order to use dither patterns on lines, the line width will be increased
automatically by GraphiC. Be sure that your color board can support
the colors you select. For example, the IBM EGA adaptor requires 256 kb
of video memory to use 16 colors, and the high-resolution 256-color drivers
may require up to 2Mb of video memory.
There are many representations of color that are used for different purposes. GraphiC uses the RGB (red, green, blue) system which is most appropriate for video systems. GraphiC provides routines to convert colors from one system to another, or for matching RGB values to the closest GraphiC color.
In general, color choices are sticky — GraphiC will continue to use
the color specified by a call to color()
until
another call to color() comes along. Some routines accept colors
in their argument list, but GraphiC always restores the color that was
active before the routine was called. You should be sure to make a call
to color() at the start of each GraphiC frame [after each call to
startplot()] to place the initial default
color into the TKF file. Otherwise, if the file is replayed, the color
at the end of the file might be used for the initial graphic elements.
The same fonts that are used to label plots may be used to write legends or to make text viewgraphs for presentations. A large selection of fonts is available. Any four of them may be active at once. To use these fonts, you should be aware of how the font routines are implemented.
Each font runs from ASCII character 32 (a space) through 199 (there is no character 127). Each character is stored as a series of vectors so that it may easily be changed in size or rotated. Characters may be plotted in any height and at any angle in one-degree increments from the horizontal. They may be skewed to the right or to the left, and their aspect ratio may be changed. The thickness of the lines that make up the character may be changed, as well as the color of the character. Strings also may be plotted along an arc.
Tabs may be embedded into strings by using an ordinary tab character (ASCII 9). The tabs are expanded into the number of spaces determined by tabspace() and do not cause a jump to a particular column. Data and text may be combined into a string by using the sprintf() C library routine. The active fonts may be changed at any time by calling font(). A font selection character must be used at the beginning of every string; otherwise, the last active font will be used. Initially, the first font listed in the call to font() will be active.
The string location is always the coordinates of the lower left-hand corner of the first character in the string, with the string upright. However, this location may be specified in two ways: pltfnt() plots the string at the x,y coordinates used in your plot. prtfnt() prints the string at a location x inches (or cm) from the left edge of the picture and y inches (or cm) from the bottom edge.
All measurements for string size and placement are in absolute units on a full page unless setscale(1) is called. With the call to setscale(), dimensions will scale with the page size as specified with the call to page().
For producing text slides, use the routines ctline(), rtline(), ltline(), and lcrline() to center, left, and /or right justify lines of text.
To make a superscript, put the letters to be elevated in square brackets. To make a subscript, put the letters to be lowered in reversed square brackets. For example, to plot
b a cyou would use the string "a[b]]c[". Nesting of scripts within each other is allowed, but at the end there should always be an equal number of left and right square brackets. In order to print a square bracket, you must precede it by the NULL symbol, an @ sign (use @@ to print an @ sign). Thus, to print x[t] you should enter it as x@[t@].
Although we think that these control characters make intuitive sense
and produce easy-to-read strings, you may
change them by calling supsym(), subsym(),
and nullsym(). The GraphiC escape symbols
lose their meaning if symoff() is called.
CHANGE |15|COLORS.To print a | use @|.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In OS/2, these routines are only activated when the menu is not active,
i.e., between startplot() and endplot().
These routines are not available in OS/2.
In addition to solid color fills, GraphiC provides a choice of 16 geometric
patterns, 125 dithered patterns, and 248 RGB color combinations. These
patterns can be viewed by using PLAY to display the files PATTERN.TKF
and PATRN256.TKF.
The debugging options are contained in the routine MEMORY?.C. Your code will run more slowly when memory debugging options are turned on, so be sure to turn them off for production code.
If TESTMEM is defined in USER.H, GraphiC will keep track of all memory
allocated and freed using these routines
in a linked list. When you call stopplot(),
this list will be checked and if there is any unfreed memory, a message
will appear. If TESTMEM is defined, GraphiC keeps track of the file and
line number of each call to gpcalloc(),
gpcfree(), and gpcrealloc().
In addition, a guard byte is placed at the end of every memory block and
set to 0xff. This byte is checked when the block is freed to be sure it
was not changed. The TESTMEM option will help you to detect memory leaks,
uninitialized pointers, and dimensioning problems. The GraphiC library
must be recompiled whenever you change the TESTMEM switch.
TESTMEM has no effect in GraphiC/OS2. But, all memory allocated using these routines will be freed in stopplot().
In GraphiC/286, if TESTMEM2 is defined in MEMORY2.C, GraphiC will allocate every piece of memory in its own selector. Since the allocated memory is just long enough to accommodate the request, reading or writing past the end of the memory block will generate a protection fault, and the compiler's debugger will allow you to locate the error.
If TESTMEM3 is defined in MEMORY2.C, GraphiC will do a heap check of the compiler's heap each time gpcalloc(), gpcfree() and gpcrealloc() are called.
Since MESSAGES.DAT contains all of GraphiC's prompts and messages, you can translate this file to create foreign-language versions of your software.
Handlers are included for Ctrl-C, Floating-Point Errors (FPE), Abnormal Termination (ABORT), Math Errors, and (for GraphiC-286 only) General Protection (GP) Fault. You can modify or disable any of these handlers by changing the appropriate BAUX???.C file.
GraphiC/OS2 does not install any error handlers.
GraphiC can produce color separations suitable for four-color printing. Thus, if you wish your program to work in all environments, do not use command-line arguments. Under DOS and OS/2, GPC_MAIN() is defined as main() so.In order to support other than the 16 pure colors, it is necessary that objects in the separations be printed in shades of gray. Only PostScript devices support this capability, so you can produce separations by printing to a PostScript printer or converting the output to PostScript. Alternatively, GraphiC's support for PostScript Level 2 means that such files are importable into desktop publishing packages such as Ventura Publisher and they can produce the separations.
After a plot is drawn, entering an s will turn on separations (cyan, magenta, yellow, black) for the next picture. Crop marks are added at the corners of the plots to allow the printer to align the four pictures for exact color registration. The color of each separation is also printed outside of the plot area.
The following routines allow you to output to the printer from within your code.
