The Plotutils Package - Drawing Functions

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

### Object-drawing functions

The following are the "drawing functions" in `libplot`. When invoked on a Plotter, these functions cause it to draw objects (paths, circles, ellipses, points, markers, and text strings) on the associated graphics display. A path is a sequence of line segments, arc segments (either circular or elliptic), and/or Bezier curve segments (either quadratic or cubic). Paths are drawn incrementally, one segment at a time.

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 `alabel` (int horiz_justify, int vert_justify, const char *s);
  `alabel` takes three arguments horiz_justify, vert_justify, and s, which specify an `adjusted label,' i.e., a justified text string. The path under construction (if any) is ended, and the string s is drawn according to the specified justifications. If horiz_justify is equal to ``l'`, ``c'`, or ``r'`, then the string will be drawn with left, center or right justification, relative to the current graphics cursor position. If vert_justify is equal to ``b'`, ``x'`, ``c'`, or ``t'`, then the bottom, baseline, center or top of the string will be placed even with the current graphics cursor position. The graphics cursor is moved to the right end of the string if left justification is specified, and to the left end if right justification is specified. The string may contain escape sequences of various sorts (see section Text string format and escape sequences), though it should not contain line feeds or carriage returns. In fact it should include only printable characters, from the byte ranges `0x20`...`0x7e` and `0xa0`...`0xff`. The string may be plotted at a nonzero angle, if `textangle` has been called.
int `arc` (int xc, int yc, int x0, int y0, int x1, int y1);
int `farc` (double xc, double yc, double x0, double y0, double x1, double y1);
int `arcrel` (int xc, int yc, int x0, int y0, int x1, int y1);
int `farcrel` (double xc, double yc, double x0, double y0, double x1, double y1);
  `arc` and `farc` take six arguments specifying the beginning (x0, y0), end (x1, y1), and center (xc, yc) of a circular arc. If the graphics cursor is at (x0, y0) and a path is under construction, then the arc is added to the path. Otherwise the current path (if any) is ended, and the arc begins a new path. In all cases the graphics cursor is moved to (x1, y1). The direction of the arc (clockwise or counterclockwise) is determined by the convention that the arc, centered at (xc, yc), sweep through an angle of at most 180 degrees. If the three points appear to be collinear, the direction is taken to be counterclockwise. If (xc, yc) is not equidistant from (x0, y0) and (x1, y1) as it should be, it is corrected by being moved to the closest point on the perpendicular bisector of the line segment joining (x0, y0) and (x1, y1). `arcrel` and `farcrel` are similar to `arc` and `farc`, but use cursor-relative coordinates.
int `bezier2` (int x0, int y0, int x1, int y1, int x2, int y2);
int `fbezier2` (double x0, double y0, double x1, double y1, double x2, double y2);
int `bezier2rel` (int x0, int y0, int x1, int y1, int x2, int y2);
int `fbezier2rel` (double x0, double y0, double x1, double y1, double x2, double y2);
  `bezier2` and `fbezier2` take six arguments specifying the beginning `p0`=(x0, y0) and end `p2`=(x2, y2) of a quadratic Bezier curve, and its intermediate control point `p1`=(x1, y1). If the graphics cursor is at `p0` and a path is under construction, then the curve is added to the path. Otherwise the current path (if any) is ended, and the curve begins a new path. In all cases the graphics cursor is moved to `p2`. `bezier2rel` and `fbezier2rel` are similar to `bezier2` and `fbezier2`, but use cursor-relative coordinates. The quadratic Bezier curve is tangent at `p0` to the line segment joining `p0` to `p1`, and is tangent at `p2` to the line segment joining `p1` to `p2`. So it fits snugly into a triangle with vertices `p0`, `p1`, and `p2`. When using a PCL Plotter to draw Bezier curves on a LaserJet III, you should set the parameter `PCL_BEZIERS` to "no". That is because the LaserJet III, which was Hewlett--Packard's first PCL 5 printer, does not recognize the Bezier instructions supported by later PCL 5 printers. See section Device driver parameters.
