Editing Graphics development with vplot (section)

==Variables==
The following variables are used to communicate information between dovplot and the device routines.

These variables must be initialized in either dev.open or dev.reset:

<syntaxhighlight lang="c">
int dev_xmax, dev_ymax, dev_xmin, dev_ymin;
</syntaxhighlight>
These variables should give the device coordinates of the lower-leftmost and upper-rightmost pixels on the device screen. It is assumed that the device X axis is horizontal and the device Y axis is vertical, and that dev_xmax > dev_xmin and dev_ymax > dev_ymin. If this is not true for your device, it is up to the device routines to transform the device coordinate system so it is true. (Examples of devices that do this are gigipen and ipen.)

<syntaxhighlight lang="c">
float pixels_per_inch, aspect_ratio;
</syntaxhighlight>
Pixels_per_inch gives the number of pixels per inch on the device in the horizontal direction. Aspect_ratio gives the height to width ratio of the pixels. (Aspect_ratio > 1 means that the pixels are tall and skinny, and thus that the resolution is less in the vertical direction than in the horizontal direction.)

<syntaxhighlight lang="c">
int num_col;
</syntaxhighlight>
Num_col is the number of settable colors that the device has. Colors that can't be reset from the host don't count. Currently num_col can be at most 256, because this is all the raster routines can handle (due to use of unsigned char's). If mono=y is set, init_vplot will set num_col to zero.

The following variables are set by dovplot but may be reset in dev.open (NOT dev.reset) if the default value is not appropriate. For the most part, resetting these variables is for the purpose of making a device-dependent default; the user is given a chance to override the value the device sets them to.
<syntaxhighlight lang="c">
int size=RELATIVE;
</syntaxhighlight>
Large hardcopy devices (the kinds that make wallpaper plots) should set this to size=ABSOLUTE, or else people will regularly make 5 foot tall graphs with 6 inch high labels. Normal devices, like terminals or laserprinters, should just take the default.

<syntaxhighlight lang="c">
int mono=NO;
</syntaxhighlight>
If mono=NO, then the device is assumed to have color EVEN IF num_col is zero. If mono=YES, then the device is monochrome. (The user cannot override mono=YES, but can mono=NO.) See comments about the effects of mono and num_col on color in dev.attributes below, and on raster in dev.raster. Mono=YES forces num_col=0.

<syntaxhighlight lang="c">
int invras=YES;
</syntaxhighlight>
This variable is only used in the utility routine "greycorr.c". Invras is meant to be used with dithered raster. Raster is only dithered if mono=YES and dither>0. Normally such devices draw in black on a white page, which is the reverse of what is normal for screen devices, and so invras=YES. If the background color is BLACK then invras should be NO. Devices which dither for themselves do not need to do the inverting; it is done before the raster is passed to the device routine.

<syntaxhighlight lang="c">
int dither=1;
</syntaxhighlight>
Default dithering style to use for this device. See vplotraster(9) for the different values to be explained.

<syntaxhighlight lang="c">
float greyc=1.;
</syntaxhighlight>
This variable is used only when dithering is being performed, and really should only be used for hardcopy devices. It alters the grey scale so that grey rasters come out on paper with the same nonlinear appearance that is perceived on display devices. See vplotraster(9) for a discussion of the parameter and how to use it.

<syntaxhighlight lang="c">
float pixc=1.;
</syntaxhighlight>
This variable is used only when dithering is being performed, and also should only be used for hardcopy devices. It alters the grey scale to correct for pixel overlap on the device, which (if uncorrected) causes grey raster images to come out much darker on paper than on graphics displays. See vplotraster(9) for a discussion of the parameter and how to use it.

<syntaxhighlight lang="c">
int txfont=DEFAULT_FONT, txprec=DEFAULT_PREC;
</syntaxhighlight>
Default text font, precision, and overlay mode. Text fonts of less than NUMGENFONT are reserved for genvector fonts. If you want the device to by default use some nice hardware font, you can reset txfont to the appropriate device-dependent font number. Alternatively, if the device is one in which plotting speed is not a problem, txfont can be set to DEFAULT_HARDCOPY_FONT. Txprec is pretty much ignored by genvector. Fancy output devices should 	set txprec to DEFAULT_HARDCOPY_PREC to enable ligatures. Txprec may be used by device-dependent text routines. Txprec must be in the range 0 through 2.

<syntaxhighlight lang="c">
float hshift=0., vshift=0.; int rotate=0;
</syntaxhighlight>
These values are in addition to whatever the user may set from the command line. This provides a way for a device to rotate or translate all plots.

<syntaxhighlight lang="c">
int shade=YES;
</syntaxhighlight>
If shade=NO, then no attempt will be made by vplot to ask the device to shade the interiors of polygons due to the vplot `a' and `A' commands. Instead it will just outline them with vectors whenever it tries to fill a polygon. This option is for devices that CAN fill but are very slow to do so.

<syntaxhighlight lang="c">
int wantras=YES;
</syntaxhighlight>
If wantras=NO, then no attempt will be made by vplot to ask the device to handle raster due to the vplot `r' and `R' commands. Instead it will just shade the raster area solid white using dev.area. This option is for devices that CAN do raster but are very slow to do it.

<syntaxhighlight lang="c">
float fatmult=1., patternmult=1.;
</syntaxhighlight>
If fat lines are too slow, you can set fatmult=0. and disable line fattening. The user can still turn it on again by overriding with fatmult=1 from the command line. Patternmult can be used to scale up or down patterns by default on a specific device.

<syntaxhighlight lang="c">
int endpause=NO;
</syntaxhighlight>
If the device needs a pause at the end of the plot (via dev.close(CLOSE_PAUSE) and then dev.interact(INT_F_PAUSE)) then endpause should be set to YES.

<syntaxhighlight lang="c">
int cachepipe=NO;
</syntaxhighlight>
If the device may need to reread files it will have problems with pipes. If cachepipe is set to YES any piped input will be copied to a temporary file. This allows reverse seeks on the file. On the other had you incur the overhead of the copy so the user may want to turn it off for humongous files. 	This option is currently set to YES in vppen, xvpen and sunpen.

<syntaxhighlight lang="c">
int allowecho=?;
</syntaxhighlight>
Allowecho controls whether echoing is turned off for the duration of plotting. Allowecho=NO turns off echoing. If the dev.open sets allowecho, dovplot assumes that it knows what it's doing and leaves it alone. Otherwise, dovplot tries to decide whether allowecho should be YES or NO depending on where the output stream pltout goes. If after calling dev.open pltout and stderr point to the same place, then it assumes that allowecho should be NO. The user can force allowecho to be YES from the command line if the device or dovplot set it to be NO, but the user cannot force it to be NO.

<syntaxhighlight lang="c">
int (*message)()=genmessage;
</syntaxhighlight>
Dovplot decides where to send messages (such as error messages, for example) in the same way that it decides how to set allowecho. Before dev.open has been called, the device is not open and dev.message cannot be called. Instead, it is assumed that it is safe to send all messages to stderr by calling genmessage instead. After dev.open has been called, dovplot checks to see whether stderr and pltout point to the same place. If they do, then from then on all messages are routed to dev.message. However, if they do NOT point to the same place, then it is assumed that it is still safe to route them to stderr and messages are still handled by genmessage. If this logic is incorrect for your device you will need to reset this variable to dev.message in dev.open. So far the only devices for which dovplot's logic has been wrong have been virtual ones. The user cannot determine where messages are to 	be sent.

The following variables can usually be left at their default values, but may have to be reset for some devices. They cannot be changed by the user.

<syntaxhighlight lang="c">
int need_end_erase=NO;
</syntaxhighlight>
Some devices use the "erase" routine to do things such as write out a rasterized plot image as well as for erasing. For such devices it is convenient to have dev.erase called one last time before the device is closed (via dev.erase(ERASE_END)). To get this, set need_end_erase=YES.

<syntaxhighlight lang="c">
int buffer_output=YES;
</syntaxhighlight>
If for some reason buffering the output to your device is a bad thing to do, set buffer_output=NO. This only applies if you use the FILE *pltout 	that dovplot provides.

<syntaxhighlight lang="c">
int smart_clip=NO;
</syntaxhighlight>
If smart_clip=NO, then dovplot will do all clipping for you, with the exception of polygons supported at the dev.area level. If you can do your own clipping, then set smart_clip=YES. You must then handle dev.attributes(SET_WINDOW)!

<syntaxhighlight lang="c">
int smart_background=NO;
</syntaxhighlight>
If smart_background=YES, then dovplot will handle the background command for you by drawing a borderless polygon of color 0 to exactly fill the plottable area. If your device already handles setting the background color to match whatever color 0 has been redefined to, then you can set this variable to "YES". Dovplot will then call dev.erase(ERASE_BACKGROUND) when it encounters this command, which the device can use to implement the command if needed. Devices that naturally honor changes to color 0 can ignore this command.

<syntaxhighlight lang="c">
int smart_raster=NO;
</syntaxhighlight>
If you can stretch AND clip your own raster, then set smart_raster=YES. It is then up to you to do all the stretching and clipping (and possibly dithering) of raster in the dev.raster routine, as dovplot will not then do it for you.

The following variables may be useful to refer to in dev.open, so that one pen filter can support multiple devices:

<syntaxhighlight lang="c">
char callname[]="filename";
char wstype[]="default";
</syntaxhighlight>
Callname gives the name the person invoked to run this pen filter. (The leading path is stripped for you if present.) If the person has "wstype=work_station_type" as a command line option, then wstype will be set to the string "work_station_type". Otherwise, it will be set to "default". Note that the only routine that REALLY has to be defined in dev.conf is dev.open, and the only routines that REALLY have to be defined in dev.open are dev.close, dev.reset and dev.message. However, by the time dev.reset returns everything had better be defined. Thus you can decide inside dev.open which subroutines to plug into the device table, after looking at wstype and callname to tell you which device you are supporting.