9.4.3 Attribute-setting functions

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, miter limit, and transformation matrix. Text-related attributes include pen color, font name, font size, text angle, and transformation matrix.

Setting any path-related drawing attribute automatically terminates and draws the path under construction (if any), as if the endpath operation had been invoked. The `orientation' attribute (clockwise/counterclockwise), which affects circles, ellipses, and boxes, is an exception to this. The exception allows a compound path to include circles, ellipses, and boxes with different orientations.

In the current C binding, each of these functions takes a pointer to a plPlotter as its first argument. Also in the current C binding, the name of each function begins with "pl_" and ends with "_r". ("_r" stands for `revised' or `reentrant'.) For information on older C bindings, see Older C APIs. In the C++ binding, these are member functions of the Plotter class and its subclasses, and the prefix and suffix are not used.

int capmod (const char *s);

capmod terminates and draws the path under construction (if any), as if endpath had been called, and 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.

PNG, PNM, GIF, PCL, and HP-GL Plotters support a fourth cap mode, "triangular". (For all but PCL and HP-GL Plotters, the support is currently only partial.) Plotters other than these treat "triangular" as equivalent to "round".

This function has no effect on ReGIS or 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), or on CGM Plotters if the parameter CGM_MAX_VERSION is set to a value less than "3". See Plotter 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 level, 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 level, which is specified by calling filltype.

int fillcolor (int red, int green, int blue);

fillcolor terminates and draws the path under construction (if any), as if endpath had been called, and sets the fill color for all paths 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 level, which is specified by calling filltype.

int fillcolorname (const char *name);

fillcolorname sets the fill color of all paths subsequently drawn on the graphics display to be name. Unrecognized colors are interpreted as "black". For information on what color names are recognized, see Color Names. A 24-bit RGB color may also be specified as a six-digit hexadecimal string, e.g., "#c0c0c0".

Note that the physical fill color depends also on the fill level, which is specified by calling filltype.

int fillmod (const char *s);

fillmod terminates and draws the path under construction (if any), as if endpath had been called, and sets the fill mode, i.e., fill rule, for all paths subsequently drawn on the graphics display. The fill rule affects only compound paths and self-intersecting simple 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".

CGM, Fig, and ReGIS Plotters do not support the "nonzero-winding" rule, because the CGM, Fig, and ReGIS vector graphics formats do not support it. Also, HP-GL Plotters do not support "nonzero-winding" if HPGL_VERSION is set to a value less than "2" (the default). See Plotter 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 terminates and draws the path under construction (if any), as if endpath had been called, and sets the fill level for all subsequently drawn paths. A value of 0 for level specifies no filling. This is the default. A value of 1 specifies 100% filling: the fill color will be the color previously specified by calling fillcolor or fillcolorname.

As a convenience to the user, level may be set to any value in the range 0x0000...0xffff, i.e., 0...65535. Any nonzero value will produce filling. If level=0xffff, the fill color will be white. Values in the range 0x0001...0xffff are interpreted as specifying a desaturation, or gray level. For example, 0x8000 specifies 50% filling (the fill color will be half-way between the color specified by calling fillcolor or fillcolorname, and white).

To draw the region bounded by a path in an edgeless way, you would call filltype to turn on the filling of the interior, and pentype to turn off the drawing of the boundary.

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

int fmiterlimit (double limit);

fmiterlimit terminates and draws the path under construction (if any), as if endpath had been called, and 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, ReGIS, or Fig Plotters, or on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default). See Plotter Parameters. The miter limit used by HP-GL or PCL Plotters is always rounded to the closest integer, downward.

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 for PCL Plotters, for which it is "Univers", and PNG, PNM, GIF, HP-GL, ReGIS, 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 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. The interpretation of zero font size is also Plotter-dependent (most Plotters do not draw text strings if the font size is zero).

int joinmod (const char *s);

joinmod terminates and draws the path under construction (if any), as if endpath had been called, and 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.

PNG, PNM, GIF, PCL, and HP-GL Plotters support a fourth join mode, "triangular". Other Plotters treat "triangular" as equivalent to "round".

