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.