The Ada bindings have been augmented with a number of features which are intended to simplify the use of PLplot. They include high-level features for simplified plotting (such as easy foreground-background control, a collection of "simple plotters," and easy color map manipulations), integer options which have been given meaningful names, and a few other focused additions. Many users will find that they can do most of their work using the "simple plotters".
The default for PLplot is to draw its graphics on a black
background. A white background can be used instead with
Draw_On_White or reset to the original mode with
Draw_On_Black. Each of these manipulates color
map 0 by swapping black and white so that e.g.with
Draw_On_White, formerly white lines on a black
background automatically become black lines on a white
background.
Several high-level but flexible plotters are available and more might be added in the future. It is expected that many users will find that these high-level routines are adequate for most of their day-to-day plotting.
Plot up to five x-y pairs with easy labelling, coloring, line width and styles, justification, and zooming.
Plot up to five y's against a single x with easy labelling and automatic line colors and styles.
Plot up to five x-y pairs with easy labelling and automatic line colors and styles.
Plot a single x-y pair with flexible labels, axis styles, colors, line width and style, justification, and zooming.
PLplot provides extensive manipulation and control of two separate color maps, color map 0 and color map 1. The Ada binding makes basic manipulations easier and also adds facilities for making snapshots of color map 0 so that any state of the map can easily be restored later. An initial snapshot is taken when the package is initialized so that the default color settings can always be restored after having been changed.
Another set of features lets the user reset the 16 individual
colors in color map 0 after a color definition has been changed. It is
important to note that while Set_Pen_Color(Red)
(plcol0 in the traditional binding) normally does
what it says, Red simply has the value
1. If the user changes the color map so that
1 corresponds to another color, then
Set_Pen_Color(Red) will draw in that color instead
of red. To always assure that red is drawn even if the color map has
been changed for integer 1, use
Set_Pen_Color(Reset_Red) instead. These 16 "reset"
functions return the appropriate default integer for the specified
color but also reset that slot in the color table so that a subsequent
call such as Set_Pen_Color(Red) will also cause
drawing in red.
Color map 1 also gets a easy-to-use makeover for Ada users.
There are several prebuilt color themes that are useful for quickly
making surface and mesh plots,
Color_Themes_For_Map_1_Type. These color themes can
be quickly applied with
Quick_Set_Color_Map_1.
Miscellaneous other Ada features include a prebuilt mask
function for Shade_Regions that does no masking;
perhaps the most useful purpose is to provide a template for writing
mask functions that do mask. And there is a handy function for
calculating the contour levels for making contour plots.
Color table snapshots
Make_Snapshot_Of_Color_Map_0
Restore_Snapshot_Of_Color_Map_0
Restore_Default_Snapshot_Of_Color_Map_0
Color resetting functions for the 16 colors of color map 0
Reset_Black, Reset_Red, ..., Reset_White
Easy manipulation of color map 1
Prebuilt color themes for color map 1:
Color_Themes_For_Map_1_Type
Quick application of prebuilt color themes:
Quick_Set_Color_Map_1
Other features
A prebuilt mask function for
Shade_Regions that does no masking:
Mask_Function_No_Mask
An easy way to calculate an array of contour levels for
contour plots: Calculate_Contour_Levels
The C version of PLplot uses a number of integers to mean specific things. Unfortunately, the meaning is lost when it it consigned to being a mere integer with no name. The Ada binding partially rectifies this situation by giving names to these integer constants. The integer can still be used if desired. (A more complete and safer rectification would use enumerated types.)
Below is a listing of at least the contexts in which these "re-namings" have been applied. In some cases the entire range of values is listed, but if there are more than about four such values for each context, only a sampling is given.
Instances
Colors: Plot_Color_Type
0 is Black, 1 is Red,
etc
Justification for plots:
Justification_Type
User_Justified
Not_Justified
Justified
Justified_Square_Box
Axis styles: Axis_Style_Type
Linear_Major_Grid
Linear_Minor_Grid
etc.
Font styles: Font_Style_Type
Normal_Font
Roman_Font
Italic_Font
Script_Font
Character sets: Character_Set_Type
Standard_Character_Set
Extended_Character_Set
Plot orientation: Orientation_Type
Landscape
Portrait
Modes for parsing command line arguments:
Parse_Mode_Type
E.g. PL_PARSE_PARTIAL
Descriptions of map outlines (continents, states, etc.):
Map_Type
Continents
USA_and_States
Continents_and_Countries
USA_States_and_Continents
Various style and view options for 3D and surface plots
E.g. Lines_Parallel_To_X
Kind of gridding algorithm for interpolating 2D data to a
grid: Gridding_Algorithm_Type
E.g.
Grid_Bivariate_Cubic_Spline_Approximation
Flags for histogram style
E.g. Histogram_Default
Flags for histogram binning
E.g. Bin_Default
Names for color space models
Hue, Lightness, Saturation: HLS
Red, Green, Blue: RGB
To provide convenient string handling in a fashion that is
familiar to Ada programmers, function versions which return a
String type are provided of
Get_Device_Name,
Get_Version_Number, and
Get_Output_File_Name (plgdev,
plgver, and plgfnam in the
traditional binding). These functions replace the procedure-style
subprograms that are described in the C API documentation.
Overloaded Set_Line_Style
(plstyl in the traditional binding) with a version
that takes a single argument,
Default_Continuous_Line. This replaces the awkward
situation of calling the normal versions of these procedures with unused
arguments simply to set the line style to the default, continuous,
line.
The contour plotter Contour_Plot_Irregular_Data
(plfcont in the traditional binding) is provided for
making contour plots from irregularly spaced data. This feature is not
documented in the PLplot API documentation.
The custom label function Set_Custom_Label
(plslabelfunc in the traditional binding) can be
called with null arguments to revert to using the default labelling
scheme. Alternately, an Ada-only procedure with no arguments,
Use_Default_Labels, is provided. See Ada example 19
(x19a.adb or xthick19a.adb) for a
usage example.
The custom coordinate transform setter,
Set_Custom_Coordinate_Transform,
(plstransform in the traditional binding) can be
called with null arguments to clear any previous custom coordinate
transforms that the user has set, thus reverting to the default
coordinate transform. Alternately, an Ada-only procedure with no
arguments, Clear_Custom_Coordinate_Transform, is
provided. See Ada example 19 (x19a.adb or
xthick19a.adb) for a usage example.
The procedure Set_Arrow_Style_For_Vector_Plots
(plsvect in the traditional binding) normally is called
to define the shape of an arrow in vector plots. However, calling it with
null pointer arguments (System.Null_Address) in place
of the Real_Vector arrays and False
for the Fill_Arrow argument causes the arrow shape to
be reset to the default shape; this is implemented in Ada as an overloaded
procedure in order to be consistent with the C API but is rather awkward.
So there are two additional procedures that are added for the convenience
of Ada programmers: Reset_Vector_Arrow_Style and plsvect, both without
arguments, both available in both bindings, and the latter an overload of
the normal arrow-setting procedure.
The procedures Plot_Shapefile and
Plot_Shapefile_World (plmapfill
) and plmapline in the traditional binding)
are each provided an overloaded version allowing either an array of
integers or a null pointer to be passed for the last argument, so that the
documentation makes sense. An additional related procedure is provided in
each case, Plot_Shapefile_All and
Plot_Shapefile_World_All (identically named in the traditional
binding) for the case when a null pointer would otherwise be passed, thus
allowing the Ada programmer a way to specify "plot all the Shapefile
elements" without having to conjure a null pointer. See Example 19.