Go to the first, previous, next, last section, table of contents.
The following are the "attribute functions" in libplot. When
invoked on a Plotter, these functions set its drawing attributes, or
save them or restore them. Path-related attributes include graphics
cursor position, pen color, fill color, fill rule, line thickness, line
style, cap style, join style, and miter limit. Text-related attributes
include pen color, font name, font size, and text angle.
Setting any path-related drawing attribute automatically terminates the
path under construction (if any), as if the endpath
operation had been invoked.
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 capmod (const char *s);
-
capmod sets the cap mode (i.e., cap style) for all paths
subsequently drawn on the graphics display. Recognized styles are
"butt" (the default), "round", and "projecting". The three styles are
visibly distinct only if the line thickness is fairly large. Butt caps
do not extend beyond the end of the path. The other two kinds do,
however. Round caps are filled semicircles, and projecting caps are
filled rectangular regions that extend a distance equal to half the line
width beyond the end of the path.
PCL and HP-GL Plotters support a fourth cap mode, "triangular".
Plotters other than PCL and HP-GL Plotters treat "triangular" as
equivalent to "round".
This function has no effect on Tektronix Plotters. Also, it has no
effect on HP-GL Plotters if the parameter
HPGL_VERSION is set to
a value less than "2" (the default). See section Device driver parameters.
- int color (int red, int green, int blue);
-
color is a convenience function. Calling color is equivalent to
calling both pencolor and fillcolor, to set both the the pen
color and fill color of all objects subsequently drawn on the graphics
display. Note that the physical fill color depends also on the fill
fraction, which is specified by calling filltype.
- int colorname (const char *name);
-
colorname is a convenience function. Calling colorname is
equivalent to calling both pencolorname and fillcolorname, to
set both the the pen color and fill color of all objects subsequently
drawn on the graphics display. Note that the physical fill color
depends also on the fill fraction, which is specified by calling
filltype.
- int fillcolor (int red, int green, int blue);
-
fillcolor sets the fill color of all objects subsequently drawn on
the graphics display, using a 48-bit RGB color model. The arguments
red, green and blue specify the red, green and blue
intensities of the fill 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.
Note that the physical fill color depends also on the fill fraction,
which is specified by calling filltype.
- int fillcolorname (const char *name);
-
fillcolorname sets the fill color of all objects subsequently drawn
on 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 "black". Note that the physical fill color depends also
on the fill fraction, which is specified by calling filltype.
- int fillmod (const char *s);
-
fillmod sets the fill mode, i.e., fill rule, for all objects
subsequently drawn on the graphics display. The fill rule affects only
filled, self-intersecting paths: it determines which points are
`inside'. Two rules are supported: "even-odd" (the default for all
Plotters), and "nonzero-winding". For the distinction, see the
Postscript Language Reference Manual. "alternate" is an alias
for "even-odd" and "winding" is an alias for "nonzero-winding".
Fig Plotters do not support the "nonzero-winding" fill rule, because
xfig itself does not support it. Also, HPGL Plotters do not
support it if HPGL_VERSION is set to a value less than "2" (the
default). See section Device driver parameters.
The LaserJet III, which was Hewlett--Packard's first PCL 5 printer,
did not support the nonzero-winding fill rule. However, all later
PCL 5 printers from Hewlett--Packard support it.
- int filltype (int level);
-
filltype sets the fill fraction for all subsequently drawn objects.
A value of 0 for level indicates that objects should be
unfilled, or transparent. This is the default. A value in the
range 0x0001...0xffff, i.e., 1...65535, indicates that
objects should be filled. A value of 1 signifies 100% filling
(the fill color will simply be the color specified by calling
fillcolor or fillcolorname). If level=0xffff, the
fill color will be white. Values between 0x0001 and 0xffff are
interpreted as specifying a desaturation, or gray level. For
example, 0x8000 specifies 50% filling (the fill color will be
intermediate between the color specified by calling fillcolor or
fillcolorname, and white).
Tektronix Plotters do not support filling, and HP-GL Plotters support
filling of arbitrary paths only if the parameter
HPGL_VERSION is
equal to "1.5" or "2" (the default). (If the version is "1"
then only circles and rectangles aligned with the coordinate axes may be
filled.) Opaque filling, including white filling, is supported
only if the parameter HPGL_VERSION is "2" and the parameter
HPGL_OPAQUE_MODE is "yes" (the default). See section Device driver parameters.
- int fmiterlimit (double limit);
-
fmiterlimit sets the miter limit for all paths subsequently drawn on
the graphics display. The miter limit controls the treatment of
corners, if the join mode is set to "miter" (the default). At a
join point of a path, the `miter length' is defined to be the distance
between the inner corner and the outer corner. The miter limit is the
maximum value that will be tolerated for the miter length divided by the
line thickness. If this value is exceeded, the miter will be cut
off: the "bevel" join mode will be used instead.
Examples of typical values for limit are 10.43 (the default, which
cuts off miters if the join angle is less than 11 degrees), 2.0 (the
same, for 60 degrees), and 1.414 (the same, for 90 degrees). In
general, the miter limit is the cosecant of one-half the minimum angle
for mitered joins. The minimum meaningful value for limit is
1.0, which converts all mitered joins to beveled joins, irrespective of
join angle. Specifying a value less than 1.0 resets the limit to the
default.
This function has no effect on X Drawable Plotters or X
Plotters, since the X Window System miter limit, which is also
10.43, cannot be altered. It also has no effect on Tektronix Plotters
or Fig Plotters, or on HP-GL Plotters if the parameter
HPGL_VERSION is set to a value less than "2" (the default).
See section Device driver parameters.
- int fontname (const char *font_name);
-
- double ffontname (const char *font_name);
-
fontname and ffontname take a single case-insensitive string
argument, font_name, specifying the name of the font to be used
for all text strings subsequently drawn on the graphics display. (The
font for plotting strings is fully specified by calling fontname,
fontsize, and textangle.) The size of the font in user
coordinates is returned.
The default font name depends on the type of Plotter. It is
"Helvetica" for all Plotters except PNM, GIF, HP-GL, Tektronix and
Metafile Plotters, for which it is "HersheySerif". If the argument
font_name is NULL or the empty string, or the font is not
available, the default font name will be used. Which fonts are
available also depends on the type of Plotter; for a list of all
available fonts, see section Available text fonts.
- int fontsize (int size);
-
- double ffontsize (double size);
-
fontsize and ffontsize take a single argument, interpreted as
the size, in the user coordinate system, of the font to be used for all
text strings subsequently drawn on the graphics display. (The font for
plotting strings is fully specified by calling fontname,
fontsize, and textangle.) The size of the font in user
coordinates is returned. A negative value for size sets the
size to the default, which depends on the type of Plotter. Typically,
the default font size is 1/50 times the size (i.e., minimum dimension)
of the display.
- int joinmod (const char *s);
-
joinmod sets the join mode (i.e., join style) for all paths
subsequently drawn on the graphics display. Recognized styles are
"miter" (the default), "round", and "bevel". The three styles are
visibly distinct only if the line thickness is fairly large. Mitered
joins are sharp, rounded joins are round, and beveled joins are
squared off. However, unusually sharp joins are never mitered:
instead, they are beveled. The angle at which beveling replaces
mitering may be specified by calling fmiterlimit.
PCL and HP-GL Plotters support a fourth join mode, "triangular".
Plotters other than PCL and HP-GL Plotters treat "triangular" as
equivalent to "round".
This function has no effect on Tektronix Plotters. Also, it has no
effect on HP-GL Plotters if the parameter
HPGL_VERSION is set to
a value less than "2" (the default). See section Device driver parameters.
- int linedash (int n, const int *dashes, int offset);
-
- int flinedash (int n, const double *dashes, double offset);
-
linedash and flinedash set the line style for all paths,
circles, and ellipses subsequently drawn on the graphics display. They
provide much finer control of dash patterns than the linemod
function (see below) provides. dashes should be an array of
length n. Its elements, which should be positive, are
interpreted as distances in the user coordinate system. Along any path,
circle, or ellipse, the elements
dashes[0]...dashes[n-1] alternately specify the
length of a dash and the length of a gap between dashes. When the end
of the array is reached, the reading of the array wraps around to the
beginning. If the array is empty, i.e., n equals zero, there is
no dashing: the drawn line is solid.
The offset argument specifies the `phase' of the dash pattern
relative to the start of the path. It is interpreted as the distance
into the dash pattern at which the dashing should begin. For example,
if offset equals zero then the path will begin with a dash, of
length dashes[0] in user space. If offset equals
dashes[0] then the path will begin with a gap of length
dashes[1], and so forth. offset is allowed to be
negative.
Not all Plotters fully support linedash and flinedash. HP-GL
and PCL Plotters cannot dash with a nonzero offset, and in the dash
patterns used by X and X Drawable Plotters, each dash and each
gap has a maximum length of 255 pixels. linedash and flinedash
have no effect on Tektronix and Fig Plotters, and they have no effect on
HP-GL Plotters for which the parameter
HPGL_VERSION is less
than "2" (the default; see section Device driver parameters).
Warning: If the map from the user coordinate system to the
device coordinate system is not uniform, each dash in a dashed path
should ideally be drawn on the graphics display with a length that
depends on its direction. But currently, only Postscript Plotters do
this. Other Plotters always draw any specified dash with the same
length, irrespective of its direction. The length that is used is the
minimum length, in the device coordinate system, that can correspond to
the specified dash length in the user coordinate system.
- int linemod (const char *s);
-
linemod sets the line style for all paths, circles, and ellipses
subsequently drawn on the graphics display. The supported line styles
are "solid", "dotted", "dotdashed", "shortdashed", "longdashed",
"dotdotdashed", "dotdotdotdashed", and "disconnected". The first seven
correspond to the following dash patterns:
"solid" --------------------------------
"dotted" - - - - - - - -
"dotdashed" ---- - ---- - ---- -
"shortdashed" ---- ---- ---- ----
"longdashed" ------- ------- -------
"dotdotdashed" ---- - - ---- - -
"dotdotdotdashed" ---- - - - ---- - - -
In the preceding patterns, each hyphen stands for one line
thickness. This is the case for sufficiently thick lines, at least.
So for sufficiently thick lines, the distance over which a dash
pattern repeats is scaled proportionately to the line thickness.
The "disconnected" line style is special. A "disconnected" path is
rendered as a set of filled circles, each of which has diameter equal to
the nominal line thickness. One of these circles is centered on each of
the juncture points of the path (i.e., the endpoints of the line
segments or arcs from which it is constructed). Circles and ellipses
with "disconnected" line style are invisible. Disconnected paths,
circles, and ellipses are not filled.
All line styles are supported by all Plotters, with the following
exceptions. HP-GL Plotters do not support the "dotdotdotdashed" style
unless the parameter HPGL_VERSION is set to "2" (the default).
Tektronix Plotters do not support the "dotdotdotdashed" style, and do
not support the "dotdotdashed" style unless the parameter TERM is
set to "kermit". See section Device driver parameters.
- int linewidth (int size);
-
- int flinewidth (double size);
-
linewidth and flinewidth set the thickness, in the user
coordinate system, of all paths, circles, and ellipses subsequently
drawn on the graphics display. A negative value resets the
thickness to the default. The default thickness depends on the type of
Plotter. For most Plotters, it is 1/850 times the size (i.e., minimum
dimension) of the display. But for Plotters that produce bitmaps, i.e.,
X Plotters, X Drawable Plotters, PNM Plotters, and GIF Plotters,
it is zero.
By convention, a zero-thickness line is the thinnest line that can be
drawn. However, the drawing editors
idraw and xfig treat
zero-thickness lines as invisible. So when producing editable
graphics with a Postscript or Fig Plotter, using a zero line thickness
may not be desirable.
Tektronix Plotters do not support drawing with other than a default
thickness, and HP-GL Plotters do not support doing so if the parameter
HPGL_VERSION is set to a value less than "2" (the default;
see section Device driver parameters).
Warning: If the map from the user coordinate system to the
device coordinate system is not uniform, each line segment in a
polygonal path should ideally be drawn on the graphics display with a
thickness that depends on its direction. But currently, only Postscript
Plotters do this. Other Plotters draw all line segments in a path
with the same thickness. The thickness that is used is the minimum
thickness, in the device coordinate system, that can correspond to the
thickness of the path in the user coordinate system.
- int move (int x, int y);
-
- int fmove (double x, double y);
-
- int moverel (int x, int y);
-
- int fmoverel (double x, double y);
-
move and fmove take two arguments specifying the coordinates
(x, y) of a point to which the graphics cursor should be
moved. The path under construction (if any) is ended, and the
graphics cursor is moved to (x, y). This is equivalent to
lifting the pen on a plotter and moving it to a new position, without
drawing any line. moverel and fmoverel are similar to move
and fmove, but use cursor-relative coordinates.
- int pencolor (int red, int green, int blue);
-
pencolor sets the pen color of all objects subsequently drawn on the
graphics display, using a 48-bit RGB color model. The arguments
red, green and blue specify the red, green and blue
intensities of the pen 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.
HP-GL Plotters support drawing with a white pen only if the value of the
parameter
HPGL_VERSION is "2" (the default), and the value of
the parameter HPGL_OPAQUE_MODE is "yes" (the default).
See section Device driver parameters.
- int pencolorname (const char *name);
-
pencolorname sets the pen color of all objects subsequently drawn on
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 "black".
HP-GL Plotters support drawing with a white pen only if the value of the
parameter
HPGL_VERSION is "2" (the default) and the value of
the parameter HPGL_OPAQUE_MODE is "yes" (the default).
See section Device driver parameters.
- int restorestate ();
-
restorestate pops the current graphics context off the stack of
drawing states. The graphics context consists largely of
libplot's drawing attributes, which are set by the attribute
functions documented in this section. So popping off the graphics
context restores the drawing attributes to values they previously had.
A path under construction is regarded as part of the graphics
context. For this reason, calling restorestate automatically calls
endpath to terminate the path under construction, if any. All
graphics contexts on the stack are popped off when closepl is
called, as if restorestate had been called repeatedly.
- int savestate ();
-
savestate pushes the current graphics context onto the stack of
drawing states. The graphics context consists largely of
libplot's drawing attributes, which are set by the attribute
functions documented in this section. A path under construction,
if any, is regarded as part of the graphics context. That is
because paths may be drawn incrementally, one line segment or arc at a
time. When a graphics context is returned to, the path under
construction may be continued.
- int textangle (int angle);
-
- double ftextangle (double angle);
-
textangle and ftextangle take one argument, which specifies the
angle in degrees counterclockwise from the x (horizontal) axis in
the user coordinate system, for text strings subsequently drawn on the
graphics display. The default angle is zero. (The font for plotting
strings is fully specified by calling fontname, fontsize, and
textangle.) The size of the font for plotting strings, in user
coordinates, is returned.
Go to the first, previous, next, last section, table of contents.