Unique Features of the Ada bindings

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".

High-level features for simplified plotting

Foreground-background control

Draw_On_Black, Draw_On_White

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 autotmatically become black lines on a white background.

Simple Plotters

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.

Multiplot_Pairs

Plot up to five x-y pairs with easy labeling, coloring, line width and styles, justification, and zooming.

Simple_Plot

Plot up to five y's against a single x with easy labeling and automatic line colors and styles.

Simple_Plot_Log_X

Same as Simple_Plot but with logarithmic x-axis.

Simple_Plot_Log_Y

Same as Simple_Plot but with logarithmic y-axis.

Simple_Plot_Log_XY

Same as Simple_Plot but with logarithmic x- and y-axes.

Simple_Plot_Pairs

Plot up to five x-y pairs with easy labeling and automatic line colors and styles.

Single_Plot

Plot a single x-y pair with flexible labels, axis styles, colors, line width and style, justification, and zooming.

Simple_Contour

Make a contour plot with labels

Simple_Mesh_3D

Easy 3D mesh plot with labels, zooming, and perspective controls

Simple_Surface_3D

Easy 3D surface plot with labels, zooming, and perspective controls

Simple color map manipulations

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 easlily 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 pre-built 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 pre-built 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

Pre-built color themes for color map 1: Color_Themes_For_Map_1_Type

Quick application of pre-built color themes: Quick_Set_Color_Map_1

Other features

A pre-built 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

Integer-options Given Ada Names

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

One-offs

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 labeling 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 procdure with no arguments, Clear_Custom_Coordinate_Transform, is provided. See Ada example 19 (x19a.adb or xthick19a.adb) for a usage example.