GrADS has begun to make use of plug-ins, which are software components (modules) that add specific features to an existing program. The use of plug-ins brings an improvement in performance and flexibility for users who want to create customized functions or features for GrADS. The User Defined Plug-in Table (UDPT) is a simple stand-alone text file that contains all the information about plug-ins that GrADS requires. Check the documentation for more information about the proper syntax of UDPT records.
The first plug-in capability was introduced in version 2.1.1.b0, and replaced the old interface for user-defined functions. The User Defined Plug-ins (UDP) allow users to write their own GrADS functions in the computer language of their choice, and have them
perform customized calculations and operations via the GrADS expression.
The function arguments and data grids are no longer passed between GrADS and the user's program through data files written out to disk. With plug-ins, the user's code is dynamically loaded into GrADS when the function is invoked by the user, and the data is operated on while still sitting in memory. The documentation has more information about how to compile, setup, and use user-defined plug-in functions.
Version 2.2.0 introduced a redesign of the GrADS code so that the graphics capabilities are treated as plug-ins, with separate modules for the interactive display (in an X window) and printing (creating graphics output in image and vector formats). The graphics plug-ins are part of the GrADS core source code -- they are not user-defined -- although the plug-in architecture certainly makes it possible for motivated users to create new interfaces for printing or display that could be used instead of the options we provide. The plug-in architecture makes it possible to re-introduce the older graphics engines that were part of GrADS before the Cairo library was adopted. The display and printing plug-ins are independent, so users can mix and match new and old depending on what is needed. The old pre-Cairo code for creating vector graphic output for printing (.ps and .eps) is no longer supported at all -- those output formats are now only supported through the Cairo interface.
Graphics Display
For the interactive X-window display, users can choose between the newer Cairo interface or the tradtional X11 code that supports widgets (buttons, drop menus, and rubber banding). The Cairo plug-in creates a more visually pleasing graphic because it support fonts, anti-aliasing, transparent colors, and pattern filling. The downsides of using Cairo for the display are: (1) it doesn't support the widgets, (2) it slower than the old X11 code, and (3) a few users have reported that it is buggy (fragmented and only partially rendered) for X11 servers on some desktop unix platforms.
Graphics Printing
For printing -- creating graphical output in image or vector formats -- users can choose between Cairo or the GD library. The GD interface is very fast and creates relatively small image files, but the image quality is low. The GrADS GD plug-in does not support fonts, anti-aliasing, transparent colors, or pattern filling. If image quality is more important than the time it takes to create the files or the size of the output files, then the Cairo interface is recommended. The Cairo plug-in supports only .png for image output; the GD plug-in supports .png as well as .gif and .jpg image formats. If you want a vector graphic (.ps, .eps, .pdf, or .svg) then your only option is the Cairo plug-in.
GrADS without Graphics
We also provide a plug-in that is a no-op for all the graphics subroutines, called gxdummy. The gxdummy plug-in can be used when no graphics capabilities are needed, or as a template for creating new graphics plug-ins.
Mix and Match
All combinations of display and printing plug-ins are supported. Selecting the Cairo plug-ins for display and printing guarantees that the output will exactly match what is seen in the display. Similarly, the selection of the old X11 and GD plug-ins will ensure that the output matches the display, except for the widgets, which are never printed. Specific user needs dictate which options are best.
How to Specify Graphics Plug-ins
The user can specify which graphics plug-ins to use on startup with the following arguments: -d (for display) and -h (for printing; 'h' is for hardcopy). Each argument is followed by the name of the desired plug-in. The names are provided in the UDPT.
Examples are:
> grads -d Cairo -h GD
If the -h and -d options are not used, GrADS will look for graphics and display plug-ins named "Cairo" by default. It is only necessary to use -h or -d when Cairo is not desired.
> grads -d Cairo -h Cairo
> grads -d X11 -h GD
> grads -d X11 -h Cairo
Errors
On startup, GrADS will look for information about plug-ins in two places: in
the file named by the GAUDPT environment variable, and in a file named "udpt" in the GADDIR directory. If there are any syntax errors in either of these files, it is not a fatal error -- GrADS will issue a warning message with information about where the error is and what is wrong with the record, then it will ignore the record and continue. After all the available information about plug-ins has been parsed, GrADS will initialize the graphics package, with the message "GX Package Initialization". It is at this point that GrADS will try to open and load the graphics plug-ins. If there are any problems, GrADS will return the message "GX Package Error: Could not find a record for the printing plug-in" or "GX Package Error: Could not find a record for the display plug-in" followed by some helpful information about the name of the plug-in it is looking for, and the names of the files it parsed. These errors mean that something is wrong with the User-Defined Plug-in Tables. Remember that the records in the GAUDPT file take precedence over records in the default udpt in GADDIR. If GrADS returns the message "GX Package Error: dlopen failed" it means the error is related to the shared object file itself -- it may be missing, corrupted, or the permissions may be wrong.
How to Query Graphics Plug-Ins
The 'q udpt' command will return a list of the plug-ins that GrADS found after parsing the User-Defined Plug-in Tables on startup.
The 'q gxconfig' command will return information about the graphics plug-ins currently in use: the name, shared object filename, and any relevant library version information.