The Bindings

The OCaml bindings for PLplot provide an interface to the PLplot C API. In addition to providing access to the core functions of the C API, the OCaml PLplot interface also includes a set of higher-level plotting functions which, while built on top of the core PLplot API, retain more of an OCaml flavor.

The OCaml PLplot API is defined within the Plplot module. In general, it is suggested to include the line open Plplot in OCaml code using PLplot. The function and constant definitions are named such that they should avoid namespace collisions with other libraries. Core PLplot functions have a pl prefix, while constant constructors/variant types have a PL_ prefix.

The core binding provides a close to direct mapping to the underlying C library. It follows the C API very closely, with the exception of a few parameters which become redundant under OCaml (ex. array lengths are determined automatically by OCaml and function callbacks which are handled slightly differently than in C). An OCaml user of PLplot does not need to worry about memory management issues as they are handled automatically by the bindings.

There are also a selection of functions which provide support for operations outside of the base C API. These higher level functions are defined within the Plplot.Plot and Plplot.Quick_plot modules.

Core Binding

The core binding is mostly a direct and obvious mapping of the C application programming interface (API) to OCaml. Thus, for example, where a C function such as plcol0 requires a single integer argument, there is a corresponding OCaml function also called plcol0 which also requires a single integer argument. (plcol0 happens to set the drawing color using a number which is associated with a set of colors). Various constants from the C API are also included here as OCaml variant types with a PL_ prefix to avoid namespace clashes when the Plplot module is opened. For example, where the C PLplot API uses GRID_* to select between the data gridding methods, the OCaml API uses PL_GRID_*.

OCaml-specific variations to the core PLplot API

Several of the PLplot core functions allow the user to provide a transformation callback function to adjust the location of the plotted data. This is handled differently in the OCaml bindings than in order to keep the interface between C and OCaml as simple as possible. Rather than passing transformation functions directly to each PLplot function which supports a coordinate transformation, the coordinate transform functions are set globally using the plset_pltr and plset_mapform functions. Similarly, the functions plunset_pltr and plunset_mapform can be used to clear the globally defined coordinate transformation function. Note that the transform functions are only used in the functions which support them in the C API (ex. plmap)- they are not automatically applied to plotted data in other function calls (ex. plline). For demonstrations of their use, see OCaml PLplot examples 16 and 20 for plset_pltr and example 19 for plset_mapform.

OCaml high level 2D plotting API

In addition to the core PLplot API, the OCaml bindings provide two modules which provide a more OCaml-like interface: Plplot.Plot and Plplot.Quick_plot. Plplot.Plot provides a simplified naming scheme for plotting functions, as well as the means to more easily track multiple plot streams at once. Plplot.Quick_plot provides functions to quickly plot points, lines, data arrays (images) and functions without the need for any plot setup or boilerplate.