The Bindings
Prev | Chapter 11. OCaml Language | Next

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

Prev | Up | Next
Chapter 11. OCaml Language | Home | The Examples