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.
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_*.
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.
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.