libplg is a compact C function library for displaying vector graphics and text.
Intent is for results to be essentially equivalent regardless of output device (GIF, PNG, PostScript, EPS, SVG, SWF, etc.).
All raster image formats (GIF, PNG) are implemented via calls to the Boutell GD library.
Some devices may not be present depending on build details of your application.
Coding note: All function names begin with PLG_ ... for brevity the prefix is omitted in this doc
but must be used in code. Codefiles must #include plg.h
Initializing
set_early_defaults()
Set hard defaults. Call this before any other libplg function.
init( char dev )
Begin a new drawing. dev identifies the display device and may be one of:
g = GD (GIF or PNG)
c = paginated postscript
e = EPS
s = SVG
f = SWF
x = x11
For GIF and PNG call setimfmt() beforehand otherwise default will be GIF.
For devices other than PostScript, the drawable area will be 8" x 8" unless setsize() is called beforehand and the
output graphic filename will use an automatic default unless setoutfilename() is called beforehand.
These may be called before init() depending on output device:
setsize( double ux, double uy, int x, int y )
For output devices with sizable drawing areas, this function may be used before init() to set the drawing area size to ux inches wide and uy inches high.
For onscreen displays x and y may be specified as the screen pixel location of window's upper-left corner, otherwise pass these as 0.
setoutfilename( char *name )
May be called before init() to set the name for the graphic output file.
setimfmt( char *fmt )
If producing GIF or PNG this may be called before init() to specify result image
fmt ... one of "gif", "png", or "jpeg".
Coordinate system and scaling
PLG absolute coordinates are inches, with origin in the lower left corner of the drawing area.
In addition, a data coordinate system may be set up for data plotting.
The routines in this section may be used to set up scaling and provide conversions between data units and absolute units.
scaletype( char *scaletype, char axis )
Set the scaletype either "linear" or "log" on an axis either 'x' or 'y'.
Call before setting up the scaling, otherwise "linear" is the default.
scale_x( double alow, double ahi, double ulow, double uhi )
Set data units scaling in x.
The range from ulow to uhi will be mapped to the absolute area from alow to ahi.
scale_y( double alow, double ahi, double ulow, double uhi )
Set data units scaling in y.
The range from ulow to uhi will be mapped to the absolute area from alow to ahi.
double ax( double u )
double ay( double u )
Convert from data units to absolute units.
double dx( double a )
double dy( double a )
Convert from absolute units to data units.
Drawing primitives
Draw operations always update the current location to the last-drawn point.
Lines are drawn in the current color, thickness and dash pattern and
text is rendered in current font, size, and direction (see attributes below).
clr()
Clear drawing area to background color.
mov( x, y )
lin( x, y )
Move to / draw line to location (x, y) in absolute units.
movu( x, y )
linu( x, y )
Move to / draw line to location (x, y) in data units.
Same as e.g. mov( ax( x ), ay( y ) );
dotext( char *s, char a )
Display text string s, aligning as per a. a is one of 'L', 'C', 'R'
(left-aligned to the current location, centered around the current location, or right-aligned to the current location, respectively).
These calls are equivalent:
text( char *s ) centext( char *s ) rightjust( char *s )
path( double x, double y )
Start or extend a polygon path to x, y in absolute units).
Typically path() is called multiple times, for example it's called five times to draw a pentagon.
pathu( double x, double y )
Same as path() but in data units.
colorfill( char *color )
Close and fill a polygon defined with preceding path() calls. Fills polygon with the given color.
[color names].
Drawn objects
cblock( double x1, double y1, double x2, double y2, char *color, int outln )
Draw a rectangle in absolute units ... lower left corner at (x1, y1)
and upper right corner at (x2, y2) and fill with color.
If color is passed as "" no fill will occur,
otherwise the rectangle will be filled with color
[color names].
If outln is passed as 1 the rectangle will be outined using current line color and attributes.
arrow( double x1, double y1, double x2, double y2, double r, double w, char *color )
Draw arrow from (x1,y1) to (x2,y2) all in absolute units.
Tip of arrow is at (x1,y1). r is length of the arrowhead in inches.
w is theta controlling arrowhead width .. suggested default is 0.3.
color is arrowhead color.
mark( double x, double y, char *symcode, double r )
Render a geometric data point symbol centered around (x, y) with
radius r (all in absolute units). sym is a geometric point symbol.
Symcodes are described at bottom of
this page.
Setting graphics and text attributes
color( char *color )
Set current color for drawn lines and text.
[color names].
textsize( int p )
Set current text size to point size p.
font( char *s )
Set current font to s which is a fontname native to the output device.
More info on font support.
textdir( int dir )
Set current text direction to dir degrees. 0 is normal horizontal;
90 is vertical moving upward (such as when labelling Y axis).
For output devices that don't support vertical text a placeholder box representation is shown.
gettextsize( double *width, double *height )
Get the approximate width and height in absolute units, of most recently rendered text string.
linetype( int style, double width, double magfactor )
Set line style, line width, and dashing pattern magnification factor.
The default line style is 0 (solid).
The default line thickness is 0.7.
The default line dash magnification factor is 1.0.
More info on line styles and dashing.
normline()
Set the line style, width, and dashing parameters to their hard defaults.
backcolor( char *color )
Set the background color.
[color names].
A subsequent clr() will then actually set the drawing area background to this color.
Pagination
These only apply to paginated postscript.
paper( int p )
Set paper orientation... p = 0 for portrait or 1 for landscape. Call after init() before drawing.
print()
Print / eject current page. After last page is produced, a call to Eendoffile() will finish up the result file.
Global vars
The following global variables may be accessed by applications. Applications should not change the values of these variables directly.
double PLG.xlo, PLG.ylo, PLG.xhi, PLG.yhi = lower and upper bounds current plotting area (absolute units)
double PLG.dxlo, PLG.dxlo, PLG.dxhi, PLG.dyhi = upper and lower bounds of the current plotting area (data units)
char *(PLG.curcolor) = the current color for lines/text
char *(PLG.curbkcolor) = the current color for background
int PLG.curtextsize = the current text size in pts
double PLG.curtextheight = approximate height of a line of text in absolute units
char *(PLG.curfont) = name of the current font
double PLG.curlinewidth = the current line thickness.
int PLG.curlinetype = the current line dashstyle number.
int PLG.curtextdirection = the current text direction in degrees.
double PLG.curpatternfactor = the current line dash density (default = 1.0)
|
