Devices
Prev | Chapter 3. Advanced Use of PLplot | Next

## 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.

The list of available devices is determined at configuration time by our CMake-based build system based on what device drivers are possible and what devices are enabled by default for a given platform. Most users just accept that default list of devices, but it is also possible for users to modify the list of enabled devices in any way they like. For example, they could use `-DPLD_svg=OFF` to exclude just the svg device from the default list; they could use `-DDEFAULT_NO_DEVICES=ON -DPLD_svg=ON` to enable just the svg device (say if they were interested just in that device and they wanted to save some configuration and build time); or they could use `-DDEFAULT_ALL_DEVICES=ON -DPLD_svg=OFF` to enable all devices other than svg. Note, however, extreme caution should be used with `-DDEFAULT_ALL_DEVICES=ON` since the result is often one of the "disabled by default" devices below gets enabled which is almost always problematic since those devices are typically unmaintained, deprecated, or just being developed which means they might not even build or if they do build, they might not run properly.

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”.

Table 3.1. PLplot File Devices

Description | Keyword | Source code | Default?
--- | --- | --- | ---
PDF (cairo) | pdfcairo | cairo.c | Yes
PNG (cairo) | pngcairo | cairo.c | Yes
PostScript (cairo) | pscairo | cairo.c | Yes
Encapsulated PostScript (cairo) | epscairo | cairo.c | Yes
SVG (cairo) | epscairo | cairo.c | Yes
CGM | cgm | cgm.c | No
Encapsulated PostScript (Qt) | epsqt | qt.cpp | Yes
PDF (Qt) | pdfqt | qt.cpp | Yes
BMP (Qt) | bmpqt | qt.cpp | Yes
JPEG (Qt) | jpgqt | qt.cpp | Yes
PNG (Qt) | pngqt | qt.cpp | Yes
PPM (Qt) | ppmqt | qt.cpp | Yes
TIFF (Qt) | tiffqt | qt.cpp | Yes
SVG (Qt) | svgqt | qt.cpp | Yes
PNG (GD) | png | gd.c | No
JPEG (GD) | jpeg | gd.c | No
GIF (GD) | gif | gd.c | No
PDF (Haru) | pdf | pdf.c | Yes
PLplot Native Meta-File | plmeta | plmeta.c | No
PostScript (monochrome) | ps | ps.c | Yes
PostScript (color) | psc | ps.c | Yes
PostScript (monochrome), (LASi) | psttf | psttf.cc | Yes
PostScript (color), (LASi) | psttfc | psttf.cc.c | Yes
SVG | svg | svg.c | Yes
XFig | xfig | xfig.c |

Table 3.2. PLplot Interactive Devices

Device | Keyword | Source Code | Default?
--- | --- | --- | ---
Aquaterm | aqt | aqt.c | Yes
X (cairo) | xcairo | cairo.c | Yes
Windows (cairo) | wincairo | cairo.c | Yes
X or Windows (Qt) | qtwidget | qt.cpp | Yes
X | xwin | xwin.c | Yes
Tcl/Tk | tk | tk.c | Yes
New Tcl/Tk | ntk | ntk.c | Yes
Windows | wingcc | wingcc.c | Yes
wxWidgets | wxwidgets | wxwidgets*.cpp |

### Driver Functions

A dispatch table is used to direct function calls to whatever driver is chosen at run-time. Below are listed the names of each entry in the PLDispatchTable dispatch table struct defined in `plcore.h`. The entries specific to each device (defined in `drivers/*.c`) are typically named similarly but with “pl_” replaced by a string specific for that device (the logical order must be preserved, however). The dispatch table entries are :

- `pl_MenuStr`: Pointer to string that is printed in device menu.

- `pl_DevName`: A short device "name" for device selection by name.

- `pl_type`: 0 for file-oriented device, 1 for interactive (the null driver uses -1 here).