int `bezier3` (int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
int `fbezier3` (double x0, double y0, double x1, double y1, double x2, double y2, double x3, double y3);
int `bezier3rel` (int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
int `fbezier3rel` (double x0, double y0, double x1, double y1, double x2, double y2, double x3, double y3);
  `bezier3` and `fbezier3` take eight arguments specifying the beginning `p0`=(x0, y0) and end `p3`=(x3, y3) of a cubic Bezier curve, and its intermediate control points `p1`=(x1, y1) and `p2`=(x2, y2). If the graphics cursor is at `p0` and a path is under construction, then the curve is added to the path. Otherwise the current path (if any) is ended, and the curve begins a new path. In all cases the graphics cursor is moved to `p3`. `bezier3rel` and `fbezier3rel` are similar to `bezier3` and `fbezier3`, but use cursor-relative coordinates. The cubic Bezier curve is tangent at `p0` to the line segment joining `p0` to `p1`, and is tangent at `p3` to the line segment joining `p2` to `p3`. So it fits snugly into a quadrangle with vertices `p0`, `p1`, `p2`, and `p3`. When using a PCL Plotter to draw Bezier curves on a LaserJet III, you should set the parameter `PCL_BEZIERS` to "no". That is because the LaserJet III, which was Hewlett--Packard's first PCL 5 printer, does not recognize the Bezier instructions supported by later PCL 5 printers. See section Device driver parameters.
int `box` (int x1, int y1, int x2, int y2);
int `fbox` (double x1, double y1, double x2, double y2);
int `boxrel` (int x1, int y1, int x2, int y2);
int `fboxrel` (double x1, double y1, double x2, double y2);
  `box` and `fbox` take four arguments specifying the lower left corner (x1, y1) and upper right corner (x2, y2) of a `box', or rectangle. The path under construction (if any) is ended, and the box is drawn as a new path. This path is also ended, and the graphics cursor is moved to the midpoint of the box. `boxrel` and `fboxrel` are similar to `box` and `fbox`, but use cursor-relative coordinates.
int `circle` (int xc, int yc, int r);
int `fcircle` (double xc, double yc, double r);
int `circlerel` (int xc, int yc, int r);
int `fcirclerel` (double xc, double yc, double r);
  `circle` and `fcircle` take three arguments specifying the center (xc, yc) and radius (r) of a circle. The path under construction (if any) is ended, and the circle is drawn. The graphics cursor is moved to (xc, yc). `circlerel` and `fcirclerel` are similar to `circle` and `fcircle`, but use cursor-relative coordinates for xc and yc.
int `cont` (int x, int y);
int `fcont` (double x, double y);
int `contrel` (int x, int y);
int `fcontrel` (double x, double y);
  `cont` and `fcont` take two arguments specifying the coordinates (x, y) of a point. If a path is under construction, the line segment from the current graphics cursor position to the point (x, y) is added to it. Otherwise the line segment begins a new path. In all cases the graphics cursor is moved to (x, y). `contrel` and `fcontrel` are similar to `cont` and `fcont`, but use cursor-relative coordinates.
int `ellarc` (int xc, int yc, int x0, int y0, int x1, int y1);
int `fellarc` (double xc, double yc, double x0, double y0, double x1, double y1);
int `ellarcrel` (int xc, int yc, int x0, int y0, int x1, int y1);
int `fellarcrel` (double xc, double yc, double x0, double y0, double x1, double y1);
  `ellarc` and `fellarc` take six arguments specifying the three points `pc`=(xc,yc), `p0`=(x0,y0), and `p1`=(x1,y1) that define a so-called quarter ellipse. This is an elliptic arc from `p0` to `p1` with center `pc`. If the graphics cursor is at point `p0` and a path is under construction, the quarter-ellipse is added to it. Otherwise the path under construction (if any) is ended, and the quarter-ellipse begins a new path. In all cases the graphics cursor is moved to `p1`. The quarter-ellipse is an affinely transformed version of a quarter circle. It is drawn so as to have control points `p0`, `p1`, and `p0`+`p1`-`pc`. This means that it is tangent at `p0` to the line segment joining `p0` to `p0`+`p1`-`pc`, and is tangent at `p1` to the line segment joining `p1` to `p0`+`p1`-`pc`. So it fits snugly into a triangle with these three control points as vertices. Notice that the third control point is the reflection of `pc` through the line joining `p0` and `p1`. `ellarcrel` and `fellarcrel` are similar to `ellarc` and `fellarc`, but use cursor-relative coordinates.
int `ellipse` (int xc, int yc, int rx, int ry, int angle);
int `fellipse` (double xc, double yc, double rx, double ry, double angle);
int `ellipserel` (int xc, int yc, int rx, int ry, int angle);
int `fellipserel` (double xc, double yc, double rx, double ry, double angle);
  `ellipse` and `fellipse` take five arguments specifying the center (xc, yc) of an ellipse, the lengths of its semiaxes (rx and ry), and the inclination of the first semiaxis in the counterclockwise direction from the x axis in the user coordinate system. The path under construction (if any) is ended, and the ellipse is drawn. The graphics cursor is moved to (xc, yc). `ellipserel` and `fellipserel` are similar to `ellipse` and `fellipse`, but use cursor-relative coordinates.
int `endpath` ();
  `endpath` terminates the path under construction, if any. A path is constructed by one or more successive calls to `cont`, `line`, `arc`, `ellarc`, `bezier2`, `bezier3`, and/or their floating-point counterparts. The path will also be terminated if any non-path object is drawn, if any path-related drawing attribute is set, or if `move` or `fmove` is invoked to set the cursor position. So `endpath` is almost redundant. However, if a Plotter plots objects in real time, calling `endpath` will ensure that a constructed path is drawn on the graphics display without delay.
int `label` (const char *s);
  `label` takes a single string argument s and draws the text contained in s at the current graphics cursor position. The text is left justified, and the graphics cursor is moved to the right end of the string. This function is provided for backward compatibility; the function call `label`(s) is equivalent to `alabel`(`l',`x',s).
int `labelwidth` (const char *s);
double `flabelwidth` (const char *s);
  `labelwidth` and `flabelwidth` compute and return the width of a string in the current font, in the user coordinate system. The string is not plotted.
int `line` (int x1, int y1, int x2, int y2);
int `fline` (double x1, double y1, double x2, double y2);
int `linerel` (int x1, int y1, int x2, int y2);
int `flinerel` (double x1, double y1, double x2, double y2);
  `line` and `fline` take four arguments specifying the start point (x1, y1) and end point (x2, y2) of a line segment. If the graphics cursor is at (x1, y1) and a path is under construction, the line segment is added to it. Otherwise the path under construction (if any) is ended, and the line segment begins a new path. In all cases the graphics cursor is moved to (x2, y2). `linerel` and `flinerel` are similar to `line` and `fline`, but use cursor-relative coordinates.
int `marker` (int x, int y, int type, int size);
int `fmarker` (double x, double y, int type, double size);
int `markerrel` (int x, int y, int type, int size);
int `fmarkerrel` (double x, double y, int type, double size);
  `marker` and `fmarker` take four arguments specifying the location (x,y) of a marker symbol, its type, and its size in user coordinates. The path under construction (if any) is ended, and the marker symbol is plotted. The graphics cursor is moved to (x,y). `markerrel` and `fmarkerrel` are similar to `marker` and `fmarker`, but use cursor-relative coordinates for the position (x,y). Marker symbol types 0 through 31 are taken from a standard set, and marker symbol types 32 and above are interpreted as the index of a character in the current text font. See section Available marker symbols.
int `point` (int x, int y);
int `fpoint` (double x, double y);
int `pointrel` (int x, int y);
int `fpointrel` (double x, double y);
  `point` and `fpoint` take two arguments specifying the coordinates (x, y) of a point. The path under construction (if any) is ended, and the point is plotted. (Plotters that produce bitmaps draw points as single pixels. Other Plotters draw them as small solid circles, usually the smallest that can be plotted.) The graphics cursor is moved to (x, y). `pointrel` and `fpointrel` are similar to `point` and `fpoint`, but use cursor-relative coordinates.

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