The following are the “control functions” in (plotutils plot).
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 Guile binding, each of these functions takes
a <plotter> as its first argument.
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!.
Given a plotter and three integers
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.
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 Specifying Colors by Name.
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.
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.
space! takes 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! 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. space! would usually be
invoked at the beginning of each page of graphics, i.e., immediately
after the call to openpl!. Additional calls to space!
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 Sizes and Viewport Sizes.
space2! is an extended version of space!.
The 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.
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 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.
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.
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 (plotutils plot), 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.