Subject: v14i025: Device-independant graphics system, with drivers Newsgroups: comp.sources.unix Sender: sources Approved: rsalz@uunet.UU.NET Submitted-by: Joe Dellinger Posting-number: Volume 14, Issue 25 Archive-name: vplot/part20 #! /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 'Vplot_Kernel/Documentation/vplot.mn' <<'END_OF_FILE' X.TH VPLOT 9 X.SH NAME vplot - definition of the vplot graphics metalanguage X.SH INTRODUCTION Vplot is a graphical meta-language that is interpreted by the X.B pen filters to produce plotted images in a device-independent way on many different graphics terminals and hard copy devices. New devices can readily be supported. Unfortunately, X.B vplot has only a primitive interactive capability. The reason for writing your plots in a device-independent intermediate plot language such as X.B vplot is to make your plot programs portable and long lasting. X.PP Vplot originally stood for `vector plot', but this name is now insufficient because vplot supports not only vectors, but also filled areas (either raster patterns or hatched), text (Hershey fonts), and raster images X(including grey-scale dithered ones on monochrome devices such as laser printers). X.SH COPYRIGHT Vplot is not in the public domain, although the copyright is not very restrictive. Here is the official Vplot copyright notice (the one that all the other manual pages and the source code tell you about): X.PP Copyright 1987 the Board of Trustees of the Leland Stanford Junior University. All Rights Reserved. Permission is hereby given to use, copy, modify, and distribute this software provided that (1) copyright and proprietary notices are retained in each copy, (2) any files which are modified are identified as such, and (3) you do not copy or distribute the software for payment or for commercial use without prior written consent from Stanford. STANFORD MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND concerning this software or its use. X.PP Vplot consists of everything in this distribution, except for the contents of ``.../vplot/Hershey'' and ``.../vplot/filters/loclib''. These are in the public domain. The contents of ``.../vplot/Hershey_Fonts'', which may or may not be included in your copy of the distribution, are under their own restrictions contained in the file README_Hershey. X.PP You are invited to make improvements to Vplot, support new devices, fix bugs, use Vplot as a spare parts junkyard, etc, as long as you abide by the copyright given above. Older public domain versions of Vplot exist, although not as complete and as bug-free as this ``official'' version. Before embarking on any major project, you might want to ask me (Joe Dellinger) for advice as to how to proceed. Other than that, you're on your own. When all else fails, read the manual! X(And when that fails, read the source code.) X.PP You can get a tape of this distribution at cost by writing: X.br X X.br X Office of Technology Licensing X.br X Stanford University X.br X 350 Cambridge Avenue, Suite 250 X.br X Palo Alto, CA 94306 X.br X X.SH ASSOCIATED PROGRAMS Self-documenting Utilities: pldb plas X.br For info on pen programs: man pen X.br For info on libvplot: man libvplot X.br For info on text under vplot: man vplottext X.br For info on raster under vplot: man vplotraster X.br Library of test routines and examples: .../vplot/filters/Tests/* X.SH COORDINATE SYSTEMS Vplot fits the largest 3-high by 4-wide rectangle X(or whatever ratio is defined by SCREENRATIO in vplot.h) onto the device's screen that it can. The rectangle is left and bottom justified. Clipping is not done to the edge of this rectangle, but to the edge of the device's screen. For convenience, from here on in the documentation I will consider the X3 by 4 rectangle inscribed inside the device's screen to BE the device's screen for the purposes of describing Vplot's coordinate system. X Vplot coordinates can either be measured in integer vplot units (the actual integer numbers that go into the metafile) or as real inches. How many integer units there are per inch for various sorts of Vplot primitives is defined in vplot.h. RPERIN is the number of integer vplot units per inch for most things. Unfortunately, in order to be backwards compatible we have to measure some primitives in different units: TXPERIN gives the number of text-height units per inch, and FATPERIN gives the number of line-fatness-width units per inch. X(HATCHPERIN is only used by libvplot, not vplot itself.) At Stanford, RPERIN=600, FATPERIN=200, and TXPERIN=33. These are not particularly convenient numbers, and new sites installing Vplot from scratch might consider selecting more reasonable values for all of these. (In theory, all you should have to do is change the definitions in vplot.h, update the documentation, and recompile everything in sight.) Whenever any of these ``magic numbers'' are referred to in code, they should be ``#define''d by vplot.h. X Two different scaling systems are possible, ``relative'' and ``absolute''. The so-called ``real inches'' in Vplot can either correspond to absolute inches on your device's screen (size=absolute), or can scale with the size of the screen (size=relative). How many inches tall the screen is considered to be unfortunately depends on the ``plot style'', which is defined next. X Two different coordinate systems are possible, ``standard'' and ``rotated''. X(This is called the ``plot style''.) The plot style can be set with the vplot `S' command, set from the command line, set from the environment, or allowed to default, with that order of precedence. X Standard Style: The origin is in the lower left hand corner, with the X axis horizontal and the Y axis vertical. If size=relative, the plot is scaled so that the screen is considered to be X10.24 (STANDARD_HEIGHT in vplot.h) inches tall. That is, if you move to the Vplot coordinate (in inches) of (x=0.,y=10.24), you will be at the top left corner of the screen no matter how big or small your device's screen actually is. X Rotated Style: Plot is scaled so that the screen is considered to be X7.5 inches tall. The origin is in the upper left hand corner, with the XX axis vertical running down the screen and the Y axis horizontal. If size=relative, the plot is scaled so that the screen is considered to be X7.5 (ROTATED_HEIGHT in vplot.h) inches tall. That is, if you move to the Vplot coordinate (in inches) of (x=7.5,y=0.) you will be at the bottom left corner of the screen no matter how big or small your device's screen actually is. X X.SH DESCRIPTION The following list constitutes the plot commands for the various plotting programs. The commands are universal in the sense that they are properly read in and appropriately used or ignored. The commands are specified by a literal one byte command character followed by zero or more half-word (2 byte) integers X(sometimes characters or bytes if so stated in the text). X.PP The program ``pldb'' converts the binary Vplot format described here into a human-readable ASCII one. Pldb-format Vplot follows the documentation here closely. Commas show where newlines occur in `pldb' format vplot that are not shown as newlines here. X.PP X.SH COMMANDS X.TP X.B e X.B erase the screen and start a new plot. All plot frames begin with an erase. X(The ``erase'' pen filter option can be used to add an erase as the very first thing in an input plot file, but will only do so if the plot file doesn't already have an initial erase. Erases that occur near, but not at, the beginning of the plot file are NOT considered initial erases, even if the commands preceding the erase produce no actual output on the device.) X.PP X.TP X.B b X.B break, same as erase in that it is a possible place to pause, but doesn't erase the screen. The erase command basically has 2 functions: first, it signals that the current frame of the plot is completed, and secondly it erases the current frame of the plot so that the next frame can start fresh. The break command only carries the first meaning. The ``next frame'' of the plot builds upon the previous ones. This is useful when you want to be able to stop at various times as an image is being built up. X.TP X.B o x y redefine X.B origin X(0,0) on the device (the lower left hand corner of the screen for standard plot style with no global translations via pen command line options) as vplot (x,y). This shift applies to everything until the next origin command. An origin command is not affected by previous ones. Changing the plot style resets the origin to zero. X.TP X.B m x y X.B move the current position to (x,y). X.TP X.B d x y X.B draw a line from the current position to (x,y), and make this the new current position. X.TP X.B w xmin ymin xmax ymax set clipping X.B window. The initial window is set to the maximum dimensions of the particular plot device. If the coordinate system is rotated, the smallest clipping window with vertical and horizontal sides that contains the desired rotated clipping window will be used. If xmin > xmax or ymin > ymax, then an inverted window will be used that should clip away everything. X.TP X.B T size orientation, string Start X.B text mode. A character X.B string is plotted starting at the old pen position (as set by a previous move, draw, or text command). A nullbyte terminates the string. The character X.B size X(the height) is in units of 1/33'rds of an inch (Ug!). The character width is font and character dependent. The character X.B orientation is in degrees, and the angle is measured counter-clockwise from the X-axis. The carriage controls newline, carriage return, and backspace are correctly interpreted. The origin for newline and carriage return is taken as the pen position as of the last move. X.IP A large number of special escape sequences for accessing multiple fonts, colors, sizes, fatnesses, symbols, and positions of text are available. See man vplottext. X.IP The archaic text command X.B t has been left in the code only for backwards compatibility. It should no longer be used, so I'm not going to even tell you the ridiculous format it used. X.TP X.B G xpath ypath xup yup, string An alternate text command, which uses X.B GKS notation. The vector given by X.B xpath and X.B ypath is the ``text path vector'', and the vector given by X.B xup and X.B yup is the ``text up vector'', as defined in the GKS standard. Since it is important for these vectors to be very accurate, both are measured in units TEXTVECSCALE (defined in params.h, set to 10 at Stanford) times finer than normal vplot units. X.TP X.B f k Set line X.B fatness. The integer X.B k specifies the number of additional lines to be drawn parallel to, and one bit over from all future lines. The extra lines are added symmetrically. k=0 resets back to single-line mode. The fatness is scaled to approximate the behavior of a 200 pixel per inch device. X.TP X.B c k Select new X.B color from menu of 512 colors. X.B K is an integer from 0 to 511. Colors 0 through 7 are guaranteed to be by default the Regis colors: X0-background, 1-blue, 2-red, 3-magenta, X4-green, 5-cyan, 6-yellow, and 7-white. X(This is the order of colors in a color bar pattern on a TV. It is used for that because on a black and white TV it makes a grey scale.) X.IP Color zero is always the background color. Monochrome devices should consider ANY non-zero color to NOT be the background color. X.IP See important comments in the `set color table' command with regards to color mapping. X.TP X.B C color red green blue set X.B Color table: Color number X.B color is set to have red value X.B red, green value X.B green, and blue value X.B blue. These are integers from 0 to 255, (or floats from 0. to 1. when using plas and pldb in inch or centimeter units) with 255 being fully on and 0 being fully off. The corresponding `grey level' for grey-scale devices is given by floor((4 * green + 2 * red + blue + 6) / 7). Note that the only way to get grey level 0 is if all three color levels are 0. X.IP Vplot will try to give you the color you want, but this may not always be possible. If the device has N settable colors, then colors X0 through N-1 will be set exactly as you request. If you attempt to define a color X outside of this range, Vplot will pick which color in the range 0 through N-1 is the closest and map all requests for color number X to that available color value. Whenever any color in the range 0 through N-1 is changed, all the mappings will be re-calculated (although of course what is already drawn or stored cannot be changed.) X.IP This scheme is especially useful when for example mixing grey scales for raster information and bright colors for labels. The few bright colors which you might need are allocated to the first few color numbers. Then the remainder of the lower half of the color scale is filled with the grey level values you will need, but ordered so that the most important grey levels come first. In the upper half of the color table you define a normally ordered grey scale. Now when you want to draw grey scales, you refer only to the upper half of the grey scale and vplot will automatically map your requests down onto the real available colors of the particular device. X.IP Color zero is always the background color. Color 0 is only mapped to if the match is exact. X.TP X.B a npts X.TP X.B afat xmask ymask X.TP X.B x1 y1, x2 y2, ... Define polygonal X.B area for stippling (on monochrome devices) or solid area fill with current drawing color (for devices with color). The polygon is specified by its vertices X.B (x1,y1),...,(xn,yn). X.B Npts is the number of vertices; the polygon is automatically closed only if necessary. X.B Afat is the fatness of the outline; 0 is the minimum, and -1 draws no outline. The shading for monochrome devices is determined by the integer mask. A point within the polygonal area is darkened if X((x mod X.B xmask X== 0) and (y mod X.B ymask X)) is true, where x and y are all points within the polygon. For example, xmask=1 and ymask=1 fills the area completely, and xmask=1 ymask=5 makes horizontal bars spaced 4 vertical bits apart. The origin for x and y coordinates used in shading is device dependent but will usually be the lower left hand corner of the device screen. X.IP As a special case, if either X.B xmask or X.B ymask is zero no shading is done. (The area filling routine for the device is never even called.) This is true for both color and monochrome devices. X.TP X.B A npts X.TP X.B x1 y1, x2 y2, ... Fill polygonal X.B area with pattern or color. Fills polygon with patterns loaded with the `l' command (q.v.). The pattern number used is the same as the current drawing color. Note that a pattern can either be a hatch-line pattern or an arbitrary raster pattern, depending on the format of the `l' command used. X.IP The purpose of this scheme is to associate each color with a particular fill pattern. Once a current drawing color is set, all vectors will have that color and all filled areas will have the associated fill pattern. X.IP Devices that can't fill with arbitrary patterns should simply fill solidly with the current drawing color. If no pattern has been loaded, the `A' command will fill solidly with the current drawing color automatically. X.TP X.B l ppi nx ny ipat X.TP X.B XXXX..., ... (nx*ny X's) X.B Load raster pattern for `A' command. Each X.B `X' is an integer containing a color number. X(These color numbers can be mapped, etc, just like color numbers in the `c' command.) The X.B X's represent pixels in a rectangular pattern of dimensions nx by ny. X(In pldb format the X.B X's are single-digit Hex numbers.) The pattern is repeated to fill the polygon. The pattern is scanned so that the first ny numbers are the first line, the second ny numbers are the second line, etc, for nx lines. The scanning of the pattern is done TV-style, ie starting at the upper left and working left-to-right and then top-to-bottom. (If in doubt, remember that patterns should appear on the device in the same orientation as in pldb-format vplot files.) X.IP The pattern is given the pattern number X.B ipat. This pattern will be used for filling by the `A' command when the current color is number X.B ipat. X.B Ppi is used to scale the pattern; it says how many pixels per inch you wanted this pattern to have. E.g. on a 300 pixel per inch device X.br X.B l 300 2 2 17 X.br X.B 0 1 X.br X.B 2 0 X.br represents X.br X01 X.br X20 X.br whereas X.br X.B l 150 2 2 17 X.br X.B 0 1 X.br X.B 2 0 X.br represents X.br X0011 X.br X0011 X.br X2200 X.br X2200 X.br where the digits are color numbers for the corresponding pixels. The result when you load a new pattern with the same pattern number as one already defined is device-dependent. X.TP X.B l angle -1 numhatch ipat X.TP X.B fat color offset interval, X.TP X.B ..., X.TP X.B (numhatch * 2 sets of 4) X.B Load hatch pattern for `A' command. The X.B angle gives the amount to rotate off horizontal. The X.B `-1' is a flag to distinguish this case from the previous command. X.B Numhatch is the number of sets of hatched lines to place in each direction (X and Y). Each set of hatched lines has four parameters: X.B fat, color, offset, and X.B interval. The X.B fat and X.B color give the fatness and color of every line in the set. The X.B interval is the spacing (in regular vplot units) between the lines. The X.B offset parameter displaces all the lines in the set. It should be less than the repeat interval. The purpose of X.B offset is so that you can have two different sets of lines (differently colored, perhaps) interleaved. All the X sets are specified, and then all the Y sets. X.IP X.B Ipat is the pattern number. (See above for explanation.) X.TP X.B v flag Change X.B overlay mode. X.br Overlay mode controls the opacity of the background color of polygon and raster fills (see `a',`A',`l',`r',`R'). If flag=0, the polygon area is cleared before the new pattern is filled in. If flag=1, the new pattern is simply added to whatever is already there with what is underneath showing through where the new pattern is color 0. The default overlay flag can also be set in the command line. flag=0 mode takes significantly longer to fill the polygon on many devices. Some devices that have hardware raster or area fill may ignore this option if they are unable to implement it. X.TP X.B n X.B no-op for word aligning. Does nothing. X.TP X.B p X.B purge or flush plot buffers. X.TP X.B z, string Print X.B string out on the text screen of the plot device. X.TP X.B L npts X.TP X.B x1 y1, x2 y2, ... Draw a X.B polyLine through the given points. X.TP X.B M npts mtype msize X.TP X.B x1 y1, x2 y2, ... Draw X.B Markers of type X.B mtype and size X.B msize at the given set of points. For small integer values of X.B msize, this is as defined in GKS. For larger values, it is taken to be a font glyph number (for most fonts this will correspond to the ASCII character number. However X.B mtype may still be valid even when greater than 255 for some fonts.) X.B msize is measured in the same units as text is. X.TP X.B s ndash X.TP X.B dash1 gap1, dash2 gap2, ... Set line X.B style. This command is used to make dashed or dotted lines. It affects all vectors produced by the `m', `d', and `L' commands. X.B Ndash is the number of dash-gap pairs in the pattern. If X.B ndash is 0, then continuous vectors will be drawn. X.TP X.B J hjust vjust Set text X.B Justification. Values have meanings set in the include file X`/usr/include/vplot.h'. The finer points of text justification are discussed in `man vplottext'. X.TP X.B F font precision overlay_mode Set text X.B Font and X.B precision. X.B Font is an integer from 0 on up. Font numbers less than 100 are reserved for device-independent `gentext' fonts. X.B Precision is an integer zero through two, meaning: string, 0; char, 1; stroke, 2. The generic vplot text routine gentext draws everything with stroke precision, but only parses for ligatures at precision 2. The standard `pen' font should be font number 0. How many others are available is site-dependent, and should be documented in `man vplottext'. X.IP The overlay mode is an integer from 0 through 3, with the following meanings: X0: nothing unusual. 1: Draw a box around the text. 2: Clear behind the text with a polygon drawn in the background color before drawing the text. X3: both 1 and 2. X.IP All fonts, precisions, and text overlay modes are``#define''d in vplot.h. X.TP X.B S styleflag Set Vplot X.B Style. X.br Style is a single character, with possible values X`r' rotated, `s' standard, `a' absolute. Case distinctions don't matter. These affect the scaling and orientation of the plot. X``Standard'' and ``rotated'' styles are defined in the ``Coordinates'' section at the beginning of this document. Absolute style is like standard style, except the plot is scaled to be in true inches. Some other archaic styles are recognized (old, mazama) but should no longer be used. The style is reset to the default at the start of every plot frame. It is probably a good idea to set the style immediately after every X.B erase command, especially if the style you want to use is not STANDARD. X.TP X.B R orient offset X.TP X.B xll yll, xur yur X.TP X.B xpix ypix X.TP X.B {linerep1, {numpat1 numbyte1, b1, b2, ...}} Byte deep X.B Raster data, each point having X.B offset added to it as it is read in. It is X.B xpix pixels wide and X.B ypix pixels tall, with lower left hand pixel at X.B (xll, yll) and width X.B xur-xll and height X.B yur-yll. X.B Linerep tells how many times to repeat the following raster line. X.B Numpat gives the number of repetitions of the following X.B numbyte bytes X.B b1, b2, ... bN within a line. This is repeated until all the bytes within the raster line have been accounted for. (The last byte of the line must also be the last byte of the repeat pattern.) The same holds for the loop over lines. X.IP The orientation of the axes of the raster is determined by the value of X.B orient. For X.B orient=0 the raster is oriented TV-style, with the fast axis left-to-right and the slow axis top-to-bottom. For each increase of 1 in the value of X.B orient, the raster rotates 90 degrees clockwise. X.IP Note that the lower-leftmost pixel of the raster image will be exactly at the vplot coordinate X.B (xll,yll). However, the point at vplot coordinate X.B (xur,yur) will be the pixel just outside the raster image, touching the upper-rightmost corner. Things were done this way so that X.B xur-xll for example gives the width of the raster data box in vplot units. X.IP The X.B offset parameter is provided so that there is some way to access color table values greater than 255. (For example, 4 different 64-value color schemes could be defined in the color table in slots 256-511. You could switch between these by merely changing the value of X.B `offset'. X) X.TP X.B r orient rastermult X.TP X.B xll yll, xur yur X.TP X.B xpix ypix X.TP X.B {linerep1, {numpat1 numbit1, b1, b2, ...}} Same format as the `R' command, except that the data is encoded in bits and X.B rastermult is multiplied by the value of each bit. X8 bits are encoded into each byte, in each byte the bits ordered from highest to lowest. As many bytes are used as are needed to hold X.B numbit bits. For example, 13 bits would be encoded as X.br X.B b1: (1 2 3 4 5 6 7 8) b2: (9 10 11 12 13 X X X). X.TP X.B [, string Begin group named X.B string. X.TP X.B ] End last-opened group (it is an error to use this command if no group is open). Groups may be nested. Groups may not contain an erase command. Groups may not extend across files. X.SH "SEE ALSO" pen vplotlib vplottext vplotraster vplothacker X.SH "BUGS" There may be no bugs in the vplot language, but there are in the programs which read and write it. X.PP I had a heck of a time with troff bugs eating words and characters while trying to write this, so if something seems to be missing you might refer back to the unformatted original. X.PP Vplot at Stanford suffers somewhat by the restriction of having to remain backwards compatible to the stone age (1980). The vplot coordinate system is integers, with 600 pixels to the inch. A much higher resolution should be used! This isn't too hard to change, all you have to do is to make plas and pldb write and read 4 bytes instead of 2. (Plas and pldb already work with integers anyway, and there are no short ints used in the code anywhere.) Several other `magic numbers' show up in this documentation as well. These are defined in `vplot.h' and `params.h'. I recommend that any new site starting to use vplot from scratch change these numbers to more reasonable values. If ALL code uses the #define's in vplot.h, as all Vplot source code (hopefully) does and all user code ought, then these values can be changed without breaking any programs, only old metafiles. X.SH "AUTHOR" Robert W. Clayton began the vplot software while in the Geophysics Department at Stanford University (circa 1979) on a PDP-11. He was last seen at Cal Tech. Since then Jeff Thorson, Stew Levin, Jon Claerbout, Dave Hale, Ron Ullmann, Glenn Kroeger, Michel Debiche, Shuki Ronen, Doug Wilson, Wes Monroe, Chuck Karish, Steve Cole, Clement Kostov, Kai Lanz, Jean-Luc Guiziou, and especially Joe Dellinger have altered and expanded it almost beyond recognition, for the most part preserving backwards compatibility, even when that required compromising of ideals. This manual page was hacked together by Joe Dellinger out of an ancient and out-of-date original by Michel Debiche, which was itself a hack of something even more ancient of unknown origin. X.br X X.br X Joe Dellinger, X.br X (joe@hanauma.stanford.edu, decvax!hanauma!joe, convex!convexw!hanauma!joe) X.br X Stanford Exploration Project X.br X Dept of Geophysics, Stanford University, Jan 1988 X.br X END_OF_FILE if test 25193 -ne `wc -c <'Vplot_Kernel/Documentation/vplot.mn'`; then echo shar: \"'Vplot_Kernel/Documentation/vplot.mn'\" unpacked with wrong size! fi # end of 'Vplot_Kernel/Documentation/vplot.mn' fi echo shar: End of archive 20 \(of 24\). cp /dev/null ark20isdone 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