This function has no effect on ReGIS or 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), or on CGM Plotters if the parameter CGM_MAX_VERSION is set to a value less than "3". See Plotter Parameters.

int linedash (int n, const int *dashes, int offset);

int flinedash (int n, const double *dashes, double offset);

linedash and flinedash terminate and draw the path under construction (if any), as if endpath had been called, and set the line style for all paths 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. PCL and HP-GL Plotters cannot dash with a nonzero offset, and in the dash patterns used by X and X Drawable Plotters, each dash or gap has a maximum length of 255 pixels. linedash and flinedash have no effect at all on Tektronix, ReGIS, and Fig Plotters. Also, they have no effect on HP-GL Plotters for which the parameter HPGL_VERSION is less than "2" (the default), or on CGM Plotters for which the parameter CGM_MAX_VERSION is less than "3". For information on Plotter parameters, see Plotter Parameters.

Warning: If the transformation from the user coordinate system to the device coordinate system is anisotropic, each dash pattern should ideally be drawn on the graphics display with a length that depends on its direction. But currently, only SVG and Postscript Plotters do this. Other Plotters always draw any specified dash pattern 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 pattern length in the user coordinate system.

int linemod (const char *s);

linemod terminates and draws the path under construction (if any), as if endpath had been called, and sets the line style for all paths 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 are not filled; this includes circles and ellipses.

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

int linewidth (int size);

int flinewidth (double size);

linewidth and flinewidth terminate and draws the path under construction (if any), as if endpath had been called, and set the thickness, in the user coordinate system, of all paths 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 of the viewport, i.e., the drawn-on portion of the display. (Here `size' means minimum dimension.) But for Plotters that produce bitmaps, i.e., X Plotters, X Drawable Plotters, PNG 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 and ReGIS 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 Plotter Parameters).

Warning: If the transformation from the user coordinate system to the device coordinate system is anisotropic, 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 SVG and 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 specified line thickness 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 drawn, as if endpath had been called, 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.

When a new page of graphics is begun by invoking openpl, the cursor is initially at the point (0,0) in user space. Most of the drawing functions reposition the cursor. See Drawing Functions.

int orientation (int direction);

orientation sets the orientation for all circles, ellipses, and boxes subsequently drawn on the graphics display. direction must be 1, meaning counterclockwise, or −1, meaning clockwise. The default is 1.

orientation will have a visible effect on a circle, ellipse, or box only if it is dashed, or if it is one of the simple paths in a filled compound path. Its effects on filling, when the "nonzero-winding" fill rule is used, are dramatic, since it is the orientation of each simple path in a compound path that determines which points are `inside' and which are `outside'.

int pencolor (int red, int green, int blue);

pencolor terminates and draws the path under construction (if any), as if endpath had been called, and sets the pen color for 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 Plotter Parameters.

int pencolorname (const char *name);

pencolorname sets the pen color of all objects subsequently drawn on the graphics display to be name. Unrecognized colors are interpreted as "black". For information on what color names are recognized, see Color Names. A 24-bit RGB color may also be specified as a six-digit hexadecimal string, e.g., "#c0c0c0".

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

int pentype (int level);

pentype terminates and draws the path under construction (if any), as if endpath had been called, and sets the pen level for all subsequently drawn paths. A value of 1 for level specifies that an outline of each of these objects should be drawn, in the color previously specified by calling pencolor or pencolorname. This is the default. A value of 0 specifies that outlines should not be drawn.

To draw the region bounded by a path in an edgeless way, you would call pentype to turn off the drawing of the boundary, and filltype to turn on the filling of the interior.

pentype also affects the drawing of marker symbols and points, i.e., pixels. A value of 0 specifies that they should not be drawn.

Note: In future releases, pentype may also affect the drawing of text strings (a value of 0 will specify that they should not be drawn). It already affects text strings that are rendered using Hershey fonts, since they are drawn using polygonal paths.

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 and draw 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. The new graphics context created by savestate will contain no path. When the previous graphics context is returned to by calling restorestate, the path previously 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.

Warning: Some X Window System displays do not generate or display rotated fonts correctly. In effect, they only support a zero rotation angle.