<!-- -*-  mode: nxml -*- -->
<!--
    drivers.xml: "The PLplot X Driver Family" chapter

    Copyright (C) 1994 Geoffrey Furnish and Maurice LeBrun
    Copyright (C) 1999-2017 Alan W. Irwin
    Copyright (C) 1999, 2000, 2001, 2002, 2003 Rafael Laboissiere
    Copyright (C) 2003 Joao Cardoso
    Copyright (C) 2005 Thomas J. Duck

Redistribution and use in source (XML DocBook) and "compiled" forms
(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code (XML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs,
converted to HTML, PDF, PostScript, and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<chapter id="file-drivers">
  <title>Drivers which implement file devices</title>

  <para>
    Drivers which produce output files are described in this chapter.
    Each of the drivers has a list of options, and these may be set as
    outlined in <xref linkend="arguments" />.
  </para>

  <sect1 id="qt-driver">
    <title>The qt driver</title>

    <para>
      The qt driver uses the <ulink url="https://www.qt.io/">the Qt
      library</ulink> (either Qt4 or Qt5) to produce plots in the PDF, EPS
      (Encapsulated PostScript), PNG, JPEG, TIFF, SVG, BMP, and PPM file
      formats.  Text and graphics are antialised, font selection is done
      automatically for any given unicode glyph requested using the
      recommended fontconfig approach, and complex text layout is used to
      render text.  As a result this driver is considered to be one of our
      two best (our cairo driver described in <xref linkend="cairo-driver"/>
      is the other) file device drivers.
    </para>
  </sect1>

  <sect1 id="cairo-driver">
    <title>The cairo driver</title>

    <para>
      The cairo driver uses the Pango/Cairo subset of the <ulink
      url="https://www.gtk.org/">GTK+ suite of libraries </ulink> to produce
      plots in the PDF, PostScript, EPS (Encapsulated PostScript), PNG, and
      SVG file formats.  Text and graphics are antialised, font selection is
      done automatically for any given unicode glyph requested using the
      recommended fontconfig approach, and complex text layout is used to
      render text.  As a result this driver is considered to be one of our
      two best (our qt driver described in <xref linkend="qt-driver"/> is
      the other) file device drivers.
    </para>
  </sect1>

  <sect1 id="svg-driver">
    <title>The svg driver</title>

    <para>
      The svg driver produces SVG (Scalable Vector Graphics) files that are
      compliant with the SVG 1.1 specification as defined <ulink
      url="http://www.w3.org/Graphics/SVG/">here</ulink>.  This driver has
      no external library dependencies.  The driver is unicode enabled.  As
      SVG is just an XML based graphics language, the visual quality of the
      resulting plot (e.g., antialiasing of text and graphics, unicode system font
      availability, and handling of complex text layout issues) will depend
      on the SVG rendering engine that is used.
    </para>
  </sect1>

  <sect1 id="postscript-driver">
    <title>The ps driver</title>

    <para>
      The ps driver produces publication-quality PostScript
      output but only for a limited selection of glyphs.  The driver
      provides two devices: the ps device for black-and-white plots, and the
      psc device for color plots.
    </para>

    <para>
      This driver is unicode enabled, and PostScript Type I fonts are
      used.  This driver has no external
      library dependencies.  However, a drawback is that text layout is
      limited to left-to-right scripts (i.e., languages with complex text
      layout are not supported).  Furthermore, Type I fonts have an
      extremely limited selection of glyphs compared to, e.g., TrueType
      fonts (see <xref linkend="truetype-postscript-driver"/>). For this
      reason, Hershey fonts are used for drawing symbols by default for this
      device driver, unless specified otherwise using the driver options.
    </para>

    <para>
      The available driver options are:
      <itemizedlist>
	<listitem><para>
	  text: Use PostScript text (0|1); default 1
	</para></listitem>
	<listitem><para>
	  color: Use color (0|1); default 1
	</para></listitem>
	<listitem><para>
	  hrshsym: Use Hershey fonts for symbols (0|1); default 1
	</para></listitem>
      </itemizedlist>
    </para>

  </sect1>

  <sect1 id="truetype-postscript-driver">
    <title>The psttf driver</title>

    <para>
      This is a PostScript driver that supports TrueType fonts. This
      allows access to a far greater range of glyphs than
      is possible using Type 1 PostScript fonts
      (see <xref linkend="postscript-driver"/>).
      The driver provides two devices: the psttf device
      for black-and-white plots and the psttfc device for color plots.
    </para>

    <para>
      The driver requires the LASi (v1.0.5), pango and pangoft2 libraries
      to work. The pango and pangoft2 libraries are widely distributed
      with most Linux distributions and give the psttf driver full complex
      text layout (CTL) capability (see
      <ulink url="&PLplot-website;/examples.php?demo=24">
      &PLplot-website;/examples.php?demo=24</ulink>
      for an example of this capability).  The LASi library is not part of
      most distributions at this time. The source code can be downloaded
      from <ulink url="https://sourceforge.net/projects/lasi/files/lasi/"></ulink>.
      The library is small and easy to build and install.
    </para>

    <para>
      The available driver options are:
      <itemizedlist>
	<listitem><para>
	  text: Use TrueType fonts for text (0|1); default 1
	</para></listitem>
	<listitem><para>
	  color: Use color (0|1); default 1
	</para></listitem>
	<listitem><para>
	  hrshsym: Use Hershey fonts for symbols (0|1); default 0
	</para></listitem>
      </itemizedlist>
    </para>
  </sect1>

  <sect1 id="pdf-driver">
    <title>The pdf driver</title>
    <para>
      This basic PDF driver is based on the <ulink
      url="http://libharu.org/"> libharu library</ulink>.  At present only
      the Hershey fonts are used (i.e., there is no support for pdf or ttf
      fonts), compression of the pdf output is not enabled, and the paper
      size can't be chosen.
    </para>
  </sect1>

  <sect1 id="gd-driver">
    <title>The gd driver</title>

    <para>
      N.B. This driver is disabled by default because it is not
      maintained and because it depends on the deprecated plfreetype
      approach (see <xref linkend="FreeType-notes"/>) for rendering unicode
      text (which implies font-selection issues and no support for complex
      text layout).
    </para>

    <para>
      The gd driver uses the <ulink url="http://libgd.github.io/">GD
      library</ulink> to produce plots in the PNG, JPEG, and GIF file formats.
      Text is anti-aliased, but lines and fills are not.
    </para>

    <para>
      The available driver options are:
      <itemizedlist>
	<listitem><para>
	  optimize: Optimize PNG palette when possible
	</para></listitem>
	<listitem><para>
	  def_black15: Define idx 15 as black. If the background is
	  "whiteish" (from "-bg" option), force index 15 (traditionally
	  white) to be "black"
	</para></listitem>
	<listitem><para>
	  swp_red15: Swap index 1 (usually red) and 1 (usually white);
	  always done after "black15"; quite useful for quick changes to
	  web pages
	</para></listitem>
	<listitem><para>8bit: Palette (8 bit) mode</para></listitem>
	<listitem><para>24bit: Truecolor (24 bit) mode</para></listitem>
	<listitem><para>text: Use driver text (FreeType)</para></listitem>
	<listitem><para>
	  smooth: Turn text smoothing on (1) or off (0)
	</para></listitem>
      </itemizedlist>
    </para>
  </sect1>
  <sect1 id="latex-postscript-driver">
    <title>The pstex driver</title>

    <para>
      N.B. This driver is disabled by default because it is not maintained.
      This is a PostScript device driver that writes out its results in two
      files.  (1) The encapsulated postscript (EPS) file contains all the
      postscript commands for rendering the plot without characters, and (2)
      the LaTeX file contains a fragment of LaTeX that reads in the EPS file
      and renders the plot characters using LaTeX commands (and LaTeX
      fonts!) in alignment with the EPS file to produce a combined result.
    </para>

    <para>

      Suppose you create the EPS and LaTeX files with the following command:
      <userinput>./x01c -dev pstex -o x01c.eps</userinput>.  The EPS file
      is then stored in <filename>x01c.eps</filename> and the LaTeX fragment
      is stored in <filename>x01c.eps_t</filename>.  Then
      you may use the generated files with the <filename>x01c.tex</filename>
      LaTeX code that follows:
    </para>

    <para>
      <programlisting>\documentclass{article}
      \usepackage[dvips]{graphicx}
      \begin{document}
      \input{x01c.eps_t}
      \end{document}
      </programlisting>
    </para>

    <para>
      and generate PostScript results using the LaTeX fonts with the following
      command: <userinput>latex x01c.tex; dvips -f &lt;x01c.dvi &gt;x01c.ps
      </userinput>.  The results look good (aside from an obvious bounding-box
      problem that still needs to be fixed with this device) and should be
      useful for LaTeX enthusiasts.
    </para>

    <para>
      There are no available driver options.
    </para>

  </sect1>

</chapter>

<chapter id="interactive-drivers">
  <title>Drivers which implement interactive devices</title>

  <para>
    Drivers that provide interactive devices are described in this chapter.
    Each of the drivers has a list of options, and these may be set as
    outlined in <xref linkend="arguments" />.
  </para>


  <sect1 id="interactive-qt-driver">
    <title>The qt driver</title>

    <para>
      The qt driver uses the <ulink url="https://www.qt.io/">the Qt
      library</ulink> (either Qt4 or Qt5) to implement the qtwidget
      interactive device. Text and graphics are antialised, font selection
      is done automatically for any given unicode glyph requested using the
      recommended fontconfig approach, and complex text layout is used to
      render text.  As a result the qtwidget device is considered to be one
      of our three best (the other two are described in <xref
      linkend="interactive-cairo-driver"/>) interactive devices in terms of
      graphical and text rendering quality.  However, this device's raw
      interactive capabilities are still immature compared to those
      described in <xref linkend="xwin-driver"/>.  For example, the
      interactive parts of standard example 20 do not yet work correctly
      with the qtwidget device.  Furthermore, the GUI capability of this
      device needs enhancing, e.g., to reorient or zoom plots or to
      provide a cmap0 and cmap1 palette editor.
    </para>
  </sect1>

  <sect1 id="interactive-cairo-driver">
    <title>The cairo driver</title>

    <para>
      The cairo driver uses the Pango/Cairo subset of the <ulink
      url="https://www.gtk.org/">GTK+ suite of libraries </ulink> to
      implement the xcairo interactive device on platforms with X and the
      wincairo interactive device on Windows platforms.  Text and graphics
      are antialised, font selection is done automatically for any given
      unicode glyph requested using the recommended fontconfig approach, and
      complex text layout is used to render text.  As a result these devices
      are two of our three best (the other one is described in <xref
      linkend="interactive-qt-driver"/>) interactive devices in terms of
      graphical and text rendering quality.  However, the xcairo and
      wincairo raw interactive capabilities are still immature compared to
      those described in <xref linkend="xwin-driver"/>.  For example, the
      interactive parts of standard example 20 do not yet work correctly
      with these devices.  Furthermore, the GUI capability of these
      devices needs enhancing, e.g., to reorient or zoom plots or to
      provide a cmap0 and cmap1 palette editor.
    </para>
  </sect1>

  <sect1 id="xwin-driver">
    <title>The xwin driver</title>

    <para>
      The xwin driver directly uses the X library to implement the
      xwin device.  The graphical quality of this device is poor (e.g.,
      there is no antialiasing of graphics or text, it uses Hershey fonts
      rather than unicode-aware system fonts, and it has no complex text
      layout capabilities).  Nevertheless its raw interactive capabilities
      are the best of all our devices.  For example, the interactive parts
      of standard example 20 work correctly with this device.
    </para>

    <para>
      Plots are displayed one page at a time.  The pager is advanced by
      pressing the Enter key, and may only be advanced in the forward
      direction.
    </para>

    <para>
      The available driver options are:
      <itemizedlist>
	<listitem><para>
	  sync: Synchronized X server operation (0|1)
	</para></listitem>
	<listitem><para>
	  nobuffered: Sets unbuffered operation (0|1)
	</para></listitem>
	<listitem><para>
	  noinitcolors: Sets cmap0 allocation (0|1)
	</para></listitem>
	<listitem><para>
	  defvis: Use the Default Visual (0|1)
	</para></listitem>
	<listitem><para>
	  usepth: Use pthreads (0|1)
	</para></listitem>
      </itemizedlist>
    </para>
  </sect1>

  <sect1 id="tk-driver">
    <title>The tk driver</title>

    <para>
      The tk driver combines the xwin driver (see <xref
      linkend="xwin-driver"/>) with Tcl/Tk to implement the tk device.  So
      it shares the weaknesses (ugly graphics and text) of the xwin device
      as well as its strength (excellent raw interactive capability).  Also
      unlike our other interactive devices the tk device provides GUI
      capabilities such as orient and zoom and a cmap0 and cmap1 palette
      editor.
    </para>

  </sect1>

  <sect1 id="aqt-driver">
    <title>The aqt driver</title>

    <para>
      The AquaTerm driver is a driver that is specific to Mac OS X and
      the AquaTerm Graphics Terminal. It is unicode enabled. Text, lines
      and shades are anti-aliased.
    </para>

    <para>
      There are no options...
    </para>
  </sect1>

  <sect1 id="wxWidgets-driver">
    <title>The wxwidgets driver</title>

    <para>
      The basic wxWidgets driver's features and user interface are described
      in the section called 'Driver Basics'. The file
      drivers/README.wxwidgets describes how you can use the PLplot library
      within your wxWidgets application.
    </para>

    <sect2 id="wxWidgets-driver-basics">
      <title>wxWidgets Driver Basics</title>

      <para>
	The wxWidgets driver plots in a Frame provided by the wxWidgets
	library. The driver is quite complete but lacks many of the GUI
	features of the TK driver. All plots are available at once
	an one can switch between all plots by pressing Alt-n. The
	application can be quit with Alt-x. These functions are also
	available in the menu. After the last plot one will advance again
	to the first plot. Anti-aliasing is supported and and the wxWidgets
	driver is unicode enabled. It is also possible to address the
	wxWidgets driver from within a wxWidgets application - this is
	described in the next section.
      </para>

      <para>
	The available driver options (used with the
	<parameter>-drvopt</parameter> command-line argument) are:
	<itemizedlist>
	  <listitem><para>
	    text: Use TrueType fonts (0|1); default 1
	  </para></listitem>
	  <listitem><para>
	    smooth: switch on/off anti-aliasing (0|1); default 1
	  </para></listitem>
	</itemizedlist>
      </para>

      <para>
	The text option toggles between TrueType and Hershey fonts. The
	Hershey fonts provide a reference implementation for text
	representation in PLplot.
      </para>

      <para>
	The smooth option will turn on or off text smoothing for True
	Type fonts. This will increase the time for a plot considerably.
      </para>
    </sect2>
  </sect1>
</chapter>