- `pl_init`: Initialize device. This routine may also prompt the user for certain device parameters or open a graphics file (see Notes). Called only once to set things up. Certain options such as familying and resolution (dots/mm) should be set up before calling this routine (note: some drivers ignore these).

- `pl_line`: Draws a line between two points.

- `pl_polyline`: Draws a polyline (no broken segments).

- `pl_eop`: Finishes out current page (see Notes).

- `pl_bop`: Set up for plotting on a new page. May also open a new a new graphics file (see Notes).

- `pl_tidy`: Tidy up. May close graphics file (see Notes).

- `pl_state`: Handle change in PLStream state (color, pen width, fill attribute, etc).

- `pl_esc`: Escape function for driver-specific commands.

Notes: Most devices allow multi-page plots to be stored in a single graphics file, in which case the graphics file should be opened in the pl_init() routine, closed in pl_tidy(), and page advances done by calling pl_eop and pl_bop() in sequence. If multi-page plots need to be stored in different files then pl_bop() should open the file and pl_eop() should close it. Do NOT open files in both pl_init() and pl_bop() or close files in both pl_eop() and pl_tidy(). It is recommended that when adding new functions to only a certain driver, the escape function be used. Otherwise it is necessary to add a null routine to all the other drivers to handle the new function.

### 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. For example:

    	  % x01c

    	  Plotting Options:
    	  < 1> xwin       X-Window (Xlib)
    	  < 2> tk         Tcl/TK Window
    	  < 3> ps         PostScript File (monochrome)
    	  < 4> psc        PostScript File (color)
    	  < 5> xfig       Fig file
    	  < 6> null       Null device
    	  < 7> ntk        New tk driver
    	  < 8> tkwin      New tk driver
    	  < 9> mem        User-supplied memory device
    	  <10> wxwidgets  wxWidgets Driver
    	  <11> psttf      PostScript File (monochrome)
    	  <12> psttfc     PostScript File (color)
    	  <13> svg        Scalable Vector Graphics (SVG 1.1)
    	  <14> pdf        Portable Document Format PDF
    	  <15> bmpqt      Qt Windows bitmap driver
    	  <16> jpgqt      Qt jpg driver
    	  <17> pngqt      Qt png driver
    	  <18> ppmqt      Qt ppm driver
    	  <19> tiffqt     Qt tiff driver
    	  <20> svgqt      Qt SVG driver
    	  <21> qtwidget   Qt Widget
    	  <22> epsqt      Qt EPS driver
    	  <23> pdfqt      Qt PDF driver
    	  <24> extqt      External Qt driver
    	  <25> memqt      Memory Qt driver
    	  <26> xcairo     Cairo X Windows Driver
    	  <27> pdfcairo   Cairo PDF Driver
    	  <28> pscairo    Cairo PS Driver
    	  <29> epscairo   Cairo EPS Driver
    	  <30> svgcairo   Cairo SVG Driver
    	  <31> pngcairo   Cairo PNG Driver
    	  <32> memcairo   Cairo Memory Driver
    	  <33> extcairo   Cairo External Context Driver

    	  Enter device number or keyword:

Either the device number or a device keyword is accepted. Specifying the device by keyword is preferable in aliases or scripts since the device number is dependent on the install procedure (the installer can choose which device drivers to include). The device can be specified prior to the call to `plinit` by:

- A call to `plsdev`.

- The `-dev` `device` command line argument, if the program's command line arguments are being passed to the PLplot function `plparseopts`.

- The value of the `PLPLOT_DEV` environment variable. Note that specifying the output device via `plsdev` or the `-dev` command line argument will override the value given by the `PLPLOT_DEV` environment variable.

Additional start up routines `plstar` and `plstart` are available but these are simply front-ends to `plinit`, and should be avoided. It is preferable to call `plinit` directly, along with the appropriate setup calls, for the greater amount of control this provides (see our standard examples for more info).

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.

Prev | Up | Next
Command Line Arguments | Home | Adding FreeType Library Support to Bitmap Drivers