9.4.1 Control functions

The following are the “control 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 current C binding, each of these functions takes a pointer to a plPlotter as its first argument. Also in the current C binding, the name of each function begins with "pl_" and ends with "_r". ("_r" stands for `revised' or `reentrant'.) For information on older C bindings, see Older C APIs. In the C++ binding, these are member functions of the Plotter class and its subclasses, and the prefix and suffix are not used.

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 have a notion of background color, i.e., X Plotters, X Drawable Plotters, PNG Plotters, PNM Plotters, and GIF Plotters (all of which produce bitmaps), CGM Plotters, ReGIS Plotters and Metafile 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. Unrecognized colors are interpreted as "white". For information on what color names are recognized, see Color Names. A 24-bit RGB color may also be specified as a six-digit hexadecimal string, e.g., "#c0c0c0".

bgcolorname affects only Plotters that have a notion of background color, i.e., X Plotters, X Drawable Plotters, PNG Plotters, PNM Plotters, and GIF Plotters (all of which produce bitmaps), CGM Plotters, ReGIS Plotters, and Metafile 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.

SVG Plotters and CGM Plotters support "none" as a value for the background color. It will turn off the background: the drawn objects will not be backed by anything. This is useful when the generated SVG or WebCGM file is to be placed on a Web page.

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 Plotter 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 Plotter 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 and upper right corners of a rectangular window in the user coordinate system that will be mapped to the `viewport': the rectangular portion of the output device that graphics will be drawn in. The default window is a square, with opposite corners (0,0) and (1,1).

In mathematical terms, calling space or fspace sets the affine transformation from user coordinates to device coordinates. That is, it sets the transformation matrix attribute for each object subsequently drawn on the display. Either space or fspace would usually be invoked at the beginning of each page of graphics, i.e., immediately after the call to openpl. Additional calls to space or fspace are allowed, and there are several “mapping functions” that also affect the transformation matrix attribute. See Mapping Functions.

Note that the size and location of the viewport depend on the type of Plotter, and on the Plotter parameters that are specified at Plotter creation time. For example, the default viewport used by any Illustrator, Postscript, Fig, PCL, and HP-GL Plotter is a square whose size depends on the Plotter's page type. See Page and Viewport Sizes.

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. Their arguments are the three defining vertices of an parallelogram-shaped window in the user coordinate system. The specified vertices are the lower left, the lower right, and the upper left. This window will be mapped affinely onto the viewport: the rectangular portion of the output device that graphics will be drawn in.

int havecap (const char *s);

havecap is not really a control function: it is a query function. It 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 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 previously plotted objects to the graphics display. This is useful only if the affected Plotter is one that does real-time plotting (X Plotters, X Drawable Plotters, ReGIS Plotters, Tektronix Plotters, and Metafile Plotters). It ensures that all previously plotted objects are visible to the user. On Plotters that do not do real-time plotting, this operation has no effect.

int closepl ();

closepl closes a Plotter, i.e., ends a page of graphics. If a path is in progress, it is first ended and plotted, as if endpath had been called. A negative return value indicates the Plotter could not be closed.

In the present release of libplot, some Plotters output each page of graphics immediately after it is plotted, i.e., when closepl is invoked to end the page. That is the case with PCL and HP-GL Plotters, in particular. Plotters that can output only a single page of graphics (PNG, PNM, GIF, SVG, Illustrator, and Fig Plotters) do so immediately after the first page is plotted, i.e., when closepl is invoked for the first time. Postscript and CGM Plotters store all pages of graphics internally, and do not produce output until they are deleted.