www.delorie.com/gnu/docs/plotutils/plotutils_66.html

search

	Buy GNU books!

The Plotutils Package

9.5 Plotter 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 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.

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 (i.e., the viewport) in terms of pixels. This is relevant only to X Plotters, PNG 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. 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.

PAGESIZE

(Default "letter".) The page type, which determines the size of the graphics display (i.e., the viewport) used by the Plotter. This is relevant only to SVG, Illustrator, Postscript, CGM, 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, 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 the default display size, SVG and CGM Plotters will use the graphics display size that is used by other Plotters.

For the default size and location of the graphics display for each page type, see C. Page Sizes and Viewport Sizes. You do not need to use the default graphics display, 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.

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 preceding options may be intermingled. 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.

ROTATION

(Default "0".) Relevant to all Plotters other than Metafile Plotters, which have no output device. The angle, in degrees, by which the graphics display (i.e., the viewport) should be rotated, relative to its default orientation. Recognized values are "0", "90", "180", and "270"; "no" and "yes" are equivalent to "0" and "90" respectively. The rotation is counterclockwise.

A 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_COLOR

(Default "white".) The initial background color of the graphics display, when drawing each page of graphics. This is relevant to X Plotters, PNG Plotters, PNM Plotters, GIF Plotters, CGM Plotters, ReGIS Plotters, and Metafile Plotters; also to X Drawable Plotters (for the last, the background color shows up only if erase is invoked). For information on what color names are recognized, see B. Specifying Colors by Name. 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_ENCODING

(Default "binary".) Relevant only to CGM Plotters. "binary" means that the CGM output should use the binary encoding. "clear_text" means that the CGM output should use a human-readable encoding. The WebCGM profile requires that the binary encoding be used, but many CGM viewers and interpreters can also parse the clear text encoding. The third standard CGM encoding, "character", is not currently supported.

CGM_MAX_VERSION

(Default "4".) Relevant only to CGM Plotters. An upper bound on the version number of CGM format that is produced. Many older CGM interpreters and viewers, such as the ones built into Microsoft Office and other commercial software, only support version 1 CGM files. For fully adequate handling of fonts and line styles, version 3 is necessary. By default, the present release of libplot produces version 3 CGM files, i.e., it does not use version 4 features.

EMULATE_COLOR

(Default "no".) Relevant to all Plotters. "yes" means that each color in the output should be replaced by an appropriate shade of gray. The well known formula for CIE luminance, namely 0.212671R + 0.715160G + 0.072169B, is used.

This 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_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. In particular, HP-GL/2 pen plotters do not. 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 B. 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 (i.e., the viewport) 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. "180" and "270" are supported only if HPGL_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_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 linewidth, 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).

INTERLACE

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

MAX_LINE_LENGTH

(Default "500".) The maximum number of defining points that a path may have, before it is flushed to the output 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 to be 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 metafile should use a portable (human-readable) encoding of graphics, rather than the default (binary) encoding. See section D. 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.

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 a string beginning with "xterm", "nxterm", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm, 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_COLOR

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

XDRAWABLE_VISUAL

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

(Default "yes".) Relevant only to X Plotters. If the value is "yes", an XFlush 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.

The following appendices contain supplementary information on the GNU plotting utilities and the GNU libplot library.

A. Fonts, Strings, and Symbols		Text fonts, text strings, and marker symbols
B. Specifying Colors by Name		Specifying colors by name
C. Page Sizes and Viewport Sizes		Specifying the size of an output page
D. The Graphics Metafile Format		The device-independent GNU metafile format
E. Obtaining Auxiliary Software		How to obtain auxiliary software
History and Acknowledgements		The contributors
Reporting Bugs		How to report bugs