The Plotutils Package - Setup Functions

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

### 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.