Setup functions

The following are the "setup functions" in libplot. They are the basic functions that open, initialize, or close an already-created Plotter. They are listed in the approximate order in which they would be called.

In the C binding, the names of all functions should be preceded by "pl_", unless the header file plotcompat.h is included. See section C compiling and linking. In the C++ binding, these are member functions of the Plotter class and its subclasses.

int openpl ();

openpl opens a Plotter, i.e., begins a page of graphics. This resets the Plotter's drawing attributes to their default values. A negative return value indicates the Plotter could not be opened. Currently, an X Plotter pops up a new window on an X Window System display for each page of graphics, i.e., with each invocation of openpl. Future releases may support window re-use.

int bgcolor (int red, int green, int blue);

bgcolor sets the background color for the Plotter's graphics display, using a 48-bit RGB color model. The arguments red, green and blue specify the red, green and blue intensities of the background color. Each is an integer in the range 0x0000...0xffff, i.e., 0...65535. The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white. bgcolor affects only Plotters that produce bitmaps, i.e., X Plotters, X Drawable Plotters, PNM Plotters, and GIF Plotters. Its effect is simple: the next time the erase operation is invoked on such a Plotter, its display will be filled with the specified color.

int bgcolorname (const char *name);

bgcolorname sets the background color for the the graphics display to be name. For information on what color names are recognized, see section Specifying Colors by Name. Unrecognized colors are interpreted as "white". bgcolorname affects only Plotters that produce bitmaps, i.e., X Plotters, X Drawable Plotters, PNM Plotters, and GIF Plotters. Its effect is simple: the next time the erase operation is invoked on such a Plotter, its display will be filled with the specified color.

int erase ();

erase begins the next frame of a multiframe page, by clearing all previously plotted objects from the graphics display, and filling it with the background color (if any). It is frequently useful to invoke erase at the beginning of each page, i.e., immediately after invoking openpl. That is because some Plotters are persistent, in the sense that objects drawn within an openpl...closepl pair remain on the graphics display even after a new page is begun by a subsequent invocation of openpl. Currently, only X Drawable Plotters and Tektronix Plotters are persistent. Future releases may support optional persistence for X Plotters also. On X Plotters and X Drawable Plotters the effects of invoking erase will be altogether different if the device driver parameter USE_DOUBLE_BUFFERING is set to "yes". In this case, objects will be written to an off-screen buffer rather than to the graphics display, and invoking erase will (1) copy the contents of this buffer to the display, and (2) erase the buffer by filling it with the background color. This `double buffering' feature facilitates smooth animation. See section Device driver parameters.

int space (int x0, int y0, int x1, int y1);

int fspace (double x0, double y0, double x1, double y1);

space and fspace take two pairs of arguments, specifying the positions of the lower left corner and upper right corner of the graphics display, in user coordinates. In other words, calling space or fspace sets the affine transformation from user coordinates to device coordinates. One of these operations must be performed at the beginning of each page of graphics, i.e., immediately after openpl is invoked.

int space2 (int x0, int y0, int x1, int y1, int x2, int y2);

int fspace2 (double x0, double y0, double x1, double y1, double x2, double y2);

space2 and fspace2 are extended versions of space and fspace, and may be used instead. Their arguments are the three defining vertices of an `affine window' (a drawing parallelogram), in user coordinates. The specified vertices are the lower left, the lower right, and the upper left. This window will be mapped affinely onto the graphics display.

int havecap (const char *s);

havecap tests whether or not a Plotter, which need not be open, has a specified capability. The return value is 0, 1, or 2, signifying no/yes/maybe. For unrecognized capabilities the return value is zero. Recognized capabilities include "WIDE_LINES" (i.e., the ability to draw lines with a non-default thickness), "DASH_ARRAY" (the ability to draw in arbitrary dashing styles, as requested by the linedash function), "SETTABLE_BACKGROUND" (the ability to set the color of the background), and "SOLID_FILL". The "HERSHEY_FONTS", "PS_FONTS", "PCL_FONTS", and "STICK_FONTS" capabilities indicate whether or not fonts of a particular class are supported. See section Available text fonts. All Plotters except Tektronix Plotters have the "SOLID_FILL" capability, meaning they can fill paths with solid color. Each such Plotter has at least one of the "EVEN_ODD_FILL" and "NONZERO_WINDING_NUMBER_FILL" capabilities. These indicate the supported rules for determining the `inside' of a path. The `maybe' value is returned for most capabilities by Metafile Plotters, which do no drawing themselves. The output of a Metafile Plotter must be translated to another format, or displayed, by invoking plot.

int flushpl ();

flushpl flushes (i.e., pushes onward) all plotting commands to the display device. This is useful only if the currently selected Plotter does real-time plotting, since it may be used to ensure that all previously plotted objects have been sent to the display and are visible to the user. It has no effect on Plotters that do not do real-time plotting.

int closepl ();

closepl closes a Plotter, i.e., ends a page of graphics. A negative return value indicates the Plotter could not be closed. In the present release of libplot, some Plotters output pages in real time, i.e., with each invocation of closepl. This is true of PCL and HP-GL Plotters, for example. Similarly, Plotters that normally output only a single page (PNM, GIF, Illustrator, and Fig Plotters) do so immediately after that page is ended. However, Postscript Plotters do not output their page(s) of graphics until they are deleted.

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