rsalz@bbn.com (Rich Salz) (04/07/88)
Submitted-by: Joe Dellinger <joe@hanauma.STANFORD.EDU> Posting-number: Volume 14, Issue 26 Archive-name: vplot/part21 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 21 (of 24)." # Wrapped by rsalz@fig.bbn.com on Fri Mar 25 11:47:33 1988 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'Vplot_Kernel/Documentation/libvplot.mn' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/Documentation/libvplot.mn'\" else echo shar: Extracting \"'Vplot_Kernel/Documentation/libvplot.mn'\" \(28451 characters\) sed "s/^X//" >'Vplot_Kernel/Documentation/libvplot.mn' <<'END_OF_FILE' X.TH libvplot 9 "6 June 1987" "Stanford Earth Sciences" X.SH NAME libvplot \- programmer's interface to the vplot - pen graphics system X.SH SYNOPSIS X.B #include <vplot.h> X.PP Use X X {cc,f77} myprog.o -lvplot -lm X to link in the X.B libvplot functions. X.PP One of the functions {vp_file(), vp_filep(), or vp_unit()} must be called to initialize the output file. X.SH INTRODUCTION X.B Libvplot is a set of subroutines which write graphics calls in the X.B vplot(9) graphics language. The output file may be an ordinary file or a pipe to a X.B pen(9) display program. X.PP The subroutines are callable either from C or from FORTRAN. C function names have an embedded underbar (e.g., `vp_break()') while the corresponding FORTRAN name will not use the underbar (`CALL VPBREAK()'). X.PP Input to X.B vplot plot files should be done ONLY through the X.B libvplot calls. Programs which write X.B vplot language directly are doomed to early obsolescence. Future versions of X.B vplot will provide backwards compatibility at the X.B libvplot subroutine call level, not necessarily at the X.B vplot language level. X.PP Separate functions are available to accept geometric arguments in inches and in arbitrary user units. The routines which accept user units have `u' prepended to their root names. Absolute coordinates (x,y) in inches are computed internally from user coordinates (xu,yu) in user units via: X.PP X.br X x = x0+(xu-xu0)*xscl X.br X y = y0+(yu-yu0)*yscl X This transformation is set by calls to X.B vp_orig, which sets x0 and y0; X.B vp_uorig, which sets xu0 and yu0; and X.B vp_scale, which sets xscl and yscl. X.SH COORDINATES Vplot fits the largest rectangle with a 3 (high) by 4 (wide) aspect ratio X(SCREENRATIO in vplot.h) onto your device screen that it can. This window defines your output space. X(Although clipping is still done at the edges of the actual screen.) X.PP Two different coordinate system orientations are available, ``standard'' and ``rotated''. In the standard coordinate orientation, the origin is in the lower left hand corner and the X axis is horizontal and the Y axis is vertical. In the rotated coordinate orientation, the origin is in the upper left hand corner and the X axis is vertical and the Y axis is horizontal. The standard coordinate orientation is the default. (See vp_style.) X.PP Two different scaling methods are available, ``relative'' and ``absolute''. Which mode is used can be set by the device, options to pen, or vp_style. In absolute mode inches in vplot correspond to real inches on the device display screen. In relative mode the plot is scaled to the size of the screen. In the standard coordinate system orientation the screen is considered to be X10.24 (STANDARD_HEIGHT) inches tall, and in the rotated coordinate orientation system the screen is considered to be 7.5 (ROTATED_HEIGHT) inches tall. X.PP The routine vp_stretch is a utility routine which calls vp_scale, vp_orig, and vp_uorig for you if you just want to ``fill the screen''. X.PP For more on coordinate systems and ``magic numbers'', refer to the Vplot manual page. X.SH FORTRAN All of these routines can also be called from FORTRAN. The argument types are given for C, but these can be easily converted to FORTRAN by the following table: X.br int x -- integer x X.br float y -- real y X.br float *x -- real x() (unless otherwise noted) X.br int *y -- integer y() (unless otherwise noted) X.br char *s -- character(*) s X.br unsigned char *a -- No Standard Fortran Equivalent X.PP X.SH SUBROUTINES X.PP X.ft 3 X.ne 5 geth X.br int geth (iop) X.br register FILE * iop; X.ft 1 X.RS X.PP Get a two-byte integer from file or pipe `iop'. Uses the same byte order on all machines. (This is important!) Usually called by other X.B libvplot functions, not by user programs. X.RE X.PP X.ne 5 X.ft 3 puth (w, iop) X.br register int w; X.br register FILE * iop; X.ft 1 X.RS X.PP Put the low two bytes of `w' on stream `iop'. Uses the same byte order on all machines. Usually called by other X.B libvplot functions, not by user programs. X.RE X.PP X.ft 3 X.ne 6 vp_area(xp, yp, lp, fat, xmask, ymask) X.br vp_uarea(xp, yp, lp, fat, xmask, ymask) X.br float *xp, *yp; X.br int lp, fat, xmask, ymask; X.ft 1 X.RS X.PP Fill the area within the polygon defined by the points in the `xp' and `yp' arrays. Uses the X.B VP_OLDAREA vplot command, which knows how to do solid fills or simple halftone-style stipples. `Lp' is the number of vertices. `Fat' is the fatness of the border line. If fat<0, no border is drawn. The filling style varies depending on whether or not the device has color. If the device has color, the fill is done solidly using the current drawing color. If the device is monochrome, the masks tell how many blank pixels to use to pad each pixel to be drawn. Filling is done by tiling the area with rectangles of size `xmask' by `ymask', with only the lower right pixel turned on. Thus, both masks 1 gives a solid fill; xmask=1 and ymask=2 produces horizontal lines spaced one pixel apart; xmask=4, ymask=4 gives a 9.1% `gray' color. If either xmask or ymask is zero, then the interior is not filled (even on color devices). X.RE X.PP X.ft 3 X.ne 5 vp_arrow(x0, y0, x, y, r) X.br vp_uarrow(x0, y0, x, y, r) X.br float x0, y0, x, y, r; X.ft 1 X.RS X.PP Plot an arrow from (x0,y0) to (x,y) with arrowhead-size `r'. The arrowhead is half a square. `r' is the length of a side of the square. If `r' is negative, the arrowhead is not filled. If (x0,y0) = (x,y), a centered box is drawn of size r. All sizes are in inches (vp_arrow) or user units (vp_uarrow). If your user-unit coordinate system is not square, you'll probably want to use vp_where and vp_arrow instead of vp_uarrow. X.RE X.PP X.ft 3 X.ne 7 vp_bgroup(string) X.br char *string; X.ft1 X.RS X.PP Begin a new group. Groups are used to combine several vplot primitives into one entity. Groups may be nested. Groups may not contain an erase. X.TP 10 string: The name of this group. X.RE X.PP X.ft 3 X.ne 7 vp_egroup() X.ft1 X.RS X.PP End a group. Each begin group must be paired with an end group, like parenthesis in formulas. X.RE X.PP X.ft 3 X.ne 3 vp_break() X.ft 1 X.RS X.PP Interrupt the output processing of the vplot file. Prompt the user (or pause, depending on the `pause' argument to X.B pen(9) X) allow interaction, and reset global plotting parameters, but don't erase the previous output. X.RE X.PP X.ft 3 X.ne 5 vp_clip(xmin, ymin, xmax, ymax) X.br vp_uclip(xmin,ymin,xmax,ymax) X.br float xmin,ymin,xmax,ymax; X.ft 1 X.RS X.PP Define the current clipping rectangle, in inches or in user units. There is currently no call for simply turning off clipping. Just define a clipping window larger than the space you're working in. The best way to do this is with the call X.br vp_clip(-VP_MAX, -VP_MAX, VP_MAX, VP_MAX). VP_MAX is defined in vplot.h. X.RE X.PP X.ft 3 X.ne 4 vp_color(col) X.br int col; X.ft 1 X.RS X.PP Set the current drawing color to a number X`col' between 0 and 511 (MAX_COL in params.h). The first eight colors are predefined: X X.ta 0.5i 1.7i X.br X BLACK 0 X.br X BLUE 1 X.br X RED 2 X.br X PURPLE 3 X.br X GREEN 4 X.br X CYAN 5 X.br X YELLOW 6 X.br X WHITE 7 X.br X X.PP These numbers are defined in <vplot.h>, so the color name X(all in caps) can be used instead of the number (within the to-be-compiled program, NOT as input to plas). These 8 colors may be re-assigned, if desired, but usually aren't. Color 0 is always the background color; drawing in color 0 erases. Color/pattern numbers larger than 7 should be set by the program, using the X.B vp_coltab() call, before being used (what color you get when you plot with an unset color is device-dependent). The numbers 0-511 are used both for colors and for area-fill patterns. The user is responsible for keeping track of how the color/pattern table is set. See the descriptions of X.ft 3 vp_fill(), vp_area(), vp_patload(), X.ft 1 and X.B vp_hatchload() for more information. X.RE X.PP X.ft 3 X.ne 5 vp_coltab(col, red, green, blue) X.br int col; X.br float red, green, blue; X.ft 1 X.RS X.PP Color number `col' is set to have the color X(red, green, blue). The color levels are all between X0. and 1. Thus, (1.,1.,1.) is white and (1.,1.,0.) is yellow. `col' is between 0 and 511 (MAX_COL in params.h). X(The handling of colors on devices that don't have many colors, or don't have settable colors at all is a tricky business. In general Vplot will try to take care of all of this for you and come as close as is possible to what you want. Read the Vplotraster manual page to find out more about this.) Color table settings last until changed by the user, except that colors 0 through 7 are reset to the default when a pen filter is first fired up. Normally colors 0 through 7 are left at their default settings, so that simple plots using only those colors can be freely interspersed with a complex many-hued plot without problems. Color 0 defines the background color. X.RE X.PP X.ft 3 X.ne 4 vp_dash(dash1, gap1, dash2, gap2) X.br float dash1, gap1, dash2, gap2; X.ft 1 X.RS X.PP Set the current line style, by defining a special line type. X`Dash' and `gap' are in inches. This dashing is done within vplotlib itself, and so these dashes are guaranteed to scale with the rest of the plot. X.B Vp_setdash allows a more complicated (and efficient) dashed line pattern to be defined. X.RE X.PP X.ft 3 X.ne 5 vp_draw(x, y) X.br vp_udraw(x, y) X.br float x, y; X.ft1 X.RS X.PP Draw from the current position to (x,y) using the current color, fatness, and line style. X.RE X.PP X.ft 3 X.ne 3 vp_endplot() X.ft1 X.RS X.PP Close the plot file (output stream). X.RE X.PP X.ft 3 X.ne 3 vp_erase() X.ft1 X.RS X.PP Clear the screen, feed a page of paper, or flush a raster file to the output stream. Reset most global plotting parameters to their default values. Prompt the user (or pause, depending on the `pause' argument to X.B pen(9) X) and allow interaction. Normally every plot file should start with a X.B vp_erase call, as the very first thing (after opening the output file). A common mistake is to call routines like vp_style, vp_fat, etc, and only THEN vp_erase to erase the screen before actually drawing something. This is a mistake, as the vp_erase command will start a new frame. This is not noticeable on most screen devices (unless you are pausing between frames), but it will be very noticeable on hardcopy devices that will spit out a blank first page before ``doing the plot''. Since X.B vp_erase resets most of the vplot global parameters (fatness, current color, text attributes, current clipping window, dash line pattern, etc), you should set these to their desired values again after every call. Color table settings are NOT reset at erases. X.RE X.PP X.ft 3 X.ne 4 vp_fat(fatness) X.br int fatness; X.ft1 X.RS X.PP Set the line width, 200 (FATPERIN) per inch. Default: 0, which is the thinnest line possible on the device. X.RE X.PP X.ft 3 X.ne 4 vp_file(filename) X.br char *filename; X.ft1 X.RS X.PP Open the file called `filename' as the output stream. Works for C and for FORTRAN. One of the functions { X.B vp_file(), vp_filep(), or X.B vp_unit() X} MUST be called to initialize the output. X.RE X.PP X.ft 3 X.ne 4 vp_filep(filepntr) X.br FILE *filepntr; X.ft1 X.RS X.PP Connect the already-open stream pointer `filepntr' to the output stream. C language only. (Example: vp_filep(stdout).) One of the functions { X.B vp_file(), vp_filep(), or X.B vp_unit() X} MUST be called to initialize the output. X.RE X.PP X.ft 3 X.ne 4 vp_unit(lunit) X.br int *lunit; X.ft1 X.RS X.PP Connect the Fortran logical unit `lunit' to the output stream. Works for 4.2/4.3 BSD Unix only. This routine was written using details of the Berkeley Fortran implementation, which have been changed in ports to some machines other than VAXes. One of the functions { X.B vp_file(), vp_filep(), or X.B vp_unit() X} MUST be called to initialize the output. X.RE X.PP X.ft 3 X.ne 6 vp_fill(xp, yp, npts) X.br vp_ufill(xp, yp, npts) X.br float *xp, *yp; X.br int npts; X.ft1 X.RS X.PP Fill the area within the polygon defined by the points in the `xp' and `yp' arrays using the X.B VP_AREA vplot command. The polygon fill style is determined by the current fill pattern, which is the loaded pattern with the same index number as the current drawing color. Patterns are loaded with the X.B vp_patload() and X.B vp_hatchload() calls. If no pattern has been loaded for this number, the polygon will be filled solidly with the current drawing color. X`Npts' is the number of vertices of the bounding polygon. X.RE X.PP X.ft 3 X.ne 5 vp_hatchload(angle, numhatch, ipat, array); X.br int angle, numhatch, ipat; X.br int *array; X.ft1 X.RS X.PP Load a hatch pattern as pattern number `ipat'. (When the current drawing color is number `ipat', this is the pattern that will be used with the X.B vp_fill() call.) The hatch pattern consists of `numhatch' sets of lines drawn at an angle of `angle' to each of the two coordinate axes. For each set of lines (numhatch * 2 of them), the array contains 4 elements specifying: `fatness', `color', X`offset', `repeat interval'. (Thus the array is of dimension numhatch * 2 * 4.) The `repeat interval' determines the distance between the lines in a set. The `offset' parameter is used to shift all the lines in the set. Both of these parameters are in units of 1/100'ths of an inch (HATCHPERIN in vplot.h). Color and fatness are just as you'd expect. X.RE X.PP X.ft 3 X.ne 5 vp_message(string) X.br char *string; X.ft1 X.RS X.PP Have the vplot filter issue the message given in ``string''. X.RE X.PP X.ft 3 X.ne 5 vp_move(x, y) X.br vp_umove(x, y) X.br float x, y; X.ft1 X.RS X.PP Resets the current position to (x,y), but doesn't actually draw anything. Used in conjunction with vp_draw(), vp_udraw(), or vp_where(). Units are inches (vp_move) or user units (vp_umove). X.RE X.PP X.ft 3 X.ne 4 vp_orig(x0, y0) X.br float x0, y0; X.ft1 X.RS X.PP Sets where on the device screen (in inches) the origin of the user coordinate system will be plotted. The initial reference point is the lower left corner of the display area for style=STANDARD, and the upper left corner for style=ROTATED. X.RE X.PP X.ft 3 X.ne 4 vp_uorig(x0, y0) X.br float x0, y0; X.ft1 X.RS X.PP Assigns values, in user units, to the origin of the user coordinate system, whose location on the screen was set by the X.B vp_orig() command. X.RE X.PP X.ft 3 X.ne 5 vp_patload(ppi, nx, ny, ipat, raster) X.br int ppi, nx, ny, ipat; X.br int *raster; X.ft1 X.RS X.PP Load a raster pattern as pattern number `ipat'. The pattern is designed at `ppi' pixels per inch. The raster pattern itself is in the array `raster', which is an array of color table numbers. It will be represented on the display scanned TV-style, starting in the upper left hand corner and working left-to-right (up to ny) and then top-to-bottom (up to nx scan lines). X.RE X.PP X.ft 3 X.ne 5 vp_pendn(x, y) X.br vp_upendn(x, y) X.br float x, y; X.ft1 X.RS X.PP Move to the location (x, y) in inches (vp_pendn) or user units X(vp_upendn) and then put the pen down. X.RE X.PP X.ft 3 X.ne 4 vp_penup() X.ft1 X.RS X.PP Pick the pen up. X.RE X.PP X.ft 3 X.ne 6 vp_pline(xp, yp, npts) X.br vp_upline(xp, yp, npts) X.br float *xp, *yp; X.br int npts; X.ft1 X.RS X.PP Draw a polyline through the points given in the `xp' and `yp' arrays. X.RE X.PP X.ne 6 X.ft 3 vp_plot(x,y,down) X.br vp_uplot(x,y,down) X.br float x, y; X.br int down; X.ft1 X.RS X.PP Draw a vector from the current position to (x, y) with the pen up (`down' = 0) or down (`down' = 1). Uses the current line style. (Fat, dashed lines may look odd on some devices.) Usually called by other X.B libvplot functions, not by user programs. X.RE X.PP X.ft 3 X.ne 7 vp_pmark(npts, mtype, msize, xp, yp) X.br vp_upmark(npts, mtype, msize, xp, yp) X.br int npts, mtype, msize; X.br float *xp, *yp; X.ft1 X.RS X.PP Plot `npts' polymarkers, of type `mtype' and size `msize'. X`xp' and `yp' are arrays of x and y values in inches (vp_pmark) or user units (vp_upmark). `msize' is in vplot text height units. X`Mtype' gives the following special symbols from font 15 for these special values: X2, plus; 3, asterisk; 4, circle; 5, cross; 20, square; X21, triangle; 22, diamond; 23, star. X`mtype' = 0 or 1 sets a single pixel, the smallest displayable dot. Other values of `mtype' refer to glyph numbers in the current font (which should be compatible with ASCII for most fonts). X.RE X.PP X.ft 3 X.ne 3 vp_purge() X.ft 1 X.RS X.br Flush the output buffer. Flushes both the vplot stream and the device stream. X.RE X.ft 3 X.ne 7 vp_raster (array, blast, bit, offset, xpix, ypix, xll, yll, ppi, xur, yur, orient, invert) X.br vp_uraster (array, blast, bit, offset, xpix, ypix, xll, yll, ppi, xur, yur, orient, invert) X.br unsigned char *array; X.br float xll, yll, *xur, *yur, ppi; X.br int xpix, ypix, bit, offset, blast, orient, invert; X.ft1 X.RS X.PP Display the raster data pointed to by `array'. X.TP 10 blast If `blast' = 1, don't try to compact the output. If `blast' = 0, compaction will be done. Compaction does run-length encoding and compacts repeated lines. Compaction can make the vplot file considerably smaller, but it also takes longer to create the file. X.TP 10 bit If `bit' = 1, the raster is saved as one bit per pixel; if `bit' = 0, as one byte per pixel. Byte raster is faster! X.TP 10 X[xy]pix X`xpix', `ypix': Number of pixels in each direction. X.TP 10 X[xy]ll X`xll', `yll': The display coordinates of the lower left corner of the array, in inches (vp_raster) or user units (vp_uraster). X.TP 10 ppi X`ppi': If `ppi' is non-zero, scale the image by duplicating or dropping image pixels to a factor of `ppi' output pixels per inch. The point (xur, yur) is returned as the upper right hand corner. If `ppi' is zero, use whatever resolution is required to make X(xur, yur), which must then be supplied, the upper right hand corner. X.TP 10 X[xy]ur X`xur', `yur': The display coordinates of the upper right corner (Well, actually, not quite. Read the vplotraster manual page.). Either in inches (vp_raster) or user units (vp_uraster). These two variables should NOT be arrays in FORTRAN, despite being declared `float *' for C. Note that `xll' <= `xur', `yll' <= `yur'. X.TP 10 array X`array': The `array' contains values from 0 to 255. For byte raster these values have `offset' added to them and then they are interpreted as color values. For bit raster, a value of 0 is interpreted as color 0, and anything else is interpreted as color `offset'. X.TP 10 orient For `orient' = 0 and `invert' = 0, the array is drawn on the screen television style. The filling starts from the upper left and works to the right and then down. X`Orient' 1 rotates this 90 degrees clockwise, `orient' 2 180 degrees, etc. X.TP 10 invert X`Invert' reverses the `array' over the slow axis. The data occupies the same area of the output regardless of the value of `orient' and `invert'. X.RS Note that the point (xll, yll) is the lower leftmost pixel of the data, whereas the point (xur, yur) is one to the right and above the upper rightmost pixel of the data. This is so that (xur-xll) and (yur-yll) give the length of the two dimensions of the data box. X.RE X.TP 10 offset The `offset' parameter is provided so that several different raster color tables can be maintained at once, perhaps from 0-255 for ordinary colors and from 256-511 for a gray scale. X.RE X.PP X.ft 3 X.ne 6 vp_scale(xscl,yscl) X.br float xscl, yscl; X.ft1 X.RS X.PP Set the scale of user units for the plot, in inches per user unit. X.RE X.PP X.ft 3 X.ne 6 vp_setdash(dashp,gapp,lp) X.br float *dashp, *gapp; X.br int lp; X.ft1 X.RS X.PP Set the dashed line pattern. The pattern is set to dashp[0], gapp[0], dashp[1], gapp[1], ..., dashp[lp-1], gapp[lp-1], where dashp contains the lengths of the solid-line segments (dashes) of the pattern and gapp contains the lengths of the gaps between dashes. All lengths must be specified in INCHES. This dashing will be done either by the device hardware itself or by code in the pen filter. This dash pattern will be of the specified size in inches regardless of any scaling done to the plot as a whole! X.PP Generally, unless you have some reason to require that the dash pattern scale exactly with the size of the plot, vp_setdash is preferable to vp_dash. This is especially true when using devices that support fat dashed lines in hardware. X.RE X.PP X.ft 3 X.ne 6 vp_stretch(xmin,ymin,xmax,ymax) X.br float xmin, ymin, xmax, ymax; X.ft1 X.RS X.PP This routine makes calls to vp_orig, vp_uorig, and vp_scale for you so that X(xmin,ymin) is the user coordinate of the lower left hand corner of the output space and (xmax,ymax) is the user coordinate of the upper right hand corner. X.PP As an example, suppose that you want to display everything in the unit box X(0. to 1.) on both axes, but that you also want your coordinate system to remain isotropic. You would call X.br vp_stretch(0.,0.,1./SCREENRATIO,1.); X.RE X.PP X.ft 3 X.ne 4 vp_style(st) X.br int st; X.ft1 X.RS X.PP Set the overall display style. Choices are: X X.TP 13 STANDARD X(default, for terminals) Origin in lower left, scaled so that the maximum Y value (top of the screen) is 10.24 (STANDARD_HEIGHT) `inches'. X.TP 13 ABSOLUTE X(default, for plotters) Origin in lower left, plotted in actual inches on the device. X.TP 13 ROTATED Origin in upper left, Y-axis horizontal increasing to the right, XX-axis vertical and increasing down, scaled so that the maximum X value (bottom of the screen) is X7.5 (ROTATED_HEIGHT) `inches'. X.RE X.PP I write `inches' because unless absolute scaling is being used vplot's X`inches' do not correspond to real, physical inches on the device screen. X.PP Note that the STANDARD style scales the output so a square X10.24 inches on a side will fit on the terminal screen. This allows a full 8.5x11-inch image to be shown on most terminals. The magic numbers 10.24 and 7.5 are defined in X.B vplot.h. More about coordinate systems can be found in the Vplot manual page. The plot style reverts to the default at the start of every frame. X.RE X.PP X.ft 3 X.ne 7 vp_text(x, y, size, orient, string) X.br vp_utext(x, y, size, orient, string) X.br float x, y; X.br int size, orient; X.br char *string; X.ft1 X.RS X.PP Display text, using the currently-defined font, precision, and text alignment. X.TP 10 x, y: The coordinates of the reference point for the string. Either in inches (vp_text) or user units (vp_utext). X.TP 10 size: Height of a character, 33 (TXPERIN in vplot.h) units per inch (!!!). X.TP 10 orient: Text drawing direction, in degrees counter-clockwise from horizontal, right-facing. X.TP 10 string: The text string that is to be displayed. X`man vplottext' explains the many special escape sequences recognized by the generic vplot text routine gentext. X.RE X.PP X.ft 3 X.ne 7 vp_gtext(x, y, xpath, ypath, xup, yup, string) X.br vp_ugtext(x, y, xpath, ypath, xup, yup, string) X.br float x, y; X.br float xpath, ypath; X.br float xup, yup; X.br char *string; X.ft1 X.RS X.PP Display text, using the currently-defined font, precision, and text alignment. The text coordinate system is defined in the GKS standard. X.TP 10 x, y: The coordinates of the reference point for the string. Either in inches (vp_gtext) or user units (vp_ugtext). X.TP 10 xpath, ypath: A vector pointing in the direction the text string will extend. Either in inches (vp_gtext) or user units (vp_ugtext). X.TP 10 xup, yup: A vector pointing in the ``up'' direction for individual letters. Either in inches (vp_gtext) or user units (vp_ugtext). X.PP For normal, unstretched text, the up vector is 90 degrees counterclockwise from the path vector, and both vectors are the same length. This length is the text size. Projecting these two vectors will project the entire text string accordingly. X.TP 10 string: The text string to be displayed, just as in the other text command. X.RE X.PP X.ft 3 X.ne 4 vp_tfont(font, prec, ovly) X.br int font, prec, ovly; X.ft1 X.RS X.PP Choose the font to be used for output. (All the following values are defined in vplot.h.) X.TP 10 font: Which font to use. Sixteen software fonts are defined (if you have the Hershey fonts installed, otherwise you've only got font 0. You may also have hardware fonts starting at 100 (NUMGENFONT in params.h) available on some devices). The fonts names are defined in vplot.h. Font 0 (PEN in vplot.h), the traditional vplot font, is fastest and is the default on terminals (unless they have an even faster hardware font). Another better-looking font should be the default on hard copy devices. NO_CHANGE leaves the font unchanged from that in effect before the call. X.TP 10 prec: Font precision. This doesn't matter much if you're using a software font to begin with. `Prec' is one of X.RS X.TP 13 STRING Use the hardware text capabilities to write the whole string. The default for screen devices. X.TP 13 CHAR Use hardware characters, but position them individually. X.TP 13 STROKE Software text. This should be the default for hardcopy devices. Ligatures in the Vplot software fonts are only enabled at STROKE precision. (See the vplottext manual page for more about this.) X.TP 13 NO_CHANGE Use the previous value. X.RE X.TP 10 ovly: Overlay mode: X.RS X.TP 13 OVLY_NORMAL: just draw the text over what's there in the standard way; X.TP 13 OVLY_BOX: draw a box around the text first; X.TP 13 OVLY_SHADE: clear a box under the text first; X.TP 13 OVLY_SHADE_BOX: box the text and clear under it too; X.TP 13 NO_CHANGE: use the previous value. X.RE X.RE X.PP X.ft 3 X.ne 4 vp_tjust(hjust, vjust) X.br int hjust, vjust; X.ft1 X.RS X.PP Set the position of the reference point for locating strings or characters. Choices are (these are defined in vplot.h): X hjust: X.RS X.TP 14 TH_NORMAL Use the default. X.TP 14 TH_LEFT Left justify. X.TP 14 TH_CENTER Center the string. X.TP 14 TH_RIGHT Right justify. X.TP 14 TH_SYMBOL Position the character for use as a symbol marking the point. X.br X.RE X vjust: X.RS X.TP 14 TV_NORMAL Use the default. X.TP 14 TV_BOTTOM Reference point is at the bottom of the letters. X.TP 14 TV_BASE Reference point is at the bottom of the descenders. X.TP 14 TV_HALF Centered. X.TP 14 TV_TOP Reference point at the top of the writing area, including space above letters. X.TP 14 TV_CAP Reference point is at the tops of capital letters. X.TP 14 TV_SYMBOL Position the character for use as a symbol marking the point. X.RE X X.br It is possible to change font size, change font, and do many other tricks ``on the fly'' by including escape codes in the text string. See the vplottext manual page for information about the details of interpretation of special characters within vplot text. X.RE X.PP X.ft 3 X.ne 4 vp_where(x,y) X.br float *x, *y; X.PP X.ft 1 X.RS Return the current position, in inches. Fortran users note that x and y are not arrays, despite being declared `float *' in C. X.RE X.SH ACCESSING VPLOTLIB VARIABLES X.PP At present, few inquiry functions are provided by X.B libvplot. It would be wonderful if someone could turn the one-way pipes into two-way sockets and provide some. The changes required to the pen filters themselves would be minimal, as the required device dependent structures already exist. X.PP The current values of the global parameters used in libvplot are stored in the external structure X.B vp_pc. This structure is defined in the file vp_pc.h, which is ``#include''ed by the libvplot routines that need to refer to the variables in vp_pc. User programs should probably have no need to do this. X.SH MAGIC NUMBERS The magic numbers (200, 100, 33, 7.5, 10.24, etc) used in this document are subject to being changed at new sites. At Stanford we are forced to live with these off-the-wall numbers in order to not break a large mass of ancient code. They are all defined in ``vplot.h'' X(which should be in /usr/include, and which you should probably #include) and ``params.h'' (which you probably don't need to worry about). X I would have loved to have turned everything into inches or centimeters, but it just wasn't possible here. It is especially annoying that text is currently quantized in such rough units. Sometimes it is impossible to get text the exact size you need! X.SH COPYRIGHT The Vplot code is copyrighted. Refer to the Vplot manual page for the official copyright notice. X.SH SEE ALSO pen(9), vplot(9), vplottext(9), vplotraster(9), plas, pldb X.SH AUTHOR Dave Hale, Joe Dellinger, Chuck Karish, and Steve Cole X.SH LIMITATIONS X.PP Vector fonts and hardware fonts cannot be intermixed in a single string. X.PP Inquiry functions should be provided. X.PP Vpunit() only works under 4.x BSD FORTRAN. X.PP Vplot.h should have defines for the various special markers. X.SH BUGS X.PP None, that I know of. It is likely that some of the lesser-used FORTRAN routines still harbor bugs. END_OF_FILE if test 28451 -ne `wc -c <'Vplot_Kernel/Documentation/libvplot.mn'`; then echo shar: \"'Vplot_Kernel/Documentation/libvplot.mn'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/Documentation/libvplot.mn' fi if test -f 'Vplot_Kernel/lvplot/vp_ufill.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/vp_ufill.c'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/vp_ufill.c'\" \(627 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/vp_ufill.c' <<'END_OF_FILE' X/* X * Copyright 1987 the Board of Trustees of the Leland Stanford Junior X * University. Official permission to use this software is included in X * the documentation. It authorizes you to use this file for any X * non-commercial purpose, provided that this copyright notice is not X * removed and that any modifications made to this file are commented X * and dated in the style of my example below. X */ X X/* X * X * source file: ./lvplot/vp_ufill.c X * X * Joe Dellinger (SEP), June 11 1987 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X#define UUU X#include "vp_fill.c" END_OF_FILE if test 627 -ne `wc -c <'Vplot_Kernel/lvplot/vp_ufill.c'`; then echo shar: \"'Vplot_Kernel/lvplot/vp_ufill.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/vp_ufill.c' fi if test -f 'Vplot_Kernel/lvplot/vp_umove.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/vp_umove.c'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/vp_umove.c'\" \(627 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/vp_umove.c' <<'END_OF_FILE' X/* X * Copyright 1987 the Board of Trustees of the Leland Stanford Junior X * University. Official permission to use this software is included in X * the documentation. It authorizes you to use this file for any X * non-commercial purpose, provided that this copyright notice is not X * removed and that any modifications made to this file are commented X * and dated in the style of my example below. X */ X X/* X * X * source file: ./lvplot/vp_umove.c X * X * Joe Dellinger (SEP), June 11 1987 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X#define UUU X#include "vp_move.c" END_OF_FILE if test 627 -ne `wc -c <'Vplot_Kernel/lvplot/vp_umove.c'`; then echo shar: \"'Vplot_Kernel/lvplot/vp_umove.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/vp_umove.c' fi if test -f 'Vplot_Kernel/lvplot/vp_uorig.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/vp_uorig.c'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/vp_uorig.c'\" \(627 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/vp_uorig.c' <<'END_OF_FILE' X/* X * Copyright 1987 the Board of Trustees of the Leland Stanford Junior X * University. Official permission to use this software is included in X * the documentation. It authorizes you to use this file for any X * non-commercial purpose, provided that this copyright notice is not X * removed and that any modifications made to this file are commented X * and dated in the style of my example below. X */ X X/* X * X * source file: ./lvplot/vp_uorig.c X * X * Joe Dellinger (SEP), June 11 1987 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X#define UUU X#include "vp_orig.c" END_OF_FILE if test 627 -ne `wc -c <'Vplot_Kernel/lvplot/vp_uorig.c'`; then echo shar: \"'Vplot_Kernel/lvplot/vp_uorig.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/vp_uorig.c' fi if test -f 'Vplot_Kernel/lvplot/vp_upendn.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/vp_upendn.c'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/vp_upendn.c'\" \(629 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/vp_upendn.c' <<'END_OF_FILE' X/* X * Copyright 1987 the Board of Trustees of the Leland Stanford Junior X * University. Official permission to use this software is included in X * the documentation. It authorizes you to use this file for any X * non-commercial purpose, provided that this copyright notice is not X * removed and that any modifications made to this file are commented X * and dated in the style of my example below. X */ X X/* X * X * source file: ./lvplot/vp_upendn.c X * X * Joe Dellinger (SEP), June 11 1987 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X#define UUU X#include "vp_pendn.c" END_OF_FILE if test 629 -ne `wc -c <'Vplot_Kernel/lvplot/vp_upendn.c'`; then echo shar: \"'Vplot_Kernel/lvplot/vp_upendn.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/vp_upendn.c' fi if test -f 'Vplot_Kernel/lvplot/vp_upline.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/vp_upline.c'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/vp_upline.c'\" \(629 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/vp_upline.c' <<'END_OF_FILE' X/* X * Copyright 1987 the Board of Trustees of the Leland Stanford Junior X * University. Official permission to use this software is included in X * the documentation. It authorizes you to use this file for any X * non-commercial purpose, provided that this copyright notice is not X * removed and that any modifications made to this file are commented X * and dated in the style of my example below. X */ X X/* X * X * source file: ./lvplot/vp_upline.c X * X * Joe Dellinger (SEP), June 11 1987 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X#define UUU X#include "vp_pline.c" END_OF_FILE if test 629 -ne `wc -c <'Vplot_Kernel/lvplot/vp_upline.c'`; then echo shar: \"'Vplot_Kernel/lvplot/vp_upline.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/vp_upline.c' fi if test -f 'Vplot_Kernel/lvplot/vp_upmark.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/vp_upmark.c'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/vp_upmark.c'\" \(629 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/vp_upmark.c' <<'END_OF_FILE' X/* X * Copyright 1987 the Board of Trustees of the Leland Stanford Junior X * University. Official permission to use this software is included in X * the documentation. It authorizes you to use this file for any X * non-commercial purpose, provided that this copyright notice is not X * removed and that any modifications made to this file are commented X * and dated in the style of my example below. X */ X X/* X * X * source file: ./lvplot/vp_upmark.c X * X * Joe Dellinger (SEP), June 11 1987 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X#define UUU X#include "vp_pmark.c" END_OF_FILE if test 629 -ne `wc -c <'Vplot_Kernel/lvplot/vp_upmark.c'`; then echo shar: \"'Vplot_Kernel/lvplot/vp_upmark.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/vp_upmark.c' fi if test -f 'Vplot_Kernel/lvplot/vp_where.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/vp_where.c'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/vp_where.c'\" \(819 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/vp_where.c' <<'END_OF_FILE' X/* X * Copyright 1987 the Board of Trustees of the Leland Stanford Junior X * University. Official permission to use this software is included in X * the documentation. It authorizes you to use this file for any X * non-commercial purpose, provided that this copyright notice is not X * removed and that any modifications made to this file are commented X * and dated in the style of my example below. X */ X X/* X * X * source file: ./lvplot/vp_where.c X * X * Joe Dellinger (SEP), June 11 1987 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X#include <stdio.h> X#include <vplot.h> X#include "vp_pc.h" X X#ifdef FORTRAN X X#define WHERE vpwhere_ X X#else X X#define WHERE vp_where X X#endif X WHERE (x, y) X float *x, *y; X{ X *x = vp_pc._xold; X *y = vp_pc._yold; X} END_OF_FILE if test 819 -ne `wc -c <'Vplot_Kernel/lvplot/vp_where.c'`; then echo shar: \"'Vplot_Kernel/lvplot/vp_where.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/vp_where.c' fi if test -f 'Vplot_Kernel/util/README' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/util/README'\" else echo shar: Extracting \"'Vplot_Kernel/util/README'\" \(710 characters\) sed "s/^X//" >'Vplot_Kernel/util/README' <<'END_OF_FILE' This directory contains some utility routines which are useful when editing vplot files by hand. They self document. X You will need to edit the makefile to tailor it to your machine. X X"tube.example" is provided as an example of a simple shell that can pick the proper Vplot filter for you, so you can just type "tube" and have it work on any device. X X"Ta2vplot.c" is provided (it may be missing in your copy) as an example of a program that scrambles the order of the colors for raster so that the most important colors occupy the lowest part of the color table. X(See the vplotraster manual page.) It is a SEPlib program, so don't expect it to compile if you don't have SEPlib on your system. X X- Joe Dellinger END_OF_FILE if test 710 -ne `wc -c <'Vplot_Kernel/util/README'`; then echo shar: \"'Vplot_Kernel/util/README'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/util/README' fi if test -f 'Vplot_Kernel/filters/loclib/sepwhere.c' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/filters/loclib/sepwhere.c'\" else echo shar: Extracting \"'Vplot_Kernel/filters/loclib/sepwhere.c'\" \(513 characters\) sed "s/^X//" >'Vplot_Kernel/filters/loclib/sepwhere.c' <<'END_OF_FILE' X/* X * X * source file: ./filters/loclib/sepwhere.c X * X * Joe Dellinger (SEP), Feb 12 1988 X * Inserted this sample edit history entry. X * Please log any further modifications made to this file: X */ X X/* X * If for some reason the default places for the output and header to X * go aren't suitable, link in your own version of this routine X * ahead of this one. X */ char sepoutwhere[] = "/dev/tty"; char sepheadwhere[] = "/dev/null"; X X/* Make linker happy that it found it. */ sepwhere () X{ X}; END_OF_FILE if test 513 -ne `wc -c <'Vplot_Kernel/filters/loclib/sepwhere.c'`; then echo shar: \"'Vplot_Kernel/filters/loclib/sepwhere.c'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/filters/loclib/sepwhere.c' fi if test -f 'Vplot_Kernel/filters/makedist' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/filters/makedist'\" else echo shar: Extracting \"'Vplot_Kernel/filters/makedist'\" \(478 characters\) sed "s/^X//" >'Vplot_Kernel/filters/makedist' <<'END_OF_FILE' X #!/bin/sh X # X # Write a vplot distribution tar file. X # X # Usage: X # makedist outfile X # X # This will write a tar file to disk. X # X # Author - Chuck Karish X # X if [ $# -ne 1 ] then X echo "Usage: makedist tar_file_name" X exit 1 fi X tar cvf $1 *.c MakeMake* machdep machdepsep hosttype distribute_to makedist \ X README X for direct in *lib include utilities machines Tests do X tar rvf $1 \ X ` find $direct -type f -print | \ X egrep -v "(\\.a\$|\\.o\$|\\.bin|\\.include)" ` done END_OF_FILE if test 478 -ne `wc -c <'Vplot_Kernel/filters/makedist'`; then echo shar: \"'Vplot_Kernel/filters/makedist'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/filters/makedist' fi if test -f 'Vplot_Kernel/filters/utilities/Makefile' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/filters/utilities/Makefile'\" else echo shar: Extracting \"'Vplot_Kernel/filters/utilities/Makefile'\" \(287 characters\) sed "s/^X//" >'Vplot_Kernel/filters/utilities/Makefile' <<'END_OF_FILE' X# X# Device-Independent Subroutines X# CFILES= clip.c error.c solve.c vptodev.c dupside.c sort.c\ X intersect.c fatvec.c dashvec.c vecoutline.c dither.c\ X greycorr.c X utillib.a: $(CFILES) X rm -f *.o X -cc -c $(CFLAGS) $? X ar crv utillib.a *.o X ranlib utillib.a X rm -f *.o X clean: X rm -f *.o END_OF_FILE if test 287 -ne `wc -c <'Vplot_Kernel/filters/utilities/Makefile'`; then echo shar: \"'Vplot_Kernel/filters/utilities/Makefile'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/filters/utilities/Makefile' fi if test -f 'Vplot_Kernel/lvplot/README' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/lvplot/README'\" else echo shar: Extracting \"'Vplot_Kernel/lvplot/README'\" \(568 characters\) sed "s/^X//" >'Vplot_Kernel/lvplot/README' <<'END_OF_FILE' This directory contains the source for libvplot. This is a set of C and FORTRAN bindings for the vplot metalanguage. X The shell script "fixcplot" will convert from older vplotlib names to the new, standardized names. X Hopefully all of these routines should work. It is quite possible that some of the lesser-used ones may still harbor bugs. The FORTRAN bindings are considerably less tested than the C ones. X You will need to edit the Makefile to tailor it for your site. X If you are using 4.3, you will have to #define FOURTHREEBSD when you compile. X X- Joe Dellinger END_OF_FILE if test 568 -ne `wc -c <'Vplot_Kernel/lvplot/README'`; then echo shar: \"'Vplot_Kernel/lvplot/README'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/lvplot/README' fi if test -f 'Vplot_Kernel/util/Makefile' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/util/Makefile'\" else echo shar: Extracting \"'Vplot_Kernel/util/Makefile'\" \(409 characters\) sed "s/^X//" >'Vplot_Kernel/util/Makefile' <<'END_OF_FILE' LOCLIB= ../filters/loclib/loclib.a GROUP= graphics B= /usr/local/ CFLAGS= -I../filters/include X all: plas pldb X install: all X install -m 555 -g $(GROUP) plas $Bplas X install -m 555 -g $(GROUP) pldb $Bpldb X plas.o: plas.c X cc $(CFLAGS) -c -O plas.c X plas: plas.o X cc plas.o -O $(LOCLIB) -lm -o plas X pldb.o: pldb.c X cc $(CFLAGS) -c -O pldb.c X pldb: pldb.o X cc pldb.o -O $(LOCLIB) -lm -o pldb X clean: X rm *.o END_OF_FILE if test 409 -ne `wc -c <'Vplot_Kernel/util/Makefile'`; then echo shar: \"'Vplot_Kernel/util/Makefile'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/util/Makefile' fi if test -f 'Vplot_Kernel/util/tube.example' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'Vplot_Kernel/util/tube.example'\" else echo shar: Extracting \"'Vplot_Kernel/util/tube.example'\" \(564 characters\) sed "s/^X//" >'Vplot_Kernel/util/tube.example' <<'END_OF_FILE' X#!/bin/csh -f X# X# Keywords: graphics vplot tty X# X# Here is an example of a shell which will pick the appropriate X# pen filter for the user's terminal, so he doesn't have to remember. X# X if($TERM =~ gigi*) then X gigipen $* X else if($TERM =~ envision220*) then X envipen $* X else if($TERM =~ envision*) then X envipen wstype=envi215 $* X else if($TERM =~ tek4105*) then X ctekpen $* X else if($TERM =~ grif* || $TERM == vt100 || $TERM == tek4014) then X tekpen $* X else if($TERM =~ D2) then X rpen $* X else X echo "tube: No Graphics available on that device\!\!" X endif END_OF_FILE echo shar: 1 control character may be missing from \"'Vplot_Kernel/util/tube.example'\" if test 564 -ne `wc -c <'Vplot_Kernel/util/tube.example'`; then echo shar: \"'Vplot_Kernel/util/tube.example'\" unpacked with wrong size! fi chmod +x 'Vplot_Kernel/util/tube.example' # end of 'Vplot_Kernel/util/tube.example' fi echo shar: End of archive 21 \(of 24\). cp /dev/null ark21isdone MISSING="" for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 24 archives. rm -f ark[1-9]isdone ark[1-9][0-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 -- Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.