This is plplotdoc.info, produced by makeinfo version 5.2 from
plplotdoc.texi.

INFO-DIR-SECTION Scientific Visualization
START-INFO-DIR-ENTRY
* Documentation of the PLplot plotting software: (plplotdoc).
                                                  This reference contains
                                                  complete user documentation
                                                  for the PLplot plotting
                                                  software
END-INFO-DIR-ENTRY


File: plplotdoc.info,  Node: Top,  Next: Introduction,  Up: (dir)

Documentation of the PLplot plotting software
*********************************************

* Menu:

* Introduction : Introduction.
* Introduction: Introduction <1>.
* Programming : Programming.
* Simple Use of PLplot::
* Advanced Use of PLplot::
* Deploying programs that use PLplot::
* Drivers which implement file devices::
* Drivers which implement interactive devices::
* Supported computer languages : Supported computer languages.
* C Language::
* Ada Language::
* A C++ Interface for PLplot::
* Fortran Language::
* OCaml Language::
* Using PLplot from Perl::
* Using PLplot from Python::
* Using PLplot from Tcl::
* Building an Extended WISH::
* Embedding Plots in Graphical User Interfaces::
* Reference : Reference.
* Bibliography::
* The Common API for PLplot::
* The Specialized C/C++ API for PLplot::
* The Specialized Fortran API for PLplot::
* API compatibility definition::
* Obsolete/Deprecated API for PLplot::
* Internal C functions in PLplot::
* The PLplot Libraries::

— The Detailed Node Listing —

Introduction

* The PLplot plotting software::
* Feature Summary::
* Obtaining Access to PLplot::
* Configure, build, and install PLplot from source: Configure; build; and install PLplot from source.
* PLplot Copyright Licensing::
* Credits::

Simple Use of PLplot

* Plotting a Simple Graph::
* Initializing PLplot::
* Defining Plot Scales and Axes::
* Labelling the Graph::
* Drawing the Graph::
* Finishing Up::
* In Case of Error::

Advanced Use of PLplot

* Command Line Arguments::
* Devices::
* Adding FreeType Library Support to Bitmap Drivers::
* View Surfaces, (Sub-)Pages, Viewports and Windows: View Surfaces; [Sub-]Pages; Viewports and Windows.
* Setting Line Attributes::
* Setting the Area Fill Pattern::
* Setting Color::
* Setting Character Attributes::
* Three-dimensional Plots::
* Legends and color bars::

Drivers which implement file devices

* The qt driver::
* The cairo driver::
* The svg driver::
* The ps driver::
* The psttf driver::
* The pdf driver::
* The gd driver::
* The pstex driver::

Drivers which implement interactive devices

* The qt driver: The qt driver <1>.
* The cairo driver: The cairo driver <1>.
* The xwin driver::
* The tk driver::
* The aqt driver::
* The wxwidgets driver::

Ada Language

* Overview::
* The Bindings::
* The Examples::
* Obtaining the Software::
* How to use the Ada bindings::
* Unique Features of the Ada bindings::
* Parts That Retain a C Flavor::
* Known Variances::
* Compilation notes::
* Notes for Apple Macintosh OS X users::

A C++ Interface for PLplot

* Motivation for the C++ Interface::
* Design of the PLplot C++ Interface::
* Specializing the PLplot C++ Interface::
* Status of the C++ Interface::

OCaml Language

* Overview: Overview <1>.
* The Bindings: The Bindings <1>.
* The Examples: The Examples <1>.
* Obtaining the Software: Obtaining the Software <1>.
* How to use the OCaml bindings::
* Known Issues::

Using PLplot from Tcl

* Motivation for the Tcl Interface to PLplot::
* Overview of the Tcl Language Binding::
* The PLplot Tcl Matrix Extension::
* Contouring and Shading from Tcl::
* Understanding the Performance Characteristics of Tcl::

Building an Extended WISH

* Introduction to Tcl::
* Introduction to Tk::
* Introduction to [incr Tcl]::
* PLplot Extensions to Tcl::
* Custom Extensions to Tcl::

Bibliography

* References::

The Common API for PLplot

* pl_setcontlabelformat; Set format of numerical label for contours::
* pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label::
* pladv; Advance the (sub-)page: pladv; Advance the [sub-]page.
* plarc; Draw a circular or elliptical arc : plarc; Draw a circular or elliptical arc.
* plaxes; Draw a box with axes, etc. with arbitrary origin : plaxes; Draw a box with axes; etc_ with arbitrary origin.
* plbin; Plot a histogram from binned data : plbin; Plot a histogram from binned data.
* plbop; Begin a new page::
* plbox; Draw a box with axes, etc: plbox; Draw a box with axes; etc.
* plbox3; Draw a box with axes, etc, in 3-d : plbox3; Draw a box with axes; etc; in 3-d.
* plbtime; Calculate broken-down time from continuous time for the current stream : plbtime; Calculate broken-down time from continuous time for the current stream.
* plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates : plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates.
* plclear; Clear current (sub)page : plclear; Clear current [sub]page.
* plcol0; Set color, cmap0 : plcol0; Set color; cmap0.
* plcol1; Set color, cmap1 : plcol1; Set color; cmap1.
* plcolorbar; Plot color bar for image, shade or gradient plots : plcolorbar; Plot color bar for image; shade or gradient plots.
* plconfigtime; Configure the transformation between continuous and broken-down time for the current stream : plconfigtime; Configure the transformation between continuous and broken-down time for the current stream.
* plcont; Contour plot : plcont; Contour plot.
* plcpstrm; Copy state parameters from the reference stream to the current stream : plcpstrm; Copy state parameters from the reference stream to the current stream.
* plctime; Calculate continuous time from broken-down time for the current stream : plctime; Calculate continuous time from broken-down time for the current stream.
* plend; End plotting session : plend; End plotting session.
* plend1; End plotting session for current stream : plend1; End plotting session for current stream.
* plenv0; Same as plenv but if in multiplot mode does not advance the subpage, instead clears it : plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it.
* plenv; Set up standard window and draw box : plenv; Set up standard window and draw box.
* pleop; Eject current page : pleop; Eject current page.
* plerrx; Draw error bars in x direction : plerrx; Draw error bars in x direction.
* plerry; Draw error bars in the y direction : plerry; Draw error bars in the y direction.
* plfamadv; Advance to the next family file on the next new page : plfamadv; Advance to the next family file on the next new page.
* plfill; Draw filled polygon : plfill; Draw filled polygon.
* plfill3; Draw filled polygon in 3D : plfill3; Draw filled polygon in 3D.
* plflush; Flushes the output stream : plflush; Flushes the output stream.
* plfont; Set font : plfont; Set font.
* plfontld; Load Hershey fonts : plfontld; Load Hershey fonts.
* plGetCursor; Wait for graphics input event and translate to world coordinates. : plGetCursor; Wait for graphics input event and translate to world coordinates_.
* plgchr; Get character default height and current (scaled) height : plgchr; Get character default height and current [scaled] height.
* plgcmap1_range; Get the cmap1 argument range for continuous color plots : plgcmap1_range; Get the cmap1 argument range for continuous color plots.
* plgcol0; Returns 8-bit RGB values for given color index from cmap0 : plgcol0; Returns 8-bit RGB values for given color index from cmap0.
* plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0 : plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0.
* plgcolbg; Returns the background color (cmap0[0]) by 8-bit RGB value : plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value.
* plgcolbga; Returns the background color (cmap0[0]) by 8-bit RGB value and PLFLT alpha transparency value : plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value.
* plgcompression; Get the current device-compression setting : plgcompression; Get the current device-compression setting.
* plgdev; Get the current device (keyword) name : plgdev; Get the current device [keyword] name.
* plgdidev; Get parameters that define current device-space window : plgdidev; Get parameters that define current device-space window.
* plgdiori; Get plot orientation : plgdiori; Get plot orientation.
* plgdiplt; Get parameters that define current plot-space window : plgdiplt; Get parameters that define current plot-space window.
* plgdrawmode; Get drawing mode (depends on device support!) : plgdrawmode; Get drawing mode [depends on device support!].
* plgfam; Get family file parameters : plgfam; Get family file parameters.
* plgfci; Get FCI (font characterization integer) : plgfci; Get FCI [font characterization integer].
* plgfnam; Get output file name : plgfnam; Get output file name.
* plgfont; Get family, style and weight of the current font : plgfont; Get family; style and weight of the current font.
* plglevel; Get the (current) run level : plglevel; Get the [current] run level.
* plgpage; Get page parameters : plgpage; Get page parameters.
* plgra; Switch to graphics screen : plgra; Switch to graphics screen.
* plgradient; Draw linear gradient inside polygon : plgradient; Draw linear gradient inside polygon.
* plgriddata; Grid data from irregularly sampled data : plgriddata; Grid data from irregularly sampled data.
* plgspa; Get current subpage parameters : plgspa; Get current subpage parameters.
* plgstrm; Get current stream number : plgstrm; Get current stream number.
* plgver; Get the current library version number : plgver; Get the current library version number.
* plgvpd; Get viewport limits in normalized device coordinates : plgvpd; Get viewport limits in normalized device coordinates.
* plgvpw; Get viewport limits in world coordinates : plgvpw; Get viewport limits in world coordinates.
* plgxax; Get x axis parameters : plgxax; Get x axis parameters.
* plgyax; Get y axis parameters : plgyax; Get y axis parameters.
* plgzax; Get z axis parameters : plgzax; Get z axis parameters.
* plhist; Plot a histogram from unbinned data : plhist; Plot a histogram from unbinned data.
* plhlsrgb; Convert HLS color to RGB : plhlsrgb; Convert HLS color to RGB.
* plimagefr; Plot a 2D matrix using cmap1 : plimagefr; Plot a 2D matrix using cmap1.
* plimage; Plot a 2D matrix using cmap1 with automatic color adjustment : plimage; Plot a 2D matrix using cmap1 with automatic color adjustment.
* plinit; Initialize PLplot : plinit; Initialize PLplot.
* pljoin; Draw a line between two points : pljoin; Draw a line between two points.
* pllab; Simple routine to write labels : pllab; Simple routine to write labels.
* pllegend; Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols : pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols.
* pllightsource; Sets the 3D position of the light source : pllightsource; Sets the 3D position of the light source.
* plline; Draw a line : plline; Draw a line.
* plline3; Draw a line in 3 space : plline3; Draw a line in 3 space.
* pllsty; Select line style : pllsty; Select line style.
* plmap; Plot continental outline or shapefile data in world coordinates : plmap; Plot continental outline or shapefile data in world coordinates.
* plmapfill; Plot all or a subset of Shapefile data, filling the polygons : plmapfill; Plot all or a subset of Shapefile data; filling the polygons.
* plmapline; Plot all or a subset of Shapefile data using lines in world coordinates : plmapline; Plot all or a subset of Shapefile data using lines in world coordinates.
* plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates : plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates.
* plmaptex; Draw text at points defined by Shapefile data in world coordinates : plmaptex; Draw text at points defined by Shapefile data in world coordinates.
* plmeridians; Plot latitude and longitude lines : plmeridians; Plot latitude and longitude lines.
* plmesh; Plot surface mesh : plmesh; Plot surface mesh.
* plmeshc; Magnitude colored plot surface mesh with contour : plmeshc; Magnitude colored plot surface mesh with contour.
* plmkstrm; Creates a new stream and makes it the default : plmkstrm; Creates a new stream and makes it the default.
* plmtex; Write text relative to viewport boundaries : plmtex; Write text relative to viewport boundaries.
* plmtex3; Write text relative to viewport boundaries in 3D plots : plmtex3; Write text relative to viewport boundaries in 3D plots.
* plot3d; Plot 3-d surface plot : plot3d; Plot 3-d surface plot.
* plot3dc; Magnitude colored plot surface with contour : plot3dc; Magnitude colored plot surface with contour.
* plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits : plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits.
* plparseopts; Parse command-line arguments : plparseopts; Parse command-line arguments.
* plpat; Set area line fill pattern : plpat; Set area line fill pattern.
* plpath; Draw a line between two points, accounting for coordinate transforms : plpath; Draw a line between two points; accounting for coordinate transforms.
* plpoin; Plot a glyph at the specified points : plpoin; Plot a glyph at the specified points.
* plpoin3; Plot a glyph at the specified 3D points : plpoin3; Plot a glyph at the specified 3D points.
* plpoly3; Draw a polygon in 3 space : plpoly3; Draw a polygon in 3 space.
* plprec; Set precision in numeric labels : plprec; Set precision in numeric labels.
* plpsty; Select area fill pattern : plpsty; Select area fill pattern.
* plptex; Write text inside the viewport : plptex; Write text inside the viewport.
* plptex3; Write text inside the viewport of a 3D plot : plptex3; Write text inside the viewport of a 3D plot.
* plrandd; Random number generator returning a real random number in the range [0,1] : plrandd; Random number generator returning a real random number in the range [0;1].
* plreplot; Replays contents of plot buffer to current device/file : plreplot; Replays contents of plot buffer to current device/file.
* plrgbhls; Convert RGB color to HLS : plrgbhls; Convert RGB color to HLS.
* plschr; Set character size : plschr; Set character size.
* plscmap0; Set cmap0 colors by 8-bit RGB values : plscmap0; Set cmap0 colors by 8-bit RGB values.
* plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value : plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value.
* plscmap0n; Set number of colors in cmap0 : plscmap0n; Set number of colors in cmap0.
* plscmap1_range; Set the cmap1 argument range for continuous color plots : plscmap1_range; Set the cmap1 argument range for continuous color plots.
* plscmap1; Set opaque RGB cmap1 colors values : plscmap1; Set opaque RGB cmap1 colors values.
* plscmap1a; Set semitransparent cmap1 RGBA colors. : plscmap1a; Set semitransparent cmap1 RGBA colors_.
* plscmap1l; Set cmap1 colors using a piece-wise linear relationship : plscmap1l; Set cmap1 colors using a piece-wise linear relationship.
* plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship : plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship.
* plscmap1n; Set number of colors in cmap1 : plscmap1n; Set number of colors in cmap1.
* plscol0; Set 8-bit RGB values for given cmap0 color index : plscol0; Set 8-bit RGB values for given cmap0 color index.
* plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index : plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index.
* plscolbg; Set the background color by 8-bit RGB value : plscolbg; Set the background color by 8-bit RGB value.
* plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value. : plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_.
* plscolor; Used to globally turn color output on/off : plscolor; Used to globally turn color output on/off.
* plscompression; Set device-compression level : plscompression; Set device-compression level.
* plsdev; Set the device (keyword) name : plsdev; Set the device [keyword] name.
* plsdidev; Set parameters that define current device-space window : plsdidev; Set parameters that define current device-space window.
* plsdimap; Set up transformation from metafile coordinates : plsdimap; Set up transformation from metafile coordinates.
* plsdiori; Set plot orientation : plsdiori; Set plot orientation.
* plsdiplt; Set parameters that define current plot-space window : plsdiplt; Set parameters that define current plot-space window.
* plsdiplz; Set parameters incrementally (zoom mode) that define current plot-space window : plsdiplz; Set parameters incrementally [zoom mode] that define current plot-space window.
* plsdrawmode; Set drawing mode (depends on device support!) : plsdrawmode; Set drawing mode [depends on device support!].
* plseed; Set seed for internal random number generator. : plseed; Set seed for internal random number generator_.
* plsesc; Set the escape character for text strings : plsesc; Set the escape character for text strings.
* plsetopt; Set any command-line option : plsetopt; Set any command-line option.
* plsfam; Set family file parameters : plsfam; Set family file parameters.
* plsfci; Set FCI (font characterization integer) : plsfci; Set FCI [font characterization integer].
* plsfnam; Set output file name : plsfnam; Set output file name.
* plsfont; Set family, style and weight of the current font : plsfont; Set family; style and weight of the current font.
* plshades; Shade regions on the basis of value : plshades; Shade regions on the basis of value.
* plshade; Shade individual region on the basis of value : plshade; Shade individual region on the basis of value.
* plslabelfunc; Assign a function to use for generating custom axis labels : plslabelfunc; Assign a function to use for generating custom axis labels.
* plsmaj; Set length of major ticks : plsmaj; Set length of major ticks.
* plsmem; Set the memory area to be plotted (RGB) : plsmem; Set the memory area to be plotted [RGB].
* plsmema; Set the memory area to be plotted (RGBA) : plsmema; Set the memory area to be plotted [RGBA].
* plsmin; Set length of minor ticks : plsmin; Set length of minor ticks.
* plsori; Set orientation : plsori; Set orientation.
* plspage; Set page parameters : plspage; Set page parameters.
* plspal0; Set the cmap0 palette using the specified cmap0*.pal format file : plspal0; Set the cmap0 palette using the specified cmap0*_pal format file.
* plspal1; Set the cmap1 palette using the specified cmap1*.pal format file : plspal1; Set the cmap1 palette using the specified cmap1*_pal format file.
* plspause; Set the pause (on end-of-page) status : plspause; Set the pause [on end-of-page] status.
* plsstrm; Set current output stream : plsstrm; Set current output stream.
* plssub; Set the number of subpages in x and y : plssub; Set the number of subpages in x and y.
* plssym; Set symbol size : plssym; Set symbol size.
* plstar; Initialization : plstar; Initialization.
* plstart; Initialization : plstart; Initialization.
* plstransform; Set a global coordinate transform function : plstransform; Set a global coordinate transform function.
* plstring; Plot a glyph at the specified points : plstring; Plot a glyph at the specified points.
* plstring3; Plot a glyph at the specified 3D points : plstring3; Plot a glyph at the specified 3D points.
* plstripa; Add a point to a strip chart : plstripa; Add a point to a strip chart.
* plstripc; Create a 4-pen strip chart : plstripc; Create a 4-pen strip chart.
* plstripd; Deletes and releases memory used by a strip chart : plstripd; Deletes and releases memory used by a strip chart.
* plstyl; Set line style : plstyl; Set line style.
* plsurf3d; Plot shaded 3-d surface plot : plsurf3d; Plot shaded 3-d surface plot.
* plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits : plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits.
* plsvect; Set arrow style for vector plots : plsvect; Set arrow style for vector plots.
* plsvpa; Specify viewport in absolute coordinates : plsvpa; Specify viewport in absolute coordinates.
* plsxax; Set x axis parameters : plsxax; Set x axis parameters.
* plsyax; Set y axis parameters : plsyax; Set y axis parameters.
* plsym; Plot a glyph at the specified points : plsym; Plot a glyph at the specified points.
* plszax; Set z axis parameters : plszax; Set z axis parameters.
* pltext; Switch to text screen : pltext; Switch to text screen.
* pltimefmt; Set format for date / time labels : pltimefmt; Set format for date / time labels.
* plvasp; Specify viewport using aspect ratio only : plvasp; Specify viewport using aspect ratio only.
* plvect; Vector plot : plvect; Vector plot.
* plvpas; Specify viewport using coordinates and aspect ratio : plvpas; Specify viewport using coordinates and aspect ratio.
* plvpor; Specify viewport using normalized subpage coordinates : plvpor; Specify viewport using normalized subpage coordinates.
* plvsta; Select standard viewport : plvsta; Select standard viewport.
* plw3d; Configure the transformations required for projecting a 3D surface on a 2D window : plw3d; Configure the transformations required for projecting a 3D surface on a 2D window.
* plwidth; Set pen width : plwidth; Set pen width.
* plwind; Specify window : plwind; Specify window.
* plxormod; Enter or leave xor mode : plxormod; Enter or leave xor mode.

The Specialized C/C++ API for PLplot

* plabort; Error abort : plabort; Error abort.
* plAlloc2dGrid; Allocate a block of memory for use as a matrix of type PLFLT_MATRIX. : plAlloc2dGrid; Allocate a block of memory for use as a matrix of type PLFLT_MATRIX_.
* plClearOpts; Clear internal option table info structure. : plClearOpts; Clear internal option table info structure_.
* plexit; Error exit : plexit; Error exit.
* plFree2dGrid; Free the memory associated with a PLFLT matrix allocated using plAlloc2dGrid. : plFree2dGrid; Free the memory associated with a PLFLT matrix allocated using plAlloc2dGrid_.
* plfsurf3d; Plot shaded 3-d surface plot : plfsurf3d; Plot shaded 3-d surface plot.
* plgfile; Get output file handle : plgfile; Get output file handle.
* plMergeOpts; Merge use option table into internal info structure. : plMergeOpts; Merge use option table into internal info structure_.
* plMinMax2dGrid; Find the minimum and maximum of a PLFLT matrix of type PLFLT_MATRIX allocated using plAlloc2dGrid. : plMinMax2dGrid; Find the minimum and maximum of a PLFLT matrix of type PLFLT_MATRIX allocated using plAlloc2dGrid_.
* plOptUsage; Print usage and syntax message. : plOptUsage; Print usage and syntax message_.
* plResetOpts; Reset internal option table info structure. : plResetOpts; Reset internal option table info structure_.
* plsabort; Set abort handler : plsabort; Set abort handler.
* plSetUsage; Set the ascii character strings used in usage and syntax messages. : plSetUsage; Set the ascii character strings used in usage and syntax messages_.
* plsexit; Set exit handler : plsexit; Set exit handler.
* plsfile; Set output file handle : plsfile; Set output file handle.
* plshade1; Shade individual region on the basis of value : plshade1; Shade individual region on the basis of value.
* pltr0; Identity transformation for matrix index to world coordinate mapping : pltr0; Identity transformation for matrix index to world coordinate mapping.
* pltr1; Linear interpolation for matrix index to world coordinate mapping using singly dimensioned coordinate arrays : pltr1; Linear interpolation for matrix index to world coordinate mapping using singly dimensioned coordinate arrays.
* pltr2; Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays (row-major order as per normal C 2d arrays) : pltr2; Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays [row-major order as per normal C 2d arrays].
* plTranslateCursor; Convert device to world coordinates : plTranslateCursor; Convert device to world coordinates.
* PLGraphicsIn; PLplot Graphics Input structure::
* PLOptionTable; PLplot command line options table structure::

The Specialized Fortran API for PLplot

* plcont; Contour plot for Fortran : plcont; Contour plot for Fortran.
* plshade; Shaded plot for Fortran : plshade; Shaded plot for Fortran.
* plshades; Continuously shaded plot for Fortran : plshades; Continuously shaded plot for Fortran.
* plvect; Vector plot for Fortran : plvect; Vector plot for Fortran.
* plmesh; Plot surface mesh for Fortran : plmesh; Plot surface mesh for Fortran.
* plot3d; Plot 3-d surface plot for Fortran : plot3d; Plot 3-d surface plot for Fortran.
* plparseopts; parse arguments for Fortran : plparseopts; parse arguments for Fortran.
* plsesc; Set the escape character for text strings for Fortran : plsesc; Set the escape character for text strings for Fortran.

API compatibility definition

* What is in the API? : What is in the API?.
* Regression test for backwards compatibility : Regression test for backwards compatibility.

Obsolete/Deprecated API for PLplot

* plclr; Eject current page : plclr; Eject current page.
* plcol; Set color : plcol; Set color.
* plhls; Set current color by HLS : plhls; Set current color by HLS.
* plHLS_RGB; Convert HLS color to RGB : plHLS_RGB; Convert HLS color to RGB.
* plpage; Begin a new page : plpage; Begin a new page.
* plrgb; Set line color by red, green : plrgb; Set line color by red; green.
* plrgb1; Set line color by 8-bit RGB values : plrgb1; Set line color by 8-bit RGB values.
* plwid; Set pen width : plwid; Set pen width.

Internal C functions in PLplot

* plP_checkdriverinit; Checks to see if any of the specified drivers have been initialized : plP_checkdriverinit; Checks to see if any of the specified drivers have been initialized.
* plP_getinitdriverlist; Get the initialized-driver list : plP_getinitdriverlist; Get the initialized-driver list.

The PLplot Libraries

* Bindings Libraries::
* The PLplot Core Library::
* Enhancement Libraries::
* Device-driver Libraries::



File: plplotdoc.info,  Node: Introduction,  Next: Programming,  Prev: Top,  Up: Top

Introduction
************

* Menu:

* Introduction: Introduction <1>.


File: plplotdoc.info,  Node: Introduction <1>,  Up: Introduction

1 Introduction
**************

* Menu:

* The PLplot plotting software::
* Feature Summary::
* Obtaining Access to PLplot::
* Configure, build, and install PLplot from source: Configure; build; and install PLplot from source.
* PLplot Copyright Licensing::
* Credits::


File: plplotdoc.info,  Node: The PLplot plotting software,  Next: Feature Summary,  Up: Introduction <1>

1.1 The PLplot plotting software
================================

