Device driver parameters

In designing the libplot library, every effort was made to make the Plotter interface independent of the type of Plotter. To the extent that device dependence exists, it is captured by a manageable number of device driver parameters.

In the C binding, a value for any parameter may be specified by calling the pl_parampl function. The pl_parampl function does not operate on any particular Plotter: it belongs to the C binding as a whole. The parameter values used by any Plotter are constant over the lifetime of the Plotter, and are those that were in effect when the Plotter was created. Each driver parameter has a value that is allowed to be a generic pointer (a void *). For most parameters, this value should be a string (a char *). pl_parampl may be called any number of times. A parameter may be unset by calling pl_parampl with a value argument of NULL.

If at Plotter creation time a parameter is not set, 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 driver parameters to be specified by the user via environment variables.

In the C++ binding, the function Plotter::parampl is the analogue of pl_parampl. It is a static member of the Plotter class and its subclasses. Like pl_parampl, it does not act on any particular Plotter: rather, it sets the parameters of subsequently created Plotters.

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, PNM Plotters, and GIF Plotters, and PAGESIZE, which affects Illustrator, Postscript, Fig, and HP-GL Plotters. These three parameters are listed first and the others alphabetically. Many of the parameters, such as the several whose names begin with "HPGL", affect only a single type of Plotter.

DISPLAY

(Default NULL.) The X Window System display on which the graphics display will be popped up, as an X window. This is relevant only to X Plotters.

BITMAPSIZE

(Default "570x570".) The size of the graphics display in terms of pixels. This is relevant only to X Plotters, PNM Plotters, and GIF Plotters. For X Plotters, the value of this parameter will automatically, if it is not set, be taken from the X resource Xplot.geometry. This is for backward compatibility.

PAGESIZE

(Default "letter".) The size of the page on which the graphics display will be positioned. This is relevant only to Illustrator, Postscript, Fig, PCL, and HP-GL Plotters. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. For Illustrator and Postscript Plotters, the graphics display will be a square region centered on the specified page and occupying its full width, with allowance being made for margins. For Fig Plotters, the graphics display will be a square region of the same size, positioned in the upper left corner of an xfig display. For PCL and HP-GL Plotters, the graphics display will be a square region of the same size, but may be positioned differently. For PCL Plotters, fine control over its positioning on the page may be accomplished by setting the PCL_XOFFSET and PCL_YOFFSET parameters. For HP-GL Plotters, HPGL_XOFFSET and HPGL_YOFFSET are used similarly.

BG_COLOR

(Default "white".) The initial background color of the graphics display, when drawing each page of graphics. This is relevant to X Plotters, PNM Plotters, GIF Plotters, and X Drawable Plotters (for the last, the background color shows up only if erase is invoked). The background color may be changed at any later time by invoking the bgcolor (or bgcolorname) and erase operations. An unrecognized color name sets the background color to the default. For information on what names are recognized, see section Specifying Colors by Name.

GIF_ANIMATION

(Default "yes".) Relevant only to GIF Plotters. "yes" means that the erase 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_DELAY

(Default "0".) Relevant only to GIF Plotters. The delay, in hundredths of a second, after each image in a written-out animated pseudo-GIF file. The value should be an integer in the range "0"..."65535".

GIF_ITERATIONS

(Default "0".) Relevant only to GIF Plotters. The number of times that an animated pseudo-GIF file should be `looped'. The value should be an integer in the range "0"..."65535".

HPGL_ASSIGN_COLORS

(Default "no".) Relevant only to HP-GL Plotters, and only if the value of HPGL_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. So this parameter should be used with caution.

HPGL_OPAQUE_MODE

(Default "yes".) Relevant only to HP-GL Plotters, and only if the value of HPGL_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_PENS

(Default "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan" if the value of HPGL_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 section Specifying Colors by Name. Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.

HPGL_ROTATE

(Default "0".) Relevant only to HP-GL Plotters. The angle, in degrees, by which the graphics display should be rotated on the page relative to the default orientation. Recognized values are "0", "90", "180", and "270"; "no" and "yes" are equivalent to "0" and "90" respectively. This parameter is provided to facilitate switching between portrait and landscape orientations. For HP-GL devices this is frequently a concern, since some HP-GL devices ("plotters") draw with a default landscape orientation, and others ("printers") draw with a default portrait orientation. "180" and "270" are supported only if HPGL_VERSION is "2".

HPGL_VERSION

(Default "2".) Relevant only to HP-GL Plotters. "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is less than "2" then the only available fonts will be vector fonts, and all paths will be drawn with a default thickness, so that invoking capmod, joinmod, and fmiterlimit will have no effect. Also, the `nonzero winding number rule' will not be supported when filling paths, so invoking fillmod will have no effect. Additionally, if the version is "1" then the filling of arbitrary paths will not be supported (circles and rectangles aligned with the coordinate axes may be filled, however).

