The Plotutils Package - The C API

Go to the first, previous, next, last section, table of contents.

### The C application programming interface

`libplot` has bindings for several programming languages. Regardless of which language binding is used, the concepts behind `libplot` (Plotters, and a fixed set of operations that can be applied to any Plotter) remain the same. However, the ways in which Plotters are manipulated (created, selected for use, and deleted) may differ between bindings. This section discusses the C binding.

If you are writing an application in C that will use `libplot` to draw vector graphics, the first thing you need to know is how, in the C binding, Plotters are manipulated. There are four special functions for this, which you can invoke: `newpl`, `selectpl`, `deletepl`, and the parameter-setting function `parampl`. Actually, you would usually invoke them under the names `pl_newpl`, `pl_selectpl`, `pl_deletepl`, and `pl_parampl`. That is because in the C binding, the names of all functions begin with "pl_" unless the header file `plotcompat.h` is included. See section C compiling and linking.

The `pl_newpl` function will create a Plotter of specified type. Its first argument may be "X", "Xdrawable", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", or "meta". It returns a nonnegative integer (a "handle") that may be used to refer to the Plotter. Before using a Plotter that you have created (i.e., before invoking any of the `libplot` operations on it), you must select the Plotter for use by calling `pl_selectpl`. Only one Plotter may be selected at a time, but by calling `pl_selectpl` you may switch from Plotter to Plotter at any time, even when the selected Plotter is open. A Plotter that is not currently selected can be deleted, and its storage freed, by calling `pl_deletepl`.

Strictly speaking, you do not need to call `pl_newpl`, `pl_selectpl`, or `pl_deletepl` in order to draw graphics. That is because at startup, a single Metafile Plotter that writes to standard output (with handle `0') is automatically created and selected. The presence of this default Plotter is for compatibility with pre-GNU versions of `libplot`. Of course, you may not wish to obtain output in metafile format, and you may not wish to write to standard output.

You should get into the habit of calling `pl_deletepl` whenever you are finished using a Plotter. In general, Plotters that do not plot graphics in real time (Postscript Plotters in particular) write out graphics only when the plot is finished, and `pl_deletepl` is called.

The following table summarizes the action of the four functions in the C binding that are used for Plotter manipulation.

int `pl_newpl` (const char *type, FILE *infile, FILE *outfile, FILE *errfile);
  `pl_newpl` creates a Plotter of type type, where type may be "X", "Xdrawable", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", or "meta". The Plotter will have input stream infile, output stream outfile, and error stream errfile. Any or all of these three may be NULL. Currently, all Plotters are write-only, so infile is ignored. X Plotters and X Drawable Plotters write graphics to an X Window System display rather than to an output stream, so if type is "X" or "Xdrawable" then outfile is ignored as well. Error messages (if any) are written to the stream errfile, unless errfile is NULL. The return value from `newpl` is a `handle': a nonnegative integer by which the newly created Plotter is referred to. A negative return value indicates the Plotter could not be created.
int `pl_selectpl` (int handle);
  `pl_selectpl` selects a Plotter, referred to by its handle, for use. If any of the basic `libplot` operations is subsequently invoked, it will be applied to the selected Plotter. Only one Plotter may be selected at a time. At startup, a single Metafile Plotter that writes to standard output (with handle `0') is automatically created and selected. The handle of the previously selected Plotter is returned. A negative return value indicates the specified Plotter does not exist or could not be selected.
int `pl_deletepl` (int handle);
  `pl_deletepl` deletes a Plotter, referred to by its handle. The Plotter must not be selected at the time it is deleted. A negative return value indicates the Plotter could not be deleted.
int `pl_parampl` (const char *parameter, void *value);
  `pl_parampl` sets the value of the device driver parameter parameter to value. Device driver parameters specify Plotter options. The parameter values in effect at the time any Plotter is created are copied into it. For most parameters, value should be a `char *`, i.e., a string. Unrecognized parameters are ignored. For a list of the recognized parameters and their meaning, see section Device driver parameters.

Up to now we have not discussed the fourth function, `pl_parampl`. Even though the Plotter interface is largely Plotter-independent, it is useful to be able to specify certain aspects of a Plotter's behavior at the time it is created. Plotter behavior is captured by a manageable number of parameters, which we call device driver parameters. A value for any parameter can be specified by calling `pl_parampl`. This function does not operate on any particular Plotter: it belongs to the C binding as a whole. The parameter values used by any Plotter are constant over the lifetime of the Plotter, and are those that were in effect when the Plotter was created.

Actually, a slightly more sophisticated rule applies. If at Plotter creation time a parameter is set, the value specified by the most recent call to `pl_parampl` will be the value used by the Plotter. If at Plotter creation time a parameter is not set, its default value will be used, unless the parameter is string-valued and there is an environment variable of the same name, in which case the value of that environment variable will be used. This rule increases run-time flexibility: an application programmer may allow non-critical driver parameters to be specified by the user via environment variables. Once set, a parameter may be unset by the programmer by calling `pl_parampl` with a value argument of NULL. This further increases flexibility.

Go to the first, previous, next, last section, table of contents.