PLPlot Devices
PLplot implements a set of device drivers which support a wide variety of devices. Each driver is required to implement a small set of low-level graphics primitives such as initialization, line draw, and page advance for each device it supports. In addition a driver can implement higher-level features such as rendering unicode text. Thus a driver may be simple or complex depending on the driver capabilities that are implemented.
Most PLplot devices can be classified as either noninteractive file devices or interactive devices. The available file devices are tabulated in Table 3.1, “PLplot File Devices” while the available interactive devices are tabulated in Table 3.2, “PLplot Interactive Devices”.
Family File Output
When sending PLplot to a file, the user has the option of generating a “family” of output files for most output file drivers. This can be valuable when generating a large amount of output, so as to not strain network or printer facilities by processing extremely large single files. Each family member file can be treated as a completely independent file.
To create a family file, one must simply call plsfam with the familying flag fam set to 1, and the desired maximum member size (in bytes) in bmax. plsfam also allows you to set the current family file number. If the current output driver does not support familying, there will be no effect. This call must be made before calling plstar or plstart.
If familying is enabled, the name given for the output file (on the command line, in response to the plstar prompt, as a plstart argument, or as the result of a call to plsfnam) becomes the name template for the family. Thus, if you request an svg output file with name test-%n.svg, the files actually created will be test-1.svg, test-2.svg, and so on, where %n indicates where the member number is replaced. If there is no %n, then the output file becomes the stem name and the created files will be test.svg.1, test.svg.2, and so on. A new file is automatically started once the byte limit for the current file is passed, but not until the next page break. One may insure a new file at every page break by making the byte limit small enough. Alternatively, if the byte limit is large you can still insure a new file is automatically started after a page break if you precede the call to pleop with a call to plfamadv.
If familying is not enabled, %n is dropped from the filename if that string appears anywhere in it.
The plgfam routine can be used from within the user program to find out more about the graphics file being written. In particular, by periodically checking the number of the member file currently being written to, one can detect when a new member file is started.
Specifying the Output Device
The main initialization routine for PLplot is plinit, which sets up all internal data structures necessary for plotting and initializes the output device driver. The output device can be a terminal, disk file, window system, pipe, or socket. If the output device has not already been specified when plinit is called, the output device will be taken from the value of the PLPLOT_DEV environment variable. If this variable is not set (or is empty), a list of valid output devices is given and the user is prompted for a choice.
The device can be specified prior to the call to plinit by A call to plsdev.
Before plinit is called, you may modify the number of subpages the output device is divided into via a call to plssub. Subpages are useful for placing several graphs on a page, but all subpages are constrained to be of the same size. For greater flexibility, viewports can be used (see the section called “Defining the Viewport” for more info on viewports). The routine pladv is used to advance to a particular subpage or to the next subpage. The screen is cleared (or a new piece of paper loaded) if a new subpage is requested when there are no subpages left on the current page. When a page is divided into subpages, the default character, symbol and tick sizes are scaled inversely as the square root of the number of subpages in the vertical direction. This is designed to improve readability of plot labels as the plot size shrinks.
PLplot has the ability to write to multiple output streams. An output stream corresponds to a single logical device to which one plots independent of all other streams. The function plsstrm is used to switch between streams. For any of our supported languages our standard example 14 demonstrates of how to use multiple output streams where the same device is used for both streams, but, of course, different devices can be used for different streams as well.
At the end of a plotting program, it is important to close the plotting device by calling plend. This flushes any internal buffers and frees any memory that may have been allocated, for all open output streams. You may call plend1 to close the plotting device for the current output stream only. Note that if PLplot is initialized more than once during a program to change the output device, an automatic call to plend1 is made before the new device is opened for the given stream.