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.