9.2.1 The C application programming interface

GNU libplot has bindings for several programming languages. Regardless of which binding is used, the concepts behind libplot (Plotters, and a fixed set of operations that may 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 current C binding. For information on older C bindings, see Older C APIs.

In the C binding, a Plotter is implemented as an opaque datatype, plPlotter, which must be accessed through a pointer. Each drawing operation takes a pointer to a plPlotter as its first argument. The functions pl_newpl_r and pl_deletepl_r are the constructor and destructor for the plPlotter datatype. The final argument of pl_newpl_r must be a pointer to a plPlotterParams object, which specifies Plotter parameters. pl_newpl_r returns a pointer to a plPlotter.

You should always call pl_deletepl_r when you are finished using a Plotter. In general, Plotters that do not plot graphics in real time (Postscript Plotters and CGM Plotters in particular) write out graphics only when pl_deletepl_r is called.

The following tables summarize the action of the Plotter manipulation functions in the C binding.

plPlotter * pl_newpl_r (const char *type, FILE *infile, FILE *outfile, FILE *errfile, plPlotterParams *params);

Create a Plotter of type type, where type may be "X", "Xdrawable", "png", "pnm", "gif", "svg", "ai", "ps", "cgm", "fig", "pcl", "hpgl", "regis", "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.

All Plotter parameters will be copied from the plPlotterParams object pointed to by params. A NULL return value indicates the Plotter could not be created.

int pl_deletepl_r (plPlotter *plotter);

Delete the specified Plotter. A negative return value indicates the Plotter could not be deleted.

The functions pl_newplparams, pl_deleteplparams, and pl_copyplparams are the constructor, destructor, and copy constructor for the plPlotterParams datatype. The function pl_setplparam sets any single Plotter parameter in a plPlotterParams object.

plPlotterParams * pl_newplparams ();

int pl_deleteplparams (plPlotterParams *plotter_params);

plPlotterParams * pl_copyplparams (const plPlotterParams *params);

int pl_setplparam (plPlotterParams *params, const char *parameter, void *value);

Set the value of the parameter parameter to value in the object pointed to by params. For most parameters, value should be a char *, i.e., a string. If value is NULL, the parameter is unset.

For a list of recognized parameters and their meaning, see Plotter Parameters. Unrecognized parameters are ignored.

The reason why the plPlotterParams datatype exists is that 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 creation time. If a a parameter has been set in the specified plPlotterParams object, that will be the value used by the Plotter. If a parameter is not set, the Plotter will use a default value for it, 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 Plotter parameters to be specified by the user via environment variables.

In the C binding, each drawing operation that may be invoked on a Plotter is represented by a function whose name begins with "pl_" and ends with "_r". For example, the openpl operation is invoked on a Plotter by calling the function pl_openpl_r, the first argument of which is a pointer to the corresponding plPlotter object.