PLplot is a cross-platform (*note Cross Platform::) software package for
creating scientific plots whose (UTF-8 (http://www.utf-8.com/)) plot
symbols and text are limited in practice only by what Unicode
(http://www.utf-8.com/)-aware system fonts are installed on a user’s
computer.  The PLplot software, which is primarily licensed under the
LGPL (http://www.gnu.org/licenses/lgpl.html), has a clean architecture
that is organized as a core C library, separate language bindings (*note
Language Bindings::) for that library, and separate device drivers that
are dynamically loaded by the core library which control how the plots
are presented in noninteractive (*note Output File Formats::) and
interactive (*note Interactive Platforms::) plotting contexts.

   The PLplot core library can be used to create standard x-y plots,
semi-log plots, log-log plots, contour plots, 3D surface plots, mesh
plots, bar charts and pie charts.  Multiple graphs (of the same or
different sizes) may be placed on a single page, and multiple pages are
allowed for those device formats that support them.

   PLplot has core library support for plot symbols and text specified
by the user in the UTF-8 encoding of Unicode.  This means for our many
Unicode-aware devices that plot symbols and text are only limited by the
collection of glyphs normally available via installed system fonts.
Furthermore, a large subset of our Unicode-aware devices also support
complex text layout (CTL) languages such as Arabic, Hebrew, and Indic
and Indic-derived CTL scripts such as Devanagari, Thai, Lao, and
Tibetan.  Thus, for these PLplot devices essentially any language that
is supported by Unicode and installed system fonts can be used to label
plots.

   PLplot was originally developed by Sze Tan of the University of
Auckland in Fortran-77.  Many of the underlying concepts used in the
PLplot package are based on ideas used in Tim Pearson’s PGPLOT package.
Sze Tan writes:

     I’m rather amazed how far PLPLOT has travelled given its origins
     etc.  I first used PGPLOT on the Starlink VAX computers while I was
     a graduate student at the Mullard Radio Astronomy Observatory in
     Cambridge from 1983-1987.  At the beginning of 1986, I was to give
     a seminar within the department at which I wanted to have a
     computer graphics demonstration on an IBM PC which was connected to
     a completely non-standard graphics card.  Having about a week to do
     this and not having any drivers for the card, I started from the
     back end and designed PLPLOT to be such that one only needed to be
     able to draw a line or a dot on the screen in order to do arbitrary
     graphics.  The application programmer’s interface was made as
     similar as possible to PGPLOT so that I could easily port my
     programs from the VAX to the PC. The kernel of PLPLOT was modelled
     on PGPLOT but the code is not derived from it.

   The C version of PLplot was originally developed by Tony Richardson
on a Commodore Amiga.  That version has been improved and expanded ever
since first by Geoffrey Furnish and Maurice Lebrun in the 1990’s and
later (after the project was registered at SourceForge on 2000-02-23)
with a much-expanded development team.
(http://plplot.sourceforge.net/credits.php)

   We welcome suggestions on how to improve this code, especially in the
form of user-contributed enhancements or bug fixes.  If PLplot is used
in any published papers, please include an acknowledgement or citation
of our work, which will help us to continue improving PLplot.  Please
direct all communication to the plplot-general mailing list.
(https://lists.sourceforge.net/lists/listinfo/plplot-general)


File: plplotdoc.info,  Node: Feature Summary,  Next: Obtaining Access to PLplot,  Prev: The PLplot plotting software,  Up: Introduction <1>

1.2 Feature Summary
===================

* Menu:

* Cross Platform::
* Language Bindings::
* Output File Formats::
* Interactive Platforms::


File: plplotdoc.info,  Node: Cross Platform,  Next: Language Bindings,  Up: Feature Summary

1.2.1 Cross Platform
--------------------

PLplot is currently known to work on the following platforms:

   • Linux, Mac OS X, and other Unices

   • MSVC IDE on the Microsoft version of Windows (Windows 2000 and
     later)

   • Cygwin on the Microsoft version of Windows

   • MinGW-w64/MSYS2 on the Microsoft version of Windows

   For each of the above platforms, PLplot can be configured, built, and
installed (*note Configure; build; and install PLplot from source::)
from source (http://plplot.sourceforge.net/downloads.php), and for the
Linux and Mac OS X platforms third-party binary packages for PLplot are
available (http://plplot.sourceforge.net/downloads.php#Binary_Packages).


File: plplotdoc.info,  Node: Language Bindings,  Next: Output File Formats,  Prev: Cross Platform,  Up: Feature Summary

1.2.2 Language Bindings
-----------------------

The language bindings of the C PLplot library are currently the
following:

   • Ada

   • C++

   • D

   • Fortran

   • Java

   • Lisp (http://common-lisp.net/project/cl-plplot/)

   • Lua

   • OCaml

   • Octave

   • Perl/PDL (http://search.cpan.org/~dhunt/PDL-Graphics-PLplot)

   • Python

   • Tcl/Tk


File: plplotdoc.info,  Node: Output File Formats,  Next: Interactive Platforms,  Prev: Language Bindings,  Up: Feature Summary

1.2.3 Output File Formats
-------------------------

PLplot device drivers support the following plotting file formats:

   • CGM

   • GIF

   • JPEG

   • PBM

   • PDF

   • PNG

   • PostScript

   • SVG

   • Xfig


File: plplotdoc.info,  Node: Interactive Platforms,  Prev: Output File Formats,  Up: Feature Summary

1.2.4 Interactive Platforms
---------------------------

PLplot device drivers support the following platforms that are suitable
for interactive plotting:

   • GDI

   • GTK+

   • PyQt

   • Qt

   • Tcl/Tk

   • wxWidgets

   • X


File: plplotdoc.info,  Node: Obtaining Access to PLplot,  Next: Configure; build; and install PLplot from source,  Prev: Feature Summary,  Up: Introduction <1>

1.3 Obtaining Access to PLplot
==============================

PLplot is a SourceForge project and may be obtained by the usual
SourceForge file release and anonymous git repository access that is
made available from links at http://sourceforge.net/projects/plplot
(http://sourceforge.net/projects/plplot).


File: plplotdoc.info,  Node: Configure; build; and install PLplot from source,  Next: PLplot Copyright Licensing,  Prev: Obtaining Access to PLplot,  Up: Introduction <1>

1.4 Configure, build, and install PLplot from source
====================================================

After the source code for PLplot has been obtained
(http://plplot.sourceforge.net/downloads.php) the generic steps to
configure, build, and install PLplot are as follows:

   • Optionally set environment variables to force CMake’s find commands
     to locate any of PLplot’s software dependencies that are installed
     in non-standard locations.  See the CMake documentation for the
     ‘find_file’
     (https://cmake.org/cmake/help/latest/command/find_file.html) and
     ‘find_library’
     (https://cmake.org/cmake/help/latest/command/find_library.html)
     commands for the list of such variables which includes
     ‘CMAKE_INCLUDE_PATH’, ‘CMAKE_LIBRARY_PATH’, and ‘PATH’.  In
     addition, the ‘PKG_CONFIG_PATH’ environment variable forces CMake
     to find certain software packages which specify their
     (non-standard) install locations using ‘pkg-config’.

   • Optionally set environment variables that force CMake to use
     specific compilers to override the (normally good) default choice
     of compilers that CMake uses.  The environment variables that CMake
     recognizes for this purpose are ‘ADA’ to specify the Ada compiler,
     ‘CC’ to specify the C compiler, ‘CXX’ to specify the C++ compiler,
     ‘DC’ to specify the D compiler, and ‘FC’ to specify the Fortran
     compiler.

   • Optionally set environment variables that force CMake to use
     specific compiler flags.  The environment variables that CMake
     recognizes for this purpose are ‘ADAFLAGS’ to specify the Ada
     compiler flags, ‘CCFLAGS’ to specify the C compiler flags,
     ‘CXXFLAGS’ to specify the C++ compiler flags, ‘DFLAGS’ to specify
     the D compiler flags, and ‘FFLAGS’ to specify the Fortran compiler
     flags.

   • Prepare for running the ‘cmake’ command by removing the stale
     PLplot install tree (if it exists) that corresponds to the
     ‘-DCMAKE_INSTALL_PREFIX’ option for the ‘cmake’ command (see
     below), creating an empty build directory, and changing directories
     to that build directory (which will become the top-level directory
     of the build tree).

   • Configure the PLplot build and install by running


          	cmake <cmake options> <top-level directory of the source tree>


     on the command line.  Many ‘cmake’ options are possible.  Two
     common ones that are often sufficient for most purposes are
     ‘-DCMAKE_INSTALL_PREFIX=<installation prefix>’ (to specify the
     top-level directory of the soon-to-be created install tree) and ‘-G
     <generator identification string>’ (to identify the ‘cmake’ backend
     generator to use such as "Unix Makefiles").  However, there are
     also many other ‘cmake’ options that are specific to the PLplot
     build system that are documented in the ‘CMakeCache.txt’ file that
     is created by the ‘cmake’ command.

   • Build PLplot by building the "all" target.  For example, that would
     be done for the "Unix Makefiles" generator case by


          	make all


   • Install PLplot by building the "install" target.  For example, that
     would be done for the "Unix Makefiles" generator case by


          	make install


   • Determine the list of additional targets that are available for the
     PLplot build by building the "help" target.  For example, that
     would be done for the "Unix Makefiles" generator case by


          	make help


For additional platform-specific details beyond the above generic steps,
please consult our wiki (http://sourceforge.net/p/plplot/wiki/Home).

   After PLplot has been configured, built, and installed, you can write
code in C or any of the languages that have PLplot bindings to make the
desired PLplot calls.  Standard example programs in all supported
languages are included with the PLplot software package.  The
installation of those examples includes both a CMake-based build system
(see ‘<installation prefix>/share/plplot5.13.0/examples/CMakelists.txt’)
and a more traditional (Makefile + pkg-config) build system (see
‘<installation prefix>/share/plplot5.13.0/examples/Makefile’) for
building and linking the examples.  Either of these two build systems
can be adapted by users to build and link their own PLplot-related code
for compiled languages or to test PLplot related code that is compiled
or which is written in a scripting language where PLplot capability is
dynamically loaded.  However, note the CMake-based build system for the
installed examples should work on all platforms where PLplot can be
built while the traditional build system for the installed examples will
only work on platforms (e.g., Linux) which have ‘make’ (only with GNU
extensions), ‘pkg-config’, and ‘bash’ (required for testing targets)
installed.  Plots generated from these example programs as well as the
source code for those examples in all our supported languages are
available from links given here
(http://plplot.sourceforge.net/examples.php).


File: plplotdoc.info,  Node: PLplot Copyright Licensing,  Next: Credits,  Prev: Configure; build; and install PLplot from source,  Up: Introduction <1>

1.5 PLplot Copyright Licensing
==============================

PLplot is free software that is primarily licensed under the LGPL
(version 2 or any later version at the option of the user).  The exact
text of that license is given in the file ‘COPYING.LIB’ that is
distributed with PLplot.  The free software licenses that are used for
the parts of PLplot not distributed under the LGPL are explicitly noted
in the ‘Copyright’ file that is distributed with PLplot.


File: plplotdoc.info,  Node: Credits,  Prev: PLplot Copyright Licensing,  Up: Introduction <1>

1.6 Credits
===========

Many developers have contributed to PLplot over its long history.  For
further details see our credits page
(http://plplot.sourceforge.net/credits.php)


File: plplotdoc.info,  Node: Programming,  Next: Supported computer languages,  Prev: Introduction,  Up: Top

Programming
***********

* Menu:

* Simple Use of PLplot::
* Advanced Use of PLplot::
* Deploying programs that use PLplot::
* Drivers which implement file devices::
* Drivers which implement interactive devices::


File: plplotdoc.info,  Node: Simple Use of PLplot,  Next: Advanced Use of PLplot,  Up: Programming

2 Simple Use of PLplot
**********************

We describe simple use of PLplot in this chapter which includes many
cross-references to elements of our common (C) API (*note The Common API
for PLplot::) that use PLplot C types such as ‘PLFLT’ (*note
PLFLT-type::) and ‘PLINT’ (*note PLINT-type::).  For full documentation
of all PLplot C types see here (*note plplot-types::).  The best way to
learn how to use our common API for the language of your choice is to
look at our standard set of examples
(http://plplot.sourceforge.net/examples.php).  For additional language
documentation you should consult the various chapters in *note Supported
computer languages: Supported computer languages. as well.

* Menu:

* Plotting a Simple Graph::
* Initializing PLplot::
* Defining Plot Scales and Axes::
* Labelling the Graph::
* Drawing the Graph::
* Finishing Up::
* In Case of Error::


File: plplotdoc.info,  Node: Plotting a Simple Graph,  Next: Initializing PLplot,  Up: Simple Use of PLplot

2.1 Plotting a Simple Graph
===========================

We shall first consider plotting simple graphs showing the dependence of
one variable upon another.  Such a graph may be composed of several
elements:

   • A box which defines the ranges of the variables, perhaps with axes
     and numeric labels along its edges.

   • A set of points or lines within the box showing the functional
     dependence.

   • A set of labels for the variables and a title for the graph.

   For a good tutorial example of such a simple graph for each of our
supported languages, see our standard example 00
(http://plplot.sourceforge.net/examples.php?demo=00).

   In order to draw such a simple graph, it is necessary to call at
least four of the PLplot functions:

  1. ‘plinit’ (*note plinit; Initialize PLplot::), to initialize PLplot.

  2. ‘plenv’ (*note plenv; Set up standard window and draw box::), to
     define the range and scale of the graph, and draw labels, axes,
     etc.

  3. One or more calls to ‘plline’ (*note plline; Draw a line::) or
     ‘plstring’ (*note plstring; Plot a glyph at the specified points::)
     to draw lines or points as needed.  Other more complex routines
     include ‘plbin’ (*note plbin; Plot a histogram from binned data::)
     and ‘plhist’ (*note plhist; Plot a histogram from unbinned data::)
     to draw histograms, and ‘plerrx’ (*note plerrx; Draw error bars in
     x direction::) and ‘plerry’ (*note plerry; Draw error bars in the y
     direction::) to draw error-bars.

  4. ‘plend’ (*note plend; End plotting session::), to close the plot.

   More than one graph can be drawn on a single set of axes by making
repeated calls to the routines listed in item 3 above.  PLplot only
needs to be initialized once unless plotting to multiple output devices.


File: plplotdoc.info,  Node: Initializing PLplot,  Next: Defining Plot Scales and Axes,  Prev: Plotting a Simple Graph,  Up: Simple Use of PLplot

2.2 Initializing PLplot
=======================

Before any actual plotting calls are made, a graphics program must call
‘plinit’ (*note plinit; Initialize PLplot::), is the main initialization
routine for PLplot.  It sets up all internal data structures necessary
for plotting and initializes the output device driver.  If the output
device has not already been specified when ‘plinit’ (*note plinit;
Initialize PLplot::) is called, a list of valid output devices is given
and the user is prompted for a choice.  Either the device number or a
device keyword is accepted.

   There are several routines affecting the initialization that must be
called _before_ ‘plinit’ (*note plinit; Initialize PLplot::), if they
are used.  The function ‘plsdev’ (*note plsdev; Set the device [keyword]
name::) allows you to set the device explicitly.  The function
‘plsetopt’ (*note plsetopt; Set any command-line option::) allows you to
set any command-line option internally in your code.  The function
‘plssub’ (*note plssub; Set the number of subpages in x and y::) may be
called to divide the output device plotting area into several subpages
of equal size, each of which can be used separately.

   One advances to the next page (or screen) via ‘pladv’ (*note pladv;
Advance the [sub-]page::).  If subpages are used, this can be used to
advance to the next subpage or to a particular subpage.


File: plplotdoc.info,  Node: Defining Plot Scales and Axes,  Next: Labelling the Graph,  Prev: Initializing PLplot,  Up: Simple Use of PLplot

2.3 Defining Plot Scales and Axes
=================================

The function ‘plenv’ (*note plenv; Set up standard window and draw
box::) is used to define the scales and axes for simple graphs.  ‘plenv’
(*note plenv; Set up standard window and draw box::) starts a new
picture on the next subpage (or a new page if necessary), and defines
the ranges of the variables required.  The routine will also draw a box,
axes, and numeric labels if requested.

   For greater control over the size of the plots, axis labelling and
tick intervals, more complex graphs should make use of the functions
‘plvpor’ (*note plvpor; Specify viewport using normalized subpage
coordinates::), ‘plvasp’ (*note plvasp; Specify viewport using aspect
ratio only::), ‘plvpas’ (*note plvpas; Specify viewport using
coordinates and aspect ratio::), ‘plwind’ (*note plwind; Specify
window::), ‘plbox’ (*note plbox; Draw a box with axes; etc::), and
routines for manipulating axis labelling ‘plgxax’ (*note plgxax; Get x
axis parameters::) through ‘plszax’ (*note plszax; Set z axis
parameters::).


File: plplotdoc.info,  Node: Labelling the Graph,  Next: Drawing the Graph,  Prev: Defining Plot Scales and Axes,  Up: Simple Use of PLplot

2.4 Labelling the Graph
=======================

The function ‘pllab’ (*note pllab; Simple routine to write labels::) may
be called after ‘plenv’ (*note plenv; Set up standard window and draw
box::) to write labels on the x and y axes, and at the top of the graph.
More complex labels can be drawn using the function ‘plmtex’ (*note
plmtex; Write text relative to viewport boundaries::).  For discussion
of writing text within a plot see *note Writing Text on a Graph::.


File: plplotdoc.info,  Node: Drawing the Graph,  Next: Finishing Up,  Prev: Labelling the Graph,  Up: Simple Use of PLplot

2.5 Drawing the Graph
=====================

PLplot can draw graphs consisting of points with optional error bars,
line segments or histograms.  Functions which perform each of these
actions may be called after setting up the plotting environment using
‘plenv’ (*note plenv; Set up standard window and draw box::).  All of
the following functions draw within the box defined by ‘plenv’ (*note
plenv; Set up standard window and draw box::), and any lines crossing
the boundary are clipped.  Functions are also provided for drawing
surface and contour representations of multi-dimensional functions.  See
*note Advanced Use of PLplot:: for discussion of finer control of plot
generation.

* Menu:

* Drawing Points::
* Drawing Lines or Curves::
* Writing Text on a Graph::
* Area Fills::
* More Complex Graphs::


File: plplotdoc.info,  Node: Drawing Points,  Next: Drawing Lines or Curves,  Up: Drawing the Graph

2.5.1 Drawing Points
--------------------

‘plstring’ (*note plstring; Plot a glyph at the specified points::),
‘plpoin’ (*note plpoin; Plot a glyph at the specified points::), and
‘plsym’ (*note plsym; Plot a glyph at the specified points::) plot ‘n’
points ‘(x[i], y[i])’ using the specified symbol.  The routines differ
only in how the plotted symbol is specified.  ‘plstring’ (*note
plstring; Plot a glyph at the specified points::) is now the preferred
way of drawing points for unicode-aware devices because it gives users
full access via a UTF-8 string to any unicode glyph they prefer for the
symbol that is is available via system fonts.  ‘plpoin’ (*note plpoin;
Plot a glyph at the specified points::) and ‘plsym’ (*note plsym; Plot a
glyph at the specified points::) are limited to Hershey glyphs and are
therefore more suitable for device drivers that only use Hershey fonts.
For both of these functions the Hershey glyph is indicated by a code
value.  ‘plpoin’ (*note plpoin; Plot a glyph at the specified points::)
uses an extended ASCII index of Hershey glyphs for that code value, with
the printable ASCII codes mapping to the respective characters in the
current Hershey font, and the codes from 0–31 mapping to various useful
Hershey glyphs for symbols.  In ‘plsym’ (*note plsym; Plot a glyph at
the specified points::) however, the code is a Hershey font code number.
Standard examples 04
(http://plplot.sourceforge.net/examples.php?demo=04), 21
(http://plplot.sourceforge.net/examples.php?demo=21), and 26
(http://plplot.sourceforge.net/examples.php?demo=26), demonstrate use of
‘plstring’ (*note plstring; Plot a glyph at the specified points::)
while standard example 06
(http://plplot.sourceforge.net/examples.php?demo=06) demonstrates all
the Hershey symbols available with ‘plpoin’ (*note plpoin; Plot a glyph
at the specified points::) and standard example 07
(http://plplot.sourceforge.net/examples.php?demo=07) demonstrates all
the Hershey symbols available with ‘plsym’ (*note plsym; Plot a glyph at
the specified points::).


File: plplotdoc.info,  Node: Drawing Lines or Curves,  Next: Writing Text on a Graph,  Prev: Drawing Points,  Up: Drawing the Graph

2.5.2 Drawing Lines or Curves
-----------------------------

PLplot provides two functions for drawing line graphs.  All lines are
drawn in the currently selected color, style and width.  See *note
Setting Line Attributes:: for information about changing these
parameters.

   ‘plline’ (*note plline; Draw a line::) draws a line or curve.  The
curve consists of ‘n-1’ line segments joining the ‘n’ points in the
input arrays.  For single line segments, ‘pljoin’ (*note pljoin; Draw a
line between two points::) is used to join two points.


File: plplotdoc.info,  Node: Writing Text on a Graph,  Next: Area Fills,  Prev: Drawing Lines or Curves,  Up: Drawing the Graph

2.5.3 Writing Text on a Graph
-----------------------------

The ‘plptex’ (*note plptex; Write text inside the viewport::) API allows
UTF-* text to be written anywhere within the limits set by ‘plenv’
(*note plenv; Set up standard window and draw box::) with justification
and text angle set by the user.


File: plplotdoc.info,  Node: Area Fills,  Next: More Complex Graphs,  Prev: Writing Text on a Graph,  Up: Drawing the Graph

2.5.4 Area Fills
----------------

Area fills are done in the currently selected color, line style, line
width and pattern style.

   ‘plfill’ (*note plfill; Draw filled polygon::) fills a polygon.  The
polygon consists of ‘n’ vertices which define the polygon.


File: plplotdoc.info,  Node: More Complex Graphs,  Prev: Area Fills,  Up: Drawing the Graph

2.5.5 More Complex Graphs
-------------------------

Functions ‘plbin’ (*note plbin; Plot a histogram from binned data::) and
‘plhist’ (*note plhist; Plot a histogram from unbinned data::) are
provided for drawing histograms, and functions ‘plerrx’ (*note plerrx;
Draw error bars in x direction::) and ‘plerry’ (*note plerry; Draw error
bars in the y direction::) draw error bars about specified points.
There are lots more too (see *note The Common API for PLplot::).


File: plplotdoc.info,  Node: Finishing Up,  Next: In Case of Error,  Prev: Drawing the Graph,  Up: Simple Use of PLplot

2.6 Finishing Up
================

Before the end of the program, _always_ call ‘plend’ (*note plend; End
plotting session::) to close any output plot files and to free up
resources.  For devices that have separate graphics and text modes,
‘plend’ (*note plend; End plotting session::) resets the device to text
mode.


File: plplotdoc.info,  Node: In Case of Error,  Prev: Finishing Up,  Up: Simple Use of PLplot

2.7 In Case of Error
====================

If a fatal error is encountered during execution of a PLplot routine
then ‘plexit’ (*note plexit; Error exit::) is called.  This routine
prints an error message, does resource recovery, and then exits.  The
user may specify an error handler via ‘plsexit’ that gets called before
anything else is done, allowing either the user to abort the error
termination, or clean up user-specific data structures before exit.


File: plplotdoc.info,  Node: Advanced Use of PLplot,  Next: Deploying programs that use PLplot,  Prev: Simple Use of PLplot,  Up: Programming

3 Advanced Use of PLplot
************************

We describe advanced use of PLplot in this chapter which includes many
cross-references to elements of our common (C) API (*note The Common API
for PLplot::) that use PLplot C types such as ‘PLFLT’ (*note
PLFLT-type::) and ‘PLINT’ (*note PLINT-type::).  For full documentation
of all PLplot C types see here (*note plplot-types::).  The best way to
learn how to use our common API for the language of your choice is to
look at our standard set of examples
(http://plplot.sourceforge.net/examples.php).  For additional language
documentation you should consult the various chapters in *note Supported
computer languages: Supported computer languages. as well.

* Menu:

* Command Line Arguments::
* Devices::
* Adding FreeType Library Support to Bitmap Drivers::
* View Surfaces, (Sub-)Pages, Viewports and Windows: View Surfaces; [Sub-]Pages; Viewports and Windows.
* Setting Line Attributes::
* Setting the Area Fill Pattern::
* Setting Color::
* Setting Character Attributes::
* Three-dimensional Plots::
* Legends and color bars::


File: plplotdoc.info,  Node: Command Line Arguments,  Next: Devices,  Up: Advanced Use of PLplot

3.1 Command Line Arguments
==========================

PLplot supports a large number of command line arguments, but it is up
to the user to pass these to PLplot for processing at the beginning of
execution.  ‘plparseopts’ (*note plparseopts; Parse command-line
arguments::) is responsible for parsing the argument list, removing all
that are recognized by PLplot, and taking the appropriate action before
returning.  There are an extensive number of options available to affect
this process.  The command line arguments recognized by PLplot are given
by the -h option:


     	% x00c -h
     Usage:
             examples/c/x00c [options]

     PLplot options:
         -h                   Print out this message
         -v                   Print out the PLplot library version number
         -verbose             Be more verbose than usual
         -debug               Print debugging info (implies -verbose)
         -dev name            Output device name
         -o name              Output filename
         -display name        X server to contact
         -px number           Plots per page in x
         -py number           Plots per page in y
         -geometry geom       Window size/position specified as in X, e.g., 400x300, 400x300-100+200, +100-200, etc.
         -wplt xl,yl,xr,yr    Relative coordinates [0-1] of window into plot
         -mar margin          Margin space in relative coordinates (0 to 0.5, def 0)
         -a aspect            Page aspect ratio (def: same as output device)
         -jx justx            Page justification in x (-0.5 to 0.5, def 0)
         -jy justy            Page justification in y (-0.5 to 0.5, def 0)
         -ori orient          Plot orientation (0,1,2,3=landscape,portrait,seascape,upside-down)
         -freeaspect          Allow aspect ratio to adjust to orientation swaps
         -portrait            Sets portrait mode (both orientation and aspect ratio)
         -width width         Sets pen width (0 <= width)
         -bg color            Background color (FF0000=opaque red, 0000FF_0.1=blue with alpha of 0.1)
         -ncol0 n             Number of colors to allocate in cmap 0 (upper bound)
         -ncol1 n             Number of colors to allocate in cmap 1 (upper bound)
         -fam                 Create a family of output files
         -fsiz size[kKmMgG]   Output family file size (e.g. -fsiz 0.5G, def MB)
         -fbeg number         First family member number on output
         -finc number         Increment between family members
         -fflen length        Family member number minimum field width
         -nopixmap            Don't use pixmaps in X-based drivers
         -db                  Double buffer X window output
         -np                  No pause between pages
         -server_name name    Main window name of PLplot server (tk driver)
         -dpi dpi             Resolution, in dots per inch (e.g. -dpi 360x360)
         -compression num     Sets compression level in supporting devices
         -cmap0 file name     Initializes color table 0 from a cmap0.pal format file in one of standard PLplot paths.
         -cmap1 file name     Initializes color table 1 from a cmap1.pal format file in one of standard PLplot paths.
         -locale              Use locale environment (e.g., LC_ALL, LC_NUMERIC, or LANG) to set LC_NUMERIC locale (which affects decimal point separator).
         -eofill              For the case where the boundary of the filled region is self-intersecting, use the even-odd fill rule rather than the default nonzero fill rule.
         -drvopt option[=value][,option[=value]]* Driver specific options
         -mfo PLplot metafile name Write the plot to the specified PLplot metafile
         -mfi PLplot metafile name Read the specified PLplot metafile

     All parameters must be white-space delimited.  Some options are driver
     dependent.  Please see the PLplot reference document for more detail.


   The command-line options can also be set using the ‘plsetopt’ (*note
plsetopt; Set any command-line option::) function, if invoked before
‘plinit’ (*note plinit; Initialize PLplot::).

   Some options may not be recognized by individual drivers.  If an
option is not recognized but should be, please contact the driver author
via the plplot mailing lists.

   Many drivers have specific options that can be set using the -drvopt
command line option or with ‘plsetopt’ (*note plsetopt; Set any
command-line option::).  These options are documented in *note Drivers
which implement file devices:: and *note Drivers which implement
interactive devices::.


File: plplotdoc.info,  Node: Devices,  Next: Adding FreeType Library Support to Bitmap Drivers,  Prev: Command Line Arguments,  Up: Advanced Use of PLplot

3.2 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 (*note
Output File Formats::) file devices or interactive (*note Interactive
Platforms::) devices.  The available file devices are tabulated in *note
PLplot File Devices:: while the available interactive devices are
tabulated in *note PLplot Interactive Devices::.

   *PLplot File Devices*

Description        Keyword            Source code        Default?
PDF (cairo)        pdfcairo           cairo.c            Yes
PNG (cairo)        pngcairo           cairo.c            Yes
PostScript         pscairo            cairo.c            Yes
(cairo)
Encapsulated       epscairo           cairo.c            Yes
PostScript
(cairo)
SVG (cairo)        epscairo           cairo.c            Yes
CGM                cgm                cgm.c              No
Encapsulated       epsqt              qt.cpp             Yes
PostScript (Qt)
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      plmeta             plmeta.c           No
Meta-File
PostScript         ps                 ps.c               Yes
(monochrome)
PostScript         psc                ps.c               Yes
(color)
PostScript         psttf              psttf.cc           Yes
(monochrome),
(LASi)
PostScript         psttfc             psttf.cc.c         Yes
(color), (LASi)
SVG                svg                svg.c              Yes
XFig               xfig               xfig.c

   *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       qtwidget           qt.cpp             Yes
(Qt)
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

* Menu:

* Driver Functions::
* Family File Output::
* Specifying the Output Device::


File: plplotdoc.info,  Node: Driver Functions,  Next: Family File Output,  Up: Devices

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


File: plplotdoc.info,  Node: Family File Output,  Next: Specifying the Output Device,  Prev: Driver Functions,  Up: Devices

3.2.2 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’ (*note plsfam;
Set family file parameters::) with the familying flag ‘fam’ set to 1,
and the desired maximum member size (in bytes) in ‘bmax’.  ‘plsfam’
(*note plsfam; Set family file parameters::) 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’ (*note plstar; Initialization::) or ‘plstart’
(*note plstart; Initialization::).

   If familying is enabled, the name given for the output file (on the
command line, in response to the ‘plstar’ (*note plstar;
Initialization::) prompt, as a ‘plstart’ (*note plstart;
Initialization::) argument, or as the result of a call to ‘plsfnam’
(*note plsfnam; Set output file name::)) 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’ (*note pleop; Eject current page::) with a call to
‘plfamadv’ (*note plfamadv; Advance to the next family file on the next
new page::).

   If familying is not enabled, ‘%n’ is dropped from the filename if
that string appears anywhere in it.

   The ‘plgfam’ (*note plgfam; Get family file parameters::) 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.


File: plplotdoc.info,  Node: Specifying the Output Device,  Prev: Family File Output,  Up: Devices

3.2.3 Specifying the Output Device
----------------------------------

The main initialization routine for PLplot is ‘plinit’ (*note plinit;
Initialize PLplot::), 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’ (*note plinit; Initialize PLplot::) 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’ (*note plinit; Initialize PLplot::) by:

   • A call to ‘plsdev’ (*note plsdev; Set the device [keyword] name::).

   • The ‘-dev’ DEVICE command line argument, if the program’s command
     line arguments are being passed to the PLplot function
     ‘plparseopts’ (*note plparseopts; Parse command-line arguments::).

   • The value of the ‘PLPLOT_DEV’ environment variable.  Note that
     specifying the output device via ‘plsdev’ (*note plsdev; Set the
     device [keyword] name::) or the ‘-dev’ command line argument will
     override the value given by the ‘PLPLOT_DEV’ environment variable.

   Additional start up routines ‘plstar’ (*note plstar;
Initialization::) and ‘plstart’ (*note plstart; Initialization::) are
available but these are simply front-ends to ‘plinit’ (*note plinit;
Initialize PLplot::), and should be avoided.  It is preferable to call
‘plinit’ (*note plinit; Initialize PLplot::) directly, along with the
appropriate setup calls, for the greater amount of control this provides
(see our standard examples (http://plplot.sourceforge.net/examples.php)
for more info).

   Before ‘plinit’ (*note plinit; Initialize PLplot::) 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 *note Defining the
Viewport:: for more info on viewports).  The routine ‘pladv’ (*note
pladv; Advance the [sub-]page::) 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’ (*note
plsstrm; Set current output stream::) is used to switch between streams.
For any of our supported languages our standard example 14
(http://plplot.sourceforge.net/examples.php?demo=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’ (*note plend; End plotting
session::).  This flushes any internal buffers and frees any memory that
may have been allocated, for all open output streams.  You may call
‘plend1’ (*note plend1; End plotting session for current stream::) 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’ (*note plend1; End plotting
session for current stream::) is made before the new device is opened
for the given stream.


File: plplotdoc.info,  Node: Adding FreeType Library Support to Bitmap Drivers,  Next: View Surfaces; [Sub-]Pages; Viewports and Windows,  Prev: Devices,  Up: Advanced Use of PLplot

3.3 Adding FreeType Library Support to Bitmap Drivers
=====================================================

N.B. this FreeType approach is officially deprecated because of its
inherent font-selection issues (fonts must be specified by filename) and
because it only supports left-to-right layout (i.e., there is no support
for complex text layout languages).  Specialized libraries or system
services that automatically find the best system font to render the
given (unicode) glyph and which support complex text layout should be
used instead.  Those possibilities include Qt (https://www.qt.io/)
(available on all platforms and used by our qt device driver), the
pango/cairo subset of the GTK+ suite of libraries (https://www.gtk.org/)
(available on all platforms and used directly by our cairo device driver
and indirectly by our psttf device driver), Uniscribe
(https://en.wikipedia.org/wiki/Uniscribe) (available only on Windows for
Windows 2000 and later), and DirectWrite
(https://en.wikipedia.org/wiki/DirectWrite) (available only on Windows
for Windows 7 and later).  Currently the wingcc and gd device drivers
are the only ones that depend on the FreeType approach described here.
Because of the limitations of this approach we have plans to update
wingcc to use either Uniscribe or DirectWrite, and once those plans are
realized we will likely retire the gd device driver (currently
deprecated because of the limitations of the current approach) and also
retire this Freetype approach.


File: plplotdoc.info,  Node: View Surfaces; [Sub-]Pages; Viewports and Windows,  Next: Setting Line Attributes,  Prev: Adding FreeType Library Support to Bitmap Drivers,  Up: Advanced Use of PLplot

3.4 View Surfaces, (Sub-)Pages, Viewports and Windows
=====================================================

There is a whole hierarchy of coordinate systems associated with any
PLplot graph.  At the lowest level a device provides a view surface
(coordinates in mm’s) which can be a terminal screen or a sheet of paper
in the output device.  ‘plinit’ (*note plinit; Initialize PLplot::) or
‘plstar’ (*note plstar; Initialization::) (or ‘plstart’ (*note plstart;
Initialization::)) makes that device view surface accessible as a page
or divided up into sub-pages (see ‘plssub’ (*note plssub; Set the number
of subpages in x and y::)) which are accessed with ‘pladv’ (*note pladv;
Advance the [sub-]page::).  Before a graph can be drawn for a subpage,
the program must call appropriate routines in PLplot to define the
viewport for the subpage and a window for the viewport.  A viewport is a
rectangular region of the _subpage_ which is specified in normalized
subpage coordinates or millimetres.  A window is a rectangular region of
world-coordinate space which is mapped directly to its viewport.  (When
drawing a graph, the programmer usually wishes to specify the
coordinates of the points to be plotted in terms of the values of the
variables involved.  These coordinates are called _world coordinates_,
and may have any floating-point value representable by the computer.)

   Although the usual choice is to have one viewport per subpage, and
one window per viewport, each subpage can have more than one (possibly
overlapping) viewport defined, and each viewport can have more than one
window (more than one set of world coordinates) defined.

* Menu:

* Defining the Viewport::
* Defining the Window::
* Annotating the Viewport::
* Setting up a Standard Window::


File: plplotdoc.info,  Node: Defining the Viewport,  Next: Defining the Window,  Up: View Surfaces; [Sub-]Pages; Viewports and Windows

3.4.1 Defining the Viewport
---------------------------

After defining the view surface and subpage with the appropriate call to
‘plinit’ (*note plinit; Initialize PLplot::) or ‘plstar’ (*note plstar;
Initialization::) (or ‘plstart’ (*note plstart; Initialization::)) and a
call to ‘pladv’ (*note pladv; Advance the [sub-]page::) it is necessary
to define the portion of this subpage which is to be used for plotting
the graph (the viewport).  All lines and symbols (except for labels
drawn by ‘plbox’ (*note plbox; Draw a box with axes; etc::), ‘plmtex’
(*note plmtex; Write text relative to viewport boundaries::) and ‘pllab’
(*note pllab; Simple routine to write labels::)) are clipped at the
viewport boundaries.

   Viewports are created within the current subpage.  If the division of
the output device into equally sized subpages is inappropriate, it is
best to specify only a single subpage which occupies the entire output
device (by using ‘plinit’ (*note plinit; Initialize PLplot::) or by
setting ‘nx = 1’ and ‘ny = 1’ in ‘plstar’ (*note plstar;
Initialization::) or ‘plstart’ (*note plstart; Initialization::)), and
use one of the viewport specification subroutines below to place the
plot in the desired position on the page.

   The routines ‘plvpor’ (*note plvpor; Specify viewport using
normalized subpage coordinates::), ‘plsvpa’ (*note plsvpa; Specify
viewport in absolute coordinates::), ‘plvasp’ (*note plvasp; Specify
viewport using aspect ratio only::), ‘plvpas’ (*note plvpas; Specify
viewport using coordinates and aspect ratio::), and ‘plvsta’ (*note
plvsta; Select standard viewport::) may be used to specify the limits of
the viewport within the current subpage.  The ‘plvpor’ (*note plvpor;
Specify viewport using normalized subpage coordinates::) routine
specifies the viewport limits in normalized subpage coordinates.  The
‘plsvpa’ (*note plsvpa; Specify viewport in absolute coordinates::)
routine (often used in conjunction with the ‘plgspa’ (*note plgspa; Get
current subpage parameters::) routine which returns the physical limits
of the current subpage) specifies the viewport limits in physical
coordinates.  The routine ‘plvasp’ (*note plvasp; Specify viewport using
aspect ratio only::) specifies the largest viewport with the given
aspect ratio that fits in the current subpage while allowing for a
standard margins on each side of the viewport.  The routine ‘plvpas’
(*note plvpas; Specify viewport using coordinates and aspect ratio::)
specifies the largest viewport with the given aspect ratio that fits in
a region that is specified by normalized subpage coordinates as with
‘plvpor’ (*note plvpor; Specify viewport using normalized subpage
coordinates::).  (The routine ‘plvpas’ (*note plvpas; Specify viewport
using coordinates and aspect ratio::) is functionally equivalent to
‘plvpor’ (*note plvpor; Specify viewport using normalized subpage
coordinates::) when the specified aspect ratio is set to zero.)  The
‘plvsta’ (*note plvsta; Select standard viewport::) routine specifies
the largest viewport that fits in the current subpage while allowing for
a standard margins on each side of the viewport.  This standard viewport
is that used by ‘plenv’ (*note plenv; Set up standard window and draw
box::) (See *note Setting up a Standard Window::).


File: plplotdoc.info,  Node: Defining the Window,  Next: Annotating the Viewport,  Prev: Defining the Viewport,  Up: View Surfaces; [Sub-]Pages; Viewports and Windows

3.4.2 Defining the Window
-------------------------

The routine ‘plwind’ (*note plwind; Specify window::) is used to map the
world coordinate rectangle into the viewport rectangle.  If the order of
either the X limits or Y limits is reversed, the corresponding axis will
point in the opposite sense, (i.e., right to left for X and top to
bottom for Y). The window must be defined before any calls to the
routines which actually draw the data points.  Note however that
‘plwind’ (*note plwind; Specify window::) may also be called to change
the window at any time.  This will affect the appearance of objects
drawn later in the program, and is useful for drawing two or more graphs
with different axes on the same viewport.


File: plplotdoc.info,  Node: Annotating the Viewport,  Next: Setting up a Standard Window,  Prev: Defining the Window,  Up: View Surfaces; [Sub-]Pages; Viewports and Windows

3.4.3 Annotating the Viewport
-----------------------------

The routine ‘plbox’ (*note plbox; Draw a box with axes; etc::) is used
to specify how much (if any) of the frame is drawn around the viewport
and to control the positions of the axis subdivisions and numeric
labels.  In addition, non-default lengths of major and minor ticks on
the axes may be set up by calls to the routines ‘plsmaj’ (*note plsmaj;
Set length of major ticks::) and ‘plsmin’ (*note plsmin; Set length of
minor ticks::).

   The routine ‘pllab’ (*note pllab; Simple routine to write labels::)
is used to specify text labels for the bottom, left hand side and top of
the viewport.  These labels are not clipped, even though they lie
outside the viewport (but they are clipped at the subpage boundaries).
‘pllab’ (*note pllab; Simple routine to write labels::) actually calls
the more general routine ‘plmtex’ (*note plmtex; Write text relative to
viewport boundaries::) which can be used for plotting labels at any
point relative to the viewport.

   The appearance of axis labels may be further altered by auxiliary
calls to ‘plprec’ (*note plprec; Set precision in numeric labels::),
‘plschr’ (*note plschr; Set character size::), ‘plsxax’ (*note plsxax;
Set x axis parameters::), ‘plsyax’ (*note plsyax; Set y axis
parameters::), and ‘plszax’ (*note plszax; Set z axis parameters::).
The routine ‘plprec’ (*note plprec; Set precision in numeric labels::)
is used to set the number of decimal places precision for axis labels,
while ‘plschr’ (*note plschr; Set character size::) modifies the heights
of characters used for the axis and graph labels.  Routines ‘plsxax’
(*note plsxax; Set x axis parameters::), ‘plsyax’ (*note plsyax; Set y
axis parameters::), and ‘plszax’ (*note plszax; Set z axis parameters::)
are used to modify the ‘digmax’ setting for each axis, which affects how
floating point labels are formatted.

   The ‘digmax’ variable represents the maximum field width for the
numeric labels on an axis (ignored if less than one).  If the numeric
labels as generated by PLplot exceed this width, then PLplot
automatically switches to floating point representation.  In this case
the exponent will be placed at the top left for a vertical axis on the
left, top right for a vertical axis on the right, and bottom right for a
horizontal axis.

   For example, let’s suppose that we have set ‘digmax = 5’ via ‘plsyax’
(*note plsyax; Set y axis parameters::), and for our plot a label is
generated at ‘y = 0.0000478’.  In this case the actual field width is
longer than ‘digmax’, so PLplot switches to floating point.  In this
representation, the label is printed as simply 4.78 with the 10^-5
exponent placed separately.

   The determination of maximum length (i.e.  ‘digmax’) for fixed point
quantities is complicated by the fact that long fixed point
representations look much worse than the same sized floating point
representation.  Further, a fixed point number with magnitude much less
than one will actually gain in precision when written as floating point.
There is some compensation for this effect built into PLplot, thus the
internal representation for number of digits kept (‘digfix’) may not
always match the user’s specification (via ‘digmax’).  However, it will
always be true that ‘digfix ≤ digmax’.  The PLplot defaults are set up
such that good results are usually obtained without user intervention.

   Finally, after the call to ‘plbox’ (*note plbox; Draw a box with
axes; etc::), the user may call routines ‘plgxax’ (*note plgxax; Get x
axis parameters::), ‘plgyax’ (*note plgyax; Get y axis parameters::), or
‘plgzax’ (*note plgzax; Get z axis parameters::) to obtain information
about the window just drawn.  This can be helpful when deciding where to
put captions.  For example, a typical usage would be to call ‘plgyax’
(*note plgyax; Get y axis parameters::) to get the value of ‘digits’,
then offset the y axis caption by that amount (plus a bit more) so that
the caption ‘floats’ just to the outside of the numeric labels.  Note
that the ‘digits’ value for each axis for the current plot is not
correct until _after_ the call to ‘plbox’ (*note plbox; Draw a box with
axes; etc::) is complete.


File: plplotdoc.info,  Node: Setting up a Standard Window,  Prev: Annotating the Viewport,  Up: View Surfaces; [Sub-]Pages; Viewports and Windows

3.4.4 Setting up a Standard Window
----------------------------------

Having to call ‘pladv’ (*note pladv; Advance the [sub-]page::), ‘plvpor’
(*note plvpor; Specify viewport using normalized subpage coordinates::),
‘plwind’ (*note plwind; Specify window::) and ‘plbox’ (*note plbox; Draw
a box with axes; etc::) is cumbersome for drawing simple graphs so as an
alternative we have implemented ‘plenv’ (*note plenv; Set up standard
window and draw box::) that combines all four of these capabilities in
one routine using the standard viewport and a limited subset of the
capabilities of ‘plbox’ (*note plbox; Draw a box with axes; etc::).


File: plplotdoc.info,  Node: Setting Line Attributes,  Next: Setting the Area Fill Pattern,  Prev: View Surfaces; [Sub-]Pages; Viewports and Windows,  Up: Advanced Use of PLplot

3.5 Setting Line Attributes
===========================

The graph drawing routines may be freely mixed with those described in
this section, allowing the user to control line color, width and styles.
The attributes set up by these routines apply modally, i.e, all
subsequent objects (lines, characters and symbols) plotted until the
next change in attributes are affected in the same way.  The only
exception to this rule is that characters and symbols are not affected
by a change in the line style, but are always drawn using a continuous
line.

   Line color is set using the routine ‘plcol0’ (*note plcol0; Set
color; cmap0::).  The argument is ignored for devices which can only
plot in one color, although some terminals support line erasure by
plotting in color zero.

   Line width is set using ‘plwidth’ (*note plwidth; Set pen width::).
This option is not supported by all devices.

   Line style is set using the routine ‘plstyl’ (*note plstyl; Set line
style::) or ‘pllsty’ (*note pllsty; Select line style::).  A broken line
is specified in terms of a repeated pattern consisting of marks (pen
down) and spaces (pen up).  The arguments to this routine are the number
of elements in the vectors (dropped for the redacted API) and integer
‘mark’ and ‘space’ vectors which contain the mark and space lengths in
micrometers.  Thus a line consisting of long and short dashes of lengths
4 mm and 2 mm, separated by spaces of length 1.5 mm is specified by
‘mark’ vector elements of 4000 and 2000, and ‘space’ vector elements of
1500 and 1500.  To return to a continuous line, just call ‘plstyl’
(*note plstyl; Set line style::) with vectors with no elements.  You can
also use ‘pllsty’ (*note pllsty; Select line style::) to choose between
8 different predefined line styles.


File: plplotdoc.info,  Node: Setting the Area Fill Pattern,  Next: Setting Color,  Prev: Setting Line Attributes,  Up: Advanced Use of PLplot

3.6 Setting the Area Fill Pattern
=================================

The routine ‘plpsty’ (*note plpsty; Select area fill pattern::) may be
used to select either a solid fill or from 1 of 8 predefined area line
fill patterns.  Additional area line fill patterns using one or two sets
of parallel lines at arbitrary inclinations and spacings can be
specified with the routine ‘plpat’ (*note plpat; Set area line fill
pattern::) The (redacted) arguments to this routine are the integer
‘inc’ and ‘del’ vectors specifying the inclinations in tenths of a
degree and the spacing in micrometers of the pattern(s).  Thus to
specify an area line fill pattern consisting of horizontal lines spaced
2 mm apart the ‘inc’ vector should have single element set to 0, and the
‘del’ vector should have a single element set to 2000.  And to specify
an area line fill pattern consisting of a symmetrical crosshatch with
lines directed 30 degrees above and below the horizontal and spaced 1.5
mm apart, the ‘inc’ vector should contain the elements 300 and -300, and
the ‘del’ vector should contain the elements 1500 and 1500.

   N.B. Solid fills use the current (semitransparent) color and line
fills use the current line style, width, and (semitransparent) color.
The result is PLplot users have a large choice of different fill
patterns.


File: plplotdoc.info,  Node: Setting Color,  Next: Setting Character Attributes,  Prev: Setting the Area Fill Pattern,  Up: Advanced Use of PLplot

3.7 Setting Color
=================

Normally, color is used for all drivers and devices that support it
within PLplot subject to the condition that the user has the option of
globally turning off the color (and subsequently turning it on again if
so desired) using ‘plscolor’ (*note plscolor; Used to globally turn
color output on/off::).

   The PLplot color model allows the user to set the current color from
a wide range of colors using two distinct color maps.  Color map0
(called cmap0 and discussed in *note Color Map0::) has discrete colors
arranged in no particular order with regard to color index and is most
suited to coloring discrete elements of the plot.  Color map1 (called
cmap1 and discussed in *note Color Map1::) has colors which are a
continuous function of color index and is most suited to coloring
continuous elements of the plot.  The user can change the current color
(as opposed to the background color which is a special case that is
discussed in *note Color Map0::) at any point in the PLplot commands
that are used to create a given plot by selecting any of the colors from
either cmap0 or cmap1 using calls to ‘plcol0’ (*note plcol0; Set color;
cmap0::) or ‘plcol1’ (*note plcol1; Set color; cmap1::).  When the
current color is changed all subsequent drawing actions will utilize
that new color until it is changed again.

* Menu:

* Color Map0::
* Color Map1::


File: plplotdoc.info,  Node: Color Map0,  Next: Color Map1,  Up: Setting Color

3.7.1 Color Map0
----------------

Color map0 is most suited to coloring discrete elements of the plot such
as the background, axes, lines, and labels.  The cmap0 palette colors
are stored using RGBA (https://en.wikipedia.org/wiki/RGBA_color_space)
(i.e., red, green, blue, and alpha transparency) components (although
some drivers ignore the alpha transparency data and simply render opaque
colors corresponding to the semitransparent ones).  In the discussion
that follows all references to cmap0 API functions with a trailing "a"
in their names (e.g., ‘plscol0a’ (*note plscol0a; Set 8-bit RGB values
and PLFLT alpha transparency value for given cmap0 color index::))
refers to setting RGBA semitransparent colors while the equivalent
function (e.g., ‘plscol0’ (*note plscol0; Set 8-bit RGB values for given
cmap0 color index::)) without the trailing "a" in the name refers to
setting RGB colors with an assumed opaque alpha transparency of 1.0.

   Page 1 of our standard example 02
(http://plplot.sourceforge.net/examples.php?demo=02) illustrates the
default 16 colors in the cmap0 palette.  The background color is a
special case to be discussed below, and the current color of discrete
elements of the plot other than the background may be specified by cmap0
index (or cmap1 index, see *note Color Map1::).  The cmap0 index is 1 by
default (and corresponds to opaque red for the default cmap0 palette),
but during the course of plotting a page, the user can change that
current color as often as desired using ‘plcol0’ (*note plcol0; Set
color; cmap0::) to select the desired cmap0 color index from the cmap0
color palette in existence at the time.

   The advanced cmap0 use case includes a number of methods for changing
the cmap0 color palette.  It is possible to update one index of the
cmap0 palette using ‘plscol0a’ (*note plscol0a; Set 8-bit RGB values and
PLFLT alpha transparency value for given cmap0 color index::) or
‘plscol0’ (*note plscol0; Set 8-bit RGB values for given cmap0 color
index::), define a complete cmap0 palette with an arbitrary number of
colors using ‘plscmap0a’ (*note plscmap0a; Set cmap0 colors by 8-bit RGB
values and PLFLT alpha transparency value::) or ‘plscmap0’ (*note
plscmap0; Set cmap0 colors by 8-bit RGB values::), or read in a complete
cmap0 palette from a special cmap0 palette file with the command-line
‘cmap0’ parameter or by calling ‘plspal0’ (*note plspal0; Set the cmap0
palette using the specified cmap0*_pal format file::).  Our standard
examples 04 (http://plplot.sourceforge.net/examples.php?demo=04), 19
(http://plplot.sourceforge.net/examples.php?demo=19), 26
(http://plplot.sourceforge.net/examples.php?demo=26), 30
(http://plplot.sourceforge.net/examples.php?demo=30), 31
(http://plplot.sourceforge.net/examples.php?demo=31), and 33
(http://plplot.sourceforge.net/examples.php?demo=33) illustrate how to
use ‘plscol0a’ (*note plscol0a; Set 8-bit RGB values and PLFLT alpha
transparency value for given cmap0 color index::) and ‘plscol0’ (*note
plscol0; Set 8-bit RGB values for given cmap0 color index::).  Our
standard examples 02
(http://plplot.sourceforge.net/examples.php?demo=02), 24
(http://plplot.sourceforge.net/examples.php?demo=24), and 30
(http://plplot.sourceforge.net/examples.php?demo=30) illustrate how to
use ‘plscmap0a’ (*note plscmap0a; Set cmap0 colors by 8-bit RGB values
and PLFLT alpha transparency value::) and ‘plscmap0’ (*note plscmap0;
Set cmap0 colors by 8-bit RGB values::).  Although the user can define
and use any cmap0 palette file they like, predefined cmap0 palette files
are given in ‘data/cmap0*.pal’ within the source tree and installed in
‘<install-prefix>/share/plplot5.13.0/cmap0*.pal’ in the install tree.
By default the cmap0 palette is set using the predefined
‘cmap0_default.pal’ file, but our standard example 16
(http://plplot.sourceforge.net/examples.php?demo=16) demonstrates use of
a number of our other predefined cmap0 palette files in the various
pages of that example.  Many of the above commands indirectly set the
number of cmap0 colors, but it is also possible for the user to specify
that number directly with the command-line ‘ncol0’ parameter or by
calling ‘plscmap0n’ (*note plscmap0n; Set number of colors in cmap0::).
For all methods of defining the cmap0 palette any number of colors are
allowed in any order, but it is not guaranteed that the individual
drivers will actually be able to use more than 16 colors (although most
drivers do support more than 16 colors).

   The background color (which always corresponds to index 0 of the
cmap0 palette) is a special case that must be discussed separately.  The
default cmap0 palette index 0 corresponds to opaque black so by default
the background is that color.  However, the user may set that background
color to something else by using the command-line ‘bg’ parameter, by
calling ‘plscolbga’ (*note plscolbga; Set the background color by 8-bit
RGB value and PLFLT alpha transparency value_::) or ‘plscolbg’ (*note
plscolbg; Set the background color by 8-bit RGB value::), or by calling
‘plscol0a’ (*note plscol0a; Set 8-bit RGB values and PLFLT alpha
transparency value for given cmap0 color index::) or ‘plscol0’ (*note
plscol0; Set 8-bit RGB values for given cmap0 color index::) with a 0
index.  In addition, the background color is implicitly set when the
whole cmap0 color palette (including index 0) is changed with one of the
methods above.  However, since the background is painted at the start of
each page any of these methods of changing the background color must be
done _before_ that page start.  Note that although our long-term goal is
for each device driver that honors semitransparent colors will also
honor semitransparent background requests from users the current status
is only a few drivers (e.g., the svg device driver) do that and the rest
fall back to replacing the requested semitransparent background with the
equivalent opaque background.


File: plplotdoc.info,  Node: Color Map1,  Prev: Color Map0,  Up: Setting Color

3.7.2 Color Map1
----------------

Color map1 is most suited to coloring elements of plots in which
continuous data values are represented by a continuous range of colors.
The cmap1 palette colors are stored using RGBA
(https://en.wikipedia.org/wiki/RGBA_color_space) (i.e., red, green,
blue, and alpha transparency) components (although some drivers ignore
the alpha transparency data and simply render the opaque colors
corresponding to the requested semitransparent color).  In the
discussion that follows all references to cmap1 API functions with a
trailing "a" in their names (e.g., ‘plscmap1la’ (*note plscmap1la; Set
cmap1 colors and alpha transparency using a piece-wise linear
relationship::)) refers to setting RGBA semitransparent colors, while
the equivalent function (e.g., ‘plscmap1l’ (*note plscmap1l; Set cmap1
colors using a piece-wise linear relationship::)) without the trailing
"a" in the name refers to setting RGB colors with an assumed opaque
alpha transparency of 1.0.  The cmap1 index is a floating-point number
whose default range is 0.0-1.0, but to set and get that range use
‘plscmap1_range’ (*note plscmap1_range; Set the cmap1 argument range for
continuous color plots::) and ‘plgcmap1_range’ (*note plgcmap1_range;
Get the cmap1 argument range for continuous color plots::).

   Page 4 of our standard example 16
(http://plplot.sourceforge.net/examples.php?demo=16) illustrates use of
our default cmap1 palette to represent continuous data values as a
continuous range of colors using ‘plshades’ (*note plshades; Shade
regions on the basis of value::).  For this case and also other PLplot
API (e.g., ‘plsurf3d’ (*note plsurf3d; Plot shaded 3-d surface plot::))
where continuous data are being plotted, the range of continuous data
are scaled to the cmap1 color index range which in turn are mapped
internally using ‘plcol1’ (*note plcol1; Set color; cmap1::) to
continuous colors using the cmap1 color palette.  In addition, during
the course of plotting a page, the user can change the current color
used for discrete objects as often as desired by directly calling
‘plcol1’ (*note plcol1; Set color; cmap1::) to select the desired cmap1
color index from the cmap1 color palette in existence at the time.
However, use of ‘plcol0’ (*note plcol0; Set color; cmap0::) and the
cmap0 palette (see *note Color Map0::) to set the current color for
discrete objects is more usual.

   The advanced cmap1 use case includes a number of methods of changing
the cmap1 palette.  It is possible to define a complete cmap1 palette by
using ‘plscmap1la’ (*note plscmap1la; Set cmap1 colors and alpha
transparency using a piece-wise linear relationship::) or ‘plscmap1l’
(*note plscmap1l; Set cmap1 colors using a piece-wise linear
relationship::) (where linear interpolation between control points of
given alpha transparency and either RGB or HLS color assures the palette
is a continuous function of its index); by using ‘plscmap1a’ (*note
plscmap1a; Set semitransparent cmap1 RGBA colors_::) or ‘plscmap1’
(*note plscmap1; Set opaque RGB cmap1 colors values::) (where it is the
user’s responsibility to makes sure that palette is a continuous
function of its index); or by reading in a complete cmap1 palette from a
special cmap1 palette file with the command-line ‘cmap1’ parameter or by
calling ‘plspal1’ (*note plspal1; Set the cmap1 palette using the
specified cmap1*_pal format file::).  Our standard examples 08
(http://plplot.sourceforge.net/examples.php?demo=08), 11
(http://plplot.sourceforge.net/examples.php?demo=11), 12
(http://plplot.sourceforge.net/examples.php?demo=12), 15
(http://plplot.sourceforge.net/examples.php?demo=15), 20
(http://plplot.sourceforge.net/examples.php?demo=20), 21
(http://plplot.sourceforge.net/examples.php?demo=21), and 30
(http://plplot.sourceforge.net/examples.php?demo=30) illustrate how to
use ‘plscmap1la’ (*note plscmap1la; Set cmap1 colors and alpha
transparency using a piece-wise linear relationship::) and ‘plscmap1l’
(*note plscmap1l; Set cmap1 colors using a piece-wise linear
relationship::).  Our standard example 31
(http://plplot.sourceforge.net/examples.php?demo=31) illustrates how to
use ‘plscmap1a’ (*note plscmap1a; Set semitransparent cmap1 RGBA
colors_::) and ‘plscmap1’ (*note plscmap1; Set opaque RGB cmap1 colors
values::) (which are rarely used because of the continuity concern).
Although the user can define and use any cmap1 palette file they like,
predefined cmap1 palette files are given in ‘data/cmap1*.pal’ within the
source tree and installed in
‘<install-prefix>/share/plplot5.13.0/cmap1*.pal’ in the install tree.
By default the cmap1 palette is set using the predefined
‘cmap1_default.pal’ file, but our standard example 16
(http://plplot.sourceforge.net/examples.php?demo=16) demonstrates use of
a number of our other predefined cmap1 palette files in the various
pages of that example.  The default number of cmap1 colors is 128 which
supplies sufficient sampling of the continuous cmap1 palette for most
purposes, but that number can be set to other values with the
command-line ‘ncol1’ parameter or by calling ‘plscmap1n’ (*note
plscmap1n; Set number of colors in cmap1::).  (That number is also
updated by calls to the rarely used ‘plscmap1a’ (*note plscmap1a; Set
semitransparent cmap1 RGBA colors_::) or ‘plscmap1’ (*note plscmap1; Set
opaque RGB cmap1 colors values::).)

   There is a one-to-one correspondence between RGB
(https://en.wikipedia.org/wiki/RGB_color_model) and HLS
(https://en.wikipedia.org/wiki/HLS_color_space) color spaces.  Plplot
provides ‘plrgbhls’ (*note plrgbhls; Convert RGB color to HLS::) to
convert from RGB to HLS and ‘plhlsrgb’ (*note plhlsrgb; Convert HLS
color to RGB::) to convert from HLS to RGB.

   RGB space is characterized by three 8-bit unsigned integers
corresponding to the intensity of the red, green, and blue colors.
Thus, in hexadecimal notation with the 3 bytes concatenated together the
RGB values of FF0000, FFFF00, 00FF00, 00FFFF, 0000FF, FF00FF, 000000,
and FFFFFF correspond to red, yellow, green, cyan, blue, magenta, black,
and white.

   HLS (hue, lightness, and saturation) space is often conceptually
easier to use than RGB space.  One useful way to visualize HLS space is
as a volume made up by two cones with their bases joined at the
‘equator’.  A given RGB point corresponds to HLS point somewhere on or
inside the double cones, and vice versa.  The hue corresponds to the
‘longitude’ of the point with 0, 60, 120, 180, 240, and 300 degrees
corresponding to red, yellow, green, cyan, blue, and magenta.  The
lightness corresponds to the distance along the axis of the figure of a
perpendicular dropped from the HLS point to the axis.  This values
ranges from 0 at the ‘south pole’ to 1 at the ‘north pole’.  The
saturation corresponds to the distance of the HLS point from the axis
with the on-axis value being 0 and the surface value being 1.  Full
saturation corresponds to full color while reducing the saturation
(moving toward the axis of the HLS figure) mixes more gray into the
color until at zero saturation on the axis of the figure you have only
shades of gray with the variation of lightness along the axis
corresponding to a gray scale.


File: plplotdoc.info,  Node: Setting Character Attributes,  Next: Three-dimensional Plots,  Prev: Setting Color,  Up: Advanced Use of PLplot

3.8 Setting Character Attributes
================================

Plplot uses two separate font systems to display characters.  The
Hershey font system gives access to Hershey fonts that come with PLplot.
All of our older devices and most of our modern devices allow use of the
Hershey font system.  The unicode font system gives access to
unicode-aware system fonts.  Some of our older devices and most of our
modern devices allow use of the unicode font system.  The advantages of
the unicode font system over the Hershey font system are discussed in
*note Unicode font system::.

* Menu:

* Hershey font system::
* Unicode font system::
* FCI::
* Escape sequences in text::
* Character size adjustment::


File: plplotdoc.info,  Node: Hershey font system,  Next: Unicode font system,  Up: Setting Character Attributes

3.8.1 Hershey font system
-------------------------

There are two Hershey font character sets included with PLplot.  These
are known as the standard and extended character sets.  The standard
character set is a subset of the extended set.  It contains 177
characters including the ascii characters in a normal style font, the
Greek alphabet and several plotter symbols.  The extended character set
contains almost 1000 characters, including four font styles, and several
math, musical and plotter symbols.

   The extended character set is loaded into memory automatically when
PLplot is initialized.  The standard character set is loaded by calling
‘plfontld’ (*note plfontld; Load Hershey fonts::).  The extended
character set requires about 50 KBytes of memory, versus about 5 KBytes
for the standard set.  ‘plfontld’ (*note plfontld; Load Hershey fonts::)
can be used to switch between the extended and standard sets (one set is
unloaded before the next is loaded).  ‘plfontld’ (*note plfontld; Load
Hershey fonts::) can be called before ‘plstar’ (*note plstar;
Initialization::).

   When the extended character set is loaded there are four different
font styles to choose from.  In this case, the routine ‘plfont’ (*note
plfont; Set font::) sets up the default Hershey font for all character
strings.  It may be overridden for any portion of a string by using an
escape sequence within the text, as described in *note Escape sequences
in text::.  For the Hershey font system (but not the unicode font
system, see below) this routine has no practical effect when the
standard font set is loaded.  The default font (1) is simple and fastest
to draw; the others are useful for presentation plots on a
high-resolution device.

   The font codes are interpreted as follows:

   • ‘font = 1’: normal (sans-serif) font

   • ‘font = 2’: roman (serif) font

   • ‘font = 3’: italic font

   • ‘font = 4’: script font


File: plplotdoc.info,  Node: Unicode font system,  Next: FCI,  Prev: Hershey font system,  Up: Setting Character Attributes

3.8.2 Unicode font system
-------------------------

The advantages of the unicode fonts over the more traditional PLplot
Hershey fonts are the availability of many additional glyphs (including
mathematical symbols and glyphs from other than western-European
languages); support of complex text layout languages for a substantial
subset (see *note The svg device driver:: and *note The psttf, cairo,
qt, and wxwidgets device drivers: The psttf; cairo; qt; and wxwidgets
device drivers.) of the devices that support the Unicode font system;
and much better display of characters on computer screens using
anti-aliasing and hinting.

   The unicode font system can use font specification methods that were
designed for the Hershey fonts to specify the unicode font.  For this
case ‘plfont’ (*note plfont; Set font::) internally calls ‘plsfci’
(*note plsfci; Set FCI [font characterization integer]::) using four
different FCI values to choose unicode font attributes similar to the 4
kinds of Hershey fonts, and the corresponding Hershey text
escape-sequences (see *note Escape sequences in text::) designed to
override the Hershey font selection are treated similarly.  However, for
the unicode font system the preferred and much more flexible methods of
specifying the unicode font are calling the ‘plsfci’ (*note plsfci; Set
FCI [font characterization integer]::) routine, calling the ‘plsfont’
(*note plsfont; Set family; style and weight of the current font::)
routine which provides a user-friendly interface to ‘plsfci’ (*note
plsfci; Set FCI [font characterization integer]::), or using unicode
text escape-sequences to override unicode font attributes in the middle
of strings (see *note FCI::).

* Menu:

* The ps device driver::
* The gd and wingcc device drivers::
* The svg device driver::
* The psttf, cairo, qt, and wxwidgets device drivers: The psttf; cairo; qt; and wxwidgets device drivers.


File: plplotdoc.info,  Node: The ps device driver,  Next: The gd and wingcc device drivers,  Up: Unicode font system

3.8.2.1 The ps device driver
............................

The ps and psc devices that are implemented with the ps device driver
are only unicode-aware in a technical sense because they use a fixed
relationship between the FCI (font characterization integer, see *note
FCI::) and the actual Type 1 system fonts that are being used which
unlike typical TTF system fonts have extremely limited glyphs available.
This fixed relationship is specified in the Type1Lookup array in
include/plfci.h.  This array maps the FCI font-family attributes of
sans-serif, serif, monotype, script, and symbol to the standard
PostScript font families called Helvetica, Times-Roman, Courier,
Times-Roman, and Symbol.  (There is no script font family amongst the 35
standard Type 1 postscript fonts so that is why we map the font-family
attribute of script to Times-Roman.)  Similarly, this array maps the FCI
font-style attributes of upright, italic or oblique and the FCI
font-weight attributes of medium or bold to the appropriate variety of
the Helvetica, Times-Roman, Courier, and Symbol font families that are
part of the 35 standard Type 1 PostScript fonts.  These fonts are
normally available on all platforms (e.g., with the gsfonts package on
Linux systems).


File: plplotdoc.info,  Node: The gd and wingcc device drivers,  Next: The svg device driver,  Prev: The ps device driver,  Up: Unicode font system

3.8.2.2 The gd and wingcc device drivers
........................................

For the png, jpeg, and gif devices (implemented with the gd device
driver) and the wingcc device (implemented with the wingcc device
driver), the deprecated plfreetype approach is used for accessing
unicode-aware system fonts.  This approach is deprecated because of its
two major drawbacks.  (1) text layout is only left-to-right so that
complex text layout languages (such as those used in our standard
example 24 (http://plplot.sourceforge.net/examples.php?demo=24)) are not
correctly rendered.  (2) System fonts are only accessed by file name
rather than using the fontconfig approach or something similar to select
the best system font to render the given unicode glyph.  Because of this
latter drawback a configurable relationship must be established between
the FCI (font characterization integer, see *note FCI::) and the
TrueType font name that is actually used for rendering a unicode glyph.
This can be a considerable inconvenience for the user if they want to
specify anything other than a default set of font names.

   The TrueType font names corresponding to the 30 possible valid FCIs
can be specified using cmake options.  The defaults for the 30 cmake
variables PL_FREETYPE_FONT[_MODIFIER] (where FONT is one of MONO, SANS,
SCRIPT, SERIF or SYMBOL and the optional MODIFIER is one of BOLD,
BOLD_ITALIC, BOLD_OBLIQUE, ITALIC or OBLIQUE) are documented in
cmake/modules/freetype.cmake.  On Windows these defaults use standard
Windows font files.  On all other platforms default font file names are
taken from fonts available from the ttf-freefont font package.  We
recommend this font package because it has a rather complete set of
glyphs for most unicode blocks.  (We also recommend the gucharmap
application for determining other unicode font possibilities on your
system that are available via the FreeType library.)

   For all platforms, the 30 possible TrueType font files can be
specified at run time using the following environment variables:

   • PLPLOT_FREETYPE_SANS_FONT

   • PLPLOT_FREETYPE_SERIF_FONT

   • PLPLOT_FREETYPE_MONO_FONT

   • PLPLOT_FREETYPE_SCRIPT_FONT

   • PLPLOT_FREETYPE_SYMBOL_FONT

   • PLPLOT_FREETYPE_SANS_ITALIC_FONT

   • PLPLOT_FREETYPE_SERIF_ITALIC_FONT

   • PLPLOT_FREETYPE_MONO_ITALIC_FONT

   • PLPLOT_FREETYPE_SCRIPT_ITALIC_FONT

   • PLPLOT_FREETYPE_SYMBOL_ITALIC_FONT

   • PLPLOT_FREETYPE_SANS_OBLIQUE_FONT

   • PLPLOT_FREETYPE_SERIF_OBLIQUE_FONT

   • PLPLOT_FREETYPE_MONO_OBLIQUE_FONT

   • PLPLOT_FREETYPE_SCRIPT_OBLIQUE_FONT

   • PLPLOT_FREETYPE_SYMBOL_OBLIQUE_FONT

   • PLPLOT_FREETYPE_SANS_BOLD_FONT

   • PLPLOT_FREETYPE_SERIF_BOLD_FONT

   • PLPLOT_FREETYPE_MONO_BOLD_FONT

   • PLPLOT_FREETYPE_SCRIPT_BOLD_FONT

   • PLPLOT_FREETYPE_SYMBOL_BOLD_FONT

   • PLPLOT_FREETYPE_SANS_BOLD_ITALIC_FONT

   • PLPLOT_FREETYPE_SERIF_BOLD_ITALIC_FONT

   • PLPLOT_FREETYPE_MONO_BOLD_ITALIC_FONT

   • PLPLOT_FREETYPE_SCRIPT_BOLD_ITALIC_FONT

   • PLPLOT_FREETYPE_SYMBOL_BOLD_ITALIC_FONT

   • PLPLOT_FREETYPE_SANS_BOLD_OBLIQUE_FONT

   • PLPLOT_FREETYPE_SERIF_BOLD_OBLIQUE_FONT

   • PLPLOT_FREETYPE_MONO_BOLD_OBLIQUE_FONT

   • PLPLOT_FREETYPE_SCRIPT_BOLD_OBLIQUE_FONT

   • PLPLOT_FREETYPE_SYMBOL_BOLD_OBLIQUE_FONT

On Unix/Linux systems if these environment variables are not specified
with an absolute path starting with "/", then the absolute path is
specified by the cmake variable PL_FREETYPE_FONT_PATH or at run time
with the environment variable PLPLOT_FREETYPE_FONT_DIR.


File: plplotdoc.info,  Node: The svg device driver,  Next: The psttf; cairo; qt; and wxwidgets device drivers,  Prev: The gd and wingcc device drivers,  Up: Unicode font system

3.8.2.3 The svg device driver
.............................

The svg device (which is implemented with the svg device driver) is a
device that implements the unicode font method by mapping FCI attributes
(see *note FCI::) to corresponding combinations of the SVG attributes
font-family, font-style, and font-weight.  Since these attributes are
generic ones, (e.g., FCI font-family "sans-serif", "serif", "monospace",
"script", and "symbol" correspond to SVG font-family "sans-serif",
"serif", "mono-space", "cursive", and "sans-serif") the SVG viewer
applications that render the SVG files produced by the svg device have a
large degree of freedom within these generic guidelines for choosing
which system font to use to render a given unicode glyph.  Note that
unlike devices that use the plfreetype approach (see *note The gd and
wingcc device drivers::) this device requires no user intervention to
set up the correct mapping between FCI and font, and complex text layout
languages are rendered correctly (assuming the SVG viewer does that).


File: plplotdoc.info,  Node: The psttf; cairo; qt; and wxwidgets device drivers,  Prev: The svg device driver,  Up: Unicode font system

3.8.2.4 The psttf, cairo, qt, and wxwidgets device drivers
..........................................................

The large number of unicode-aware devices that are implemented by the
psttf, cairo, qt, and wxwidgets device drivers implement the unicode
font method using PLplot FCI values (see *note FCI::) to characterize
the generic fonts that are needed by the associated libLASi (psttf),
pango/cairo (cairo), Qt (qt), and wxWidgets (wxwidgets) library
dependencies of these device drivers.  Note that unlike devices that use
the plfreetype approach (see *note The gd and wingcc device drivers::)
these devices require no user intervention to set up the correct mapping
between FCI and font, and complex text layout languages are rendered
correctly (assuming the associated library dependency of the device
driver does that).


File: plplotdoc.info,  Node: FCI,  Next: Escape sequences in text,  Prev: Unicode font system,  Up: Setting Character Attributes

3.8.3 FCI
---------

We specify the properties of unicode fonts with the FCI (font
characterization integer).  The FCI is a 32-bit unsigned integer whose
most significant hexadecimal digit is set (by ORing 0x80000000 with the
FCI value) to distinguish it from a unicode (UCS4) integer (whose
maximum value is 0x7fffffff).  Users obtain the current FCI by calling
‘plgfci’ (*note plgfci; Get FCI [font characterization integer]::) and
store a new FCI to be used at the start of each subsequent string using
‘plsfci’ (*note plsfci; Set FCI [font characterization integer]::).  The
FCI contains three independent hexadecimal values corresponding to font
family, font-style, and font weight.  These three values can also be
obtained and set in a user-friendly way using ‘plgfont’ (*note plgfont;
Get family; style and weight of the current font::) and ‘plsfont’ (*note
plsfont; Set family; style and weight of the current font::).  These
values are also characterized by "hexdigit" (defined as the actual
hexadecimal value used for one of the hexadecimal digits) and "hexpower"
(defined as the power of 16 or number of hexadecimal places to the left
of the "decimal place" in the FCI where the hexdigit is stored).  The
interpretation of the hexdigit and hexpower values in the FCI are given
in *note FCI interpretation::.

   *FCI interpretation*

           hexdigit   0          1          2          3          4
           –>
Font       hexpower
attribute
font-family0          sans-serif serif      monospace  script     symbol
font-style 1          upright    italic     oblique
font-weight2          medium     bold

   Note the maximum value of hexdigit is 7 and the maximum value of
hexpower is 6 so there is substantial room for expansion of this scheme.
On the other hand, since each font attribute is independent of the rest,
what is implemented now gives us a maximum of 30 different font
possibilities which is probably more than enough for most plotting
purposes.


File: plplotdoc.info,  Node: Escape sequences in text,  Next: Character size adjustment,  Prev: FCI,  Up: Setting Character Attributes

3.8.4 Escape sequences in text
------------------------------

The routines which draw text all allow you to include escape sequences
in the text to be plotted.  These are character sequences that are
interpreted as instructions to change fonts, draw superscripts and
subscripts, draw non-ASCII (e.g.  Greek), and so on.  All escape
sequences start with a number symbol (‘#’) by default.  Some language
interfaces have the capability of changing this default, but we will
assume (‘#’) in the remaining documentation of the escape sequences.

   The following escape sequences are defined:

   • ‘#u’: move up to the superscript position (ended with ‘#d’)

   • ‘#d’: move down to subscript position (ended with ‘#u’)

   • ‘#b’: backspace (to allow overprinting)

   • ‘##’: number symbol

   • ‘#+’: toggle overline mode

   • ‘#-’: toggle underline mode

   • ‘#gx’: Greek letter corresponding to Roman letter ‘x’ (see below)

   • ‘#fn’: switch to normal (sans-serif) font

   • ‘#fr’: switch to Roman (serif) font

   • ‘#fi’: switch to italic font

   • ‘#fs’: switch to script font

   • ‘#(nnn)’: Hershey character nnn (1 to 4 decimal digits)

   • ‘#[nnn]’: unicode character nnn (nnn can be decimal or hexadecimal
     [e.g., starting with 0x]) (UNICODE ONLY).

   • ‘#<0x8nnnnnnn>’: absolute FCI to be used to change fonts in
     mid-string.  (nnnnnnn must be exactly 7 digits).  (UNICODE ONLY).

   • ‘#<0xmn>’: change just one attribute of the FCI in mid-string where
     m is the hexdigit and n is the hexpower.  If more than two digits
     are given (so long as the eighth digit does not mark this as an
     absolute FCI, see above) they are ignored.  (UNICODE ONLY).

   • ‘#<FCI COMMAND STRING/>’: the FCI COMMAND STRING is currently one
     of "sans-serif", "serif", "monospace", "script", "symbol",
     "upright", "italic", "oblique" "medium", or "bold" (without the
     surrounding quotes).  These FCI COMMAND STRINGS change one
     attribute of the FCI according to their name.  (UNICODE ONLY).

   Sections of text can have an underline or overline appended.  For
example, the string S̅(f̲r̲e̲q̲) is obtained by specifying
‘"#+S#+(#-freq#-)"’.

   Greek letters are obtained by ‘#g’ followed by a Roman letter.  *note
Roman Characters Corresponding to Greek Characters:: shows how these
letters map into Greek characters.

   *Roman Characters Corresponding to Greek Characters*

Roman      A     B     G     D     E     Z     Y     H     I     K     L     M
Greek      Α     Β     Γ     Δ     Ε     Ζ     Η     Θ     Ι     Κ     Λ     Μ

Roman      N     C     O     P     R     S     T     U     F     X     Q     W
Greek      Ν     Ξ     Ο     Π     Ρ     Σ     Τ     Υ     Φ     Χ     Ψ     Ω

Roman      a     b     g     d     e     z     y     h     i     k     l     m
Greek      α     β     γ     δ     ε     ζ     η     θ     ι     κ     λ     μ

Roman      n     c     o     p     r     s     t     u     f     x     q     w
Greek      ν     ξ     ο     π     ρ     σ     τ     υ     φ     χ     ψ     ω

   The escape sequences ‘#fn’, ‘#fr’, ‘#fi’, ‘#fs’, and ‘#(nnn)’ are
designed for the four Hershey fonts, but an effort has been made to
allow some limited forward compatibility so these escape sequences have
a reasonable result when unicode fonts are being used.  However, for
maximum flexibility when using unicode fonts, these 5 Hershey escape
sequences should be replaced by using the 4 unicode escape sequences
‘#<0x8nnnnnnn>’, ‘#<0xmn>’, ‘#<FCI COMMAND STRING/>’, and ‘#[nnn]’ as
appropriate.

   It should be emphasized that the unicode escape sequences above only
work properly for modern unicode-aware devices such as the svg and
wxwidgets devices or the very large set of cairo and qt devices.  And
for those devices the alternative of directly specifying the unicode
symbols using UTF-8 encoding of PLplot input strings is much more
convenient for users than using the above ‘#[nnn]’ type of escape
sequence.  For example, we use UTF-8 strings rather than escape
sequences in our standard example 24
(http://plplot.sourceforge.net/examples.php?demo=24) to render the word
"Peace" in several different languages.

   *The word "peace" expressed in several different languages in example
24 using UTF-8*

Hebrew                                           שלום
French                                           Paix
Kurdish                                          Hasîtî
English                                          Peace
Korean                                           평화
Turkish                                          Barış
Hindi                                            शांति
German                                           Friede
Arabic                                           ﺳﻼم
Mandarin                                         和平
Russian                                          Мир
Spanish                                          Paz

   For unicode-aware devices it is possible as well to specify
mathematical glyphs (such as ∂, ∇, ∑, ∫, and ∰) using UTF-8 encoding of
PLplot input strings.  A typical input method in this case is simply to
cut and paste the desired mathematical glyph from, e.g., gucharmap to
source code being edited by a unicode-aware editor such as emacs.  Such
input methods may be conveniently used, for example, to specify the very
wide range of mathematical symbols that are typically desired for
scientific plots.


File: plplotdoc.info,  Node: Character size adjustment,  Prev: Escape sequences in text,  Up: Setting Character Attributes

3.8.5 Character size adjustment
-------------------------------

The routine ‘plschr’ (*note plschr; Set character size::) is used to set
up the size of subsequent characters drawn.  The actual height of a
character is the product of the default character size and a scaling
factor.  If no call is made to ‘plschr’ (*note plschr; Set character
size::), the default character size is set up depending on the number of
subpages defined in the call to ‘plstar’ (*note plstar;
Initialization::) or ‘plstart’ (*note plstart; Initialization::), and
the scale is set to 1.0.  Under normal circumstances, it is recommended
that the user does not alter the default height, but simply use the
scale parameter.  This can be done by calling ‘plschr’ (*note plschr;
Set character size::) with ‘def = 0.0’ and ‘scale’ set to the desired
multiple of the default height.  If the default height is to be changed,
‘def’ is set to the new default height in millimeters, and the new
character height is again set to ‘def’ multiplied by ‘scale’.

   The routine ‘plssym’ (*note plssym; Set symbol size::) sets up the
size of all subsequent characters drawn by calls to ‘plpoin’ (*note
plpoin; Plot a glyph at the specified points::) and ‘plsym’ (*note
plsym; Plot a glyph at the specified points::).  It operates analogously
to ‘plschr’ (*note plschr; Set character size::) as described above.


File: plplotdoc.info,  Node: Three-dimensional Plots,  Next: Legends and color bars,  Prev: Setting Character Attributes,  Up: Advanced Use of PLplot

3.9 Three-dimensional Plots
===========================

PLplot includes three-dimensional plot routines that plot functions of
the two independent variables ‘x’ and ‘y’ in a variety of ways (see
*note Surface Plots::, *note Contour Plots::, *note Shade plots::, *note
Image plots::, and *note Vector plots::).

* Menu:

* Surface Plots::
* Contour Plots::
* Shade plots::
* Image plots::
* Vector plots::


File: plplotdoc.info,  Node: Surface Plots,  Next: Contour Plots,  Up: Three-dimensional Plots

3.9.1 Surface Plots
-------------------

PLplot provides the routines ‘plmesh’ (*note plmesh; Plot surface
mesh::), ‘plmeshc’ (*note plmeshc; Magnitude colored plot surface mesh
with contour::), ‘plot3d’ (*note plot3d; Plot 3-d surface plot::),
‘plot3dc’ (*note plot3dc; Magnitude colored plot surface with
contour::), ‘plot3dcl’ (*note plot3dcl; Magnitude colored plot surface
with contour for z[x][y] with y index limits::), ‘plsurf3d’ (*note
plsurf3d; Plot shaded 3-d surface plot::), ‘plsurf3dl’ (*note plsurf3dl;
Plot shaded 3-d surface plot for z[x][y] with y index limits::) and
‘plfill3’ (*note plfill3; Draw filled polygon in 3D::) to plot the
projection of a 3D surface on an existing 2D window.  Our standard
examples 08 (http://plplot.sourceforge.net/examples.php?demo=08), 11
(http://plplot.sourceforge.net/examples.php?demo=11), 15
(http://plplot.sourceforge.net/examples.php?demo=15), 21
(http://plplot.sourceforge.net/examples.php?demo=21), and 28
(http://plplot.sourceforge.net/examples.php?demo=28) illustrate how
these routines are used.

   In all cases the transformations required to plot the projection of a
3D surface on a 2D window are configured by ‘plw3d’ (*note plw3d;
Configure the transformations required for projecting a 3D surface on a
2D window::) and are done to a rectangular cuboid enclosing the 3D
surface which has its limits expressed in 3D world coordinates and also
normalized 3D coordinates (used for interpreting the altitude and
azimuth of the viewing angle).  This representation of the
transformation process allows considerable flexibility in specifying how
the surface is depicted.  The lengths of the sides of the normalized
rectangular cuboid are independent of the 3D world coordinate ranges of
each of the variables, making it possible to use ‘reasonable’ viewing
angles even if the ranges of the 3D world coordinates on the axes are
very different.  The size of the normalized rectangular cuboid is
determined essentially by the size of the two-dimensional window into
which it is to be mapped.  The normalized cuboid is centered about its
origin in the ‘x’ and ‘y’ directions, but rests on the plane ‘z = 0’.
It is viewed by an observer located at altitude ‘alt’ and azimuth ‘az’,
where both angles are measured in degrees.  The altitude should be
restricted to the range zero to ninety degrees for proper operation, and
represents the viewing angle above the xy plane of the normalized
cuboid.  The azimuth is defined so that when ‘az = 0’, the observer sees
the xz plane face on, and as the angle is increased, the observer moves
clockwise around the normalized cuboid as viewed from above the xy
plane.  The azimuth can take on any value.  In the above list of
examples, we have chosen x and y world-coordinate ranges near (-1.0-1.0)
for the 2D window, and x, y, z sizes of the normalized cuboid near (1.,
1., 1.), and users will likely want to adopt similar values as well.


File: plplotdoc.info,  Node: Contour Plots,  Next: Shade plots,  Prev: Surface Plots,  Up: Three-dimensional Plots

3.9.2 Contour Plots
-------------------

PLplot provides the ‘plcont’ (*note plcont; Contour plot::) routine for
generating contour plots and our standard examples 08
(http://plplot.sourceforge.net/examples.php?demo=09), 14
(http://plplot.sourceforge.net/examples.php?demo=14), 16
(http://plplot.sourceforge.net/examples.php?demo=16), and 22
(http://plplot.sourceforge.net/examples.php?demo=22) illustrate how this
routine is used.  The contourer uses a contour-following algorithm so
that it is possible to use non-continuous line styles.  Further, one may
specify arbitrary coordinate mappings from array indices to world
coordinates, such as for contours in a polar coordinate system.

   The path of each contour is initially computed in terms of the values
of the indices of the matrix that holds the data to be contoured.
Before these can be drawn in the current window (see *note Defining the
Window::), it is necessary to convert from these array indices into
world coordinates.  This transformation is normally done by a callback
function which is supplied as an argument to ‘plcont’ (*note plcont;
Contour plot::).  For C use of ‘plcont’ (*note plcont; Contour plot::)
we have included directly in the PLplot library the following
transformation callback routines: ‘pltr0’ (*note pltr0; Identity
transformation for matrix index to world coordinate mapping::) (identity
transformation); ‘pltr1’ (*note pltr1; Linear interpolation for matrix
index to world coordinate mapping using singly dimensioned coordinate
arrays::) (linear interpolation in singly dimensioned coordinate
arrays); and ‘pltr2’ (*note pltr2; Linear interpolation for grid to
world mapping using doubly dimensioned coordinate arrays [row-major
order as per normal C 2d arrays]::) (linear interpolation in doubly
dimensioned coordinate arrays), but other callbacks can be used for the
C case instead.  The above list of examples illustrates how this
callback argument and associated transformation from index arguments to
world coordinates is implemented in each of our supported languages.


File: plplotdoc.info,  Node: Shade plots,  Next: Image plots,  Prev: Contour Plots,  Up: Three-dimensional Plots

3.9.3 Shade plots
-----------------

PLplot provides the ‘plshade’ (*note plshade; Shade individual region on
the basis of value::) and ‘plshades’ (*note plshades; Shade regions on
the basis of value::) routines for generating shade plots and our
standard examples 15
(http://plplot.sourceforge.net/examples.php?demo=15), 16
(http://plplot.sourceforge.net/examples.php?demo=16), 21
(http://plplot.sourceforge.net/examples.php?demo=21), and 22
(http://plplot.sourceforge.net/examples.php?demo=22) illustrate how
those routines are used including how the needed transformation from
index arguments to world coordinates is implemented in each of our
supported languages.


File: plplotdoc.info,  Node: Image plots,  Next: Vector plots,  Prev: Shade plots,  Up: Three-dimensional Plots

3.9.4 Image plots
-----------------

PLplot provides the ‘plimage’ (*note plimage; Plot a 2D matrix using
cmap1 with automatic color adjustment::) and ‘plimagefr’ (*note
plimagefr; Plot a 2D matrix using cmap1::) routines for generating
images plots and our standard example 20
(http://plplot.sourceforge.net/examples.php?demo=20) illustrates how
those routines are used including how the needed transformation from
index arguments to world coordinates is implemented in each of our
supported languages.


File: plplotdoc.info,  Node: Vector plots,  Prev: Image plots,  Up: Three-dimensional Plots

3.9.5 Vector plots
------------------

PLplot provides the ‘plvect’ (*note plvect; Vector plot::) routine for
generating vector plots and our standard example 22
(http://plplot.sourceforge.net/examples.php?demo=22) illustrates how
that routine is used including how the needed transformation from index
arguments to world coordinates is implemented in each of our supported
languages.  In addition that routine shows how to call ‘plsvect’ (*note
plsvect; Set arrow style for vector plots::) to set the arrow style for
vector plots.


File: plplotdoc.info,  Node: Legends and color bars,  Prev: Three-dimensional Plots,  Up: Advanced Use of PLplot

3.10 Legends and color bars
===========================

The ‘pllegend’ (*note pllegend; Plot legend using discretely annotated
filled boxes; lines; and/or lines of symbols::) and ‘plcolorbar’ (*note
plcolorbar; Plot color bar for image; shade or gradient plots::)
routines are available in PLplot to provide users with the capability of
visually annotating their plots with a legend (a series of patterned
boxes, lines, or symbols with associated explanatory UTF-8 text) or a
color bar (an annotated subplot representing a continuous range of
colors within the main plot and typically identifying certain colors
with certain numerical values using an axis).  ‘pllegend’ (*note
pllegend; Plot legend using discretely annotated filled boxes; lines;
and/or lines of symbols::) is useful for visually annotating most
two-dimensional plots.  See our standard examples 04
(http://plplot.sourceforge.net/examples.php?demo=04) and26
(http://plplot.sourceforge.net/examples.php?demo=26) for some examples.
‘plcolorbar’ (*note plcolorbar; Plot color bar for image; shade or
gradient plots::) is especially useful for annotating continuous shade
plots generated by ‘plshades’ (*note plshades; Shade regions on the
basis of value::).  See our standard example 16
(http://plplot.sourceforge.net/examples.php?demo=16), for an example.

   The ‘pllegend’ (*note pllegend; Plot legend using discretely
annotated filled boxes; lines; and/or lines of symbols::) and
‘plcolorbar’ (*note plcolorbar; Plot color bar for image; shade or
gradient plots::) routines provide the users complete and convenient
control of the size and position of the results on the plot and also
return size data that makes it straightforward to stack different legend
or colorbar results together on the plot (see our standard example 33
(http://plplot.sourceforge.net/examples.php?demo=33) for an example of
this capability).  Furthermore, the ‘pllegend’ (*note pllegend; Plot
legend using discretely annotated filled boxes; lines; and/or lines of
symbols::) and ‘plcolorbar’ (*note plcolorbar; Plot color bar for image;
shade or gradient plots::) routines provide the user with many different
style possibilities for the results.  Because of all these features,
‘pllegend’ (*note pllegend; Plot legend using discretely annotated
filled boxes; lines; and/or lines of symbols::) and ‘plcolorbar’ (*note
plcolorbar; Plot color bar for image; shade or gradient plots::) have an
extensive argument list.  So we recommend first-time users of ‘pllegend’
(*note pllegend; Plot legend using discretely annotated filled boxes;
lines; and/or lines of symbols::) and ‘plcolorbar’ (*note plcolorbar;
Plot color bar for image; shade or gradient plots::) use our standard
examples 04 (http://plplot.sourceforge.net/examples.php?demo=04), 16
(http://plplot.sourceforge.net/examples.php?demo=16), and 26
(http://plplot.sourceforge.net/examples.php?demo=26) as a tutorial on
how to use these PLplot capabilities in a simple way, and for more
advanced use we recommend studying the ‘pllegend’ (*note pllegend; Plot
legend using discretely annotated filled boxes; lines; and/or lines of
symbols::) and ‘plcolorbar’ (*note plcolorbar; Plot color bar for image;
shade or gradient plots::) documentation and also our standard example
33 (http://plplot.sourceforge.net/examples.php?demo=33) which attempts
to exercise most capabilities of these two PLplot functions.


File: plplotdoc.info,  Node: Deploying programs that use PLplot,  Next: Drivers which implement file devices,  Prev: Advanced Use of PLplot,  Up: Programming

4 Deploying programs that use PLplot
************************************

This chapter provides some information on the issue of delivering
programs that use PLplot: what files should be installed and where, what
environment variables are involved and related matters.

   The scenario is this: You have created one or more programs that run
successfully on your development machine and now you need to install
them on the machine of a user.

   One solution is to provide him or her with the full development
environment that you use, but that is in general only an option if your
user is comfortable with making programs themselves.  A more common
situation is that your user just wants the executable programs and wants
to get using them right away.  We will focus on this particular
solution, as there are a few non-trivial issues.

   To be absolutely clear about what we are describing, here is a
summary:

   • Your program must run on a machine that does not have PLplot
     installed from the sources.

   • There is no development environment that you can rely on.

   • The program should be installed in a self-contained directory
     structure (which _can_ be ‘/usr/local’ or ‘c:\program’ files or
     whatever, but need not be so).

   Under Linux, the easiest way to install a binary version of PLplot on
a user’s machine is to use PLplot deb binary packages for the Debian
(http://www.debian.org) distribution, and PLplot rpm binary packages for
rpm-based distributions.  (See the download area
(http://plplot.sourceforge.net/download.php) of the PLplot web site for
locations of debs and rpms.)  Build the application on the build machine
using the results of the ‘pkg-config --cflags --libs plplotd’ command,
and copy the resulting executable(s) to the users’ machines.

   Under Unix (and also under Linux if you would prefer to use a newer
version of PLplot than is available in the debs or rpms), a good way to
deploy binary PLplot and applications that depend on that binary PLplot
on users’ machines is as follows:

   • Use the ‘cmake’ option ‘-DCMAKE_INSTALL_PREFIX=/usr/local/plplot’
     (or some other unique but consistent directory that is available on
     the build machine and all users’ machines).

   • Build and install as normal on the build machine.

   • Copy the installed PLplot tree, ‘/usr/local/plplot’, into a
     tarball.

   • Unpack that tarball on all users’ machines in the same location
     ‘/usr/local/plplot’.

   • Build the application(s) on the build machine using either the make
     or cmake based build system in
     /usr/local/plplot/share/plplotX.Y.Z/examples where X.Y.Z is the
     plplot version, and copy the resulting executable(s) to the users’
     machines.  Since the PLplot install location is consistent on all
     machines, the application should work the same way on all machines.

   On Windows, and also those rare Linux/Unix cases where you cannot
install the PLplot install tree in a consistent location on users’
machines, then there are some additional options you need to consider.

   There are three situations depending on how you configure and build
the PLplot libraries:

  1. You use the static versions of the PLplot libraries and devices
     which are not dynamically loaded.  (1)

  2. You use the shared versions of the PLplot libraries and devices
     which are not dynamically loaded.

  3. You use the shared versions of the PLplot library and devices which
     are dynamically loaded.  This combination is the default option
     under Unix/Linux.

   In the _first_ case the program will contain all the code it needs to
work, but to run successfully, it needs to find the font files,
‘plstnd5.fnt’ and ‘plxtnd5.fnt’.  The mechanism used in PLplot to find
these files is fairly simple:

   • It looks at a number of built-in places, determined at the time the
     PLplot library itself was installed and built.  For deployment
     these places are irrelevant in general.

   • It looks at the environment variables ‘PLPLOT_LIB’ and
     ‘PLPLOT_HOME’.  (Actually, this happens only, if the corresponding
     compiler macros ‘PLPLOT_LIB_ENV’ and ‘PLPLOT_HOME_ENV’ were defined
     at compile time.)

   • _(TODO: remark about Mac)_

   Note: This is also the place to put the geographical map files, if
you happen to use them.

   The environment variables should point to the directory holding the
two font files or the one above (one variable is enough though):

   • ‘PLPLOT_LIB’ should point to the directory actually holding these
     files

   • ‘PLPLOT_HOME’ should point to the directory that holds a
     subdirectory ‘‘lib’’ which in turn holds these files.

   If it can find these, PLplot can do its job.

   Note: This is the case for instance when you use the static PLplot
library on Windows (see the directory ‘sys\win32\msdev\plplib’).

   In the _second _ case the font and map files are found as in the
_first_ case.  In addition, you also require another environment
variable so the PLplot shared libraries can be found at run time by the
run-time loader.  The details depend on the system you are working on,
but here are some common platforms:

   • Most UNIX, BSD and Linux systems use an environment variable
     ‘LD_LIBRARY_PATH’ which indicates directories where shared
     libraries can be found.  Some use ‘SHLIB_PATH’, like HPUX.

   • On Windows the PATH variable is used to find the DLLs, but beware:
     Windows uses a number of places to find the DLLs a program needs
     and the ordering seems to depend on some intricate details.  It
     seems easiest and safest to put the DLLs in the same directory as
     your program.

   • On MacOSX, ...  _TODO_

   In the _third_ (default) case, the PLplot fonts and maps are found as
in the _first_ case, and the shared libraries are found as in the
_second_ case, but in addition the separated dynamic devices have to be
found as well.

   When PLplot uses dynamic devices, it first builds up a list of them,
by examining a directory which contains files describing those devices:
the ‘*.driver_info’ files.  Each of these files indicates what the
relevant properties for the device or devices.  Then when the device is
actually needed, the corresponding shared object (or plug-in or DLL
depending on your terminology) is dynamically loaded.

   The directory that contains all these files (the device descriptions
as well as the actual libraries and the description files that libtool
uses) is a directory determined at the time you configured PLplot which
is typically something like
‘/usr/local/plplot/lib/plplot5.3.1/driversd’.  This directory must be
pointed to by the ‘PLPLOT_DRV_DIR’ environment variable.  Again for
deployment, only the environment variable is of real interest.

   To summarize the case where you don’t have a deb or rpm option, and
you must use inconsistent install locations on your users’ machines:

   • The following environment variables are important:

        • ‘PLPLOT_HOME’ or ‘PLPLOT_LIB’ to indicate the position of font
          files (and also of the various geographic maps)

        • ‘LD_LIBRARY_PATH’, ‘SHLIB_PATH’ or ‘PATH’ to find the
          dynamic/shared libraries

        • ‘PLPLOT_DRV_DIR’ to find the device descriptions

   • The following files being part of PLplot must be distributed along
     with your program:

        • The font files (‘plstnd5.fnt’ and ‘plxtnd5.fnt’) and,
          possibly, if you use them, the geographic map files.

        • The PLplot shared libraries

        • The device description files and the device shared object
          files

   All the environment variables, except ‘LD_LIBRARY_PATH’ and
equivalents, can be set within the program (by using a small
configuration file or by determining the position of the files relative
to the program’s location).  They just have be set before PLplot is
initialized.

   ---------- Footnotes ----------

   (1) UNIX-like systems libraries can be static or shared, the first
type becoming part of the program, the second existing as a separate
file.  On Windows the terms are respectively static and dynamic (the
latter type is also known as DLL).


File: plplotdoc.info,  Node: Drivers which implement file devices,  Next: Drivers which implement interactive devices,  Prev: Deploying programs that use PLplot,  Up: Programming

5 Drivers which implement file devices
**************************************

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 *note Command Line Arguments::.

* Menu:

* The qt driver::
* The cairo driver::
* The svg driver::
* The ps driver::
* The psttf driver::
* The pdf driver::
* The gd driver::
* The pstex driver::


File: plplotdoc.info,  Node: The qt driver,  Next: The cairo driver,  Up: Drivers which implement file devices

5.1 The qt driver
=================

The qt driver uses the the Qt library (https://www.qt.io/) (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
*note The cairo driver:: is the other) file device drivers.


File: plplotdoc.info,  Node: The cairo driver,  Next: The svg driver,  Prev: The qt driver,  Up: Drivers which implement file devices

5.2 The cairo driver
====================

The cairo driver uses the Pango/Cairo subset of the GTK+ suite of
libraries (https://www.gtk.org/) 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 *note The qt driver:: is the other) file device drivers.


File: plplotdoc.info,  Node: The svg driver,  Next: The ps driver,  Prev: The cairo driver,  Up: Drivers which implement file devices

5.3 The svg driver
==================

The svg driver produces SVG (Scalable Vector Graphics) files that are
compliant with the SVG 1.1 specification as defined here
(http://www.w3.org/Graphics/SVG/).  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.


File: plplotdoc.info,  Node: The ps driver,  Next: The psttf driver,  Prev: The svg driver,  Up: Drivers which implement file devices

5.4 The ps driver
=================

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.

   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 *note The psttf driver::).  For this reason, Hershey
fonts are used for drawing symbols by default for this device driver,
unless specified otherwise using the driver options.

   The available driver options are:

   • text: Use PostScript text (0|1); default 1

   • color: Use color (0|1); default 1

   • hrshsym: Use Hershey fonts for symbols (0|1); default 1


File: plplotdoc.info,  Node: The psttf driver,  Next: The pdf driver,  Prev: The ps driver,  Up: Drivers which implement file devices

5.5 The psttf driver
====================

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 *note The ps driver::).  The driver provides two
devices: the psttf device for black-and-white plots and the psttfc
device for color plots.

   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
http://plplot.sourceforge.net/examples.php?demo=24
(http://plplot.sourceforge.net/examples.php?demo=24) 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
<https://sourceforge.net/projects/lasi/files/lasi/>.  The library is
small and easy to build and install.

   The available driver options are:

   • text: Use TrueType fonts for text (0|1); default 1

   • color: Use color (0|1); default 1

   • hrshsym: Use Hershey fonts for symbols (0|1); default 0


File: plplotdoc.info,  Node: The pdf driver,  Next: The gd driver,  Prev: The psttf driver,  Up: Drivers which implement file devices

5.6 The pdf driver
==================

This basic PDF driver is based on the libharu library
(http://libharu.org/).  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.


File: plplotdoc.info,  Node: The gd driver,  Next: The pstex driver,  Prev: The pdf driver,  Up: Drivers which implement file devices

5.7 The gd driver
=================

N.B. This driver is disabled by default because it is not maintained and
because it depends on the deprecated plfreetype approach (see *note
Adding FreeType Library Support to Bitmap Drivers::) for rendering
unicode text (which implies font-selection issues and no support for
complex text layout).

   The gd driver uses the GD library (http://libgd.github.io/) to
produce plots in the PNG, JPEG, and GIF file formats.  Text is
anti-aliased, but lines and fills are not.

   The available driver options are:

   • optimize: Optimize PNG palette when possible

   • def_black15: Define idx 15 as black.  If the background is
     "whiteish" (from "-bg" option), force index 15 (traditionally
     white) to be "black"

   • swp_red15: Swap index 1 (usually red) and 1 (usually white); always
     done after "black15"; quite useful for quick changes to web pages

   • 8bit: Palette (8 bit) mode

   • 24bit: Truecolor (24 bit) mode

   • text: Use driver text (FreeType)

   • smooth: Turn text smoothing on (1) or off (0)


File: plplotdoc.info,  Node: The pstex driver,  Prev: The gd driver,  Up: Drivers which implement file devices

5.8 The pstex driver
====================

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.

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

     \documentclass{article}
           \usepackage[dvips]{graphicx}
           \begin{document}
           \input{x01c.eps_t}
           \end{document}


   and generate PostScript results using the LaTeX fonts with the
following command: ‘latex x01c.tex; dvips -f <x01c.dvi >x01c.ps ’.  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.

   There are no available driver options.


File: plplotdoc.info,  Node: Drivers which implement interactive devices,  Prev: Drivers which implement file devices,  Up: Programming

6 Drivers which implement interactive devices
*********************************************

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 *note Command Line Arguments::.

* Menu:

* The qt driver: The qt driver <1>.
* The cairo driver: The cairo driver <1>.
* The xwin driver::
* The tk driver::
* The aqt driver::
* The wxwidgets driver::


File: plplotdoc.info,  Node: The qt driver <1>,  Next: The cairo driver <1>,  Up: Drivers which implement interactive devices

6.1 The qt driver
=================

The qt driver uses the the Qt library (https://www.qt.io/) (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 *note The cairo driver: The cairo driver <1>.) 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 *note The 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.


File: plplotdoc.info,  Node: The cairo driver <1>,  Next: The xwin driver,  Prev: The qt driver <1>,  Up: Drivers which implement interactive devices

6.2 The cairo driver
====================

The cairo driver uses the Pango/Cairo subset of the GTK+ suite of
libraries (https://www.gtk.org/) 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 *note The qt driver: The qt driver <1>.)
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 *note The 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.


File: plplotdoc.info,  Node: The xwin driver,  Next: The tk driver,  Prev: The cairo driver <1>,  Up: Drivers which implement interactive devices

6.3 The xwin driver
===================

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.

   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.

   The available driver options are:

   • sync: Synchronized X server operation (0|1)

   • nobuffered: Sets unbuffered operation (0|1)

   • noinitcolors: Sets cmap0 allocation (0|1)

   • defvis: Use the Default Visual (0|1)

   • usepth: Use pthreads (0|1)


File: plplotdoc.info,  Node: The tk driver,  Next: The aqt driver,  Prev: The xwin driver,  Up: Drivers which implement interactive devices

6.4 The tk driver
=================

The tk driver combines the xwin driver (see *note The 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.


File: plplotdoc.info,  Node: The aqt driver,  Next: The wxwidgets driver,  Prev: The tk driver,  Up: Drivers which implement interactive devices

6.5 The aqt driver
==================

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.

   There are no options...


File: plplotdoc.info,  Node: The wxwidgets driver,  Prev: The aqt driver,  Up: Drivers which implement interactive devices

6.6 The wxwidgets driver
========================

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.

* Menu:

* wxWidgets Driver Basics::


File: plplotdoc.info,  Node: wxWidgets Driver Basics,  Up: The wxwidgets driver

6.6.1 wxWidgets Driver Basics
-----------------------------

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.

   The available driver options (used with the ‘-drvopt’ command-line
argument) are:

   • text: Use TrueType fonts (0|1); default 1

   • smooth: switch on/off anti-aliasing (0|1); default 1

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

   The smooth option will turn on or off text smoothing for True Type
fonts.  This will increase the time for a plot considerably.


File: plplotdoc.info,  Node: Supported computer languages,  Next: Reference,  Prev: Programming,  Up: Top

Supported computer languages
****************************

* Menu:

* C Language::
* Ada Language::
* A C++ Interface for PLplot::
* Fortran Language::
* OCaml Language::
* Using PLplot from Perl::
* Using PLplot from Python::
* Using PLplot from Tcl::
* Building an Extended WISH::
* Embedding Plots in Graphical User Interfaces::


File: plplotdoc.info,  Node: C Language,  Next: Ada Language,  Up: Supported computer languages

7 C Language
************

The C computer language is fundamental to PLplot because our core
plotting library and our definitive set of standard examples are written
in that language, and the remainder of the computer languages that we
support are implemented as bindings for our core C library.  The C
standard we use is C99
(http://www.open-std.org/jtc1/sc22/wg14/www/docs/n897.pdf), and our
experience is that all C compilers accessible to our users support that
standard sufficiently to have no trouble building PLplot.

   *Argument Types for our C API*

   • *Argument types for input scalars*

        • Floating-point type (where the C macro PL_DOUBLE is #defined
          if the CMake variable PL_DOUBLE is set to ON [which occurs by
          default])


               #if defined ( PL_DOUBLE )
               typedef double PLFLT;
               #else
               typedef float PLFLT;
               #endif


        • Integer type


               typedef int32_t PLINT;


        • Boolean type


               typedef PLINT PLBOOL;


        • 32-bit type that contains either UCS4-encoded unicode or FCI
          (font characterization integer) data


               typedef uint32_t PLUNICODE;


   • *Argument types for input/output scalars*

        • Input/output PLFLT scalar


               typedef PLFLT * PLFLT_NC_SCALAR;


        • Input/output PLINT scalar


               typedef PLINT * PLINT_NC_SCALAR;


        • Input/output PLBOOL scalar


               typedef PLBOOL * PLBOOL_NC_SCALAR;


        • Input/output PLUNICODE scalar


               typedef PLUNICODE * PLUNICODE_NC_SCALAR;


        • Input/output char scalar


               typedef char * PLCHAR_NC_SCALAR;


   • *Argument types for input vectors*

        • Input PLFLT vector


               typedef const PLFLT * PLFLT_VECTOR;


        • Input PLINT vector


               typedef const PLINT * PLINT_VECTOR;


        • Input PLBOOL vector


               typedef const PLBOOL * PLBOOL_VECTOR;


        • Input character string


               typedef const char * PLCHAR_VECTOR;


          This string is NULL-terminated in C.

   • *Argument types for input/output vectors*

        • Input/output PLFLT vector


               typedef PLFLT * PLFLT_NC_VECTOR;


        • Input/output character string


               typedef char * PLCHAR_NC_VECTOR;


          This string is NULL-terminated in C.

   • 
     *Argument types for input 2D matrices*

        • Input PLFLT 2D matrix


               typedef const PLFLT * const * PLFLT_MATRIX;


        • Input vector of character strings


               typedef const char * const * PLCHAR_MATRIX;


          These strings are NULL-terminated in C.

     Note that for the C language case the above definitions allow input
     matrices to be organized either in the traditional row-major
     (https://en.wikipedia.org/wiki/Row-major_order) order or as an
     Iliffe column vector (https://en.wikipedia.org/wiki/Iliffe_vector)
     of pointers to row vectors.

   • 
     *Argument types for input/output 2D matrices*

        • Input/output PLFLT 2D matrix


               typedef PLFLT ** PLFLT_NC_MATRIX;


        • Input/output vector of character strings


               typedef char ** PLCHAR_NC_MATRIX;


          These strings are NULL-terminated in C.

     Note that for the C language case the above definitions allow
     input/output matrices to be organized either in the traditional
     row-major (https://en.wikipedia.org/wiki/Row-major_order) order or
     as an Iliffe column vector
     (https://en.wikipedia.org/wiki/Iliffe_vector) of pointers to row
     vectors.

   • *Argument type for a generic pointer*

        • Input/output generic pointer


               typedef void * PLPointer;


   • *Argument types for callback functions*

        • Map transformation callback type


               typedef void ( *PLMAPFORM_callback )( PLINT n, PLFLT_NC_VECTOR x, PLFLT_NC_VECTOR y );


          where the callback arguments are the following:

          ‘n’ (‘PLINT’, input)
               Number of elements in the ‘x’ and ‘y’ vectors.

          ‘x’ (‘PLFLT_NC_VECTOR’, input/output)
               Vector of ‘x’ coordinates of points to be transformed.

          ‘y’ (‘PLFLT_NC_VECTOR’, input/output)
               Vector of ‘y’ coordinates of points to be transformed.

        • Coordinate transformation callback type


               typedef void ( *PLTRANSFORM_callback )( PLFLT x, PLFLT y, PLFLT_NC_SCALAR tx, PLFLT_NC_SCALAR ty, PLPointer data);


          where the callback arguments are the following:

          ‘x’ (‘PLFLT’, input)
               ‘x’-position to be transformed.

          ‘y’ (‘PLFLT’, input)
               ‘y’-position to be transformed.

          ‘tx’ (‘PLFLT_NC_SCALAR’, output)
               Transformed ‘x’-position.

          ‘ty’ (‘PLFLT_NC_SCALAR’, output)
               Transformed ‘y’-position.

          ‘data’ (‘PLPointer’, input)
               Generic pointer to additional input data that may be
               required by the callback routine in order to implement
               the transformation.

        • Custom label callback type


               typedef void ( *PLLABEL_FUNC_callback )( PLINT axis, PLFLT value, PLCHAR_NC_VECTOR label, PLINT length, PLPointer data);


          where the callback arguments are the following:

          ‘axis’ (‘PLINT’, input)
               An integer whose value is ‘PL_X_AXIS = 1’ if an ‘x’-axis
               label is being generated and ‘PL_Y_AXIS = 2’ if a
               ‘y’-axis label is being generated.

          ‘value’ (‘PLFLT’, input)
               Floating-point numerical value to be used to help
               generate the label.

          ‘label’ (‘PLCHAR_NC_VECTOR’, output)
               A pointer to a memory area suitable for containing the
               output NULL-terminated character string of maximum length
               (including the NULL-terminating byte) of ‘length’.

          ‘length’ (‘PLINT’, input)
               The maximum possible length (including NULL-terminating
               byte) of the output NULL-terminated character string.

          ‘data’ (‘PLPointer’, input)
               Generic pointer to additional input data that may be
               required by the callback routine in order to generate a
               label.

        • Two-dimensional function array lookup callback type


               typedef PLFLT ( *PLF2EVAL_callback )( PLINT ix, PLINT iy, PLPointer data);


          where the callback function returns the looked-up value, and
          the callback arguments are the following:

          ‘ix’ (‘PLINT’, input)
               The ‘x’ index of the function array lookup.

          ‘iy’ (‘PLINT’, input)
               The ‘y’ index of the function array lookup.

          ‘data’ (‘PLPointer’, input)
               Generic pointer to the two-dimensional function input
               data that are required by the callback routine.  Since
               this is a generic pointer, these two-dimensional data can
               be arranged in any way that is desired by the user.

        • Fill callback type


               typedef void ( *PLFILL_callback )( PLINT n, PLFLT_VECTOR x, PLFLT_VECTOR y );


          where the callback arguments are the following:

          ‘n’ (‘PLINT’, input)
               Number of vertices in polygon to be filled.

          ‘x’ (‘PLFLT_VECTOR’, input)
               Vector of ‘x’-coordinates of vertices.

          ‘y’ (‘PLFLT_VECTOR’, input)
               Vector of ‘y’-coordinates of vertices.

        • Defined callback type


               typedef PLINT ( *PLDEFINED_callback )( PLFLT x, PLFLT y );

          where the callback function returns a 1 or 0 depending on
          whether the ‘x’ and ‘y’ arguments are within specified defined
          area, and the callback arguments are the following:

          ‘x’ (‘PLFLT’, input)
               ‘x’-coordinate to be tested for whether it is in the
               defined region.

          ‘y’ (‘PLFLT’, input)
               ‘y’-coordinate to be tested for whether it is in the
               defined region.

   • *Arguments of miscellaneous types*

        • A struct containing output mouse/keyboard event data


               typedef struct
               {
                   int          type;              // of event (CURRENTLY UNUSED)
                   unsigned int state;             // key or button mask
                   unsigned int keysym;            // key selected
                   unsigned int button;            // mouse button selected
                   PLINT        subwindow;         // subwindow (alias subpage, alias subplot) number
                   char         string[PL_MAXKEY]; // translated string
                   int          pX, pY;            // absolute device coordinates of pointer
                   PLFLT        dX, dY;            // relative device coordinates of pointer
                   PLFLT        wX, wY;            // world coordinates of pointer
               } PLGraphicsIn;


        • Input/output pointer to a struct that holds pointers to
          functions that are used to get, set, modify, and test
          individual 2-D data points referenced by a PLPointer or
          PLPointer


               typedef struct
               {
                   PLFLT ( *get )( PLPointer p, PLINT ix, PLINT iy );
                   PLFLT ( *set )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
                   PLFLT ( *add )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
                   PLFLT ( *sub )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
                   PLFLT ( *mul )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
                   PLFLT ( *div )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
                   PLINT ( *is_nan )( PLPointer p, PLINT ix, PLINT iy );
                   void ( *minmax )( PLPointer p, PLINT nx, PLINT ny, PLFLT_NC_SCALAR zmin, PLFLT_NC_SCALAR zmax );
                   //
                   // f2eval is backwards compatible signature for "f2eval" functions that
                   // existed before plf2ops "operator function families" were used.
                   //
                   PLFLT ( *f2eval )( PLINT ix, PLINT iy, PLPointer p );
               } plf2ops_t;

               typedef plf2ops_t * PLF2OPS;


        • Input/output pointer to first element of contiguous PLFLT
          array


               typedef PLFLT * PLFLT_FE_POINTER;


          Note the array must correspond to a contiguous block of memory
          but may be organized with arbitrary dimensions that conform to
          that block of memory.

   For more information on calling PLplot from C, please consult the
example C programs in ‘examples/c’ that are distributed with PLplot.
For more information on building your own PLplot-related C routines,
please consult either the traditional (Makefile + pkg-config) or
CMake-based build systems that are created as part of the install step
for our C (and other language) examples.


File: plplotdoc.info,  Node: Ada Language,  Next: A C++ Interface for PLplot,  Prev: C Language,  Up: Supported computer languages

8 Ada Language
**************

This document describes the Ada bindings to the PLplot technical
plotting software, how to obtain the necessary software components, and
how to use them together.

* Menu:

* Overview::
* The Bindings::
* The Examples::
* Obtaining the Software::
* How to use the Ada bindings::
* Unique Features of the Ada bindings::
* Parts That Retain a C Flavor::
* Known Variances::
* Compilation notes::
* Notes for Apple Macintosh OS X users::


File: plplotdoc.info,  Node: Overview,  Next: The Bindings,  Up: Ada Language

8.1 Overview
============

The Ada bindings for PLplot provide a way for Ada programmers to access
the powerful PLplot technical plotting facilities directly from Ada
programs while working completely in Ada; the Ada programmer never needs
to know or worry that PLplot itself is written in another language.

   There are a thin binding and two thick bindings provided.  The thin
binding presents the application programming interface (API) in a form
very similar to the C API, although in 100% Ada.  The thick bindings
present the API in a form to which Ada programmers will be more
accustomed and add some ease-of-use features.  It is expected that the
thick bindings will be preferred.


File: plplotdoc.info,  Node: The Bindings,  Next: The Examples,  Prev: Overview,  Up: Ada Language

8.2 The Bindings
================

The bindings are a re-expression and extension of the C-language API and
as such are a kind of abstract layer between the user’s code and the
PLplot binary library.  Additionally, there are a few capabilities not
in the official API but nonetheless which are available to the C
programmer which are included in the bindings and thus are directly
available to the Ada programmer.

   The thin binding is a layer between the thick bindings and the
underlying C code.  It is mainly a programming convenience for the
developer of the bindings; this is a common implementation for foreign
language bindings and for the most part, the user can ignore it.

   There are two thick bindings provided for the convenience of the
user.  Either may be used and they both provide exactly the same
functionality.  The thick bindings are the user’s main concern with
programming for PLplot.

* Menu:

* Thin Binding::
* The Thick Bindings::
* Standard Thick Binding Using Enhanced Names::
* Thick Binding Using Traditional Names::


File: plplotdoc.info,  Node: Thin Binding,  Next: The Thick Bindings,  Up: The Bindings

8.2.1 Thin Binding
------------------

The thin binding, in the files ‘plplotthin.ads’ and ‘plplotthin.adb’, is
mostly a direct and obvious mapping of the C application programming
interface (API) to Ada.  Thus, for example, where a C program such as
‘plcol0’ requires a single integer argument, there is a corresponding
Ada program also called ‘plcol0’ which also requires a single integer
argument.  (‘plcol0’ happens to set the drawing color using a number
which is associated with a set of colors.)  Various constants from the C
API are also included here.  Numeric types as defined in PLplot are
associated with numeric types in Ada in the thin binding by use of Ada’s
type system.  Thus, the thin binding refers to the PLplot-centric type
‘PLFLT’ for floating-point types while the thick binding uses the usual
Ada type ‘Long_Float’.

   Many of the comments from the C source header file (similar in
purpose to an Ada specification file) have been retained in the thin
binding, even when they are no longer make sense.  These might be pruned
at some point to facilitate reading the Ada source.

   Also included in the thin binding are some other declarations which
help the Ada binding to mesh well with C by emulating certain data
structures which are needed in some rather specialized usages as well as
providing certain subprogram pointer types.

   The Ada programmer working with either of the thick bindings will
have to refer to the thin binding relatively rarely, if ever, and mainly
to examine the subroutine pointer declarations and the several variant
record types which are used mostly for contour and three-dimensional
plots.  However, some of these have been ‘subtype’-ed or ‘renames’-ed in
the thick bindings so even less reference to the thin binding will be
necessary.  The goal is to put everything of interest to the user in the
thick bindings and the user need not bother with the thin binding.


File: plplotdoc.info,  Node: The Thick Bindings,  Next: Standard Thick Binding Using Enhanced Names,  Prev: Thin Binding,  Up: The Bindings

8.2.2 The Thick Bindings
------------------------

The thick bindings provide most of the information that the Ada
programmer needs.  Normally, only one of the two thick bindings would be
used per user program but it should be possible to include both but that
scenario would be unusual.

   There are three main aspects of the thick bindings: providing an
alternative access to the PLplot API, extending the PLplot functionality
with some easy-to-use features, and overlaying Ada data structures and
types.

   In the first aspect, the thick bindings provide a fully Ada interface
to the entire PLplot library.  Packages are ‘with’-ed and ‘use’-d as
normal Ada code.  Ada arrays can be passed as usual, not requiring the
array length or start or end indices to be passed separately.  All
necessary Ada types are made to match the underlying C types exactly.

   The second aspect of the thick bindings is to provide some simplified
ways to get a lot of plotting done with only one or two subroutine
calls.  For example, a single call to Simple_Plot can display from one
to five "_y_’s" as a function of a single "_x_" with default plot
appearances chosen to suit many situations.  Other simple plotters are
available for three-dimensional and contour plots.  Manipulating
PLplot’s colors is similarly made easy and some default color schemes
are provided.

   The third main aspect of the thick binding is to use Ada data
structures and Ada’s type system extensively to reduce the chances of
inappropriate actions.  For example, Ada arrays are used throughout (as
opposed to C’s
pointer-plus-offset-while-carrying-along-the-size-separately approach).
Quantities which have natural range limits are ‘subtype’-d to reflect
those constraints.  The hope is that program errors will result in
more-familiar Ada compilation or run-time errors rather than error
reports from the PLplot library or no reports at all.  However, there
remain a few instances where the typing could be improved and PLplot
errors will still be reported from time to time.

   Both the specification and body for the standard thick (and thin)
binding contain the C subroutine name as a comment line immediately
above the Ada procedure declaration; this should help in making the
associations between "Ada" names and "PLplot" names.  Also, the
subroutine-specific comments from the C API have been retained verbatim.


File: plplotdoc.info,  Node: Standard Thick Binding Using Enhanced Names,  Next: Thick Binding Using Traditional Names,  Prev: The Thick Bindings,  Up: The Bindings

8.2.3 Standard Thick Binding Using Enhanced Names
-------------------------------------------------

The distinguishing feature of this thick binding (the "standard"
binding) is to provide more descriptive names for PLplot subroutines,
variables, constants, arguments, and other objects.  Most Ada
programmers will be more comfortable using these names.  For example, in
the C API as well as the thin Ada binding and the other thick Ada
binding, the procedure ‘plcol0(1)’ sets the drawing color to red.  In
the standard thick binding, the same thing is accomplished by writing
‘Set_Pen_Color(Red)’.  The Ada program may just as well write
‘Set_Pen_Color(1)’ since the binding merely sets a constant ‘Red’ to be
equal to the integer ‘1’.  Many such numeric constants from the C API
are given names in this thick binding.  These renamed integers are
discussed more fully in Section 7.2.

   The disadvantage of this renaming is that it makes referring to the
PLplot documentation somewhat awkward.  There might be, at some time, a
utility for easing this problem by providing an HTML file with links so
that a "normal" PLplot name can be linked to the "Ada" name along with
the appropriate entry in the Ada specification, as well as another HTML
file with links from the "Ada" name directly to the PLplot web page that
documents that name.  It might also be possible to provide an alternate
version of the documentation with the enhanced names used.  (The
developer of the bindings has a sed file prepared which makes most of
the subroutine-name substitutions.)  However, this thick binding retains
the original C subprogram names as comments immediately above the
function or procedure name in the code listing so it is relatively easy
to locate the relevant item in the PLplot documentation.

   One simple rule applies in reading the PLplot API documentation: the
argument names are in the same order in Ada as in the PLplot
documentation (the names are different) except that all array lengths
are eliminated.  The PLplot documentation, for each subroutine, shows a
"redacted" version which should be correct for Ada as well as other
languages which have proper arrays.

   The standard bindings are in the Ada files ‘plplot.ads’ and
‘plplot.adb’.


File: plplotdoc.info,  Node: Thick Binding Using Traditional Names,  Prev: Standard Thick Binding Using Enhanced Names,  Up: The Bindings

8.2.4 Thick Binding Using Traditional Names
-------------------------------------------

This thick binding provides exactly the same functionality as the
standard thick binding but retains the original names as used in the C
code and the PLplot documentation.

   The traditional bindings are in the Ada files
‘plplot_traditional.ads’ and ‘plplot_traditional.adb’.


File: plplotdoc.info,  Node: The Examples,  Next: Obtaining the Software,  Prev: The Bindings,  Up: Ada Language

8.3 The Examples
================

An important part of the Ada bindings is the examples, some 33 of which
demonstrate how to use many of the features of the PLplot package.
These examples also serve as a test bed for the bindings in Ada and
other languages by checking the Postscript files that are generated by
each example against those generated by the C versions.  These examples
have been completely re-written in Ada (but retain a C flavor in the
names that are given to objects).  All of the Ada examples generate
exactly the same Postscript as the C versions, Examples 14 and 17
excepted since those operate interactively and don’t (normally) make
Postscript.  Two versions of each example are available, one calling the
standard binding and the other the traditional binding.  (In
development, a sed script does almost all of the conversion
automatically.)


File: plplotdoc.info,  Node: Obtaining the Software,  Next: How to use the Ada bindings,  Prev: The Examples,  Up: Ada Language

8.4 Obtaining the Software
==========================

There are three software components that you will need: an Ada compiler,
the PLplot library, and the Ada bindings.

* Menu:

* Obtaining an Ada compiler::
* Download and install PLplot::
* The Ada bindings to PLplot::


File: plplotdoc.info,  Node: Obtaining an Ada compiler,  Next: Download and install PLplot,  Up: Obtaining the Software

8.4.1 Obtaining an Ada compiler
-------------------------------

You will need an Ada compiler in order to use the Ada PLplot bindings.
There are several compilers available.  Here, we will focus on the free,
open source compiler that is included with the GNU Compiler Collection,
(gcc) which is at the center of much of the open source software
movement.  The gcc Ada compiler is known as GNAT, for GNU NYU Ada
Translator, where NYU stands for New York University.  (Although GNAT
was originally developed at NYU, it has for many years been developed
and supported commercially by AdaCore with academic and pro versions
available.)

   Your computer may already have GNAT installed, or you can download it
from gcc.gnu.org (http://gcc.gnu.org/).  Another route to obtaining GNAT
is from the AdaCore page, libre2.adacore.com
(https://libre2.adacore.com/).  There are versions for many operating
systems and processors including Apple’s OS X or its open source version
Darwin, Linux, and Windows.  The gcc and AdaCore versions differ in
their licenses.  Download the version that you need and follow the
installation instructions.


File: plplotdoc.info,  Node: Download and install PLplot,  Next: The Ada bindings to PLplot,  Prev: Obtaining an Ada compiler,  Up: Obtaining the Software

8.4.2 Download and install PLplot
---------------------------------

PLplot can be downloaded from the PLplot project page at sourceforge.net
(http://sourceforge.net/projects/plplot).  Follow the installation
instructions after downloading.  The installation process requires that
your computer has CMake installed.  OS X users can try installing PLplot
in its entirety from MacPorts.  The advantage of using MacPorts is that
all installation dependencies are automatically installed for you.


File: plplotdoc.info,  Node: The Ada bindings to PLplot,  Prev: Download and install PLplot,  Up: Obtaining the Software

8.4.3 The Ada bindings to PLplot
--------------------------------

The third major software component is the bindings themselves; they are
included with the PLplot software itself.

   The bindings themselves are six Ada source files named (using GNAT
filename extensions) ‘plplot.ads’, ‘plplot.adb’,
‘plplot_traditional.ads’, ‘plplot_traditional.adb’, ‘plplothin.ads’, and
‘plplotthin.adb’.  There are two additional files,
‘plplot_auxiliary.ads’ and ‘plplot_auxiliary.adb’ which will be
discussed later, in Section 9.


File: plplotdoc.info,  Node: How to use the Ada bindings,  Next: Unique Features of the Ada bindings,  Prev: Obtaining the Software,  Up: Ada Language

8.5 How to use the Ada bindings
===============================

* Menu:

* Ada 95 versus Ada 2005::
* GNAT versus non-GNAT::
* Sample command line project::


File: plplotdoc.info,  Node: Ada 95 versus Ada 2005,  Next: GNAT versus non-GNAT,  Up: How to use the Ada bindings

8.5.1 Ada 95 versus Ada 2005
----------------------------

The bindings will work for either Ada 95 or Ada 2005 but there is a
slightly subtle point regarding the use and declaration of vectors and
matrices.  The package ‘PLplot_Auxiliary’ declares the types


         type Real_Vector is array (Integer range <>) of Long_Float;
         type Real_Matrix is array (Integer range <>, Integer range <>) of Long_Float;

   These declarations mimic exactly the declarations described in Annex
G.3, Vector and Matrix Manipulation, of the Ada 2005 reference manual
when the generic package therein described is specialized for
‘Long_Float’.  The reason for this approach is to avoid requiring the
user program to ‘with’ ‘Ada.Numerics.Long_Real_Arrays’ simply to gain
access to these types and in the process require linking to the BLAS and
LAPACK numerical libraries.

   Ada 2005 introduced an annex G.3 which formally defines vector and
matrix support to Ada, along with some common mathematical operations on
those types.  (This feature is a specific to vectors and matrices and
extends the usual array apparatus.)  The Ada PLplot user has a choice on
how to deal with this.  The default, as described in
‘PLplot_Auxiliary.ads’, has ‘Real_Vector’ and ‘Real_Matrix’ declared
therein, separate from the Ada 2005 declarations.  This allows the
widest compatibility and does not require an Ada 2005 compiler.
However, many users will want to gain the benefit of the built-in
declarations of Ada 2005.  This is easily done: Read the short comments
in ‘PLplot_Auxiliary.ads’ on how to comment-out two lines and uncomment
three lines.  Either configuration will compile correctly, but depending
on the Cmake configuration to expose an Ada 2005 compiler in the later
case.  (Note that at some points in the documentation, Ada 2005 is
referred to as Ada 2007, including some Cmake flags.)

   This policy was changed in SVN version 11153.  Before this, the type
of compiler (Ada 95 or Ada 2005) had to be specified at the time that
PLplot was built, and in the case of Ada 2005, the BLAS and LAPACK
libraries had to be present and were subsequently linked.


File: plplotdoc.info,  Node: GNAT versus non-GNAT,  Next: Sample command line project,  Prev: Ada 95 versus Ada 2005,  Up: How to use the Ada bindings

8.5.2 GNAT versus non-GNAT
--------------------------

The bindings were made using the GNAT compiler and there is a slight
dependence on that compiler.  Specifically, the ‘Unrestricted_Access’
attribute of GNAT was used in making the function ‘Matrix_To_Pointers’
in ‘plplotthin.adb’ and in a few callbacks.  ‘Matrix_To_Pointers’ is
called whenever an Ada matrix (2D array) is passed to a PLplot
subroutine.  For more about ‘Unrestricted_Access attribute’, see
Implementation Defined Attributes in the GNAT Reference Manual.  This
dependency shouldn’t be difficult to remove by either incorporating the
GNAT code which implements it, by following the TO-DO comment near the
function definition in ‘plplotthin.adb’, or by providing the proper
aliasing.

   Another GNAT dependency is used to parse command line arguments in a
C-like way.

   Pragma Warnings (Off, "some text") and Pragma Warnings (On, "some
text") are used in the bindings to suppress warnings about a particular
method used to interface with C code.  These pragmas are also used in
Ada Examples 21 to suppress a particular warning.  Pragma Warnings is a
GNAT extension.  Non-GNAT usage could simply remove these pragmas with
the resulting warnings ignored as they are benign.

   Most of the GNAT dependencies can be found by searching the source
code for "‘GNAT’", "‘Unrestricted_Access’ and ‘Pragma Warnings’."

   The GNAT dependence, though slight, will no doubt frustrate users of
other Ada compilers.  We welcome comments from those users, especially
comments with specific suggestions on how to remove any GNAT-specific
usages.


File: plplotdoc.info,  Node: Sample command line project,  Prev: GNAT versus non-GNAT,  Up: How to use the Ada bindings

8.5.3 Sample command line project
---------------------------------

It is instructive to present a simple example that can be compiled and
run from the command line.  Although this example is specific to one
installation, it should be fairly straightforward to adapt it to another
installation.  Toward that end, it is helpful to understand the PLplot
lingo of "build directory" and "installation directory."

   Here is a simple program that will generate a plot of part of a
parabola.


      with
         PLplot_Auxiliary,
         PLplot;
      use
         PLplot_Auxiliary,
         PLplot;
      procedure Simple_Example is
         x, y : Real_Vector(-10 .. 10);
      begin
         for i in x'range loop
            x(i) := Long_Float(i);
            y(i) := x(i)**2;
         end loop;
         Initialize_PLplot; -- Call this only once.
         Simple_Plot(x, y); -- Make the plot.
         End_PLplot;        -- Call this only once.
      end Simple_Example;


   Next is a bash script that will compile, bind, and link it.  It is
installation-specific in that paths to the GNAT compiler, PLplot
libraries, and BLAS (Basic Linear Algebra System) and LAPACK (Linear
Algebra Package) are hard-coded.  You will have to adjust the paths to
fit your installation.  Some Linux installations which have GNAT 4.3 or
later (Ada 2005) preinstalled might have already set the paths to the
BLAS and LAPACK libraries.

   (Note that the G.3 Annex of Ada 2005, in the GNAT version, depends
heavily on BLAS and LAPACK. These packages are tried-and-true packages
that are available from several places in either C or Fortran versions.
The present example is specific to OS X which has both C and Fortran
versions preinstalled.)


      #!/bin/bash
      /usr/local/ada-4.3/bin/gnatmake simple_example.adb \
      -aI/usr/local/plplot_build_dir/bindings/ada \
      -aL/usr/local/plplot_build_dir/bindings/ada/CMakeFiles/plplotadad.dir \
      -largs \
      /usr/local/plplot/lib/libplplotd.dylib \
      /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/libblas.dylib \
      /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/liblapack.dylib


   The resulting binary program can be run by typing ‘./simple_example’


File: plplotdoc.info,  Node: Unique Features of the Ada bindings,  Next: Parts That Retain a C Flavor,  Prev: How to use the Ada bindings,  Up: Ada Language

8.6 Unique Features of the Ada bindings
=======================================

The Ada bindings have been augmented with a number of features which are
intended to simplify the use of PLplot.  They include high-level
features for simplified plotting (such as easy foreground-background
control, a collection of "simple plotters," and easy color map
manipulations), integer options which have been given meaningful names,
and a few other focused additions.  Many users will find that they can
do most of their work using the "simple plotters".

* Menu:

* High-level features for simplified plotting::
* Integer Options Given Ada Names::
* One-offs::


File: plplotdoc.info,  Node: High-level features for simplified plotting,  Next: Integer Options Given Ada Names,  Up: Unique Features of the Ada bindings

8.6.1 High-level features for simplified plotting
-------------------------------------------------

* Menu:

* Foreground-background control::
* Simple Plotters::
* Simple color map manipulations::


File: plplotdoc.info,  Node: Foreground-background control,  Next: Simple Plotters,  Up: High-level features for simplified plotting

8.6.1.1 Foreground-background control
.....................................

* Menu:

* Draw_On_Black, Draw_On_White: Draw_On_Black; Draw_On_White.


File: plplotdoc.info,  Node: Draw_On_Black; Draw_On_White,  Up: Foreground-background control

Draw_On_Black, Draw_On_White
............................

The default for PLplot is to draw its graphics on a black background.  A
white background can be used instead with ‘Draw_On_White’ or reset to
the original mode with ‘Draw_On_Black’.  Each of these manipulates color
map 0 by swapping black and white so that e.g.with ‘Draw_On_White’,
formerly white lines on a black background automatically become black
lines on a white background.


File: plplotdoc.info,  Node: Simple Plotters,  Next: Simple color map manipulations,  Prev: Foreground-background control,  Up: High-level features for simplified plotting

8.6.1.2 Simple Plotters
.......................

Several high-level but flexible plotters are available and more might be
added in the future.  It is expected that many users will find that
these high-level routines are adequate for most of their day-to-day
plotting.

* Menu:

* Multiplot_Pairs::
* Simple_Plot::
* Simple_Plot_Log_X::
* Simple_Plot_Log_Y::
* Simple_Plot_Log_XY::
* Simple_Plot_Pairs::
* Single_Plot::
* Simple_Contour::
* Simple_Mesh_3D::
* Simple_Surface_3D::


File: plplotdoc.info,  Node: Multiplot_Pairs,  Next: Simple_Plot,  Up: Simple Plotters

Multiplot_Pairs
...............

Plot up to five _x-y_ pairs with easy labelling, coloring, line width
and styles, justification, and zooming.


File: plplotdoc.info,  Node: Simple_Plot,  Next: Simple_Plot_Log_X,  Prev: Multiplot_Pairs,  Up: Simple Plotters

Simple_Plot
...........

Plot up to five _y_’s against a single _x_ with easy labelling and
automatic line colors and styles.


File: plplotdoc.info,  Node: Simple_Plot_Log_X,  Next: Simple_Plot_Log_Y,  Prev: Simple_Plot,  Up: Simple Plotters

Simple_Plot_Log_X
.................

Same as ‘Simple_Plot’ but with logarithmic _x_-axis.


File: plplotdoc.info,  Node: Simple_Plot_Log_Y,  Next: Simple_Plot_Log_XY,  Prev: Simple_Plot_Log_X,  Up: Simple Plotters

Simple_Plot_Log_Y
.................

Same as ‘Simple_Plot’ but with logarithmic _y_-axis.


File: plplotdoc.info,  Node: Simple_Plot_Log_XY,  Next: Simple_Plot_Pairs,  Prev: Simple_Plot_Log_Y,  Up: Simple Plotters

Simple_Plot_Log_XY
..................

Same as ‘Simple_Plot’ but with logarithmic _x_- and _y_-axes.


File: plplotdoc.info,  Node: Simple_Plot_Pairs,  Next: Single_Plot,  Prev: Simple_Plot_Log_XY,  Up: Simple Plotters

Simple_Plot_Pairs
.................

Plot up to five _x_-_y_ pairs with easy labelling and automatic line
colors and styles.


File: plplotdoc.info,  Node: Single_Plot,  Next: Simple_Contour,  Prev: Simple_Plot_Pairs,  Up: Simple Plotters

Single_Plot
...........

Plot a single _x_-_y_ pair with flexible labels, axis styles, colors,
line width and style, justification, and zooming.


File: plplotdoc.info,  Node: Simple_Contour,  Next: Simple_Mesh_3D,  Prev: Single_Plot,  Up: Simple Plotters

Simple_Contour
..............

Make a contour plot with labels


File: plplotdoc.info,  Node: Simple_Mesh_3D,  Next: Simple_Surface_3D,  Prev: Simple_Contour,  Up: Simple Plotters

Simple_Mesh_3D
..............

Easy 3D mesh plot with labels, zooming, and perspective controls


File: plplotdoc.info,  Node: Simple_Surface_3D,  Prev: Simple_Mesh_3D,  Up: Simple Plotters

Simple_Surface_3D
.................

Easy 3D surface plot with labels, zooming, and perspective controls


File: plplotdoc.info,  Node: Simple color map manipulations,  Prev: Simple Plotters,  Up: High-level features for simplified plotting

8.6.1.3 Simple color map manipulations
......................................

PLplot provides extensive manipulation and control of two separate color
maps, color map 0 and color map 1.  The Ada binding makes basic
manipulations easier and also adds facilities for making snapshots of
color map 0 so that any state of the map can easily be restored later.
An initial snapshot is taken when the package is initialized so that the
default color settings can always be restored after having been changed.

   Another set of features lets the user reset the 16 individual colors
in color map 0 after a color definition has been changed.  It is
important to note that while ‘Set_Pen_Color(Red)’ (‘plcol0’ in the
traditional binding) normally does what it says, ‘Red’ simply has the
value ‘1’.  If the user changes the color map so that ‘1’ corresponds to
another color, then ‘Set_Pen_Color(Red)’ will draw in that color instead
of red.  To always assure that red is drawn even if the color map has
been changed for integer ‘1’, use ‘Set_Pen_Color(Reset_Red)’ instead.
These 16 "reset" functions return the appropriate default integer for
the specified color but also reset that slot in the color table so that
a subsequent call such as ‘Set_Pen_Color(Red)’ will also cause drawing
in red.

   Color map 1 also gets a easy-to-use makeover for Ada users.  There
are several prebuilt color themes that are useful for quickly making
surface and mesh plots, ‘Color_Themes_For_Map_1_Type’.  These color
themes can be quickly applied with ‘Quick_Set_Color_Map_1’.

   Miscellaneous other Ada features include a prebuilt mask function for
‘Shade_Regions’ that does no masking; perhaps the most useful purpose is
to provide a template for writing mask functions that do mask.  And
there is a handy function for calculating the contour levels for making
contour plots.

   • Color table snapshots

     ‘Make_Snapshot_Of_Color_Map_0’

     ‘Restore_Snapshot_Of_Color_Map_0’

     ‘Restore_Default_Snapshot_Of_Color_Map_0’

   • Color resetting functions for the 16 colors of color map 0

     ‘Reset_Black, Reset_Red, ..., Reset_White’

   • Easy manipulation of color map 1

     Prebuilt color themes for color map 1:
     ‘Color_Themes_For_Map_1_Type’

     Quick application of prebuilt color themes: ‘Quick_Set_Color_Map_1’

   • Other features

     A prebuilt mask function for ‘Shade_Regions’ that does no masking:
     ‘Mask_Function_No_Mask’

     An easy way to calculate an array of contour levels for contour
     plots: ‘Calculate_Contour_Levels’


File: plplotdoc.info,  Node: Integer Options Given Ada Names,  Next: One-offs,  Prev: High-level features for simplified plotting,  Up: Unique Features of the Ada bindings

8.6.2 Integer Options Given Ada Names
-------------------------------------

The C version of PLplot uses a number of integers to mean specific
things.  Unfortunately, the meaning is lost when it it consigned to
being a mere integer with no name.  The Ada binding partially rectifies
this situation by giving names to these integer constants.  The integer
can still be used if desired.  (A more complete and safer rectification
would use enumerated types.)

   Below is a listing of at least the contexts in which these
"re-namings" have been applied.  In some cases the entire range of
values is listed, but if there are more than about four such values for
each context, only a sampling is given.

   * Instances*

   • Colors: Plot_Color_Type

     ‘ 0’ is Black, ‘1’ is Red, etc

   • Justification for plots: ‘Justification_Type’

     ‘User_Justified’

     ‘Not_Justified’

     ‘Justified’

     ‘Justified_Square_Box’

   • Axis styles: ‘Axis_Style_Type’

     ‘Linear_Major_Grid’

     ‘Linear_Minor_Grid’

     etc.

   • Font styles: ‘Font_Style_Type’

     ‘Normal_Font’

     ‘Roman_Font’

     ‘Italic_Font’

     ‘Script_Font’

   • Character sets: ‘Character_Set_Type’

     ‘Standard_Character_Set’

     ‘Extended_Character_Set’

   • Plot orientation: ‘Orientation_Type’

     ‘Landscape’

     ‘Portrait’

   • Modes for parsing command line arguments: ‘Parse_Mode_Type’

     E.g.  ‘PL_PARSE_PARTIAL’

   • Descriptions of map outlines (continents, states, etc.): ‘Map_Type’

     ‘Continents’

     ‘USA_and_States’

     ‘Continents_and_Countries’

     ‘USA_States_and_Continents’

   • Various style and view options for 3D and surface plots

     E.g.  ‘Lines_Parallel_To_X’

   • Kind of gridding algorithm for interpolating 2D data to a grid:
     ‘Gridding_Algorithm_Type’

     E.g.  ‘Grid_Bivariate_Cubic_Spline_Approximation’

   • Flags for histogram style

     E.g.  ‘Histogram_Default’

   • Flags for histogram binning

     E.g.  ‘Bin_Default’

   • Names for color space models

     Hue, Lightness, Saturation: ‘HLS’

     Red, Green, Blue: ‘RGB’


File: plplotdoc.info,  Node: One-offs,  Prev: Integer Options Given Ada Names,  Up: Unique Features of the Ada bindings

8.6.3 One-offs
--------------

To provide convenient string handling in a fashion that is familiar to
Ada programmers, function versions which return a ‘String’ type are
provided of ‘Get_Device_Name’, ‘Get_Version_Number’, and
‘Get_Output_File_Name’ (‘plgdev’, ‘plgver’, and ‘plgfnam’ in the
traditional binding).  These functions replace the procedure-style
subprograms that are described in the C API documentation.

   Overloaded ‘Set_Line_Style’ (‘plstyl’ in the traditional binding)
with a version that takes a single argument, ‘Default_Continuous_Line’.
This replaces the awkward situation of calling the normal versions of
these procedures with unused arguments simply to set the line style to
the default, continuous, line.

   The contour plotter ‘Contour_Plot_Irregular_Data’ (‘plfcont’ in the
traditional binding) is provided for making contour plots from
irregularly spaced data.  This feature is not documented in the PLplot
API documentation.

   The custom label function ‘Set_Custom_Label’ (‘plslabelfunc’ in the
traditional binding) can be called with null arguments to revert to
using the default labelling scheme.  Alternately, an Ada-only procedure
with no arguments, ‘Use_Default_Labels’, is provided.  See Ada example
19 (‘x19a.adb’ or ‘xthick19a.adb’) for a usage example.

   The custom coordinate transform setter,
‘Set_Custom_Coordinate_Transform’, (‘plstransform’ in the traditional
binding) can be called with null arguments to clear any previous custom
coordinate transforms that the user has set, thus reverting to the
default coordinate transform.  Alternately, an Ada-only procedure with
no arguments, ‘Clear_Custom_Coordinate_Transform’, is provided.  See Ada
example 19 (‘x19a.adb’ or ‘xthick19a.adb’) for a usage example.

   The procedure ‘Set_Arrow_Style_For_Vector_Plots’ (‘plsvect’ in the
traditional binding) normally is called to define the shape of an arrow
in vector plots.  However, calling it with null pointer arguments
(‘System.Null_Address’) in place of the ‘Real_Vector’ arrays and ‘False’
for the ‘Fill_Arrow’ argument causes the arrow shape to be reset to the
default shape; this is implemented in Ada as an overloaded procedure in
order to be consistent with the C API but is rather awkward.  So there
are two additional procedures that are added for the convenience of Ada
programmers: Reset_Vector_Arrow_Style and plsvect, both without
arguments, both available in both bindings, and the latter an overload
of the normal arrow-setting procedure.

   The procedures ‘Plot_Shapefile’ and ‘Plot_Shapefile_World’
(‘plmapfill ’) and ‘plmapline’ in the traditional binding) are each
provided an overloaded version allowing either an array of integers or a
null pointer to be passed for the last argument, so that the
documentation makes sense.  An additional related procedure is provided
in each case, ‘Plot_Shapefile_All’ and ‘ Plot_Shapefile_World_All’
(identically named in the traditional binding) for the case when a null
pointer would otherwise be passed, thus allowing the Ada programmer a
way to specify "plot all the Shapefile elements" without having to
conjure a null pointer.  See Example 19.


File: plplotdoc.info,  Node: Parts That Retain a C Flavor,  Next: Known Variances,  Prev: Unique Features of the Ada bindings,  Up: Ada Language

8.7 Parts That Retain a C Flavor
================================

There remains at least one area in the Ada bindings which is still
affected by the C underpinnings.  This might be cleaned up in future
versions.  There might be other residual C influence as well.

* Menu:

* Map-drawing::


File: plplotdoc.info,  Node: Map-drawing,  Up: Parts That Retain a C Flavor

8.7.1 Map-drawing
-----------------

‘plmapform’ as called by ‘Draw_Latitude_Longitude’ (‘plmap’) and
‘Draw_Latitude_Longitude’ (‘plmeridians’)

   This is the only place in the PLplot bindings where a C subprogram
calls an Ada subprogram while passing an array.  If the array is
unconstrained, there is no guarantee that it will work because C has no
way of telling Ada what offset to use for the beginning of the array.
But passing a constrained array is acceptable with the downside that the
array size must be fixed within the bindings as being large enough to
handle any situation; currently, it is sized as ‘0 .. 2000’.  See
Example 19 for how this is handled in by the user program.  The
constrained array is called ‘Map_Form_Constrained_Array’.


File: plplotdoc.info,  Node: Known Variances,  Next: Compilation notes,  Prev: Parts That Retain a C Flavor,  Up: Ada Language

8.8 Known Variances
===================

* Menu:

* Documentation::
* API::


File: plplotdoc.info,  Node: Documentation,  Next: API,  Up: Known Variances

8.8.1 Documentation
-------------------

In numerous places in the documentation, a feature is listed or
described as "C only."  Many of these features are actually available in
Ada.  For example, in ‘Contour_Plot’ (‘plcont’ in the traditional
binding), the transformation from array indices to world coordinates is
mentioned as "C only" but is actually available in Ada.


File: plplotdoc.info,  Node: API,  Prev: Documentation,  Up: Known Variances

8.8.2 API
---------

The C documentation for ‘plscmap1l’, (‘Set_Color_Map_1_Piecewise’ in the
thick binding) and ‘plscmap1la’ (‘Set_Color_Map_1_Piecewise_And_Alpha’
in the thick binding) states that if the last argument is a null
pointer, the behavior is as though a proper-length array of all ‘False’
values was passed.  In Ada, these procedures are overloaded to allow a
last argument that can be either an array of Boolean or a value of the
enumerated type ‘type Alt_Hue_Path_Type is (Alt_Hue_Path_None,
Alt_Hue_Path_All)’.


File: plplotdoc.info,  Node: Compilation notes,  Next: Notes for Apple Macintosh OS X users,  Prev: Known Variances,  Up: Ada Language

8.9 Compilation notes
=====================

* Menu:

* Ada 95 Versus Ada 2005::
* GNAT Dependence::
* PLplot_Auxiliary::


File: plplotdoc.info,  Node: Ada 95 Versus Ada 2005,  Next: GNAT Dependence,  Up: Compilation notes

8.9.1 Ada 95 Versus Ada 2005
----------------------------

As discussed in Section 6.1, the bindings are made to work with Ada 95
and Ada 2005, but special steps need to be taken in order to access the
numerical capabilities of Ada 2005 to the extent that vectors and arrays
of the type defined in the Ada Reference Manual Annex G.3 are required
to be passed to PLplot routines.


File: plplotdoc.info,  Node: GNAT Dependence,  Next: PLplot_Auxiliary,  Prev: Ada 95 Versus Ada 2005,  Up: Compilation notes

8.9.2 GNAT Dependence
---------------------

There is a slight but significant dependence on the GNAT version of Ada.
This is discussed more fully in Section 6.2


File: plplotdoc.info,  Node: PLplot_Auxiliary,  Prev: GNAT Dependence,  Up: Compilation notes

8.9.3 PLplot_Auxiliary
----------------------

The bindings include files ‘PLplot_Auxiliary.ads’ and
‘PLplot_Auxiliary.adb’.  These files are currently used to provide a few
convenience subprograms that are used in the examples.  However, they
are also associated with the above-mentioned facility to easily
accommodate accessing the G.3 Annex vector-matrix manipulation
facilities.  If not for the desire for this easy "switching" ability,
the ‘PLplot_Auxiliary’ package could be removed from the ‘with’ parts of
the other binding files.  Even so, it could be still removed with minor
modifications to the ‘with’ portions of the other binding files.  But
due to the other functions provided therein, they would still need to be
referenced by most of the Ada examples.


File: plplotdoc.info,  Node: Notes for Apple Macintosh OS X users,  Prev: Compilation notes,  Up: Ada Language

8.10 Notes for Apple Macintosh OS X users
=========================================

The following comments apply to users of Apple Macintosh computers which
run OS X. OS X users may use Apple’s free integrated development
environment (IDE) or may prefer other methods such as using a favorite
editor and building from the command line.

   OS X users should be aware that an excellent graphical terminal
program is available and is highly recommended.  It is called AquaTerm
and is a full Cocoa program with window control.  Performing a cut
operation places a PDF of the front window on the clipboard, a
convenience when working with other graphics or word processing
programs.

* Menu:

* Using Apple's Xcode IDE::
* AquaTerm::
* X11::
* GNAT for OS X::


File: plplotdoc.info,  Node: Using Apple's Xcode IDE,  Next: AquaTerm,  Up: Notes for Apple Macintosh OS X users

8.10.1 Using Apple’s Xcode IDE
------------------------------

The Macintosh Ada community has made a plug-in for Apple’s free Xcode
integrated development environment (IDE) that makes programming Ada in
Xcode possible.  The plug-in is included with the compiler that is
available at www.macada.org (http://www.macada.org/).  Since Xcode is
based on gcc, it is possible to work in the various gcc languages as
well as to incorporate binaries such as the PLplot library.

   In order to make an Xcode project, drag-and-drop source files and the
PLplot library file to the Groups & Files pane of an Ada project.  There
are a few idiosyncrasies that you may encounter so make sure to contact
the very friendly Macintosh Ada mailing list at www.macada.org
(http://www.macada.org/) or study the FAQ at that same site if you have
any difficulties.

   [This plug-in still works for some older versions of Xcode but not
for newer versions, as of 2013.]


File: plplotdoc.info,  Node: AquaTerm,  Next: X11,  Prev: Using Apple's Xcode IDE,  Up: Notes for Apple Macintosh OS X users

8.10.2 AquaTerm
---------------

AquaTerm is a display option available on Macintosh computers using OS X
and is supported by PLplot.  It is a native Cocoa graphics "terminal"
that is highly recommended.  All output is antialiased and is easily
cut-and-pasted in OS X’s native PDF format.  Get it here
(http://sourceforge.net/projects/aquaterm/files).  It can also be
installed from either the Fink (http://fink.thetis.ig42.org/) or
MacPorts (http://www.macports.org/) projects.


File: plplotdoc.info,  Node: X11,  Next: GNAT for OS X,  Prev: AquaTerm,  Up: Notes for Apple Macintosh OS X users

8.10.3 X11
----------

Apple supplies the X11 windowing system that is popular on some other
Unix and Linux operations systems.  Formerly it was available as part of
the Developer Tools but as of OS X 10.8 it is a separate installation.
All PLplot programs made with the Ada bindings will run on X11.  In
fact, some types of interactivity such as Example 17 will not run on
Apple’s Terminal.app and should be run on X11 (or some other output
device such as TCL/TK).


File: plplotdoc.info,  Node: GNAT for OS X,  Prev: X11,  Up: Notes for Apple Macintosh OS X users

8.10.4 GNAT for OS X
--------------------

A web site for OS X users is at www.macada.org
(http://www.macada.org/macada/Welcome.html).  Although rather dated, the
mailing list is still active.  Assistance can be found at other places
on the web including the usenet comp.lang.ada.


File: plplotdoc.info,  Node: A C++ Interface for PLplot,  Next: Fortran Language,  Prev: Ada Language,  Up: Supported computer languages

9 A C++ Interface for PLplot
****************************

PLplot has long had C and Fortran bindings, presenting a fairly
conventional API to the applications programmer.  Recently (1994
onwards) PLplot has been growing interfaces (language bindings) to a
variety of other languages.  In this chapter we discuss the PLplot C++
support provided in the PLplot distribution.  Of course many other
approaches are possible, perhaps even in use by PLplot users around the
world.  The purpose of this chapter then is to explain the rationale and
intended usage for the bundled C++ language support.

* Menu:

* Motivation for the C++ Interface::
* Design of the PLplot C++ Interface::
* Specializing the PLplot C++ Interface::
* Status of the C++ Interface::


File: plplotdoc.info,  Node: Motivation for the C++ Interface,  Next: Design of the PLplot C++ Interface,  Up: A C++ Interface for PLplot

9.1 Motivation for the C++ Interface
====================================

PLplot has a fairly complex C API. There are lots of functions, and
several facilities have multiple entry points with similar names but
different argument lists.  (Think contouring, shading).  Often these
differing argument lists are to accommodate a variety of data storage
paradigms, one of which you are expected to be using!

   Especially in the case of the 2-d API’s for contouring and shading,
sophisticated C++ users may feel a special sense of exasperation with
the data layout prescriptions, since they are extremely primitive,
pointer rich, and prone to a wide class of memory leaks and other sorts
of programming errors.  Many C++ users know good and well that better
ways exist (templated matrix classes, etc), but historically have not
been able to use these more sophisticated techniques if the contained
data ever needed to get plotted.

   Besides the 2-d API functions, there is also the multiple output
stream capability of PLplot.  Anyone who knows C++ well, and who has
used multiple output streams in PLplot, has probably noticed striking
similarities between the PLplot ‘PLStream’ pointer and the C++ ‘this’
pointer.  Although multiple output streams have not been widely used in
PLplot applications in the past, the availability of the plframe Tk
widget, and the extended wish concept, is making it much more attractive
to use multiple output streams.

   Unfortunately, if you do write a Tk extended wish application, and
endow your interface with multiple plframes, the event driven character
of X applications makes it difficult to ensure that PLplot output shows
up in the right plframe window.  If a plot is generated to one plframe,
the PLplot ‘PLStream’ pointer is directed to that stream.  If a user
then pushes a Tk button which should generate a plot to a different
plframe, the plot goes to the old plframe instead!  Schemes for
controlling this can be imagined, but the logic can be complex,
especially in the face of the ability to /also/ make plots to the same
plframe from either Tcl or C++.

   Beyond this, the C API is downright "ugly" for a significant number
of the functions, particularly those which return values by accepting
pointers to variables in their argument lists, and then changing them in
that way.  Sophisticated C++ users generally take considerable pride in
banishing the offensive bare pointer from their code, and consider it
disgusting to have to insert &’s just in order to make a call to an API
function.

   In order to address these issues (and more), I have begun
constructing a C++ interface to PLplot.  The purpose of this missive is
to describe its architecture and usage.


File: plplotdoc.info,  Node: Design of the PLplot C++ Interface,  Next: Specializing the PLplot C++ Interface,  Prev: Motivation for the C++ Interface,  Up: A C++ Interface for PLplot

9.2 Design of the PLplot C++ Interface
======================================

* Menu:

* Stream/Object Identity::
* Namespace Management::
* Abstraction of Data Layout::
* Callbacks and Shades::
* Collapsing the API::


File: plplotdoc.info,  Node: Stream/Object Identity,  Next: Namespace Management,  Up: Design of the PLplot C++ Interface

9.2.1 Stream/Object Identity
----------------------------

A C++ class named ‘plstream’ has been introduced.  It’s central purpose
is provide a specific, object based encapsulation of the concept of a
PLplot output stream.  Any output produced using a ‘plstream’ object,
will go to the PLplot output stream associated with that object,
regardless of what stream may have been active before.

   In order to write a multiple output stream PLplot application, a C++
program can declare ‘plstream’ objects, and invoke drawing methods on
those objects, without regard to ordering considerations or other
coherency considerations.  Although this has obvious simplification
benefit even for simple programs, the full benefit is most easily
appreciated in the context of Tk extended wish applications in which a
‘plstream’ can be associated with each plframe.


File: plplotdoc.info,  Node: Namespace Management,  Next: Abstraction of Data Layout,  Prev: Stream/Object Identity,  Up: Design of the PLplot C++ Interface

9.2.2 Namespace Management
--------------------------

The PLplot C API is composed of a set of drawing functions, all prefixed
with "pl", in an effort to prevent namespace collision.  However, the
prefix "pl" is gratuitous, and in particular is unnecessary in a C++
context.  The ‘plstream’ class mirrors most of the PLplot C API, but
does so by dropping the "pl" prefix.  The ‘plstream’ class thus serves
to collect the PLplot drawing functions into a scope in which collisions
with other similarly named functions is not a concern.  So, where a C
programmer might write:


     	plsstrm( 1 );
     	plenv( ... );
     	plline( ... );


   The C++ programmer can write:


     	plstream p( ... );
     	p.env( ... );
     	p.line( ... );


   Is that an important benefit?  The utility varies with the number of
output streams in use in the program.

   plmkstrm() is replaced by object declaration.  plsstrm() is replaced
by method invocation on the desired output stream object.  plgstrm() is
rendered irrelevant.

   The skeptic may say, "But you have to type the same number of
characters!  You’ve replaced ’pl’ with ’p.’, except it could be worse
for a longer object name."  True.  BUT, in this new scheme, most plots
will not be generated by invoking methods on a specific stream object,
but rather by deriving from ‘plstream’, and invoking methods of "this"
object.  See the section on derivation below.


File: plplotdoc.info,  Node: Abstraction of Data Layout,  Next: Callbacks and Shades,  Prev: Namespace Management,  Up: Design of the PLplot C++ Interface

9.2.3 Abstraction of Data Layout
--------------------------------

The ‘plstream’ class will provide an abstract interface to the 2-d
drawing functions.  Instead of forcing the C++ user to organize data in
one of a small set of generally brain dead data layouts with poor memory
management properties, potentially forcing the C++ user to not use a
superior method, or to copy data computed in one layout format to
another for plotting (with consequent bug production), the ‘plstream’
2-d plotting functions will accept an abstract layout specification.
The only thing which is important to the 2-d drawing functions is that
the data be "indexable".  They should not care about data layout.

   Consequently, an abstract class, "Contourable_Data" is provided.
This class provides a pure virtual method which accepts indexes, and is
to be made to produce a function value for the user’s 2-d data field.
It is of no concern to PLplot how the user does this.  Any mapping
between index and data which the user wishes to use, may be used.

   This methodology allows the C++ user to compute data using whatever
storage mechanism he wants.  Then, by deriving a class from PLplot’s
Contourable_Data abstract class, he can provide a mapping to his own
data layout.

   Note that this does /not/ mean that the C++ user’s internal data
layout must be derived from PLplot’s Contourable_Data class.  Suppose
for example that the user data is stored in a C++ "matrix" class.  To
make this data contourable, the user may define a class which
specializes the indexing concept of the PLplot Contourable_Data class to
his matrix class.  For example:


     	class Matrix { ... };
     	class Contourable_Matrix : public Contourable_Data {
     	Matrix& m;
     	public:
     	Contourable_Matrix( Matrix& _m ) : m(_m) {}
     	PLFLT  operator()( int i, int j ) const { return m(i,j); }
	     };

     	plstream p( ... );
     	Matrix m;
     	// Code to fill m with data
     	Contourable_Matrix cm(m);
     	p.shade( cm, ... );


   In this way the C++ user is completely freed from the tyranny of
moronic data layout constraints imposed by PLplot’s C or Fortran API.


File: plplotdoc.info,  Node: Callbacks and Shades,  Next: Collapsing the API,  Prev: Abstraction of Data Layout,  Up: Design of the PLplot C++ Interface

9.2.4 Callbacks and Shades
--------------------------

The ‘plstream::plshades’ method and the other similar methods require
callbacks for fill and pltr, mirroring the requirements for ‘plshades’.
The user may specify their own callbacks or may use the callbacks
provided by Plplot.  If using Plplot callbacks the user has two options.
They may use the appropriate C functions as described in the C API,
however this will require direct linkage of the user’s executable to the
C library as well as the C++ library, which would otherwise not be
necessary when using shared libraries.  To avoid linking of the C
library the user may instead utilise the functions within the
‘plcallback ’ namespace.  The ‘plcallback’ namespace provides ‘fill’,
‘tr0’, ‘tr1’, ‘tr2’, and ‘tr2p’ callbacks which mirror the functionality
of the appropriate C functions.


File: plplotdoc.info,  Node: Collapsing the API,  Prev: Callbacks and Shades,  Up: Design of the PLplot C++ Interface

9.2.5 Collapsing the API
------------------------

Use of abstraction as in C) above will allow a single method in
‘plstream’ to perform the services of multiple functions in the C API.
In those cases where multiple functions were provided with different
data layout specifications, but similar functionality, these can all be
collapsed into one, through the use of the abstract interface technique
described above.  Moreover, function name overloading can be used to
simplify the namespace for those cases where multiple functions were
used to get variations on a basic capability.  For example, a single
name such as contour or shade can be used for multiple methods taking
different argument sets, so that for example, one can make simple plots
of rectangular data sets, or more complex generalized coordinate
mappings.


File: plplotdoc.info,  Node: Specializing the PLplot C++ Interface,  Next: Status of the C++ Interface,  Prev: Design of the PLplot C++ Interface,  Up: A C++ Interface for PLplot

9.3 Specializing the PLplot C++ Interface
=========================================

The ‘plstream’ class is an ideal candidate for derivation.  By
inheriting from ‘plstream’, the user can construct a new class which is
automatically endowed with the ability to plot to a specific PLplot
output stream in a coherent manner without having to worry about
interplay with other ‘plstream’ (or derived type) objects.  Moreover,
new, higher level, plotting functionality can be constructed to provide
even more simplicity and ease of use than the PLplot API.

   The PLplot maintainers (Geoff and Maurice) expect to introduce a
class plxstream in the future which provides superior support for
constructing graphics with multiple plots per page, easier specification
of plot adornments, etc.  This should significantly ease one aspect of
PLplot usage which we regard as being clumsy at this time.

   Beyond that, users may find it useful to derive from ‘plstream’ (or
later plxstream whenever it finally makes its appearance) for the
purpose of making "application specific" output streams.  For example, a
C++ program will normally have a variety of objects which constitute the
fundamental entities in the code.  These could all be made to be
"atomically plotted" by providing suitable methods.  For example:


           class Cat { ... };
           class Dog { ... };
           class Bear { ... };
           class Fish { ... };

           class zoostream : public plstream {
           public:
           void plot( const Cat& c ) { ... }
           void plot( const Dog& d ) { ... }
           void plot( const Bear& b ) { ... }
           void plot( const Fish& f ) { ... }
           };


   Presumably the PLplot user community can think of even more
imaginative uses...  :-).


File: plplotdoc.info,  Node: Status of the C++ Interface,  Prev: Specializing the PLplot C++ Interface,  Up: A C++ Interface for PLplot

9.4 Status of the C++ Interface
===============================

The class ‘plstream’ (and the other abstraction classes in ‘plstream.h’)
provided in PLplot 4.99j (alpha) are to be considered as works in
progress.  By the standards outlined above, the work has barely begun.
At this time, ‘plstream’ is mostly a one to one mirror of the C API,
which is to say, it is still far from the goals of simplification and
abstraction outlined above.  As such, it can be expected to change
radically over the course of time.  (We don’t quote schedules–how long
have you been waiting for 5.0?  :-).

   In any event, we would welcome improvement submissions along the
lines of those above, but we would strongly discourage people from using
‘plstream’ if they are expecting it to be rock solid.  It _will_ be
changing, to become more like the design goals elucidated above.

   So, if you like the ideas described above, and are willing to accept
the burden of "upgrading" your code as the class ‘plstream’ evolves,
then feel free to use it.  Just don’t whine when I fix some of the
methods to take references instead of pointers, when I eliminate some of
the redundant methods to use the collapsed form, etc.


File: plplotdoc.info,  Node: Fortran Language,  Next: OCaml Language,  Prev: A C++ Interface for PLplot,  Up: Supported computer languages

10 Fortran Language
*******************

The new implemention of the Fortran binding of PLplot takes full
advantage of the ‘ISO_C_BINDING’ feature of the Fortran 2003 standard,
which is supported by all current compilers.  The advantage of this
approach is that the entire binding is now written in Fortran, so that
there is only one library that calling programs need to link against.
Furthermore, the binding defines overloaded routines for the case of
either single- or double-precision arguments supplied by the calling
programme regardless of the floating-point precision of the underlying C
library.  That makes this binding much easier to use than our previous
implementation of the Fortran binding where calling routines were forced
to use the same floating-point precision that was configured for the
underlying PLplot C library.

   Note: in this chapter ‘Fortran’ stands for ‘Fortran as defined by the
Fortran 2003 standard’.  Older versions of PLplot supported FORTRAN 77,
but the binding for this 40 years old version has been abandoned for
quite a few years now.  As we now use features from the Fortran 2003
standard, it is no longer appropriate to refer to the language as
Fortran 95.

   We illustrate the implementation of our Fortran binding using the
‘‘plstring’ (*note plstring; Plot a glyph at the specified points::)’
API as an example.  The summary of the C API for that routine which best
serves our purposes here is


     void plstring( PLINT n, const PLFLT *x, const PLFLT *y, const char *string );

The arguments ‘n’, ‘x’, ‘y’, and ‘string’ represent the number of times
the string is plotted, the arrays of length ‘n’ which contain the ‘x, y’
values where that string is plotted, and the NULL-terminated C string
that contains the ordinary (not wide) characters in the UTF-8 encoding
of a unicode glyph to be plotted.  The PLplot ‘PLINT’ type is normally
defined as the C fundamental type ‘int32_t’, and the PLplot ‘PLFLT’ type
is defined to be one of the two C fundamental types ‘float’ or ‘double’
depending on how the C PLplot library is configured.

   Here is an example of one fairly typical Fortran call of ‘plstring’.


     program test_plplot
         use plplot
         implicit none
         integer, parameter :: my_real  = kind(1.0)
         real(kind=my_real), dimension(6) :: x, y
         ...
         x = ...
         y = ...
         ...
         call plstring(x,y,"+")
         ...
     end program test_plplot

where for this particular case ‘x’ and ‘y’ are arrays with 6 elements
defined and the points are to be plotted using the ascii "+" symbol
(although if you are using a unicode-aware PLplot device, then you can
try many other unicode possibilities for the symbol such as the U+22C5
DOT OPERATOR, "⋅").  Note that our Fortran binding implementation below
allows use of the ‘kind(1.0d0)’ choice of ‘my_real’ precision as well.

   The ‘plstring’-relevant parts of the ‘plplot’ module used above are


     module plplot
         ...
         use plplot_single
         use plplot_double
         ...
     end module plplot

The redacted part of the ‘plplot’ module implements the interfaces to
the PLplot C library routines that happen to have no floating-point
arguments very similarly to the way that the ‘plplot_single’ and
‘plplot_double’ modules interface the PLplot C routines like ‘plstring’
(*note plstring; Plot a glyph at the specified points::) that do include
floating-point arguments.  The ‘plstring’-relevant parts of the
‘plplot_single’ module are


     module plplot_single
         ...
         integer, parameter :: wp = private_single
         ...
         interface plstring
             module procedure plstring_impl
         end interface plstring
         private :: plstring_impl
         ...
     contains
         ...
         subroutine plstring_impl( x, y, string )

            real(kind=wp), dimension (:), intent(in) :: x, y
            character(len=*), intent(in) :: string

            integer(kind=private_plint) :: n_local

            interface
                subroutine interface_plstring( n, x, y, string ) bind(c,name='c_plstring')
                    import :: private_plint, private_plflt
                    implicit none
                    integer(kind=private_plint), value, intent(in) :: n
                    real(kind=private_plflt), dimension(*), intent(in) :: x, y
                    character(len=1), dimension(*), intent(in) :: string
                end subroutine interface_plstring
            end interface

            n_local = size(x, kind=private_plint)
            if(n_local /= size(y, kind=private_plint) ) then
                write(error_unit,"(a)") "Plplot Fortran Warning: plstring: inconsistent sizes for x and y"
            end if

            call interface_plstring( n_local, real(x,kind=private_plflt), real(y,kind=private_plflt), &
                trim(string)//c_null_char )
         end subroutine plstring_impl
         ...
     end module plplot_single

The ‘plstring’-relevant parts of the ‘plplot_double’ module are defined
identically (in fact that identicality is guaranteed by using the same
included file to define the identical parts) except for


         integer, parameter :: wp = private_double

   Here are some notes on the above implementation of our Fortran
binding for ‘plstring’.  The ‘plplot_single’ and ‘plplot_double’ modules
implement two versions of the Fortran ‘plstring’ subroutine which are
identical except one subroutine has floating-point arguments with a kind
value of ‘wp = private_single = kind(1.0)’ and one subroutine has
floating-point arguments with kind value of ‘wp = private_double =
kind(1.0d0)’.  The result is the Fortran compiler automatically chooses
the correct overloaded version of ‘plstring’ that corresponds to the
precision of the floating-point arguments used by the program (e.g.,
like ‘test_plplot’ above) that is being compiled.  The intrinsic
function ‘size()’ is used to determine the size of arrays and allows
checking that their dimensions are consistent with each other when the C
implementation uses a common size for the arrays as in the ‘plstring’
case.  (See also, ‘bindings/fortran/README_array_sizes’.)  The intrinsic
function ‘real()’ is used to convert floating-point data between the
type used by the calling routine and the type used by the underlying
PLplot C library, and the intrinsic function ‘int()’ (not used in the
above example) is used for similarly converting integer data.  The
intrinsic function ‘trim()’ and the ‘ISO_C_BINDING’ parameter
‘c_null_char’ are used to help convert a Fortran character string into a
NULL-terminated C string.  Also note the above interface block defining
‘subroutine interface_plstring’ is the Fortran representation of the
exact C API of ‘plstring’ (*note plstring; Plot a glyph at the specified
points::).

   Here is a table summarizing how C data types correspond to Fortran
data types in the arguments of functions defined by our Fortran binding.
Consult the Fortran code in ‘bindings/fortran/*’ for further details of
how the conversion is done between our private Fortran types that are
equivalent to the corresponding C types, and the public Fortran types
that are available for Fortran function arguments in our Fortran
binding.  Note the ‘my_flt’ kind value used in this table is not
provided by our Fortran binding.  Instead it merely indicates that the
calling routine (e.g., the ‘test_plplot’ example routine above) has the
choice of either ‘kind(1.0)’ or ‘kind(1.0d0)’ for the kind values of the
floating-point arguments of the PLplot functions defined by our Fortran
binding.

C type                   Private Fortran type     Public Fortran type
‘PLFLT’                  ‘real(kind=private_plflt)’‘real(kind=my_flt)’
‘PLFLT *’                ‘real(kind=private_plflt),‘real(kind=my_flt),
                         dimension(*)’            dimension(:)’
‘PLFLT **’               ‘type(c_ptr),            ‘real(kind=my_flt),
                         dimension(*)’            dimension(:, :)’
‘PLINT’                  ‘integer(kind=private_plint)’‘integer’
‘PLINT *’                ‘integer(kind=private_plint),‘integer,
                         dimension(*)’            dimension(:)’
‘PLBOOL’                 ‘integer(kind=private_plbool)’‘logical’
‘char *’                 ‘character(len=1),       ‘character(len=*)’
                         dimension(*)’

In C there are two ways to pass a variable — by value (the default) or
by reference (pointer), whereas in Fortran this difference is not
visible in the call, only in the interface definition via the ‘value’
attribute.  Therefore when you see references in the documentation of
our C API to _either_ an ordinary argument or a pointer argument (e.g.
‘*data’), you simply use an ordinary Fortran variable or array name.
The new Fortran binding automatically takes care of any conversion that
may be necessary.

   In sum, the ‘plstring’ example above illustrates the way our Fortran
binding makes the PLplot C API conveniently accessible from Fortran
while letting the C binding and overloading features of the Fortran
compiler hide the complexities of the name mangling that occurs.

   Users should be aware that there are a few cases with our new Fortran
binding where we provide double-precision floating-point entities but no
equivalent single-precision floating-point alternative.

   • The Fortran standard dictates that compilers cannot disambiguate
     overloaded functions based on the type of their return value.  This
     means that the ‘plrandd’ (*note plrandd; Random number generator
     returning a real random number in the range [0;1]::) function
     cannot be disambiguated because it has no arguments.  For this
     reason we have decided to provide only one version of this function
     that returns a double-precision random value.

   • The Fortran standard dictates that compilers cannot disambiguate
     overloaded routines based on the types of arguments to callback
     routines that appear as arguments to those routines.  This means
     that the ‘plstransform’ (*note plstransform; Set a global
     coordinate transform function::) and ‘plslabelfunc’ (*note
     plslabelfunc; Assign a function to use for generating custom axis
     labels::) routines cannot be disambiguated because they have no
     _direct_ floating-point arguments.  For this reason we have decided
     that for the case where ‘plstransform’ uses a
     ‘transform_coordinate’ callback as its first argument, that
     callback will be allowed to only have double-precision arguments.
     And similarly for ‘plslabelfunc’ and the ‘label_func’ callback.

   • The new Fortran binding defines a derived ‘PLGraphicsIn’ type as
     follows:


            type :: PLGraphicsIn
               integer                   :: type           ! of event (CURRENTLY UNUSED)
               integer                   :: state          ! key or button mask
               integer                   :: keysym         ! key selected
               integer                   :: button         ! mouse button selected
               integer                   :: subwindow      ! subwindow (alias subpage, alias subplot) number
               character(len=16)         :: string         ! Fortran character string
               integer                   :: pX, pY         ! absolute device coordinates of pointer
               real(kind=private_double) :: dX, dY         ! relative device coordinates of pointer
               real(kind=private_double) :: wX, wY         ! world coordinates of pointer
            end type PLGraphicsIn


     This is the type that should be used for the argument of the
     Fortran ‘plGetCursor’ routine.  We provide no alternative
     ‘plGetCursor’ routine whose argument is similar to ‘PLGraphicsIn’
     but with single-precision ‘dX’, ‘dY’, ‘wX’, and ‘wY’ components.

   • The new Fortran binding provides three auxiliary floating-point
     parameters, ‘PL_PI’, ‘PL_TWOPI’ and ‘PL_NOTSET’ which are all
     defined in double precision.  If the calling routine requires
     single precision instead it should define a local parameter as in
     the following code fragment:


              use plplot
              ...
              integer, parameter :: my_flt = kind(1.0)
              real(kind=my_flt), parameter :: my_NOTSET = PL_NOTSET


   Users should be aware that the new Fortran binding for PLplot
enforces the following interfacing rules:

   • The new Fortran binding interfaces Fortran functions/subroutines
     with C routines if the C routines provide/do not provide a return
     value.  For example, this rule means that the C ‘plparseopts’
     (*note plparseopts; Parse command-line arguments::) routine that
     returns an error code must be invoked at the Fortran level
     similarly to the following:


              integer :: plplarseopts_rc
              ...
              plparseopts_rc = plparseopts(...)


     Of course, this rule means it is possible for Fortran routines
     invoking functions like plparseopts to respond properly to error
     conditions returned by the corresponding C routine.

   • Only the redacted form of Fortran API (with all redundant dimension
     arguments removed) is supported.

   • If the C API for the function being interfaced includes a size
     value corresponding to identical sizes of dimension(s) of multiple
     array arguments.  then the sizes of the corresponding dimensions of
     the Fortran arrays must also be identical.  The complete list of
     these adopted rules for consistently sized array arguments for our
     Fortran binding are given at ‘bindings/fortran/README_array_sizes’.
     These rules are enforced in a user-friendly way by issuing a
     run-time warning whenever these rules have been violated.  For
     those cases which generate such warnings because the calling
     routine has specified static or allocatable arrays whose relevant
     defined areas are smaller than their size, use the normal Fortran
     rules for array slicing to specify completely defined arrays with
     consistent sizes that comply with this interfacing rule.

   • Fortran logical arguments are used for all cases where the
     corresponding C argument is ‘PLBOOL’.

   • All floating-point arguments for a given function call must have
     consistent kind values (either ‘kind(1.0)’ or ‘kind(1.0.d0)’).

   For more information on calling PLplot from Fortran, please consult
the example Fortran programs in ‘examples/fortran’ that are distributed
with PLplot.  For more information on building your own PLplot-related
Fortran routines, please consult either the traditional (Makefile +
pkg-config) or CMake-based build systems that are created as part of the
install step for our Fortran (and other language) examples.


File: plplotdoc.info,  Node: OCaml Language,  Next: Using PLplot from Perl,  Prev: Fortran Language,  Up: Supported computer languages

11 OCaml Language
*****************

This document describes the OCaml bindings to the PLplot technical
plotting software, how to obtain the necessary software components and
how to use them together.

* Menu:

* Overview: Overview <1>.
* The Bindings: The Bindings <1>.
* The Examples: The Examples <1>.
* Obtaining the Software: Obtaining the Software <1>.
* How to use the OCaml bindings::
* Known Issues::


File: plplotdoc.info,  Node: Overview <1>,  Next: The Bindings <1>,  Up: OCaml Language

11.1 Overview
=============

The OCaml bindings for PLplot provide a way for OCaml programmers to
access the powerful PLplot technical plotting facilities directly from
OCaml programs while working completely in OCaml—the OCaml programmer
never needs to know or worry that PLplot itself is written in another
language.


File: plplotdoc.info,  Node: The Bindings <1>,  Next: The Examples <1>,  Prev: Overview <1>,  Up: OCaml Language

11.2 The Bindings
=================

The OCaml bindings for PLplot provide an interface to the PLplot C API.
In addition to providing access to the core functions of the C API, the
OCaml PLplot interface also includes a set of higher-level plotting
functions which, while built on top of the core PLplot API, retain more
of an OCaml flavor.

   The OCaml PLplot API is defined within the Plplot module.  In
general, it is suggested to include the line ‘open Plplot’ in OCaml code
using PLplot.  The function and constant definitions are named such that
they should avoid namespace collisions with other libraries.  Core
PLplot functions have a ‘pl’ prefix, while constant constructors/variant
types have a ‘PL_’ prefix.

   The core binding provides a close to direct mapping to the underlying
C library.  It follows the C API very closely, with the exception of a
few parameters which become redundant under OCaml (ex.  array lengths
are determined automatically by OCaml and function callbacks which are
handled slightly differently than in C). An OCaml user of PLplot does
not need to worry about memory management issues as they are handled
automatically by the bindings.

   There are also a selection of functions which provide support for
operations outside of the base C API. These higher level functions are
defined within the ‘Plplot.Plot’ and ‘Plplot.Quick_plot’ modules.

* Menu:

* Core Binding::
* OCaml-specific variations to the core PLplot API::
* OCaml high level 2D plotting API::


File: plplotdoc.info,  Node: Core Binding,  Next: OCaml-specific variations to the core PLplot API,  Up: The Bindings <1>

11.2.1 Core Binding
-------------------

The core binding is mostly a direct and obvious mapping of the C
application programming interface (API) to OCaml.  Thus, for example,
where a C function such as ‘plcol0’ requires a single integer argument,
there is a corresponding OCaml function also called ‘plcol0’ which also
requires a single integer argument.  (‘plcol0’ happens to set the
drawing color using a number which is associated with a set of colors).
Various constants from the C API are also included here as OCaml variant
types with a ‘PL_’ prefix to avoid namespace clashes when the ‘Plplot’
module is opened.  For example, where the C PLplot API uses ‘GRID_*’ to
select between the data gridding methods, the OCaml API uses
‘PL_GRID_*’.


File: plplotdoc.info,  Node: OCaml-specific variations to the core PLplot API,  Next: OCaml high level 2D plotting API,  Prev: Core Binding,  Up: The Bindings <1>

11.2.2 OCaml-specific variations to the core PLplot API
-------------------------------------------------------

Several of the PLplot core functions allow the user to provide a
transformation callback function to adjust the location of the plotted
data.  This is handled differently in the OCaml bindings than in order
to keep the interface between C and OCaml as simple as possible.  Rather
than passing transformation functions directly to each PLplot function
which supports a coordinate transformation, the coordinate transform
functions are set globally using the ‘plset_pltr’ and ‘plset_mapform’
functions.  Similarly, the functions ‘plunset_pltr’ and
‘plunset_mapform’ can be used to clear the globally defined coordinate
transformation function.  Note that the transform functions are only
used in the functions which support them in the C API (ex.  ‘plmap’)-
they are not automatically applied to plotted data in other function
calls (ex.  ‘plline’).  For demonstrations of their use, see OCaml
PLplot examples 16 and 20 for ‘plset_pltr’ and example 19 for
‘plset_mapform’.


File: plplotdoc.info,  Node: OCaml high level 2D plotting API,  Prev: OCaml-specific variations to the core PLplot API,  Up: The Bindings <1>

11.2.3 OCaml high level 2D plotting API
---------------------------------------

In addition to the core PLplot API, the OCaml bindings provide two
modules which provide a more OCaml-like interface: ‘Plplot.Plot’ and
‘Plplot.Quick_plot’.  ‘Plplot.Plot’ provides a simplified naming scheme
for plotting functions, as well as the means to more easily track
multiple plot streams at once.  ‘Plplot.Quick_plot’ provides functions
to quickly plot points, lines, data arrays (images) and functions
without the need for any plot setup or boilerplate.


File: plplotdoc.info,  Node: The Examples <1>,  Next: Obtaining the Software <1>,  Prev: The Bindings <1>,  Up: OCaml Language

11.3 The Examples
=================

An important part of the OCaml bindings is the examples, some 31 of
which demonstrate how to use many of the features of the PLplot package.
These examples also serve as a test bed for the bindings in OCaml and
other languages by checking the Postscript files that are generated by
each example against those generated by the C versions.  These examples
have been completely re-written in OCaml (but retain a C flavor in their
structure and the names that are given to objects).  All of the OCaml
examples generate exactly the same Postscript as the C versions.


File: plplotdoc.info,  Node: Obtaining the Software <1>,  Next: How to use the OCaml bindings,  Prev: The Examples <1>,  Up: OCaml Language

11.4 Obtaining the Software
===========================

There are three software components that you will need: the OCaml
compiler, the PLplot library, and the camlidl stub code generator for
OCaml bindings to C libraries.

* Menu:

* Obtaining the OCaml compiler::


File: plplotdoc.info,  Node: Obtaining the OCaml compiler,  Up: Obtaining the Software <1>

11.4.1 Obtaining the OCaml compiler
-----------------------------------

You will need the OCaml compiler in order to build and use the OCaml
PLplot bindings.  OCaml includes both a byte code compiler (ocamlc) and
a native code compiler (ocamlopt).  Both of these are supported by
PLplot.

   Your computer may already have OCaml installed, or you can download
it from caml.inria.fr (http://caml.inria.fr/).  Several Linux
distributions including Debian, Ubuntu and Fedora have OCaml binary
packages available.  Another route to obtaining OCaml is by using opam,
a source-based distribution of OCaml and a number of OCaml libraries.
opam can be retrieved from opam.ocaml.org (http://opam.ocaml.org/).


File: plplotdoc.info,  Node: How to use the OCaml bindings,  Next: Known Issues,  Prev: Obtaining the Software <1>,  Up: OCaml Language

11.5 How to use the OCaml bindings
==================================

The three examples provided below illustrate the available methods for
generating plots with PLplot from OCaml.  They proceed in order from
lowest-level to highest-level.

* Menu:

* How to setup findlib for use with the OCaml bindings::
* Sample command line project (core API): Sample command line project [core API].
* Sample command line project (OCaml-specific API): Sample command line project [OCaml-specific API].
* Sample toplevel project::


File: plplotdoc.info,  Node: How to setup findlib for use with the OCaml bindings,  Next: Sample command line project [core API],  Up: How to use the OCaml bindings

11.5.1 How to setup findlib for use with the OCaml bindings
-----------------------------------------------------------

The following examples require that findlib
(http://projects.camlcity.org/projects/findlib.html) and its associated
tools (i.e., ocamlfind) are installed in in your ‘$PATH’.

   If PLplot was installed under a non-standard prefix, or any prefix
where findlib does not check automatically for OCaml libraries, then the
following environment variables can be set to tell findlib where to look
for PLplot:


             export OCAMLPATH=$PLPLOT_INSTALL_PREFIX/lib/ocaml:$OCAMLPATH
             export LD_LIBRARY_PATH=$PLPLOT_INSTALL_PREFIX/lib/ocaml/stublibs:$LD_LIBRARY_PATH



File: plplotdoc.info,  Node: Sample command line project [core API],  Next: Sample command line project [OCaml-specific API],  Prev: How to setup findlib for use with the OCaml bindings,  Up: How to use the OCaml bindings

11.5.2 Sample command line project (core API)
---------------------------------------------

Here is a simple example that can be compiled and run from the command
line.  The result will be a program that generates a plot of part of a
parabola using only the core PLplot API.


             (* Open the Plplot module to give access to all of the PLplot
                values without the need to add the "Plplot." prefix. *)
             open Plplot

             let simple_example () =
               (* Sample at 20 points, ranging from -10.0 to 10.0 *)
               let xs = Array.init 21 (fun xi -> float xi -. 10.0) in
               let ys = Array.map (fun x -> x**2.0) xs in

               (* Initialize PLplot *)
               plinit ();

               (* Draw the plot window axes *)
               plenv (-10.0) 10.0 0.0 100.0 0 0;

               (* Draw the parabola points as a series of line segments *)
               plline xs ys;

               (* End the plotting session *)
               plend ();
               ()

             let () = simple_example ()


   Save this code as ‘simple_example_core.ml’.  The following command
can then be used to build the example:


             ocamlfind opt -package plplot -linkpkg -o simple_example_core simple_example_core.ml


   The resulting binary program can be run by typing
‘./simple_example_core’


File: plplotdoc.info,  Node: Sample command line project [OCaml-specific API],  Next: Sample toplevel project,  Prev: Sample command line project [core API],  Up: How to use the OCaml bindings

11.5.3 Sample command line project (OCaml-specific API)
-------------------------------------------------------

Here is another example that can be compiled and run from the command
line.  The result will be a program that generates a plot of part of a
parabola similar to the above example, but now using the OCaml-specific
PLplot API rather than the core PLplot API.


             (* Open the Plplot module to give access to all of the PLplot
                values without the need to add the "Plplot." prefix.
                Aliasing the module P to the module Plot will save some typing
                without further namespace pollution. *)
             open Plplot
             module P = Plot

             let simple_example () =
               (* Initialize a new plot, using the windowed Cairo device
                  ("xcairo") *)
               let p =
                 P.init (-10.0, 0.0) (10.0, 100.0) `greedy (`window `cairo)
               in

               (* Draw the parabola *)
               P.plot ~stream:p [P.func `blue (fun x -> x ** 2.0) (-10.0, 10.0)];

               (* Draw the plot axes and close up the plot stream using the default
                  spacing between tick marks. *)
               P.finish ~stream:p ();
               ()

             let () = simple_example ()


   Save this code as ‘simple_example_ocaml.ml’.  The following command
can then be used to build the example:


             ocamlfind opt -package plplot -linkpkg -o simple_example_ocaml simple_example_ocaml.ml


   The resulting binary program can be run by typing
‘./simple_example_ocaml’


File: plplotdoc.info,  Node: Sample toplevel project,  Prev: Sample command line project [OCaml-specific API],  Up: How to use the OCaml bindings

11.5.4 Sample toplevel project
------------------------------

The OCaml interactive toplevel (‘ocaml’) provides a very useful tool for
code testing, development and interactive data analysis.

   The ‘Quick_plot’ module provides a set of functions for producing
quick, simple two-dimensional plots from both the toplevel and
stand-alone OCaml programs.  Here is a set of commands which can be used
in a toplevel session to produce a plot of a portion of a parabola,
similar to the compiled examples above.


             # #use "topfind";;
             # #require "plplot";;
             # open Plplot;;
             # Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0);;


   Conversely, the above ‘ocaml’ session could be expressed in a
compiled OCaml program:


             Plplot.Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0)


   Save this code as ‘simple_example_quick.ml’.  The following command
can then be used to build the example:


             ocamlfind opt -package plplot -linkpkg -o simple_example_quick simple_example_quick.ml


   The resulting binary program can be run by typing
‘./simple_example_quick’


File: plplotdoc.info,  Node: Known Issues,  Prev: How to use the OCaml bindings,  Up: OCaml Language

11.6 Known Issues
=================

There are currently no known issues with the OCaml PLplot bindings.  If
you discover any problems with PLplot or the OCaml bindings, please
report them to the PLplot development mailing list.


File: plplotdoc.info,  Node: Using PLplot from Perl,  Next: Using PLplot from Python,  Prev: OCaml Language,  Up: Supported computer languages

12 Using PLplot from Perl
*************************

There are no proper bindings for the Perl language delivered with the
PLplot sources.  However, a PLplot interface has been added to the Perl
Data Language (PDL) since version 2.4.0.  If the PLplot library is
installed in the system, it is automatically detected by the PDL
configuration script, such that PLplot support for PDL should work out
of the box.  For further information see the PDL homepage
(http://pdl.perl.org).

   The PDL PLplot interface (PDL::Graphics::PLplot) can interact with
PLplot in two ways: (1) A low level mapping one to one mapping of perl
functions to PLplot API functions and (2) A high level object oriented
wrapper that simplifies generating 2D plots.  The PLplot source
distribution contains multiple examples of how to use the low level
interface (see examples/perl).  A key thing to note is that, due to the
architecture of PDL, all the array arguments to a function come first,
followed by the scalars.  This means that the argument order for some of
the functions in the PLplot API is different when called from PDL.

   Here is an usage example comparing the low level and the object
oriented interfaces to PLplot.


           use PDL;
           use PDL::Graphics::PLplot;

           my $x = pdl (0..5);
           my $y = $x ** 2;

           # low level interface

           plsdev ("xwin");
           plinit ();
           plcol0 (1);

           plenv (-0.5, 5.5, -1, 26, 0, 0);
           plline ($x, $y);

           plend ();

           # OO interface

           my $pl = PDL::Graphics::PLplot->new (DEV => "xwin", );
           $pl->xyplot($x, $y, TITLE => 'X vs. Y');
           $pl->close;


   There is also a Perl PLplot interface on CPAN (http://www.cpan.org)
which is not dependent on PDL. The Perl module is called
Graphics::PLplot (http://search.cpan.org/~tjenness/Graphics-PLplot/) and
is appropriate for small data arrays.  The API is very similar to the C
API except that if the number of elements in an array is required by the
C function the perl interface calculates it automatically.  Also, return
values are returned and not supplied as arguments.  Here is the PDL
example above translated to Graphics::PLplot:


           use Graphics::PLplot qw/ :all /;

           @x = (0..5);
           @y = map {$_ * $_} @x;

           plsdev ("xwin");
           plinit ();
           plcol0 (1);

           plenv (-0.5, 5.5, -1, 26, 0, 0);
           plline (\@x, \@y);

           plend ();



File: plplotdoc.info,  Node: Using PLplot from Python,  Next: Using PLplot from Tcl,  Prev: Using PLplot from Perl,  Up: Supported computer languages

13 Using PLplot from Python
***************************

NEEDS DOCUMENTATION, but here is the short story.  We currently
(February, 2001) have switched to dynamic loading of plplot following
the generic method given in the python documentation.  Most (???)  of
the PLplot common API has been implemented.  (For a complete list see
plmodules.c and plmodules2.c).  With this dynamic method all the xw??.py
examples work fine and should be consulted for the best way to use
PLplot from python.  You may have to set PYTHONPATH to the path where
plmodule.so is located (or eventually installed).  For more information
see examples/python/README

   pytkdemo and the x??.py examples it loads use the plframe widget.
Thus, this method does not currently work under dynamic loading.  They
have only worked in the past using the static method with much hacking
and rebuilding of python itself.  We plan to try dynamic loading of all
of PLplot (not just the plmodule.c and plmodule2.c wrappers) including
plframe (or a python-variant of this widget) into python at some future
date to see whether it is possible to get pytkdemo and the x??.py
examples working under dynamic loading, but only the individual
stand-alone xw??.py demos work at the moment.


File: plplotdoc.info,  Node: Using PLplot from Tcl,  Next: Building an Extended WISH,  Prev: Using PLplot from Python,  Up: Supported computer languages

14 Using PLplot from Tcl
************************

PLplot has historically had C and Fortran language bindings.  PLplot
version 5.0 introduces a plethora of new programming options including
C++ (described earlier) and several script language bindings.  The Tcl
interface to PLplot (which the PLplot maintainers regard as the
‘primary’ script language binding) is described in this chapter, with
further discussion of Tcl related issues following in additional
chapters.  But Tcl is certainly not the only script language option.
Bindings to Perl, Python, and Scheme (which is actually another compiled
language, but still has some of the flavor of a VHLL) are in various
stages of completion, and are described in separate chapters.  Use the
one that suits you best–or try them all!

* Menu:

* Motivation for the Tcl Interface to PLplot::
* Overview of the Tcl Language Binding::
* The PLplot Tcl Matrix Extension::
* Contouring and Shading from Tcl::
* Understanding the Performance Characteristics of Tcl::


File: plplotdoc.info,  Node: Motivation for the Tcl Interface to PLplot,  Next: Overview of the Tcl Language Binding,  Up: Using PLplot from Tcl

14.1 Motivation for the Tcl Interface to PLplot
===============================================

The recent emergence of several high quality VHLL script languages such
as Tcl, Perl, Python and arguably even some Lisp variants, is having a
profound effect upon the art of computer programming.  Tasks which have
traditionally been handled by C or Fortran, are beginning to be seen in
a new light.  With relatively fast processors now widely available, many
programming jobs are no longer bound by execution time, but by ‘human
time’.  Rapidity of initial development and continued maintenance, for a
surprisingly wide class of applications, is far more important than
execution time.  Result: in a very short period of time, say from 1993
to 1995, script languages have exploded onto the scene, becoming
essential tools for any serious programmer.

   Moreover, the entire concept of ‘speed of execution’ needs revising
in the face of the gains made in computer hardware in recent years.
Saying that script language processing is slower than compiled language
processing may be undeniable and simultaneously irrelevant.  If the
script language processing is fast enough, then it is fast enough.
Increasingly, computational researchers are finding that script based
tools are indeed fast enough.  And if their run time is fast enough, and
their development and maintenance time is much much better, then why
indeed should they not be used?

   Even in a field with several high visibility players, Tcl has
distinguished itself as a leading contender.  There are many reasons for
this, but perhaps the most important, at least as it relates to the
PLplot user community, is that Tcl was designed to be extensible and
embeddable.  The whole purpose of Tcl, as it name (Tool Command
Language) indicates, is to be a command language for other tools.  In
other words, the fact that Tcl is capable of being a standalone shell is
interesting, even useful, but nonetheless incidental.  The real
attraction of Tcl is that it can be the shell language for _your_ code.
Tcl can easily be embedded into your code, endowing it immediately with
a full featured, consistent and well documented script programming
language, providing all the core features you need in a programming
language: variables, procedures, control structures, error trapping and
recovery, tracing, etc.  But that is only the beginning!  After that,
you can easily extend Tcl by adding commands to the core language, which
invoke the capabilities of your tool.  It is in this sense that Tcl is a
tool command language.  It is a command language which you can augment
to provide access to the facilities of your tool.

   But Tcl is more than just an embeddable, extensible script language
for personal use.  Tcl is an industry, an internet phenomenon.  There
are currently at least two high quality books, with more on the way.
There is an industry of service providers and educators.  Furthermore,
literally hundreds of Tcl extensions exist, and are readily available
over the net.  Perhaps the most notable extension, Tk, provides a
fantastic interface to X Windows widget programming, permitting the
construction of Motif like user interfaces, with none of the hassles of
actually using Motif.  Some of these extensions endow Tcl with object
oriented facilities philosophically similar to C++ or other object
oriented languages.  Other extensions provide script level access to
system services.  Others provide a script interface to sockets, RPC, and
other network programming protocols.  The list goes on and on.  Dive
into the Tcl archive, and see what it has for you!

   So, the answer to the question ‘Why do we want a Tcl interface to
PLplot?’ is very simple.  ‘Because we we are using Tcl anyway, as the
command language for our project, and would like to be able to do
plotting in the command language just as we do so many other things.’

   But there is more than just the aesthetics of integration to
consider.  There are also significant pragmatic considerations.  If you
generate your PLplot output via function calls from a compiled language,
then in order to add new diagnostics to your code, or to refine or
embellish existing ones, you have to edit the source, recompile, relink,
and rerun the code.  If many iterations are required to get the plot
right, significant time can be wasted.  This can be especially true in
the case of C++ code making heavy use of templates, for which many C++
compilers will have program link times measured in minutes rather than
seconds, even for trivial program changes.

   In contrast, if the diagnostic plot is generated from Tcl, the
development cycle looks more like: start the shell (command line or
windowing), source a Tcl script, issue the command to generate the plot,
notice a bug, edit the Tcl script, resource the script, and regenerate
the plot.  Notice that compiling, linking, and restarting the program,
have all been dropped from the development cycle.  The time savings from
such a development cycle can be amazing!


File: plplotdoc.info,  Node: Overview of the Tcl Language Binding,  Next: The PLplot Tcl Matrix Extension,  Prev: Motivation for the Tcl Interface to PLplot,  Up: Using PLplot from Tcl

14.2 Overview of the Tcl Language Binding
=========================================

Each of the PLplot calls available to the C or Fortran programmer are
also available from Tcl, with the same name and generally the same
arguments.  Thus for instance, whereas in C you can write:


           plenv( 0., 1., 0., 1., 0, 0 );
           pllab( "(x)", "(y)", "The title of the graph" );


   you can now write in Tcl:


           plenv 0 1 0 1 0 0
           pllab "(x)" "(y)" "The title of the graph"


   All the normal Tcl rules apply, there is nothing special about the
PLplot extension commands.  So, you could write the above as:


           set xmin 0; set xmax 1; set ymin 0; set ymax 1
           set just 0; set axis 0
           set xlab (x)
           set ylab (y)
           set title "The title of the graph"
           plenv $xmin $xmax $ymin $ymax $just $axis
           pllab $xlab $ylab $title


   for example.  Not that there is any reason to be loquacious for its
own sake, of course.  The point is that you might have things like the
plot bounds or axis labels stored in Tcl variables for some other reason
(tied to a Tk entry widget maybe, or provided as the result of one of
your application specific Tcl extension commands, etc), and just want to
use standard Tcl substitution to make the PLplot calls.

   Go ahead and try it!  Enter ‘pltcl’ to start up the PLplot extended
Tcl shell, and type (or paste) in the commands.  Or put them in a file
and source it.  By this point it should be clear how incredibly easy it
is to use the PLplot Tcl language binding.

   In order to accommodate the ubiquitous requirement for matrix
oriented data in scientific applications, and in the PLplot API in
particular, PLplot includes a Tcl extension for manipulating matrices in
Tcl.  This Tcl Matrix Extension provides a straightforward and direct
means of representing one and two dimensional matrices in Tcl.  The Tcl
Matrix Extension is described in detail in the next section, but we
mention its existence now just so that we can show how the PLplot Tcl
API works.  Many of the PLplot Tcl API functions accept Tcl matrices as
arguments.  For instance, in C you might write:


           float x[100], y[100];

           /* code to initialize x and y */

           plline( 100, x, y );


   In Tcl you can write:


           matrix x f 100
           matrix y f 100

           # code to initialize x and y

           plline x y


N.B. Our Tcl binding uses a redacted API which is why the redundant
dimension of the x and y arrays must be dropped from the plline call.

   Some of the PLplot C function calls use pointer arguments to allow
retrieval of PLplot settings.  These are implemented in Tcl by changing
the value of the variable whose name you provide.  For example:


           pltcl> plgxax
           wrong # args: should be "plgxax digmax digits  "
           pltcl> set digmax 0
           0
           pltcl> set digits 0
           0
           pltcl> plgxax digmax digits
           pltcl> puts "digmax=$digmax digits=$digits"
           digmax=4 digits=0


   This example shows that each PLplot Tcl command is designed to issue
an error if you invoke it incorrectly, which in this case was used to
remind us of the correct arguments.  We then create two Tcl variables to
hold the results.  Then we invoke the PLplot ‘plgxax’ function to obtain
the label formatting information for the x axis.  And finally we print
the results.

   People familiar with Tcl culture may wonder why the ‘plg*’ series
functions don’t just pack their results into the standard Tcl result
string.  The reason is that the user would then have to extract the
desired field with either ‘lindex’ or ‘regexp’, which seems messy.  So
instead, we designed the PLplot Tcl API to look and feel as much like
the C API as could reasonably be managed.

   In general then, you can assume that each C function is provided in
Tcl with the same name and same arguments (and one or two dimensional
arrays in C are replaced by Tcl matrices).  There are only a few
exceptions to this rule, generally resulting from the complexity of the
argument types which are passed to some functions in the C API. Those
exceptional functions are described below, all others work in the
obvious way (analogous to the examples above).

   See the Tcl example programs for extensive demonstrations of the
usage of the PLplot Tcl API. To run the Tcl demos:


           % pltcl
           pltcl> source tcldemos.tcl
           pltcl> 1
           pltcl> 2


   Alternatively, you can run ‘plserver’ and source ‘tkdemos.tcl’.

   In any event, the Tcl demos provide very good coverage of the Tcl
API, and consequently serve as excellent examples of usage.  For the
most part they draw the same plots as their C counterpart.  Moreover,
many of them were constructed by literally inserting the C code into the
Tcl source file, and performing fairly mechanical transformations on the
source.  This should provide encouragement to anyone used to using
PLplot through one of the compiled interfaces, that they can easily and
rapidly become productive with PLplot in Tcl.


File: plplotdoc.info,  Node: The PLplot Tcl Matrix Extension,  Next: Contouring and Shading from Tcl,  Prev: Overview of the Tcl Language Binding,  Up: Using PLplot from Tcl

14.3 The PLplot Tcl Matrix Extension
====================================

Tcl does many things well, but handling collections of numbers is not
one of them.  You could make lists, but for data sets of sizes relevant
to scientific graphics which is the primary domain of applicability for
PLplot, the extraction time is excessive and burdensome.  You could use
Tcl arrays, but the storage overhead is astronomical and the lookup
time, while better than list manipulation, is still prohibitive.

   To cope with this, a Tcl Matrix extension has been created for the
purpose of making it feasible to work with large collections of numbers
in Tcl, in a way which is storage efficient, reasonably efficient for
accesses from Tcl, and reasonably compatible with practices used in
compiled code.

* Menu:

* Using Tcl Matrices from Tcl::
* Using Tcl Matrices from C::
* Using Tcl Matrices from C++::
* Extending the Tcl Matrix facility::


File: plplotdoc.info,  Node: Using Tcl Matrices from Tcl,  Next: Using Tcl Matrices from C,  Up: The PLplot Tcl Matrix Extension

14.3.1 Using Tcl Matrices from Tcl
----------------------------------

Much like the Tk widget creation commands, the Tcl ‘matrix’ command
considers its first argument to be the name of a new command to be
created, and the rest of the arguments to be modifiers.  After the name,
the next argument can be ‘float’ or ‘int’ or contractions thereof.  Next
follow a variable number of size arguments which determine the size of
the matrix in each of its dimensions.  For example:


     	matrix x f 100
     	matrix y i 64 64


   constructs two matrices.  ‘x’ is a float matrix, with one dimension
and 100 elements.  ‘y’ is an integer matrix, and has 2 dimensions each
of size 64.

   Additionally a matrix can be initialized when it is created, e.g.,


     	matrix x f 4 = { 1.5, 2.5, 3.5, 4.5 }


   The ‘matrix’ command supports subcommands such as ‘info’ which
reports the number of elements in each dimension, e.g.,


     	pltcl> matrix x f 4
     	pltcl> x info
     	4
     	pltcl> matrix y i 8 10
     	pltcl> y info
     	8 10


Other useful subcommands are ‘delete’ to delete the matrix (if, for
example, you wanted to use that variable name for something else such as
a differently dimensioned matrix) and ‘help’ to document all subcommands
possible with a given matrix.

   A Tcl matrix is a command, and as longtime Tcl users know, Tcl
commands are globally accessible.  The PLplot Tcl Matrix extension
attempts to lessen the impact of this by registering a variable in the
local scope, and tracing it for insets, and deleting the actual matrix
command when the variable goes out of scope.  In this way, a Tcl matrix
appears to work sort of like a variable.  It is, however, just an
illusion, so you have to keep this in mind.  In particular, you may want
the matrix to outlive the scope in which it was created.  For example,
you may want to create a matrix, load it with data, and then pass it off
to a Tk megawidget for display in a spreadsheet like form.  The proc
which launches the Tk megawidget will complete, but the megawidget, and
the associated Tcl matrix are supposed to hang around until they are
explicitly destroyed.  To achieve this effect, create the Tcl matrix
with the ‘-persist’ flag.  If present (can be anywhere on the line), the
matrix is not automatically deleted when the scope of the current proc
(method) ends.  Instead, you must explicitly clean up by using either
the ’delete’ matrix command or renaming the matrix command name to {}.
Now works correctly from within [incr Tcl].

   As mentioned above, the result of creating a matrix is that a new
command of the given name is added to the interpreter.  You can then
evaluate the command, providing indices as arguments, to extract the
data.  For example:


     	pltcl> matrix x f = {1.5, 2.5, 3.5, 4.5}
     	insufficient dimensions given for Matrix operator "x"
     	pltcl> matrix x f 4 = {1.5, 2.5, 3.5, 4.5}
     	pltcl> x 0
     	1.500000
     	pltcl> x 1
     	2.500000
     	pltcl> x 3
     	4.500000
     	pltcl> x :
     	1.500000 2.500000 3.500000 4.500000
     	pltcl> puts "x\[1\]=[x 1]"
     	x[1]=2.500000
     	pltcl> puts "x\[:\] = [x :]"
     	x[:] = 1.500000 2.500000 3.500000 4.500000
     	pltcl> foreach v [x *] { puts $v }
     	1.500000
     	2.500000
     	3.500000
     	4.500000
     	pltcl> for {set i 0} {$i < 4} {incr i} {
     	if {[x $i] < 3} {puts [x $i]} }
     	1.500000
     	2.500000


   Note from the above that the output of evaluating a matrix indexing
operation is suitable for use in condition processing, list processing,
etc.

   You can assign to matrix locations in a similar way:


     	pltcl> x 2 = 7
     	pltcl> puts "[x :]"
     	1.500000 2.500000 7.000000 4.500000
     	pltcl> x : = 3
     	pltcl> puts "[x :]"
     	3.000000 3.000000 3.000000 3.000000


   Note that the : provides a means of obtaining an index range, and
that it must be separated from the = by a space.  This is a simple
example of matrix index slices, and a full index slice capability has
been implemented following what is available for Python (see Note 5 of
<https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>
for Python 2 or Note 5 of
<https://docs.python.org/3/library/stdtypes.html#common-sequence-operations>
for Python 3).  Each index slice is represented by a colon-separated
list of three integers, i:j:k, which designate the index range and
increment.  The default value of k is 1.  For positive k the default
values of i and j are 0 and the number of elements in the dimension
while for negative k, the default values of i and j the number of
elements in the dimension and 0.  Negative values of i and j have the
number of elements in the dimension added to them.  After these rules
have been applied to determine the final i, j, and k values the slice
from i to j with step k is defined as the sequence of items with index x
= i + n*k such that 0 ≤ n < (j-i)/k.  N.B. rational division is used to
calculate the last limit of this expression.  As a result the indices in
the slice are i, i+k, i+2*k, i+3*k and so on, stopping when j is reached
(but never including j).  Some examples (see
‘bindings/tcl/test_tclmatrix.tcl’) of using this slice notation are
given by the following Tcl code:


     puts "Create one-dimensional x matrix using \"matrix x f 4 = {0., 1., 2., 3.}\""
     matrix x f 4 = {0., 1., 2., 3.}
     puts "Various start:stop:step slice examples for this matrix"
     puts "Examples where start, stop, and step are default"
     puts "\[x :\] yields [x :]"
     puts "\"*\" (implemented for backwards compatibility) has exactly the same effect as \":\""
     puts "\[x *\] yields [x *]"
     puts "\"::\" has exactly the same effect as \":\""
     puts "\[x ::\] yields [x ::]"
     puts "Examples where start and stop are default"
     puts "\[x ::1\] yields [x ::1]"
     puts "\[x ::2\] yields [x ::2]"
     puts "\[x ::3\] yields [x ::3]"
     puts "\[x ::4\] yields [x ::4]"
     puts "\[x ::-1\] yields [x ::-1]"
     puts "\[x ::-2\] yields [x ::-2]"
     puts "\[x ::-3\] yields [x ::-3]"
     puts "\[x ::-4\] yields [x ::-4]"
     puts "Examples where start and step are default"
     puts "\[x :2:\] yields [x :2:]"
     puts "\[x :2\] yields [x :2]"
     puts "Examples where stop and step are default"
     puts "\[x 2::\] yields [x 2::]"
     puts "\[x 2:\] yields [x 2:]"
     puts "Examples where start is default"
     puts "\[x :3:2\] yields [x :3:2]"
     puts "\[x :-4:-2\] yields [x :-4:-2]"
     puts "Examples where stop is default"
     puts "\[x 1::2\] yields [x 1::2]"
     puts "\[x -2::-2\] yields [x -2::-2]"
     puts "Examples where step is default"
     puts "\[x 1:3:\] yields [x 1:3:]"
     puts "\[x 1:3\] yields [x 1:3]"
     puts "Examples where start, stop, and step are all explicitly specified"
     puts "\[x 1:0:2\] yields [x 1:0:2]"
     puts "\[x 1:1:2\] yields [x 1:1:2]"
     puts "\[x 1:2:2\] yields [x 1:2:2]"
     puts "\[x 1:3:2\] yields [x 1:3:2]"
     puts "\[x 1:4:2\] yields [x 1:4:2]"
     puts "\[x 1:5:2\] yields [x 1:5:2]"
     puts "\[x -2:-1:-2\] yields [x -2:-1:-2]"
     puts "\[x -2:-2:-2\] yields [x -2:-2:-2]"
     puts "\[x -2:-3:-2\] yields [x -2:-3:-2]"
     puts "\[x -2:-4:-2\] yields [x -2:-4:-2]"
     puts "\[x -2:-5:-2\] yields [x -2:-5:-2]"
     puts "\[x -2:-6:-2\] yields [x -2:-6:-2]"


which generates (see ‘bindings/tcl/test_tclmatrix.out’) the following
results:


     Create one-dimensional x matrix using "matrix x f 4 = {0., 1., 2., 3.}"
     Various start:stop:step slice examples for this matrix
     Examples where start, stop, and step are default
     [x :] yields 0.0 1.0 2.0 3.0
     "*" (implemented for backwards compatibility) has exactly the same effect as ":"
     [x *] yields 0.0 1.0 2.0 3.0
     "::" has exactly the same effect as ":"
     [x ::] yields 0.0 1.0 2.0 3.0
     Examples where start and stop are default
     [x ::1] yields 0.0 1.0 2.0 3.0
     [x ::2] yields 0.0 2.0
     [x ::3] yields 0.0 3.0
     [x ::4] yields 0.0
     [x ::-1] yields 3.0 2.0 1.0 0.0
     [x ::-2] yields 3.0 1.0
     [x ::-3] yields 3.0 0.0
     [x ::-4] yields 3.0
     Examples where start and step are default
     [x :2:] yields 0.0 1.0
     [x :2] yields 0.0 1.0
     Examples where stop and step are default
     [x 2::] yields 2.0 3.0
     [x 2:] yields 2.0 3.0
     Examples where start is default
     [x :3:2] yields 0.0 2.0
     [x :-4:-2] yields 3.0 1.0
     Examples where stop is default
     [x 1::2] yields 1.0 3.0
     [x -2::-2] yields 2.0 0.0
     Examples where step is default
     [x 1:3:] yields 1.0 2.0
     [x 1:3] yields 1.0 2.0
     Examples where start, stop, and step are all explicitly specified
     [x 1:0:2] yields
     [x 1:1:2] yields
     [x 1:2:2] yields 1.0
     [x 1:3:2] yields 1.0
     [x 1:4:2] yields 1.0 3.0
     [x 1:5:2] yields 1.0 3.0
     [x -2:-1:-2] yields
     [x -2:-2:-2] yields
     [x -2:-3:-2] yields 2.0
     [x -2:-4:-2] yields 2.0
     [x -2:-5:-2] yields 2.0 0.0
     [x -2:-6:-2] yields 2.0 0.0


   We have already shown examples of matrix initialization above where
the RHS (right hand side) expression beyond the "=" sign was a simple
list of numbers and also an example of an matrix slice assignment above
where the RHS was a simple number, but much more complex RHS expressions
(arbitrary combinations of lists of lists and matrix slices) are allowed
for both matrix initialization and matrix slice assignment.
Furthermore, the RHS matrices are read from and the LHS (left hand side)
matrix or matrix slice are written to in row major order
(https://en.wikipedia.org/wiki/Row_major), and excess elements on the
RHS are ignored while excess elements on the LHS of a matrix
initialization or matrix slice assignment are zeroed.  Some examples
(see ‘bindings/tcl/test_tclmatrix.tcl’) of using these matrix
initialization and matrix slice assignment capabilities are given by the
following Tcl code:


     puts "Various matrix initializations and assignments"
     puts "Using a collection of space-separated numbers"
     matrix x f 4 = 1 2 3 4
     puts "\[x :\] = [x :]"
     matrix y f 2 4
     y : : = 1 2 3 4 5 6 7 8
     puts "\[y : :\] = [y : :]"
     x delete
     y delete
     puts "Using a list of lists of numbers"
     matrix x f 4 = {{{1 2}} {3 4}}
     puts "\[x :\] = [x :]"
     matrix y f 2 4
     y : : = {{1 2 3 4 5} {{6}} {7 8}}
     puts "\[y : :\] = [y : :]"
     puts "Using slices of a previously defined matrix"
     matrix z f 2 2 2 = [x ::] [x ::-1]
     puts "\[z : : :\] = [z : : :]"
     y : : = [x ::] [x ::-1]
     puts "\[y : :\] = [y : :]"
     puts "Combination of previously defined matrices, deep lists, and space-separated numbers"
     matrix a f 2 2 3 = [x ::] [x ::-1] {{{1.E-13} {2}}} 3 4 5 6 7 8 9 10 11 12 13 14
     puts "\[a : : :\] = [a : : :]"
     matrix b f 2 2 3
     b : : : = [x ::] [x ::-1] {{{1.E-13} {2}}} 3 4 5 6 7 8 9 10 11 12 13 14
     puts "\[b : : :\] = [b : : :]"


which generates (see ‘bindings/tcl/test_tclmatrix.out’) the following
results:


     Various matrix initializations and assignments
     Using a collection of space-separated numbers
     [x :] = 1.0 2.0 3.0 4.0
     [y : :] = 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0
     Using a list of lists of numbers
     [x :] = 1.0 2.0 3.0 4.0
     [y : :] = 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0
     Using slices of a previously defined matrix
     [z : : :] = 1.0 2.0 3.0 4.0 4.0 3.0 2.0 1.0
     [y : :] = 1.0 2.0 3.0 4.0 4.0 3.0 2.0 1.0
     Combination of previously defined matrices, deep lists, and space-separated numbers
     [a : : :] = 1.0 2.0 3.0 4.0 4.0 3.0 2.0 1.0 1e-13 2.0 3.0 4.0
     [b : : :] = 1.0 2.0 3.0 4.0 4.0 3.0 2.0 1.0 1e-13 2.0 3.0 4.0


A method of testing the matrix slice, initialization, and assignment
capabilities using ‘bindings/tcl/test_tclmatrix.tcl’ and
‘bindings/tcl/test_tclmatrix.out’ has been given in
‘examples/tcl/README.tcldemos’.


File: plplotdoc.info,  Node: Using Tcl Matrices from C,  Next: Using Tcl Matrices from C++,  Prev: Using Tcl Matrices from Tcl,  Up: The PLplot Tcl Matrix Extension

14.3.2 Using Tcl Matrices from C
--------------------------------

Normally you will create a matrix in Tcl, and then want to pass it to C
in order to have the data filled in, or existing data to be used in a
computation, etc.  To do this, pass the name of the matrix command as an
argument to your C Tcl command procedure.  The C code should include
‘tclMatrix.h’, which has a definition for the ‘tclMatrix’ structure.
You fetch a pointer to the ‘tclMatrix’ structure using the
‘Tcl_GetMatrixPtr’ function.

   For example, in Tcl:


     	matrix x f 100
     	wacky x


   and in C:


     	int wackyCmd( ClientData clientData, Tcl_Interp *interp,
     	int argc, char *argv[] )
	     {
     	tclMatrix *w;

     	w = Tcl_GetMatrixPtr( interp, argv[1] );
     	...


   To learn about what else you can do with the matrix once inside
compiled code, read ‘tclMatrix.h’ to learn the definition of the
‘tclMatrix’ structure, and see the examples in files like ‘tclAPI.c’
which show many various uses of the Tcl matrix.


File: plplotdoc.info,  Node: Using Tcl Matrices from C++,  Next: Extending the Tcl Matrix facility,  Prev: Using Tcl Matrices from C,  Up: The PLplot Tcl Matrix Extension

14.3.3 Using Tcl Matrices from C++
----------------------------------

Using a Tcl matrix from C++ is very much like using it from C, except
that ‘tclMatrix.h’ contains some C++ wrapper classes which are somewhat
more convenient than using the indexing macros which one has to use in
C. For example, here is a tiny snippet from one of the authors codes in
which Tcl matrices are passed in from Tcl to a C++ routine which is
supposed to fill them in with values from some matrices used in the
compiled side of the code:


     	...
     	if (item == "vertex_coords") {
     	tclMatrix *matxg = Tcl_GetMatrixPtr( interp, argv[1] );
     	tclMatrix *matyg = Tcl_GetMatrixPtr( interp, argv[2] );

     	Mat2<float> xg(ncu, ncv), yg(ncu, ncv);
     	cg->Get_Vertex_Coords( xg, yg );

     	TclMatFloat txg( matxg ), tyg( matyg );

     	for( i=0; i < ncu; i++ )
     	for( j=0; j < ncv; j++ ) {
     	txg(i,j) = xg(i,j);
     	tyg(i,j) = yg(i,j);
	     }


   There are other things you can do too, see the definitions of the
‘TclMatFloat’ and ‘TclMatInt’ classes in ‘tclMatrix.h’.


File: plplotdoc.info,  Node: Extending the Tcl Matrix facility,  Prev: Using Tcl Matrices from C++,  Up: The PLplot Tcl Matrix Extension

14.3.4 Extending the Tcl Matrix facility
----------------------------------------

The Tcl matrix facility provides creation, indexing, and information
gathering facilities.  However, considering the scientifically inclined
PLplot user base, it is clear that some users will demand more.
Consequently there is a mechanism for augmenting the Tcl matrix facility
with your own, user defined, extension subcommands.  Consider ‘xtk04.c’.
In this extended wish, we want to be able to determine the minimum and
maximum values stored in a matrix.  Doing this in Tcl would involve
nested loops, which in Tcl would be prohibitively slow.  We could
register a Tcl extension command to do it, but since the only sensible
data for such a command would be a Tcl matrix, it seems nice to provide
this facility as an actual subcommand of the matrix.  However, the
PLplot maintainers cannot foresee every need, so a mechanism is provided
to register subcommands for use with matrix objects.

   The way to register matrix extension subcommands is to call
‘Tcl_MatrixInstallXtnsn’:


     	typedef int (*tclMatrixXtnsnProc) ( tclMatrix *pm, Tcl_Interp *interp,
     	int argc, char *argv[] );

     	int Tcl_MatrixInstallXtnsn( char *cmd, tclMatrixXtnsnProc proc );


   In other words, make a function for handling the matrix extension
subcommand, with the same function signature (prototype) as
‘tclMatrixXtnsnProc’, and register the subcommand name along with the
function pointer.  For example, xtk04.c has:


     	int mat_max( tclMatrix *pm, Tcl_Interp *interp,
     	int argc, char *argv[] )
	     {
     	float max = pm->fdata[0];
     	int i;
     	for( i=1; i < pm->len; i++ )
     	if (pm->fdata[i] > max)
     	max = pm->fdata[i];

     	sprintf( interp->result, "%f", max );
     	return TCL_OK;
	     }

     	int mat_min( tclMatrix *pm, Tcl_Interp *interp,
     	int argc, char *argv[] )
	     {
     	float min = pm->fdata[0];
     	int i;
     	for( i=1; i < pm->len; i++ )
     	if (pm->fdata[i] < min)
     	min = pm->fdata[i];

     	sprintf( interp->result, "%f", min );
     	return TCL_OK;
	     }


   Then, inside the application initialization function (‘Tcl_AppInit()’
to long time Tcl users):


     	Tcl_MatrixInstallXtnsn( "max", mat_max );
     	Tcl_MatrixInstallXtnsn( "min", mat_min );


   Then we can do things like:


     	dino 65: xtk04
     	% matrix x f 4 = {1, 2, 3, 1.5}
     	% x min
     	1.000000
     	% x max
     	3.000000


   Your imagination is your only limit for what you can do with this.
You could add an FFT subcommand, matrix math, BLAS, whatever.


File: plplotdoc.info,  Node: Contouring and Shading from Tcl,  Next: Understanding the Performance Characteristics of Tcl,  Prev: The PLplot Tcl Matrix Extension,  Up: Using PLplot from Tcl

14.4 Contouring and Shading from Tcl
====================================

Contouring and shading has traditionally been one of the messier things
to do in PLplot.  The C API has many parameters, with complex setup and
tear down properties.  Of special concern is that some of the parameters
do not have a natural representation in script languages like Tcl.  In
this section we describe how the Tcl interface to these facilities is
provided, and how to use it.

* Menu:

* Drawing a Contour Plot from Tcl::
* Drawing a Shaded Plot from Tcl::


File: plplotdoc.info,  Node: Drawing a Contour Plot from Tcl,  Next: Drawing a Shaded Plot from Tcl,  Up: Contouring and Shading from Tcl

14.4.1 Drawing a Contour Plot from Tcl
--------------------------------------

By way of reference, the primary C function call for contouring is:


     	void plcont( PLFLT **f, PLINT nx, PLINT ny, PLINT kx, PLINT lx,
     	PLINT ky, PLINT ly, PLFLT *clevel, PLINT nlevel,
     	void (*pltr) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer),
     	PLPointer pltr_data);


   This is a fairly complex argument list, and so for this function (and
for plshade, described below) we dispense with trying to exactly mirror
the C API, and just concentrate on capturing the functionality within a
Tcl context.  To begin with, the data is provided through a 2-d Tcl
matrix.  The Tcl matrix carries along its size information with it, so
‘nx’ and ‘ny’ are no longer needed.  The ‘kx’, ‘lx’, ‘ky’ and ‘ly’
variables are potentially still useful for plotting a subdomain of the
full data set, so they may be specified in the natural way, but we make
this optional since they are frequently not used to convey anything more
than what could be inferred from ‘nx’ and ‘ny’.  However, to simplify
processing, they must be supplied or omitted as a set (all of them, or
none of them).  ‘clevel’ is supplied as a 1-d Tcl matrix, and so
‘nlevel’ can be omitted.

   Finally, we have no way to support function pointers from Tcl, so
instead we provide token based support for accessing the three
coordinate transformation routines which are provided by PLplot, and
which many PLplot users use.  There are thus three courses of action:

   • Provide no pltr specification.  In this case, ‘pltr0’ is used by
     default.

   • Specify ‘pltr1 x y’ where x and y are 1-d Tcl matrices.  In this
     case ‘pltr1’ will be used, and the 1-d arrays which it needs will
     be supplied from the Tcl matrices ‘x’ and ‘y’.

   • Specify ‘pltr2 x y’ where x and y are 2-d Tcl matrices.  In this
     case ‘pltr2’ will be used, and the 2-d arrays which it needs will
     be supplied from the Tcl matrices ‘x’ and ‘y’.

   Now, there can be no question that this is both more concise and less
powerful than what you could get in C. The loss of the ability to
provide a user specified transformation function is regrettable.  If you
really do need that functionality, you will have to implement your own
Tcl extension command to do pretty much the same thing as the provided
Tcl extension command ‘plcont’ (which is in ‘tclAPI.c’ in function
‘plcontCmd()’), except specify the C transformation function of your
choice.

   However, that having been said, we recognize that one common use for
this capability is to provide a special version of ‘pltr2’ which knows
how to implement a periodic boundary condition, so that polar plots, for
example, can be implemented cleanly.  That is, if you want to draw
contours of a polar data set defined on a 64 x 64 grid, ensuring that
contour lines would actually go all the way around the origin rather
than breaking off like a silly pacman figure, then you had basically two
choices in C. You could copy the data to a 65 x 64 grid, and replicate
one row of data into the spare slot, and then plot the larger data set
(taking care to replicate the coordinate arrays you passed to pltr2 in
the same way), _or_ you could make a special version of ‘pltr2’ which
would understand that one of the coordinates was wrapped, and perform
transformations accordingly without actually making you replicate the
data.

   Since the former option is ugly in general, and hard to do in Tcl in
particular, and since the second option is even more difficult to do in
Tcl (requiring you do make a special Tcl extension command as described
above), we provide special, explicit support for this common activity.
This is provided through the use of a new, optional parameter ‘wrap’
which may be specified as the last parameter to the Tcl command, only if
you are using ‘pltr2’.  Supplying ‘1’ will wrap in the first coordinate,
‘2’ will wrap in the second coordinate.

   The resultant Tcl command is:


     	plcont f [kx lx ky ly] clev [pltr x y] [wrap]


   Note that the brackets here are used to signify optional arguments,
_not_ to represent Tcl command substitution!

   The Tcl demo ‘x09.tcl’ provides examples of all the capabilities of
this interface to contouring from Tcl.  Note in particular, ‘x09_polar’
which does a polar contour without doing anything complicated in the way
of setup, and without getting a pacman as the output.

