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 :

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.

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.

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:

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.