HPGL_XOFFSET, HPGL_YOFFSET

(Defaults "0.0cm" and "0.0cm".) Relevant only to HP-GL Plotters. Adjustments, in the x and y directions, of the position of the graphics display on the page. They may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in".

INTERLACE

(Default "no".) Relevant only to GIF Plotters. If the value is "yes", the pseudo-GIF output file will be interlaced. That means that it will be displayed in an interlaced (nonlinear) way by many applications.

MAX_LINE_LENGTH

(Default "500".) The maximum number of points that a path may contain, before it is flushed to the display device. If this flushing occurs, the path will be split into two or more sub-paths, though the splitting should not be noticeable. Splitting will not be performed if the path is filled. This 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_PORTABLE

(Default "no".) Relevant only to Metafile Plotters. "yes" means that the output should be in a portable (human-readable) version of the metafile format, rather than the default (binary) version. See section The Graphics Metafile Format.

PCL_ASSIGN_COLORS

(Default "no".) Relevant only to PCL Plotters. "no" means to draw with a fixed set of pens. "yes" means that pen colors will not restricted to this palette: colors will be assigned to "logical pens", as needed. Other than color LaserJet printers, not many PCL 5 devices allow the assignment of colors to logical pens. So this parameter should be used with caution.

PCL_BEZIERS

(Default "yes".) Relevant only to PCL Plotters. "yes" means that when drawing Bezier curves, the special `Bezier instructions' will be used. "no" means that these instructions will not be used. Instead, each Bezier curve will be approximated and drawn as a polygonal line. Other than the LaserJet III, which was Hewlett--Packard's first PCL 5 printer, all Hewlett--Packard's PCL 5 printers support the Bezier instructions.

PCL_ROTATE

(Default "0".) Relevant only to PCL Plotters. The angle, in degrees, by which the graphics display should be rotated on the page relative to the default orientation. Recognized values are "0", "90", "180", and "270"; "no" and "yes" are equivalent to "0" and "90" respectively. This parameter is provided to facilitate switching between portrait and landscape orientations. For PCL 5 devices this is frequently a concern, since some PCL 5 devices ("plotters") draw with a default landscape orientation, and others ("printers") draw with a default portrait orientation.

PCL_XOFFSET, PCL_YOFFSET

(Defaults "0.0cm" and "0.0cm".) Relevant only to PCL Plotters. Adjustments, in the x and y directions, of the position of the graphics display on the page. They may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in".

PNM_PORTABLE

(Default "no".) Relevant only to PNM Plotters. "yes" means that the output should be in a portable (human-readable) version of PBM/PGM/PPM format, rather than the default (binary) version. `Portable' is something of a misnomer, since binary PBM/PGM/PPM files are also portable, in the sense that they are machine-independent.

TERM

(Default NULL.) Relevant only to Tektronix Plotters. If the value is "xterm", "xterms", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm. 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 "kermit", "ansi.sys", "ansissys", "ansi.sysk", or "ansisysk", 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_COLOR

(Default "none".) Relevant only to GIF Plotters. If the value is a recognized color name, that color, if it appears in the pseudo-GIF output file, will be treated as transparent by most applications that display GIF files. For information on what names are recognized, see section Specifying Colors by Name. If 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_BUFFERING

(Default "no".) Relevant only to X Plotters and X Drawable Plotters. If the value is "yes", a double buffering scheme will be used when drawing graphics. Each frame of graphics, within a openpl...closepl pair, will be written to an off-screen buffer rather than to the Plotter's display. When erase is invoked to end a frame, or when closepl is invoked, the contents of the off-screen buffer will be copied to the Plotter's display, pixel by pixel. If successive frames differ only slightly, this will create the illusion of smooth animation. Some 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_DELETE

(Default "no".) Relevant only to X Plotters. If the value is "yes", when a Plotter is deleted, the window or windows that it has popped up will vanish. Otherwise, each such window will remain on the screen until it is removed by the user (by typing `q' in it, or by clicking with a mouse).

XDRAWABLE_COLORMAP

(Default NULL.) Relevant only to X Drawable Plotters. If the value is non-NULL, it should be a Colormap *, 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_DISPLAY

(Default NULL.) Relevant only to X Drawable Plotters. The value should be a Display *, a pointer to the X display with which the drawable(s) to be drawn in are associated.

XDRAWABLE_DRAWABLE1

XDRAWABLE_DRAWABLE2

(Default NULL.) Relevant only to X Drawable Plotters. If set, the value of each of these parameters should be a Drawable *, 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.

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