In designing the libplot library, every effort was made to make
the Plotter interface independent of the type of Plotter. To the
extent that Plotters display individual (i.e., instance-specific)
behavior, that behavior is captured by a manageable number of
Plotter parameters. Each parameter has a value that is allowed
to be a generic pointer (a void *). For most parameters, the
value is a string (a char *).
The parameter values of any Plotter are constant over the lifetime of
the Plotter, and are specified when the Plotter is created. In the C binding, a value for any parameter is specified by calling the
pl_setplparam function. The pl_setplparam function acts
on a plPlotterParams object, which encapsulates Plotter
parameters. When a Plotter is created by calling pl_newpl_r,
a pointer to a plPlotterParams object is passed as the final
argument.
If at Plotter creation time a parameter is not specified, 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 Plotter parameters to be specified by the user via environment variables.
In the C++ binding, the PlotterParams class and
PlotterParams::setplparam, a member function, are the
analogues of the plPlotterParams datatype and the function
pl_setplparam.
The following are the currently recognized parameters (unrecognized ones
are ignored). The most important ones are DISPLAY, which affects
X Plotters, BITMAPSIZE, which affects X Plotters, PNG
Plotters, PNM Plotters, and GIF Plotters, PAGESIZE, which affects
Illustrator, Postscript, CGM, Fig, and HP-GL Plotters, and
ROTATION, which affects all Plotters except Metafile Plotters.
These four parameters are listed first and the others alphabetically.
Most of the remaining parameters, such as the several whose names begin
with "HPGL", affect only a single type of Plotter.
BITMAPSIZEXplot.geometry. That is for backward
compatibility.
X Plotters support precise positioning of the graphics display. For
example, if BITMAPSIZE is "570x570+0+0" then it will be
positioned in the upper left corner of the X Window System display.
PAGESIZEFor Illustrator, Postscript, PCL and Fig Plotters, the graphics
display will be, by default, a square region centered on the specified
page. (For example, it will be a centered 8in square if
PAGESIZE is "letter".) For HP-GL Plotters, it will be a square
region of the same size, but will not by default be centered. SVG
format and WebCGM format have no notion of the Web page on which the
graphics display will ultimately be positioned. They do have a notion
of default display size, though this will normally be overridden when
the SVG or WebCGM file is placed on a Web page. For this default
display size, SVG and CGM Plotters will use the same graphics display
size that is used by other Plotters.
For the default size (and location) of the graphics display for each
page type, see Page and Viewport Sizes. You do not need to use
the default size, since either or both of its dimensions can be
specified explicitly. For example, PAGESIZE could be specified
as "letter,xsize=4in", or "a4,xsize=10cm,ysize=15cm". The dimensions
are allowed to be negative (a negative dimension results in a
reflection).
For Plotters other than SVG and CGM Plotters, the position of the
graphics display on the page, relative to its default position, can be
adjusted by specifying an offset vector. For example, PAGESIZE
could be specified as "letter,yoffset=1.2in", or
"a4,xoffset=−5mm,yoffset=2.0cm". Inches, centimeters, and
millimeters are the supported units. The "xoffset" and "yoffset"
options may be used in conjunction with "xsize" and "ysize".
It is also possible to position the graphics display precisely, by
specifying the location of its lower left corner relative to the lower
left corner of the page. For example, PAGESIZE could be
specified as "letter,xorigin=2in,yorigin=3in", or
"a4,xorigin=0.5cm,yorigin=0.5cm". The "xorigin" and "yorigin" options
may be used in conjunction with "xsize" and "ysize". SVG and WebCGM
Plotters ignore the "xoffset", "yoffset", "xorigin", and "yorigin"
options, since SVG format and WebCGM format have no notion of the Web
page on which the graphics display will ultimately be positioned.
ROTATIONA rotated viewport does not change the position of its four corners. Rather, the graphics are rotated within it. If the viewport is rectangular rather than square, this `rotation' necessarily includes a rescaling.
This parameter is useful for switching between portrait and landscape
orientations. Internally, it determines the affine transformation from
NDC (normalized device coordinate) space to device space.
BG_COLORerase is
invoked). For information on what color names are recognized, see
Color Names. The background color may be changed at any later
time by invoking the bgcolor (or bgcolorname) and erase
operations.
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.
CGM_ENCODINGCGM_MAX_VERSIONlibplot produces
version 3 CGM files, i.e., it does not use version 4 features.
EMULATE_COLORThis parameter is seldom useful, except when using a PCL Plotter to
prepare output for a monochrome PCL 5 device. Many monochrome
PCL 5 devices, such as monochrome LaserJets, do a poor job of
emulating color on their own. They usually map HP-GL/2's seven standard
pen colors, including even yellow, to black.
GIF_ANIMATIONerase operation will have special semantics: with the exception
of its first invocation, it will act as a separator between successive
images in the written-out pseudo-GIF file. "no" means that
erase should act as it does on other Plotters that do not write
graphics in real time, i.e., it should erase the image under
construction by filling it with the background color. If "no" is
specified, the pseudo-GIF file will contain only a single image.
GIF_DELAYGIF_ITERATIONSHPGL_ASSIGN_COLORSHPGL_VERSION is "2". "no" means to draw with a fixed
set of pens, specified by setting the HPGL_PENS parameter. "yes"
means that pen colors will not restricted to the palette specified in
HPGL_PENS: colors will be assigned to “logical pens” in the
range #1...#31, as needed. Other than color LaserJet printers
and DesignJet plotters, not many HP-GL/2 devices allow the assignment of
colors to logical pens. In particular, HP-GL/2 pen plotters do not.
So this parameter should be used with caution.
HPGL_OPAQUE_MODEHPGL_VERSION is "2". "yes" means that the HP-GL/2 output
device should be switched into opaque mode, rather than transparent
mode. This allows objects to be filled with opaque white and other
opaque colors. It also allows the drawing of visible white lines,
which by convention are drawn with pen #0. Not all HP-GL/2 devices
support opaque mode or the use of pen #0 to draw visible white
lines. In particular, HP-GL/2 pen plotters do not. Some older
HP-GL/2 devices reportedly malfunction if asked to switch into opaque
mode. If the output of an HP-GL Plotter is to be sent to such a
device, a "no" value is recommended.
HPGL_PENSHPGL_VERSION is "1.5" or "2" and "1=black" if the
value of HPGL_VERSION is "1". Relevant only to HP-GL
Plotters. The set of available pens; the format should be
self-explanatory. The color for any pen in the range #1...#31 may
be specified. For information on what color names are recognized, see
Color Names. Pen #1 must always be present, though it need
not be black. Any pen in the range #2...#31 may be omitted.
HPGL_ROTATEHPGL_VERSION is "2".
The rotation requested by HPGL_ROTATE is different from the sort
requested by the ROTATION parameter. ROTATION rotates the
graphics display in place, but HPGL_ROTATE both rotates the
graphics display and moves its lower left corner toward another corner
of the page. Altering the plotting area in such a way is supported by
the HP-GL language.
The HPGL_ROTATE parameter facilitates switching between portrait
and landscape orientations. For HP-GL devices that is frequently a
concern, since some HP-GL devices (“plotters”) draw with a default
landscape orientation, while others (“printers”) draw with a default
portrait orientation. There is no programmatic way of determining which
is which.
HPGL_VERSIONINTERLACEMAX_LINE_LENGTHThis parameter is relevant to all Plotters except Tektronix and Metafile
Plotters. The reason for splitting long paths is that some display
devices (e.g., old Postscript printers and HP-GL pen plotters) have
limited buffer sizes. It is not relevant to Tektronix or Metafile
Plotters, since they draw paths in real time and have no buffer
limitations.
META_PORTABLEPCL_ASSIGN_COLORSPCL_BEZIERSPNM_PORTABLETERMxterm, nxterm, or
kterm. Before drawing graphics, a Tektronix Plotter will emit an
escape sequence that causes the terminal emulator's auxiliary Tektronix
window, which is normally hidden, to pop up. After the graphics are
drawn, an escape sequence that returns control to the original VT100
window will be emitted. The Tektronix window will remain on the screen.
If the value is a string beginning with "kermit", "ansi.sys", or
"nansi.sys", it is taken as a sign that the current application is
running in the VT100 terminal emulator provided by the MS-DOS version of
kermit. Before drawing graphics, a Tektronix Plotter will emit
an escape sequence that switches the terminal emulator to Tektronix
mode. Also, some of the Tektronix control codes emitted by the Plotter
will be kermit-specific. There will be a limited amount of color
support, which is not normally the case (the 16 ansi.sys colors
will be supported). The "dotdotdashed" line style will be supported,
which is also not normally the case. After drawing graphics, the
Plotter will emit an escape sequence that returns the emulator to VT100
mode. The key sequence `ALT minus' may be employed manually within
kermit to switch between the two modes.
TRANSPARENT_COLORIf TRANSPARENT_COLOR is set and an animated pseudo-GIF file is
produced, the `restore to background' disposal method will be used for
each image in the file. Otherwise, the `unspecified' disposal method
will be used.
USE_DOUBLE_BUFFERINGSome X displays provide special hardware support for double buffering.
If this support is available, the X Plotter will detect its
presence, and will draw graphics using the appropriate extension to the
X11 protocol (either DBE or MBX). In this case the animation will be
significantly faster; on high-end graphics hardware, at least.
VANISH_ON_DELETEXDRAWABLE_COLORMAPColormap *, a pointer to a
colormap from which colors should be allocated. NULL indicates that the
colormap to be used should be the default colormap of the default screen
of the X display.
XDRAWABLE_DISPLAYDisplay *, a pointer to the X display with
which the drawable(s) to be drawn in are associated.
XDRAWABLE_DRAWABLE1XDRAWABLE_DRAWABLE2Drawable *, a
pointer to a drawable to be drawn in. A `drawable' is either a
window or a pixmap. At the time an X Drawable Plotter is created,
at least one of the two parameters must be set.
X Drawable Plotters support simultaneous drawing in two drawables
because it is often useful to be able to draw graphics simultaneously in
both an X window and its background pixmap. If two drawables are
specified, they must have the same dimensions and depth, and be
associated with the same screen of the X display.
XDRAWABLE_VISUALVisual *, a pointer to the `visual' with
which the colormap (see above) is associated. Setting this parameter is
not required, but it is recommended that it be set if
XDRAWABLE_COLORMAP is set. Under some circumstances, that will
speed up color cell allocation.
X_AUTO_FLUSHXFlush operation is performed after each drawing operation.
That ensures that graphics are flushed to the X Window System
display, and are visible to the user, immediately after they are drawn.
However, it slows down rendering considerably. If the value is
"no", drawing is faster, since it does not take place in real time.