This is
/tmp/plplot-dist-prep/build_dir/doc/docbook/src/info/plplotdoc.info,
produced by makeinfo version 4.13 from
/tmp/plplot-dist-prep/build_dir/doc/docbook/src/plplotdoc.texi.

INFO-DIR-SECTION Scientific Visualization
START-INFO-DIR-ENTRY
* PLplot: (plplotdoc).   The PLplot Plotting Library
END-INFO-DIR-ENTRY


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

The PLplot Plotting Library
***************************

* Menu:

* Introduction::
* Simple Use of PLplot::
* Advanced Use of PLplot::
* Deploying programs that use PLplot::
* The PLplot Display Driver Family::
* The PLplot Output Driver Family::
* Ada Language::
* C Language::
* A C++ Interface for PLplot::
* Fortran 95 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::
* Bibliography::
* The Common API for PLplot::
* The Specialized C API for PLplot::
* The Specialized Fortran 95 API for PLplot::
* API compatibility definition::
* Obsolete/Deprecated API for PLplot::
* Internal C functions in PLplot::
* Notes for each Operating System that We Support::
* The PLplot Libraries::

— The Detailed Node Listing —

Introduction

* The PLplot Plotting Library::
* Getting a Copy of the PLplot Package::
* Installing and Using the PLplot Library::
* Organization of this Manual::
* Copyrights::
* 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::
* Output 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 Surface Plots::
* Contour and Shade Plots::
* Legends and color bars::

The PLplot Display Driver Family

* The Xwin Driver (X-Windows): The Xwin Driver [X-Windows].
* The Tk Driver::
* The AquaTerm Driver (Mac OS X): The AquaTerm Driver [Mac OS X].
* The wxWidgets Driver (Linux, Mac OS X, Windows): The wxWidgets Driver [Linux; Mac OS X; Windows].

The PLplot Output Driver Family

* The GD Driver::
* The PDF Driver::
* The PostScript Driver::
* The TrueType PostScript Driver::
* The LaTeX PostScript Driver::
* The SVG 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 x error bar : plerrx; Draw x error bar.
* plerry; Draw y error bar : plerry; Draw y error bar.
* 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 character font : plfont; Set character font.
* plfontld; Load character font : plfontld; Load character font.
* 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 double alpha transparency value for given color index from cmap0 : plgcol0a; Returns 8-bit RGB values and double 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 double alpha transparency value : plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and double 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 colour adjustment : plimage; Plot a 2D matrix using cmap1 with automatic colour 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 in world coordinates : plmap; Plot continental outline 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 fill pattern : plpat; Set area 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 double alpha transparency value : plscmap0a; Set cmap0 colors by 8-bit RGB values and double 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 cmap1 colors using 8-bit RGB values : plscmap1; Set cmap1 colors using 8-bit RGB values.
* plscmap1a; Set cmap1 colors using 8-bit RGB values and double alpha transparency values : plscmap1a; Set cmap1 colors using 8-bit RGB values and double alpha transparency values.
* 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 double alpha transparency value for given cmap0 color index : plscol0a; Set 8-bit RGB values and double 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 double alpha transparency value. : plscolbga; Set the background color by 8-bit RGB value and double 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.
* plshade1; Shade individual region on the basis of value : plshade1; 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 colors for color table 0 from a cmap0 file : plspal0; Set the colors for color table 0 from a cmap0 file.
* plspal1; Set the palette for cmap1 using the specified cmap1*.pal format file : plspal1; Set the palette for cmap1 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.
* plfsurf3d; Plot shaded 3-d surface plot : plfsurf3d; Plot shaded 3-d surface plot.
* 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 coordinates : plvpor; Specify viewport using coordinates.
* plvsta; Select standard viewport : plvsta; Select standard viewport.
* plw3d; Set up window for 3-d plotting : plw3d; Set up window for 3-d plotting.
* plwidth; Set pen width : plwidth; Set pen width.
* plwind; Specify world coordinates of viewport boundaries : plwind; Specify world coordinates of viewport boundaries.
* plxormod; Enter or leave xor mode : plxormod; Enter or leave xor mode.

The Specialized C API for PLplot

* plabort; Error abort : plabort; Error abort.
* plAlloc2dGrid; Allocate a block of memory for use as a 2-d grid of type PLFLT. : plAlloc2dGrid; Allocate a block of memory for use as a 2-d grid of type PLFLT_.
* 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 2-d grid allocated using plAlloc2dGrid. : plFree2dGrid; Free the memory associated with a 2-d grid allocated using plAlloc2dGrid_.
* plGetCursor; Wait for graphics input event and translate to world coordinates. : plGetCursor; Wait for graphics input event and translate to world coordinates_.
* 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 2d grid allocated using plAlloc2dGrid. : plMinMax2dGrid; Find the minimum and maximum of a 2d grid allocated using plAlloc2dGrid_.
* plOptUsage; Print usage and syntax message. : plOptUsage; Print usage and syntax message_.
* plMergeOpts; Reset internal option table info structure. : plMergeOpts; Reset internal option table info structure_.
* plsabort; Set abort handler : plsabort; Set abort handler.
* plSetUsage; Set the strings used in usage and syntax messages. : plSetUsage; Set the 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.
* pltr0; Identity transformation for grid to world mapping : pltr0; Identity transformation for grid to world mapping.
* pltr1; Linear interpolation for grid to world mapping using singly dimensioned coordinate arrays : pltr1; Linear interpolation for grid to world mapping using singly dimensioned coordinate arrays.
* pltr2; Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays (column dominant, as per normal C 2d arrays) : pltr2; Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays [column dominant; as per normal C 2d arrays].
* PLGraphicsIn; PLplot Graphics Input structure::
* PLOptionTable; PLplot command line options table structure::

The Specialized Fortran 95 API for PLplot

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

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.

Notes for each Operating System that We Support

* Linux/Unix Notes::
* Windows Notes::

The PLplot Libraries

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


File: plplotdoc.info,  Node: Introduction,  Next: Simple Use of PLplot,  Prev: Top,  Up: Top

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

* Menu:

* The PLplot Plotting Library::
* Getting a Copy of the PLplot Package::
* Installing and Using the PLplot Library::
* Organization of this Manual::
* Copyrights::
* Credits::


File: plplotdoc.info,  Node: The PLplot Plotting Library,  Next: Getting a Copy of the PLplot Package,  Up: Introduction

1.1 The PLplot Plotting Library
===============================

PLplot is a library of C functions that are useful for making
scientific plots from programs written in C, C++, Fortran95, Java,
Octave, Perl, Python, and Tcl/Tk. The PLplot project is being developed
by a world-wide team who interact via the facilities provided by
SourceForge (http://sourceforge.net/projects/plplot
(http://sourceforge.net/projects/plplot))

   The PLplot library can be used to create standard x-y plots, semi-log
plots, log-log plots, contour plots, 3D plots, shade (gray-scale and
color) plots, mesh plots, bar charts and pie charts. Multiple graphs
(of the same or different sizes) may be placed on a single page with
multiple lines in each graph. Different line styles, widths and colors
are supported. A virtually infinite number of distinct area fill
patterns may be used.  There is full unicode support in the PLplot
library, and most of the display drivers are capable of displaying any
of the millions(?) of characters in the unicode standard. Those driver
that are not unicode enabled can still display almost 1000 characters
in the extended character set.  This includes four different fonts, the
Greek alphabet and a host of mathematical, musical, and other symbols.
A variety of output devices and file formats are supported including a
metafile format which can be subsequently rendered to any device/file.
New devices and file formats can be easily added by writing a driver
routine. For example, we have recently added a postscript driver with
TrueType font support (PSTTF), a SVG file driver and a PDF file driver.
A wxWidgets interactive driver is currently in development.

   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 developed by Tony Richardson on a
Commodore Amiga.  In the process, several of the routines were
rewritten to improve efficiency and some new features added.  The
program structure was changed somewhat to make it easier to incorporate
new devices.  Additional features were added to allow three-dimensional
plotting and better access to low-level routines.

   PLplot 5.0 is a continuation of our work on PLplot 4.0, which never
got widely distributed.  It became clear during the work on 4.0 that in
order to support an interactive driver under Unix (using Tcl/Tk), many
additions to the basic capabilities of the package were needed.  So
without stopping to fully document and bug-fix the 4.0 additions, work
on 5.0 was begun.  The result is that a very capable PLplot-based
widget for the Tk toolkit has been written.  This widget can manipulate
the plot (zoom/pan, scale, orient, change colors), as well dump it to
any supported device.  There are help menus and user customization
options.  These are still in the process of being documented.

   Other changes include the introduction of a new color palette (cmap1)
for smooth color shaded images (typically for 2d or 3d plots - in which
color represents function intensity), support for color fill plots, and
lots more cool stuff.  The manual has been rewritten in LaTeXinfo, so
that there is now a printed version and an online (info) version of the
document.  The manual is still in a state of flux and will be fleshed
out in more detail in later updates.

   Some of the improvements in PLplot 5.0 include: the addition of
several new routines to enhance usage from Fortran and design of a
portable C to Fortran interface.  Additional support was added for
coordinate mappings in contour plots and some bugs fixed.  New
labelling options were added.  The font handling code was made more
flexible and portable.  A portable PLplot metafile driver and renderer
was developed, allowing one to create a generic graphics file and do
the actual rendering later (even on a different system).  The ability
to create family output files was added.  The internal code structure
was dramatically reworked, with elimination of global variables (for a
more robust package), the drivers rewritten to improve consistency, and
the ability to maintain multiple output streams added.  An XFig driver
was added.  Other contributions include Clair Nielsen's (LANL) X-window
driver (very nice for high-speed color graphics) and tektronix file
viewer.  At present, Maurice LeBrun and Geoff Furnish are the active
developers and maintainers of PLplot.

   We have attempted to keep PLplot 5.0 backward compatible with
previous versions of PLplot.  However, some functions are now obsolete,
and many new ones have been added (e.g.  new contouring functions,
variable get/set routines, functions that affect label appearance).
Codes written in C that use PLplot must be recompiled including the new
header file `plplot.h' before linking to the new PLplot library.

   PLplot is currently known to work on the following systems:
Unix/Linux, Mac OS-X and Windows XP. The Unix/Linux version is the best
supported of these possibilities.  The PLplot package is freely
distributable, but _not_ in the public domain.  See *note Copyrights::
for distribution criteria.

   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 general PLplot mailing list,
plplot-general@lists.sourceforge.net.


File: plplotdoc.info,  Node: Getting a Copy of the PLplot Package,  Next: Installing and Using the PLplot Library,  Prev: The PLplot Plotting Library,  Up: Introduction

1.2 Getting a Copy of the PLplot Package
========================================

At present, the only mechanism we are providing for distribution of the
PLplot is by electronic transmission over the Internet.  We encourage
others to make it available to users without Internet access.  PLplot
is a SourceForge project and may be obtained by the usual SourceForge
file release and anonymous svn repository access that is made available
from links at http://sourceforge.net/projects/plplot
(http://sourceforge.net/projects/plplot).


File: plplotdoc.info,  Node: Installing and Using the PLplot Library,  Next: Organization of this Manual,  Prev: Getting a Copy of the PLplot Package,  Up: Introduction

1.3 Installing and Using the PLplot Library
===========================================

The installation procedure is by necessity system specific;
installation notes for each system are provided in *note Notes for each
Operating System that We Support::.  The procedure requires that all of
the routines be compiled and they are then usually placed in a linkable
library.

   After the library has been created, you can write your main program
to make the desired PLplot calls.  Example programs in C, C++,
Fortran95 and Java are included as a guide.  Plots generated from the
example programs are shown here
(http://plplot.sourceforge.net/examples.php).

   You will then need to compile your program and link it with the
PLplot library(s).  See *note Notes for each Operating System that We
Support:: for more details).

   You can also use Tcl/Tk, Perl and Python scripts to generate plots
using the PLplot libraries.  Examples of these possibilities are also
included as a guide.


File: plplotdoc.info,  Node: Organization of this Manual,  Next: Copyrights,  Prev: Installing and Using the PLplot Library,  Up: Introduction

1.4 Organization of this Manual
===============================

The PLplot library has been designed so that it is easy to write
programs producing graphical output without having to set up large
numbers of parameters.  However, more precise control of the results
may be necessary, and these are accommodated by providing lower-level
routines which change the system defaults.  The manual first describes
the overall process of producing a graph using the high-level routines
(see *note Plotting a Simple Graph::).  For a discussion of the
underlying concepts of the plotting process and an introduction to some
of the more complex routines (see *note Advanced Use of PLplot::).  An
alphabetical list of the user-accessible PLplot functions with detailed
descriptions is given in the reference section of the manual (see *note
The Common API for PLplot::).

   Because the PLplot kernel is written in C, standard C syntax is used
in the description of each PLplot function. If you have difficulty
interpreting the call syntax as described in this manual, please refer
to part III, Language Bindings. This manual includes: C (*note C
Language::), C++ (*note A C++ Interface for PLplot::), Fortran 95
(*note Fortran 95 Language::), Java (???), Tcl (*note Using PLplot from
Tcl::), Perl (*note Using PLplot from Perl::) and Python (*note Using
PLplot from Python::). Since PLplot has a long history, bindings to
your language of choice are probably available though not necessarily
in the PLplot distribution. It is a good idea to ask around and do a
quick search before rolling your own.

   The meaning of the function (subroutine) arguments is typically the
same regardless of what language you are using to call PLplot (but
there are some exceptions to this).  The arguments for each function
are usually specified in terms of PLBOOL, PLINT,and PLFLT--these are
the internal PLplot representations for logical, integer, and floating
point, and are typically a zero (false) or non-zero (true) contained in
a long, a long, and a float (or a LOGICAL, INTEGER, and a REAL, for
Fortran programmers).  See *note C Language:: for more detail.

   Most of the output devices supported by PLplot are listed in *note
The PLplot Display Driver Family:: and *note The PLplot Output Driver
Family::, along with description of the device driver-PLplot interface,
metafile output, family files, and vt100/tek4010 emulators.


File: plplotdoc.info,  Node: Copyrights,  Next: Credits,  Prev: Organization of this Manual,  Up: Introduction

1.5 Copyrights
==============

The PLplot package may be distributed under the following terms:


           This library is free software; you can redistribute it and/or
           modify it under the terms of the GNU Library General Public
           License as published by the Free Software Foundation; either
           version 2 of the License, or (at your option) any later version.

           This library is distributed in the hope that it will be useful,
           but WITHOUT ANY WARRANTY; without even the implied warranty of
           MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
           Library General Public License for more details.

           You should have received a copy of the GNU Library General Public
           License along with this library; if not, write to the Free Software
           Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

   The text of this license is given in the file COPYING.LIB in the
distribution directory.  Exceptions are noted below.

   The intent behind distributing PLplot under the LGPL is to ensure
that it continues to evolve in a positive way, while remaining freely
distributable. Note in particular that either open-source or
proprietary code can be linked to LGPLed code such as PLplot, see the
interpretation here (http://www.gnu.org/philosophy/license-list.html).
Full details of the LGPL are given here
(http://www.gnu.org/copyleft/lesser.html).

* Menu:

* Additional Copyrights::


File: plplotdoc.info,  Node: Additional Copyrights,  Up: Copyrights

1.5.1 Additional Copyrights
---------------------------

The start up code used in argument handling (`utils/plrender.c' and
`src/plargs.c') is partially derived from `xterm.c' of the X11R5
distribution, and its copyright is reproduced here:


     	******************************************************************************
     	Copyright 1987, 1988 by Digital Equipment Corporation, Maynard,
     	Massachusetts, and the Massachusetts Institute of Technology, Cambridge,
     	Massachusetts.

     	All Rights Reserved

     	Permission to use, copy, modify, and distribute this software and its
     	documentation for any purpose and without fee is hereby granted,
     	provided that the above copyright notice appear in all copies and that
     	both that copyright notice and this permission notice appear in
     	supporting documentation, and that the names of Digital or MIT not be
     	used in advertising or publicity pertaining to distribution of the
     	software without specific, written prior permission.

     	DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
     	ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
     	DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
     	ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
     	WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
     	ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
     	SOFTWARE.
     	******************************************************************************

   Any file that is explicitly marked as "public domain" is free from
any restriction on distribution.

   Any file that has a explicit copyright notice may be distributed
under the terms of both the LGPL and whatever stated conditions
accompany the copyright.


File: plplotdoc.info,  Node: Credits,  Prev: Copyrights,  Up: Introduction

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

PLplot 5.0 was created through the effort of many individuals and
funding agencies.  We would like to acknowledge the support (financial
and otherwise) of the following institutions:

   * The Institute for Fusion Studies, University of Texas at Austin

   * The Scientific and Technology Agency of Japan

   * Japan Atomic Energy Research Institute

   * Duke University

   * Universite de Nice

   * National Energy Research Supercomputer Center

   * Los Alamos National Labs

   Thanks are also due to the many contributors to PLplot, including:

   * Tony Richardson: Creator of PLplot 2.6b, 3.0

   * Sam Paolucci (postscript driver)

   * Sam Paolucci (postscript driver)

   * Tom Rokicki (IFF driver and Amiga printer driver)

   Finally, thanks to all those who submitted bug reports and other
suggestions.


File: plplotdoc.info,  Node: Simple Use of PLplot,  Next: Advanced Use of PLplot,  Prev: Introduction,  Up: Top

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

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

   In order to draw such a 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
     `plpoin' (*note plpoin; 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, `plerrx' (*note plerrx; Draw x error bar::)
     and `plerry' (*note plerry; Draw y error bar::) 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.  The syntax for
`plenv' (*note plenv; Set up standard window and draw box::) is:

     plenv (xmin, xmax, ymin, ymax, just, axis);

`xmin, xmax'  (`PLFLT', input)
     The left and right limits for the horizontal axis.

`ymin, ymax'  (`PLFLT', input)
     The bottom and top limits for the vertical axis.

`just'  (`PLINT', input)
     This should be zero or one.  If `just' is one, the scales of the
     x-axis and y-axis will be the same (in units per millimeter);
     otherwise the axes are scaled independently.  This parameter is
     useful for ensuring that objects such as circles have the correct
     aspect ratio in the final plot.

`axis'  (`PLINT', input)
     `axis' controls whether a box, tick marks, labels, axes, and/or a
     grid are drawn.

        * `axis' = -2: No box or annotation.

        * `axis' = -1: Draw box only.

        * `axis' = 0: Draw box, labelled with coordinate values around
          edge.

        * `axis' = 1: In addition to box and labels, draw the two axes
          X = 0 and Y = 0.

        * `axis' = 2: Same as `axis' = 1, but also draw a grid at the
          major tick interval.

        * `axis' = 10: Logarithmic X axis, linear Y axis.

        * `axis' = 11: Logarithmic X axis, linear Y axis and draw line
          Y = 0.

        * `axis' = 20: Linear X axis, logarithmic Y axis.

        * `axis' = 21: Linear X axis, logarithmic Y axis and draw line
          X = 0.

        * `axis' = 30: Logarithmic X and Y axes.

   Note: Logarithmic axes only affect the appearance of the axes and
their labels, so it is up to the user to compute the logarithms prior
to passing them to `plenv' (*note plenv; Set up standard window and
draw box::) and any of the other routines.  Thus, if a graph has a
3-cycle logarithmic axis from 1 to 1000, we need to set `xmin' =
`log_10'(1) = 0.0, and `xmax' = `log_10'(1000) = 3.0.

   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 coordinates::), `plvasp'
(*note plvasp; Specify viewport using aspect ratio only::), `plvpas'
(*note plvpas; Specify viewport using coordinates and aspect ratio::),
`plwind' (*note plwind; Specify world coordinates of viewport
boundaries::), `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
picture.  All the variables are character variables or constants.
Trailing spaces are removed and the label is centered in the
appropriate field.  The syntax for `pllab' (*note pllab; Simple routine
to write labels::) is:

     pllab (xlbl, ylbl, toplbl);

`xlbl' (`char *', input)
     Pointer to string with label for the X-axis (bottom of graph).

`ylbl' (`char *', input)
     Pointer to string with label for the Y-axis (left of graph).

`toplbl' (`char *', input)
     Pointer to string with label for the plot (top of picture).}

   More complex labels can be drawn using the function `plmtex' (*note
plmtex; Write text relative to viewport boundaries::).  For discussion
of writing text in a plot see *note Writing Text on a Graph::, and for
more detailed discussion about label generation 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
--------------------

`plpoin' (*note plpoin; Plot a glyph at the specified points::) and
`plsym' (*note plsym; Plot a glyph at the specified points::) mark out
`n' points `(x[i], y[i])' with the specified symbol.  The routines
differ only in the interpretation of the symbol codes.  `plpoin' (*note
plpoin; Plot a glyph at the specified points::) uses an extended ASCII
representation, with the printable ASCII codes mapping to the
respective characters in the current font, and the codes from 0-31
mapping to various useful symbols.  In `plsym' (*note plsym; Plot a
glyph at the specified points::) however, the code is a Hershey font
code number.  Example programs are provided which display each of the
symbols available using these routines.

     plpoin(n, x, y, code);

     plsym (n, x, y, code);

`n' (`PLINT', input)
     The number of points to plot.

`x, y' (`PLFLT *', input)
     Pointers to arrays of the coordinates of the `n' points.

`code' (`PLINT',  input)
     Code number of symbol to draw


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.

     plline (n, x, y);

`n' (`PLINT', input)
     The number of points.

`x, y' (`PLFLT *', input)
     Pointers to arrays with coordinates of the `n' points.

     pljoin (x1, y1, x2, y2);

`x1, y1' (`PLFLT', input)
     Coordinates of the first point.

`x2, y2' (`PLFLT', input)
     Coordinates of the second point.


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

`plptex' (*note plptex; Write text inside the viewport::) allows text
to be written within the limits set by `plenv' (*note plenv; Set up
standard window and draw box::).  The reference point of a text string
may be located anywhere along an imaginary horizontal line passing
through the string at half the height of a capital letter.  The
parameter `just' specifies where along this line the reference point is
located.  The string is then rotated about the reference point through
an angle specified by the parameters `dx' and `dy', so that the string
becomes parallel to a line joining `(x, y)' to `(x+dx, y+dy)'.

     plptex (x, y, dx, dy, just, text);

`x, y' (`PLFLT', input)
     Coordinates of the reference point.

`dx, dy' (`PLFLT', input)
     These specify the angle at which the text is to be printed.  The
     text is written parallel to a line joining the points `(x, y)' to
     `(x+dx, y+dy)' on the graph.

`dx, dy' (`PLFLT', input)
     These specify the angle at which the text is to be printed.  The
     text is written parallel to a line joining the points `(x, y)' to
     `(x+dx, y+dy)' on the graph.

`just' (`PLFLT', input)
     Determines justification of the string by specifying which point
     within the string is placed at the reference point `(x, y)'.  This
     parameter is a fraction of the distance along the string.  Thus if
     ``just' = 0.0', the reference point is at the left-hand edge of
     the string.  If ``just' = 0.5', it is at the center and if ``just'
     = 1.0', it is at the right-hand edge.

`text' (`char *', input)
     Pointer to the string of characters to be written.


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.

     plfill (n, x, y);

`n' (`PLINT', input)
     The number of vertices.

`x, y' (`PLFLT *', input)
     Pointers to arrays with coordinates of the `n' vertices.


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 x error bar::) and `plerry' (*note plerry; Draw y error bar::)
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: Top

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

In this chapter, we describe advanced use of PLplot.

* Menu:

* Command Line Arguments::
* Output 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 Surface Plots::
* Contour and Shade Plots::
* Legends and color bars::


File: plplotdoc.info,  Node: Command Line Arguments,  Next: Output 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:


     	% x01c -h
     	Usage:
     	./x01c [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, in pixels (e.g. -geometry 400x300)
     	-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,2=landscape, 1,3=portrait)
     	-freeaspect          Do not preserve aspect ratio on orientation swaps
     	-portrait            Sets portrait mode (both orientation and aspect ratio)
     	-width width         Sets pen width (1 <= width <= 10)
     	-bg color            Background color (0=black, FFFFFF=white)
     	-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 in MB (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
     	-drvopt option[=value][,option[=value]]* Driver specific options
     	-cmap0 name          Sets PLplot color table 0 using the file name
     	-cmap1 name          Sets PLplot color table 1 using the file name

   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 are 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 The
PLplot Display Driver Family:: and *note The PLplot Output Driver
Family::.


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

3.2 Output Devices
==================

PLplot supports a variety of output devices, via a set of device
drivers.  Each driver is required to emulate a small set of low-level
graphics primitives such as initialization, line draw and page advance,
as well as be completely independent of the PLplot package as a whole.
Thus a driver may be very simple, as in the case of the many black and
white file drivers (tektronix, etc.).  More complicated and/or color
systems require a bit more effort by the driver, with the most effort
required by an output device with a graphical user interface, including
menus for screen dumps, palette manipulation, and so forth.  At present
only the tk driver does the latter on Unix systems.  At present we
aren't pursuing a Macintosh development effort due to a lack of time
and expertise, but will assist anyone wanting to volunteer for the job.

   Note that if you always render to a PLplot metafile, you can always
`plrender' them to new devices as they become available.

   The list of available devices presented when starting PLplot (via
`plstar') is determined at compile time.  When installing PLplot you
may wish to exclude devices not available on your system in order to
reduce screen clutter.  To include a specified device, simply define
the appropriate macro constant when building PLplot (see the
installation instructions for your system).

   The device drivers for PLplot terminal output at present are given in
*note PLplot Terminal Output Devices:: while drivers for file output
are given in *note PLplot File Output Devices::.  The driver for OS/2
PM is available separately.  See the section on OS/2 in the Appendix
for more details.  *PLplot Terminal Output Devices*

Device                   keyword                  driver file
X-Window Screen          xwin                     xwin.c
Tcl/Tk widget            tk                       tk.c
Linux console VGA        vga                      linuxvga.c
Xterm Window             xterm                    tek.c
Tektronix Terminal       tekt                     tek.c
(4010)                                            
Tektronix Terminal       tek4107t                 tek.c
(4105/4107)                                       
MS-Kermit emulator       mskermit                 tek.c
Versaterm vt100/tek      versaterm                tek.c
emulator                                          
VLT vt100/tek emulator   vlt                      tek.c
Conex vt320/tek emulator conex                    tek.c
DG300 Terminal           dg300                    dg300.c
NeXT display             nx                       next.c
(unsupported)                                     

*PLplot File Output Devices*

Device                   keyword                  driver file
PLplot Native Meta-File  plmeta                   plmeta.c
Tektronix File (4010)    tekf                     tek.c
Tektronix File           tek4107f                 tek.c
(4105/4107)                                       
PostScript File          ps                       ps.c
(monochrome)                                      
PostScript File (color)  psc                      ps.c
XFig file                xfig                     xfig.c
LaserJet IIp Bitmap      ljiip                    ljiip.c
File                                              
LaserJet II Bitmap File  ljii                     ljii.c
(150 dpi)                                         
HP 7470 Plotter File     hp7470                   hpgl.c
(HPGL Cartridge Small                             
Plotter)                                          
HP 7580 Plotter File     hp7580                   hpgl.c
(Large Plotter)                                   
HP Laser Jet, HPGL file  lj_hpgl                  hpgl.c
Impress File             imp                      impress.c
Portable bitmap file     pbm                      pbm.c
Null device              null                     null.c
JPEG file                jpeg                     gd.c
PNG file                 png                      gd.c
Computer Graphics        cgm                      cgm.c
Metafile                                          

* Menu:

* Driver Functions::
* PLplot Metafiles and Plrender::
* Family File Output::
* Interactive Output Devices::
* Specifying the Output Device::


File: plplotdoc.info,  Node: Driver Functions,  Next: PLplot Metafiles and Plrender,  Up: Output 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: PLplot Metafiles and Plrender,  Next: Family File Output,  Prev: Driver Functions,  Up: Output Devices

3.2.2 PLplot Metafiles and Plrender
-----------------------------------

The PLplot metafile is a way to store and transport your graphical data
for rendering at a later time or on a different system.  A PLplot
metafile is in binary format in order to speed access and keep storage
costs reasonable.  All data is stored in device-independent format
(written as a stream of bytes); the resulting file is about as portable
as a tektronix vector graphics file and only slightly larger.

   Each PLplot metafile begins with a header string that identifies it
as such, as well as the version number of the format since this may
change in time.  The utility for rendering the metafile, `plrender',
verifies that the input file is indeed a valid PLplot metafile, and
that it ‘understands’ the format the metafile is written in.
`plrender' is part of the PLplot package and should be built at the
time of building PLplot, and then put into your search path.  It is
capable of high speed rendering of the graphics file, especially if the
output device can accept commands at a high rate (e.g. X windows).

   The commands as written by the metafile driver at present are as
follows:

   * `INITIALIZE'

   * `CLOSE'

   * `SWITCH_TO_TEXT'

   * `SWITCH_TO_GRAPH'

   * `CLEAR'

   * `PAGE'

   * `NEW_COLOR'

   * `NEW_WIDTH'

   * `LINE'

   * `LINETO'

   * `ESCAPE'

   * `ADVANCE'

   Each command is written as a single byte, possibly followed by
additional data bytes.  The `NEW_COLOR' and `NEW_WIDTH' commands each
write 2 data bytes, the `LINETO' command writes 4 data bytes, and the
`LINE' command writes 8 data bytes.  The most common instruction in the
typical metafile will be the `LINETO' command, which draws a
continuation of the previous line to the given point.  This data
encoding is not quite as efficient as the tektronix format, which uses
4 bytes instead of 5 here (1 command `+' 4 data), however the PLplot
encoding is far simpler to implement and more robust. The `ESCAPE'
function writes a second command character (opcode) followed by an
arbitrary number of data bytes depending on the value of the opcode.
Note that any data written must be in device independent form to
maintain the transportability of the metafile so floating point numbers
are not allowed.

   The short usage message for `plrender' is printed if one inputs
insufficient or invalid arguments, and is as follows:


     	  % plrender

     	  No filename specified.

     	  Usage:
     	  plrender [options] [files]

     	  plrender options:
     	  [-v] [-i name] [-b number] [-e number] [-p page]

     	  PLplot options:
     	  [-h] [-v] [-verbose] [-debug] [-dev name] [-o name] [-display name]
     	  [-px number] [-py number] [-geometry geom] [-wplt xl,yl,xr,yr]
     	  [-mar margin] [-a aspect] [-jx justx] [-jy justy] [-ori orient]
     	  [-freeaspect] [-width width] [-bg color] [-ncol0 n] [-ncol1 n] [-fam]
     	  [-fsiz size] [-fbeg number] [-finc number] [-fflen length] [-nopixmap]
     	  [-db] [-np] [-server_name name] [-server_host name] [-server_port name]
     	  [-user name]


     	  Type plrender -h for a full description.

   The longer usage message goes into more detail, and is as follows:


     	  % plrender -h

     	  Usage:
     	  plrender [options] [files]

     	  plrender options:
     	  -v                   Print out the plrender version number
     	  -i name              Input filename
     	  -b number            Beginning page number
     	  -e number            End page number
     	  -p page              Plot given page only

     	  If the "-i" flag is omitted, unrecognized input will assumed to be filename
     	  parameters.  Specifying "-" for the input or output filename means use stdin
     	  or stdout, respectively.  See the manual for more detail.

     	  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, in pixels (e.g. -geometry 400x300)
     	  -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,2=landscape, 1,3=portrait)
     	  -freeaspect          Do not preserve aspect ratio on orientation swaps
     	  -portrait            Sets portrait mode (both orientation and aspect ratio)
     	  -width width         Sets pen width (1 <= width <= 10)
     	  -bg color            Background color (0=black, FFFFFF=white)
     	  -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 in MB (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
     	  -drvopt option[=value][,option[=value]]* Driver specific options

   The options are generally self explanatory (family files are
explained in *note Family File Output::).  Most of these options have
default values, and for those that don't `plrender' will prompt the
user.  The `-px' and `-py' options are not so useful at present,
because everything is scaled down by the specified factor -- resulting
in labels that are too small (future versions of `plrender' might allow
changing the label size as well).

   Additional options may be added in future releases.


File: plplotdoc.info,  Node: Family File Output,  Next: Interactive Output Devices,  Prev: PLplot Metafiles and Plrender,  Up: Output Devices

3.2.3 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.  In addition, `plrender' has the ability to process a
set of family member files as a single logical 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 a plmeta output file with name
`test-%n.plm', the files actually created will be `test-1.plm',
`test-2.plm', 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 like `test.plm.1',
`test.plm.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.  This information might be
used in various ways; for example you could spawn a process to
automatically plrender each metafile after it is closed (perhaps during
a long simulation run) and send it off to be printed.

   `plrender' has several options for dealing with family files.  It
can process a single member file (`plrender'  `test.plm.1') or the
entire family if given only the stem name (`plrender'  `test.plm') It
can also create family files on output, rendering to any device that
supports familying, including another metafile if desired.  The size of
member files in this case is input through the argument list, and
defaults to 1MB if unspecified (this may be changed during the PLplot
installation, however). `plrender' can also create a single output file
from a familied input metafile.


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

3.2.4 Interactive Output Devices
--------------------------------

Here we shall discuss briefly some of the more common interactive output
devices.

   Many popular terminals or terminal emulators at present have a
facility for switching between text and graphics ‘screens’.  This
includes the xterm emulator under X-windows, vt100's with
Retrographics, and numerous emulators for microcomputers which have a
dual vt100/tek4010 emulation capability.  On these devices, it is
possible to switch between the text and graphics screens by surrounding
your PLplot calls by calls to `plgra' (*note plgra; Switch to graphics
screen::) and `pltext' (*note pltext; Switch to text screen::).  This
will allow your diagnostic and informational code output to not
interfere with your graphical output.

   At present, only the xterm driver supports switching between text
and graphics screens.  The escape sequences as sent by the xterm driver
are fairly standard, however, and have worked correctly on most other
popular vt100/tek4010 emulators we've tried.

   When using the xterm driver, hitting a RETURN will advance and clear
the page.  If indeed running from an xterm, you may resize, move, cover
and uncover the window.  The behavior of the X-window driver is quite
different, however.  First, it is much faster, as there is no tty-like
handshaking going on.  Second, a mouse click is used to advance and
clear the page, rather than a RETURN.

   On a tektronix 4014 compatible device, you may preview tektronix
output files via the `pltek' utility.  `pltek' will let you step
through the file interactively, skipping backward or forward if
desired.  The help message for `pltek' is as follows:


     	  % pltek
     	  Usage: pltek filename
     	  At the prompt, the following replies are recognized:
     	  h,?    Give this help message.
     	  q     Quit program.
     	  <n>    Go to the specified page number.
     	  -<n>   Go back <n> pages.
     	  +<n>   Go forward <n> pages.
     	  <Return> Go to the next page.

The output device is switched to text mode before the prompt is given,
which causes the prompt to go to the vt102 window under xterm and most
vt100/tek4010 emulators.


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

3.2.5 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> xterm      Xterm Window
     	  < 4> tekt       Tektronix Terminal (4010)
     	  < 5> tek4107t   Tektronix Terminal (4105/4107)
     	  < 6> mskermit   MS-Kermit emulator
     	  < 7> versaterm  Versaterm vt100/tek emulator
     	  < 8> vlt        VLT vt100/tek emulator
     	  < 9> plmeta     PLPLOT Native Meta-File
     	  <10> tekf       Tektronix File (4010)
     	  <11> tek4107f   Tektronix File (4105/4107)
     	  <12> ps         PostScript File (monochrome)
     	  <13> psc        PostScript File (color)
     	  <14> xfig       Xfig file
     	  <15> ljiip      LaserJet IIp/deskjet compressed graphics
     	  <16> ljii       LaserJet II Bitmap File (150 dpi)
     	  <17> null       Null device

     	  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 the example programs 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
- you may only write to one output stream at a time.  At present, an
output stream is not limited by the type of device, however, it may not
be wise to attempt opening two terminal devices.  An example usage for
the creation of multiple streams is as follows:

     #include "plplot.h"

     	main()
     	{
     	int nx = 2, ny = 2;

     	plssub(nx, ny);
     	plsdev("xwin");
     	plinit();

     	plots for stream 0

     	plsstrm(1);
     	plssub(nx, ny);
     	plsdev("plmeta");
     	plsfnam("tst.plm");
     	plinit();

     	plots for stream 1

     	plsstrm(0);

     	plots for stream 0

   and so on, for sending output simultaneously to an X-window and a
metafile.  The default stream corresponds to stream number zero.  At
present, the majority of output drivers can only be used by a single
stream (exceptions include the metafile driver and X-window driver).
Also see example program 14 (note: only the C version is available,
although it can be done equally well from Fortran).

   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: Output Devices,  Up: Advanced Use of PLplot

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

Any bitmap driver in the PLplot family should be able to use fonts
(TrueType and others) that are rendered by the FreeType library just as
long as the device supports setting an individual pixel. Note that
drivers interact with FreeType using the support routines
`plD_FreeType_init', `plD_render_freetype_text', `plD_FreeType_Destroy',
`pl_set_extended_cmap0', and `pl_RemakeFreeType_text_from_buffer' that
are coded in `plfreetype.c'.

   The use of these support routines is exemplified by the `gd.c'
driver.  Here we make some notes to accompany this driver which should
make it easier to migrate other drivers to use the FreeType library.
Every code fragment we mention below should be surrounded with a
`#ifdef PL_HAVE_FREETYPE...#endif' to quarantine these fragments for
systems without the FreeType library.  For interactive devices that
need caching of text drawing, reference should also be made to
`wingcc.c'.

* Menu:

* Write a call back function to plot a single pixel::
* Initialize FreeType::
* Add A Command to redraw text (interactive drivers only): Add A Command to redraw text [interactive drivers only].
* Add Function Prototypes::
* Add Closing functions::


File: plplotdoc.info,  Node: Write a call back function to plot a single pixel,  Next: Initialize FreeType,  Up: Adding FreeType Library Support to Bitmap Drivers

3.3.1 Write a call back function to plot a single pixel
-------------------------------------------------------

First, write a call back function, of type `plD_pixel_fp', which
specifies how a single pixel is set in the current color. This can be
of type static void. For example, in the `gd.c' driver it looks like
this:


     	void plD_pixel_gd (PLStream *pls, short x, short y)
     	{
     	png_Dev *dev=(png_Dev *)pls->dev;

     	gdImageSetPixel(dev->im_out, x, y,dev->colour);
     	}


File: plplotdoc.info,  Node: Initialize FreeType,  Next: Add A Command to redraw text [interactive drivers only],  Prev: Write a call back function to plot a single pixel,  Up: Adding FreeType Library Support to Bitmap Drivers

3.3.2 Initialize FreeType
-------------------------

Next, we have to initialize the FreeType library. For the `gd.c' driver
this is done via two separate functions due to the order that dependent
information is initialized in the driver.

   The "level 1" initialization of FreeType does two things: 1) calls
`plD_FreeType_init(pls)', which in turn allocates memory to the pls->FT
structure; and 2) stores the location of the call back routine.


     	  void init_freetype_lv1 (PLStream *pls)
     	  {
     	  FT_Data *FT;

     	  plD_FreeType_init(pls);

     	  FT=(FT_Data *)pls->FT;
     	  FT->pixel= (plD_pixel_fp)plD_pixel_gd;

     	  }

   This initialization routine is called at the end of
`plD_init_png_Dev(PLStream *pls)' in the `gd.c' driver:


     	  if (freetype)
     	  {
     	  pls->dev_text = 1; /* want to draw text */
     	  init_freetype_lv1(pls);
     	  FT=(FT_Data *)pls->FT;
     	  FT->smooth_text=smooth_text;
     	  }

   `"freetype"' is a local variable which is parsed through
`plParseDrvOpts' to determine if the user wanted FreeType text. In that
case `pls->dev_text' is set to 1 to indicate the driver will be
rendering it's own text. After that, we always use `pls->dev_text' to
work out if we want FreeType or not.

   Similarly, `"smooth_text"' is a local variable passed through
`plParseDrvOpts' to find out if the user wants smoothing. Since there
is nothing in PLStream to track smoothing, we have to set the
FT->smooth_text flag as well at this time.

   The "level 2" initialization function initializes everything else
required for using the FreeType library but has to be called after the
screen resolution and dpi have been set. Therefore, it is called at the
end of `plD_init_png()', where it looks like:


     	if (pls->dev_text)
     	{
     	init_freetype_lv2(pls);
     	}

   The actual function looks like this:


     	static void init_freetype_lv2 (PLStream *pls)
     	{
     	png_Dev *dev=(png_Dev *)pls->dev;
     	FT_Data *FT=(FT_Data *)pls->FT;

     	FT->scale=dev->scale;
     	FT->ymax=dev->pngy;
     	FT->invert_y=1;

     	if (FT->smooth_text==1)
     	{
     	FT->ncol0_org=pls->ncol0;                                   /* save a copy of the original size of ncol0 */
     	FT->ncol0_xtra=NCOLOURS-(pls->ncol1+pls->ncol0);            /* work out how many free slots we have */
     	FT->ncol0_width=FT->ncol0_xtra/(pls->ncol0-1);              /* find out how many different shades of anti-aliasing we can do */
     	if (FT->ncol0_width>64) FT->ncol0_width=64;                 /* set a maximum number of shades */
     	plscmap0n(FT->ncol0_org+(FT->ncol0_width*pls->ncol0));      /* redefine the size of cmap0 */
     	/* the level manipulations are to turn off the plP_state(PLSTATE_CMAP0)
     	* call in plscmap0 which (a) leads to segfaults since the GD image is
     	* not defined at this point and (b) would be inefficient in any case since
     	* setcmap is always called later (see plD_bop_png) to update the driver
     	* color palette to be consistent with cmap0. */
     	{
     	PLINT level_save;
     	level_save = pls->level;
     	pls->level = 0;
     	pl_set_extended_cmap0(pls, FT->ncol0_width, FT->ncol0_org); /* call the function to add the extra cmap0 entries and calculate stuff */
     	pls->level = level_save;
     	}
     	}

     	}

   FT->scale is a scaling factor to convert coordinates. This is used by
the `gd.c' and some other drivers to scale back a larger virtual page
and this eliminate the "hidden line removal bug". Set it to 1 if your
device driver doesn't use any scaling.

   Some coordinate systems have zero on the bottom, others have zero on
the top. FreeType does it one way, and most everything else does it the
other. To make sure everything is working OK, we have to "flip" the
coordinates, and to do this we need to know how big in the Y dimension
the page is, and whether we have to invert the page or leave it alone.

   * FT->ymax specifies the size of the page

   * FT->invert_y=1 tells us to invert the y-coordinates,
     FT->invert_y=0 will not invert the coordinates.

   We also do some computational gymnastics to "expand" cmap0 if the
user wants anti-aliased text.  Basically, you have to work out how many
spare colors there are in the driver after cmap0 and cmap1 are done,
then set a few variables in FT to let the render know how many colors
it's going to have at its disposal, and call plscmap0n to resize cmap0.
The call to `pl_set_extended_cmap0' does the remaining part of the
work.  Note it essential to protect that call by the `pls->level'
manipulations for the reasons stated.


File: plplotdoc.info,  Node: Add A Command to redraw text [interactive drivers only],  Next: Add Function Prototypes,  Prev: Initialize FreeType,  Up: Adding FreeType Library Support to Bitmap Drivers

3.3.3 Add A Command to redraw text (interactive drivers only)
-------------------------------------------------------------

Plplot only caches drawing commands, not text plotting commands, so for
interactive devices which refresh their display by replaying the plot
buffer, a separate function has to be called to redraw the text.
plfreetype knows when buffering is being used by a device driver, and
will automatically start caching text when necessary.  To redraw this
cached text, a call to `pl_RemakeFreeType_text_from_buffer' has to be
added after the driver has called `plRemakePlot'.  The following
example is from `wingcc.c'.


     	if (dev->waiting==1)
     	{
     	plRemakePlot(pls);
     	#ifdef PL_HAVE_FREETYPE
     	pl_RemakeFreeType_text_from_buffer(pls);
     	#endif
     	}


File: plplotdoc.info,  Node: Add Function Prototypes,  Next: Add Closing functions,  Prev: Add A Command to redraw text [interactive drivers only],  Up: Adding FreeType Library Support to Bitmap Drivers

3.3.4 Add Function Prototypes
-----------------------------

Next, to the top of the drivers' source file add the prototype
definitions for the functions just written.


     	static void plD_pixel_gd (PLStream *pls, short x, short y);
     	static void init_freetype_lv1 (PLStream *pls);
     	static void init_freetype_lv2 (PLStream *pls);


File: plplotdoc.info,  Node: Add Closing functions,  Prev: Add Function Prototypes,  Up: Adding FreeType Library Support to Bitmap Drivers

3.3.5 Add Closing functions
---------------------------

Finally, add a `plD_FreeType_Destroy(pls)' entry to the device "tidy"
function; this command deallocates memory allocated to the FT entry in
the stream, closes the FreeType library and any open fonts. It is also
a good idea to reset CMAP0 back to it's original size here if
anti-aliasing was done. For example, in the `gd.c' driver, it looks
like this:


     	void plD_tidy_png(PLStream *pls)
     	{
     	fclose(pls->OutFile);

     	#ifdef PL_HAVE_FREETYPE
     	FT_Data *FT=(FT_Data *)pls->FT;
     	plscmap0n(FT->ncol0_org);

     	plD_FreeType_Destroy(pls);
     	#endif

     	free_mem(pls->dev);
     	}


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.

   There are four methods for specifying the viewport size, using the
subroutines `plvpor' (*note plvpor; Specify viewport using
coordinates::), `plsvpa' (*note plsvpa; Specify viewport in absolute
coordinates::), `plvasp' (*note plvasp; Specify viewport using aspect
ratio only::), and `plvpas' (*note plvpas; Specify viewport using
coordinates and aspect ratio::) which are called like this:

         plvpor(xmin, xmax, ymin, ymax);
     	plsvpa(xmin, xmax, ymin, ymax);
     	plvasp(aspect);
     	plvpas(xmin, xmax, ymin, ymax, aspect);

   where in the case of `plvpor' (*note plvpor; Specify viewport using
coordinates::) and `plvpas' (*note plvpas; Specify viewport using
coordinates and aspect ratio::), the arguments are given in _normalized
subpage coordinates_ which are defined to run from 0.0 to 1.0 along
each edge of the subpage.  Thus for example,

         plvpor(0.0, 0.5, 0.5, 1.0);

   uses the top left quarter of the current subpage.

   In order to get a graph of known physical size, the routine `plsvpa'
(*note plsvpa; Specify viewport in absolute coordinates::) defines the
viewport in terms of absolute coordinates (millimeters) measured from
the bottom left-hand corner of the current subpage.  This routine
should only be used when the size of the view surface is known, and a
definite scaling is required.

   The routine `plvasp' (*note plvasp; Specify viewport using aspect
ratio only::) gives the largest viewport with the given aspect ratio
that fits in the current subpage (i.e. the ratio of the length of the y
axis to that of the x axis is equal to `aspect').  It also allocates
space on the left and top of the viewport for labels.

   The routine `plvpas' (*note plvpas; Specify viewport using
coordinates and aspect ratio::) gives the largest viewport with the
given aspect ratio that fits in the specified region (specified with
normalized subpage coordinates, as with `plvpor' (*note plvpor; Specify
viewport using coordinates::)).  This routine is functionally
equivalent to `plvpor' (*note plvpor; Specify viewport using
coordinates::) when a ‘natural’ aspect ratio is chosen (done by setting
`aspect' to 0.0).  Unlike `plvasp' (*note plvasp; Specify viewport
using aspect ratio only::), this routine reserves no extra space at the
edges for labels.

   To help the user call `plsvpa' (*note plsvpa; Specify viewport in
absolute coordinates::) correctly, the routine `plgspa' (*note plgspa;
Get current subpage parameters::) is provided which returns the
positions of the extremities of the current subpage measured in
millimeters from the bottom left-hand corner of the device.  Thus, if
to set up a viewport with a 10.0 mm margin around it within the current
subpage, the following sequence of calls may be used:

         plgspa(xmin, xmax, ymin, ymax);
     	plsvpa(10.0, xmax-xmin-10.0, 10.0, ymax-ymin-10.0);

   A further routine `plvsta' (*note plvsta; Select standard
viewport::) is available which sets up a standard viewport within the
current subpage with suitable margins on each side of the viewport.
This may be used for simple graphs, as it leaves enough room for axis
labels and a title.  This standard viewport is that used by `plenv'
(*note plenv; Set up standard window and draw box::) (See *note Setting
up a Standard Window::).

   Another way to get a specified aspect ratio is via the routine
`plsasp' [not!.. fix this], which sets the global aspect ratio and must
be called prior to `plstar' (*note plstar; Initialization::).  An
aspect ratio of 0.0 corresponds to ‘natural’ dimensions (i.e. fill the
page); any positive value will give the specified aspect ratio.  This
scaling of plots is actually done in the driver, and so may not work
for all output devices (note that `plrender' is capable of scaled
aspect ratio plots to any device whether that device supports scaling
or not).  In such scaled plots, absolute plotting is done in the scaled
coordinate system.


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 window must be defined after the viewport in order to map the world
coordinate rectangle into the viewport rectangle.  The routine `plwind'
(*note plwind; Specify world coordinates of viewport boundaries::) is
used to specify the rectangle in world-coordinate space.  For example,
if we wish to plot a graph showing the collector current I_C as a
function of the collector to emitter voltage V_CE for a transistor
where 0 ≤ I_C ≤ 10.0 mA and 0 ≤ V_CE ≤ 12.0 V, we would call the
function `plwind' (*note plwind; Specify world coordinates of viewport
boundaries::) as follows:

         plwind(0.0, 12.0, 0.0, 10.0);

   Note that each of the arguments is a floating point number, and so
the decimal points are required.  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 world coordinates of viewport boundaries::) 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 piece of
paper.


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 whether a frame is drawn around the viewport and to control
the positions of the axis subdivisions and numeric labels.  For our
simple graph of the transistor characteristics, we may wish to draw a
frame consisting of lines on all four sides of the viewport, and to
place numeric labels along the bottom and left hand side.  We can also
tell PLplot to choose a suitable tick interval and the number of
subticks between the major divisions based upon the data range
specified to `plwind' (*note plwind; Specify world coordinates of
viewport boundaries::).  This is done using the following statement

         plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0);

   The lengths of major and minor ticks on the axes are set up by the
routines `plsmaj' (*note plsmaj; Set length of major ticks::) and
`plsmin' (*note plsmin; Set length of minor ticks::).

   Another routine `pllab' (*note pllab; Simple routine to write
labels::) provides for 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.  For our example, we may
use

         pllab("V#dCE#u (Volts)", "I#dC#u (mA)", "TRANSISTOR CHARACTERISTICS");

   Note that `#d' and `#u' are escape sequences (see *note Escape
sequences in text::) which allow subscripts and superscripts to be used
in text.  They are described more fully later in this chapter.

   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 coordinates::), `plwind'
(*note plwind; Specify world coordinates of viewport boundaries::) and
`plbox' (*note plbox; Draw a box with axes; etc::) is excessively
cumbersome for drawing simple graphs.  Subroutine `plenv' (*note plenv;
Set up standard window and draw box::) combines all four of these in
one subroutine, using the standard viewport, and a limited subset of
the capabilities of `plbox' (*note plbox; Draw a box with axes; etc::).
For example, the graph described above could be initiated by the call:

         plenv(0.0, 12.0, 0.0, 10.0, 0, 0);

   which is equivalent to the following series of calls:

         pladv(0);
     	plvsta();
     	plwind(0.0, 12.0, 0.0, 10.0);
     	plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0);


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 line, followed by two pointers to integer
arrays specifying 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[0] = 4000;
           mark[1] = 2000;
           space[0] = 1500;
           space[1] = 1500;
           plstyl(2, mark, space);

   To return to a continuous line, just call `plstyl' (*note plstyl;
Set line style::) with first argument set to zero.  You can use
`pllsty' (*note pllsty; Select line style::) to choose between 8
different predefined 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 `plpat' (*note plpat; Set area fill pattern::) can be used
to set the area fill pattern.  The pattern consists of 1 or 2 sets of
parallel lines with specified inclinations and spacings.  The arguments
to this routine are the number of sets to use (1 or 2) followed by two
pointers to integer arrays (of 1 or 2 elements) specifying the
inclinations in tenths of a degree and the spacing in micrometers (the
inclination should be between -900 and 900).  Thus to specify an area
fill pattern consisting of horizontal lines spaced 2 mm apart use:

         *inc = 0;
           *del = 2000;
           plpat(1, inc, del);

   To set up a symmetrical crosshatch pattern with lines directed 30
degrees above and below the horizontal and spaced 1.5 mm apart use:

         *inc = 300;
           *(inc+1) = -300;
           *del = 1500;
           *(del+1) = 1500;
           plpat(2, inc, del);

   The routine `plpsty' (*note plpsty; Select area fill pattern::) can
be used to select from 1 of 8 predefined patterns.

   The area fill routines also use the current line style, width and
colors to give a virtually infinite number of different 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
(discussed in *note Color Map0::) has discrete colors with no
particular order and is most suited to coloring the background, axes,
lines, and labels, and color map1 (discussed in *note Color Map1::) has
continuously changing colors and is most suited to plots (see *note
Contour and Shade Plots::) in which data values are represented by
colors.  Setting the background color is a special case that is handled
exclusively by color map 0 (as discussed in *note Color Map0::).  The
user can change the current color (as opposed to the background color)
at any point in the plot by selecting any of the colors from either
color map 0 or 1 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
the 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 the background, axes, lines, and
labels.  Generally, the default color map0 palette of 16 colors is
used. (`examples/c/x02c.c' illustrates these colors.) The default
background color is taken from the index 0 color which is black by
default.  The default foreground color is red.

   There are a number of options for changing the default red on black
colors.  The user may set the index 0 background color using the
command-line `bg' parameter or by calling `plscolbg' (*note plscolbg;
Set the background color by 8-bit RGB value::) (or `plscol0' (*note
plscol0; Set 8-bit RGB values for given cmap0 color index::) with a 0
index) _before_ `plinit' (*note plinit; Initialize PLplot::).  During
the course of the plot, the user can change the foreground color as
often as desired using `plcol0' (*note plcol0; Set color; cmap0::) to
select the index of the desired color.

   For more advanced use it is possible to define an arbitrary map0
palette of colors. The user may set the number of colors in the map0
palette using the command-line `ncol0' parameter or by calling
`plscmap0n' (*note plscmap0n; Set number of colors in cmap0::).
`plscol0' (*note plscol0; Set 8-bit RGB values for given cmap0 color
index::) sets the RGB value of the given index which must be less than
the maximum number of colors (which is set by default, by command line,
by `plscmap0n' (*note plscmap0n; Set number of colors in cmap0::), or
even by `plscmap0' (*note plscmap0; Set cmap0 colors by 8-bit RGB
values::)).  Alternatively, `plscmap0' (*note plscmap0; Set cmap0
colors by 8-bit RGB values::) sets up the entire map0 color palette. For
all these ways of defining the map0 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.


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

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

Color map1 is most suited to plots (see *note Contour and Shade
Plots::) in which data values are represented by colors. The data are
scaled to the input map1 range of floating point numbers between 0. and
1. which in turn are mapped (using `plcol1' (*note plcol1; Set color;
cmap1::)) to colors using a default or user-specified map1 color
transformation.  Thus, there are calls to `plcol1' (*note plcol1; Set
color; cmap1::) from within the code for `plshade' (*note plshade;
Shade individual region on the basis of value::) (see `src/plshade.c')
and `plsurf3d' (*note plsurf3d; Plot shaded 3-d surface plot::) (see
`src/plot3d.c') to give a continuous range of color corresponding to
the data being plotted. In addition `plcol1' (*note plcol1; Set color;
cmap1::) can be used to specify the foreground color using the map1
continuous color palette (see the commented out section of
`examples/c/x12c.c' which gives an example of this for a histogram),
but normally `plcol0' (*note plcol0; Set color; cmap0::) is a better
tool for this job (see *note Color Map0::) since discrete colors often
give a better-looking result.

   For more advanced use it is possible to define an arbitrary map1
palette of colors. The user may set the number of colors in this palette
using the command-line `ncol1' parameter or by calling `plscmap1n'
(*note plscmap1n; Set number of colors in cmap1::).  Furthermore,
`plscmap1l' (*note plscmap1l; Set cmap1 colors using a piece-wise
linear relationship::) can be used to set the map1 color palette using
linear interpolation between control points specified in either RGB or
HLS space.

   There is a one-to-one correspondence between RGB and HLS color
spaces.  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.

   Here are some C-code fragments which use `plscmap1l' (*note
plscmap1l; Set cmap1 colors using a piece-wise linear relationship::)
to set the map1 color palette. This first example illustrates how to
set up a gray-scale palette using linear interpolation in RGB space.

         i[0] = 0.;
           i[1] = 1.;
           /* RGB are rescaled to the range from 0 to 1. for input to plscmap1l.*/
           r[0] = 0.;
           r[1] = 1.;
           g[0] = 0.;
           g[1] = 1.;
           b[0] = 0.;
           b[1] = 1.;
           plscmap1l(1, 2, i, r, g, b, NULL);

   This second example illustrates doing the same thing in HLS space.

         i[0] = 0.;
           i[1] = 1.;
           /* Hue does not matter for zero saturation.*/
           h[0] = 0.;
           h[1] = 0.;
           /* Lightness varies through its full range.*/
           l[0] = 0.;
           l[1] = 1.;
           /* Saturation is zero for a gray scale.*/
           s[0] = 0.;
           s[1] = 0.;
           /* Note the first argument which specifies HLS space.*/
           plscmap1l(0, 2, i, h, l, s, NULL);

   This final example using `plscmap1l' (*note plscmap1l; Set cmap1
colors using a piece-wise linear relationship::) illustrates how the
default map1 color palette is set with just 4 control points (taken from
`src/plctrl.c').

     /*--------------------------------------------------------------------------*\
           * plcmap1_def()
           *
           * Initializes color map 1.
           *
           * The default initialization uses 4 control points in HLS space, the two
           * inner ones being very close to one of the vertices of the HLS double
           * cone.  The vertex used (black or white) is chosen to be the closer to
           * the background color.  If you don't like these settings you can always
           * initialize it yourself.
           \*--------------------------------------------------------------------------*/

           static void
           plcmap1_def(void)
           {
           PLFLT i[4], h[4], l[4], s[4], vertex = 0.;

           /* Positions of control points */

           i[0] = 0;		/* left boundary */
           i[1] = 0.45;	/* just before center */
           i[2] = 0.55;	/* just after center */
           i[3] = 1;		/* right boundary */

           /* For center control points, pick black or white, whichever is closer to bg */
           /* Be careful to pick just short of top or bottom else hue info is lost */

           if (plsc->cmap0 != NULL)
           vertex = ((float) plsc->cmap0[0].r +
           (float) plsc->cmap0[0].g +
           (float) plsc->cmap0[0].b) / 3. / 255.;

           if (vertex < 0.5)
           vertex = 0.01;
           else
           vertex = 0.99;

           /* Set hue */

           h[0] = 260;		/* low: blue-violet */
           h[1] = 260;		/* only change as we go over vertex */
           h[2] = 0;		/* high: red */
           h[3] = 0;		/* keep fixed */

           /* Set lightness */

           l[0] = 0.5;		/* low */
           l[1] = vertex;	/* bg */
           l[2] = vertex;	/* bg */
           l[3] = 0.5;		/* high */

           /* Set saturation -- keep at maximum */

           s[0] = 1;
           s[1] = 1;
           s[2] = 1;
           s[3] = 1;

           c_plscmap1l(0, 4, i, h, l, s, NULL);
           }

   Finally, `plscmap1' (*note plscmap1; Set cmap1 colors using 8-bit
RGB values::) is an additional method of setting the map1 color palette
directly using RGB space.  No interpolation is used with `plscmap1'
(*note plscmap1; Set cmap1 colors using 8-bit RGB values::) so it is
the programmer's responsibility to make sure that the colors vary
smoothly.  Here is an example of the method taken from
`examples/c/x08c.c' which sets (yet again) the gray-scale color palette.

         for (i=0;i<n_col;i++)
           rr[i] = gg[i] = bb[i] = i*256/n_col;
           plscmap1(rr,gg,bb,n_col);


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

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

Plplot uses two separate font systems to display characters. The
traditional system uses Hershey fonts which are available for all
device drivers, while the recently introduced unicode system is
currently available only for the ps, psc, png, jpeg, and gif devices.
For details on how to enable the unicode font system for additional
device drivers using the FreeType library, see *note Adding FreeType
Library Support to Bitmap Drivers::.

* Menu:

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


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

3.8.1 Hershey fonts
-------------------

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
`plstar' (*note plstar; Initialization::) or `plstart' (*note plstart;
Initialization::) is called.  The standard character set is loaded by
calling `plfontld' (*note plfontld; Load character font::).  The
extended character set requires about 50 KBytes of memory, versus about
5 KBytes for the standard set.  `plfontld' (*note plfontld; Load
character font::) can be used to switch between the extended and
standard sets (one set is unloaded before the next is loaded).
`plfontld' (*note plfontld; Load character font::) 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 character 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 below.  This
routine has no 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 fonts,  Next: FCI,  Prev: Hershey fonts,  Up: Setting Character Attributes

3.8.2 Unicode fonts
-------------------

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) and much better display of characters on computer screens
using anti-aliasing and hinting.  Unicode fonts are obtained by
specifying a command-line option of -drvopt text for the devices
(currently ps, psc, png, jpeg, gif, and wingcc) where it has been
implemented.

   For the ps and psc devices, there is a fixed relationship between the
FCI (font characterization integer, see *note FCI::) and the actual
Type 1 fonts that are being used.  This fixed relationship is specified
in the Type1Lookup array in include/plfci.h.  This array maps the
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 font-style attributes of upright, italic
or oblique and the 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 standard postscript fonts are normally installed on a user's
system using the gsfonts package.

   For the devices handled by the FreeType library (currently png, jpeg,
and gif) there is a configurable relationship between the FCI (font
characterization integer, see *note FCI::) and the TrueType fonts that
are actually used.

   The TrueType fonts 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 fonts. On all other platforms defaults 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 systems, the 30 possible TrueType fonts 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: FCI,  Next: Escape sequences in text,  Prev: Unicode fonts,  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 marked with an 0x8 (0x80000000 is
ORed with the FCI value to mark it) to distinguish it from a unicode
(UCS4) integer (whose maximum value 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]::). Independent hexadecimal values
within the FCI are characterized by the hexdigit and hexpower.  The
hexpower is 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 escape sequences
should be replaced by using the 4 escape sequences `#[nnn]',
`#<0x8nnnnnnn>', `#<0xmn>', or `#<FCI COMMAND STRING/>' as appropriate.

   It should be emphasized that the unicode escape sequences above only
work properly for modern unicode-aware devices such as the svg device
or the very large set of cairo and qt devices.  And for those devices
the alternative of simply specifying the unicode symbols using UTF-8
encoding of PLplot input strings is much more convenient for users than
using the above escape sequences.  For example, we use UTF-8 strings
rather than escape sequences in example 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
scentific 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 Surface Plots,  Next: Contour and Shade Plots,  Prev: Setting Character Attributes,  Up: Advanced Use of PLplot

3.9 Three Dimensional Surface Plots
===================================

PLplot includes routines that will represent a single-valued function
of two variables as a surface.  In this section, we shall assume that
the function to be plotted is `Z[X][Y]', where `Z' represents the
dependent variable and `X' and `Y' represent the independent variables.

   As usual, we would like to refer to a three dimensional point `(X,
Y, Z)' in terms of some meaningful user-specified coordinate system.
These are called _three-dimensional world coordinates_.  We need to
specify the ranges of these coordinates, so that the entire surface is
contained within the cuboid defined by `xmin' < `x' < `xmax', `ymin' <
`y' < `ymax', and `zmin' < `z' < `zmax'.  Typically, we shall want to
view the surface from a variety of angles, and to facilitate this, a
two-stage mapping of the enclosing cuboid is performed.  Firstly, it is
mapped into another cuboid called the _normalized box_ whose size must
also be specified by the user, and secondly this normalized box is
viewed from a particular azimuth and elevation so that it can be
projected onto the two-dimensional window.

   This two-stage transformation process allows considerable flexibility
in specifying how the surface is depicted.  The lengths of the sides of
the normalized box are independent of the world coordinate ranges of
each of the variables, making it possible to use ‘reasonable’ viewing
angles even if the ranges of the world coordinates on the axes are very
different.  The size of the normalized box is determined essentially by
the size of the two-dimensional window into which it is to be mapped.
The normalized box is centered about the 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.  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 box as viewed from
above the xy plane.  The azimuth can take on any value.

   The first step in drawing a surface plot is to decide on the size of
the two-dimensional window and the normalized box.  For example, we
could choose the normalized box to have sides of length

         basex = 2.0;
           basey = 4.0;
           height = 3.0;

   A reasonable range for the x coordinate of the two-dimensional window
is -2.5 to +2.5, since the length of the diagonal across the base of
the normalized box is sqrt(2^2+4^2) = 2 sqrt(5), which fits into this
coordinate range.  A reasonable range for the y coordinate of the two
dimensional window in this case is -2.5 to +4, as the the projection of
the normalized box lies in this range for the allowed range of viewing
angles.

   The routine `plwind' (*note plwind; Specify world coordinates of
viewport boundaries::) or `plenv' (*note plenv; Set up standard window
and draw box::) is used in the usual way to establish the size of the
two-dimensional window.  The routine `plw3d' (*note plw3d; Set up
window for 3-d plotting::) must then be called to establish the range
of the three dimensional world coordinates, the size of the normalized
box and the viewing angles.  After calling `plw3d' (*note plw3d; Set up
window for 3-d plotting::), the actual surface is drawn by a call to
`plot3d' (*note plot3d; Plot 3-d surface plot::).

   For example, if the three-dimensional world-coordinate ranges are
-10.0 ≤ `x' ≤ 10.0, -3.0 ≤ `y' ≤ +7.0, and 0.0 ≤ `z' ≤ 8.0, we could
use the following statements:

         xmin2d = -2.5;
           xmax2d =  2.5;
           ymin2d = -2.5;
           ymax2d =  4.0;
           plenv(xmin2d, xmax2d, ymin2d, ymax2d, 0, -2);
           basex = 2.0;
           basey = 4.0;
           height = 3.0;
           xmin = -10.0;
           xmax = 10.0;
           ymin = -3.0;
           ymax = 7.0;
           zmin = 0.0;
           zmax = 8.0;
           alt = 45.0;
           az = 30.0;
           side = 1;
           plw3d(basex, basey, height, xmin, xmax, ymin, ymax, zmin, zmax, alt, az);
           plot3d(x, y, z, nx, ny, opt, side);

   The values of the function are stored in a two-dimensional array
`z[][]' where the array element `z[i][j]' contains the value of the
function at the point x_i, y_j.  (The two-dimensional array `z' is a
vectored array instead of a fixed size array.  `z' points to an array
of pointers which each point to a row of the matrix.)  Note that the
values of the independent variables x_i and y_j do not need to be
equally spaced, but they must lie on a rectangular grid.  Thus two
further arrays `x[nx]' and `y[ny]' are required as arguments to
`plot3d' (*note plot3d; Plot 3-d surface plot::) to specify the values
of the independent variables.  The values in the arrays x and y must be
strictly increasing with the index.  The argument `opt' specifies how
the surface is outlined.  If `opt = 1', a line is drawn representing z
as a function of x for each value of y, if `opt = 2', a line is drawn
representing z as a function of y for each value of x, and if `opt = 3',
a net of lines is drawn.  The first two options may be preferable if
one of the independent variables is to be regarded as a parameter,
whilst the third is better for getting an overall picture of the
surface.  If side is equal to one then sides are drawn on the figure so
that the graph doesn't appear to float.

   The routine `plmesh' (*note plmesh; Plot surface mesh::) is similar
to `plot3d' (*note plot3d; Plot 3-d surface plot::), except that it is
used for drawing mesh plots.  Mesh plots allow you to see both the top
and bottom sides of a surface mesh, while 3D plots allow you to see the
top side only (like looking at a solid object).  The side option is not
available with `plmesh' (*note plmesh; Plot surface mesh::).

   Labelling a three-dimensional or mesh plot is somewhat more
complicated than a two dimensional plot due to the need for skewing the
characters in the label so that they are parallel to the coordinate
axes.  The routine ` plbox3' (*note plbox3; Draw a box with axes; etc;
in 3-d::) thus combines the functions of box drawing and labelling.


File: plplotdoc.info,  Node: Contour and Shade Plots,  Next: Legends and color bars,  Prev: Three Dimensional Surface Plots,  Up: Advanced Use of PLplot

3.10 Contour and Shade Plots
============================

Several routines are available in PLplot which perform a contour or
shade plot of data stored in a two-dimensional array.  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.  In this case it is best to
draw the distinction between the C and Fortran 95 interfaces so these
are handled in turn.

* Menu:

* Contour Plots from C::
* Shade Plots from C::
* Contour Plots from the Fortran 95 interface::
* Shade Plots from the Fortran 95 interface::


File: plplotdoc.info,  Node: Contour Plots from C,  Next: Shade Plots from C,  Up: Contour and Shade Plots

3.10.1 Contour Plots from C
---------------------------

`plcont' (*note plcont; Contour plot::) is the routine callable from C
for plotting contours.  This routine has the form:

     plcont (z, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr,
     pltr_data);

   where `z' is the two-dimensional array of size `nx' by `ny'
containing samples of the function to be contoured.  (`z' is a vectored
two-dimensional array as described in the previous section.  It is
_not_ a fixed-size two-dimensional array.) The parameters `kx', `lx',
`ky' and `ly' specify the portion of `z' that is to be considered.  The
array `clevel' of length `nlevel' is a list of the desired contour
levels.

   The path of each contour is initially computed in terms of the
values of the array indices which range from `0' to `nx-1' in the first
index and from `0' to `ny-1' in the second index.  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 is done by passing a pointer `pltr' to a user-defined
transformation function to `plcont' (*note plcont; Contour plot::).
For C use of `plcont' (*note plcont; Contour plot::) (and `plshade'
(*note plshade; Shade individual region on the basis of value::), see
next subsection) we have included directly in the PLplot library the
following transformation routines: `pltr0' (*note pltr0; Identity
transformation for grid to world mapping::) (identity transformation or
you can enter a NULL argument to get the same effect); `pltr1' (*note
pltr1; Linear interpolation for grid to world 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 [column dominant; as per normal C 2d arrays]::)
(linear interpolation in doubly dimensioned coordinate arrays).
Examples of the use of these transformation routines are given in
`examples/c/x09c.c', `examples/c/x14c.c', and `examples/c/x16c.c'.
These same three examples also demonstrate a user-defined
transformation function `mypltr' which is capable of arbitrary
translation, rotation, and/or shear. By defining other transformation
subroutines, it is possible to draw contours wrapped around polar grids
etc.


File: plplotdoc.info,  Node: Shade Plots from C,  Next: Contour Plots from the Fortran 95 interface,  Prev: Contour Plots from C,  Up: Contour and Shade Plots

3.10.2 Shade Plots from C
-------------------------

NEEDS DOCUMENTATION.  Follow the plshade and plshades usage in
`examples/c/x??c.c'.


File: plplotdoc.info,  Node: Contour Plots from the Fortran 95 interface,  Next: Shade Plots from the Fortran 95 interface,  Prev: Shade Plots from C,  Up: Contour and Shade Plots

3.10.3 Contour Plots from the Fortran 95 interface
--------------------------------------------------

NEEDS DOCUMENTATION.  Follow the plcont usage (with a variety of
overloaded forms available with different arguments) in
`examples/f95/x??f.f90'.


File: plplotdoc.info,  Node: Shade Plots from the Fortran 95 interface,  Prev: Contour Plots from the Fortran 95 interface,  Up: Contour and Shade Plots

3.10.4 Shade Plots from the Fortran 95 interface
------------------------------------------------

NEEDS DOCUMENTATION.  Follow the plshade and plshades usage (with a
variety of overloaded forms available with different arguments) in
`examples/f95/x??f.f90'.


File: plplotdoc.info,  Node: Legends and color bars,  Prev: Contour and Shade Plots,  Up: Advanced Use of PLplot

3.11 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 standard examples 4 and 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 standard example 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 standard example
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 examples 4, 16, and 26 as a
tutorial on how to use these PLplot capabilities in a simple way, and
for more advanced use we recommend that users study 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 example 33 which attempts to exercise most capabilities of these
two PLplot functions.


File: plplotdoc.info,  Node: Deploying programs that use PLplot,  Next: The PLplot Display Driver Family,  Prev: Advanced Use of PLplot,  Up: Top

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: The PLplot Display Driver Family,  Next: The PLplot Output Driver Family,  Prev: Deploying programs that use PLplot,  Up: Top

5 The PLplot Display Driver Family
**********************************

Drivers that provide screen displays 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 Xwin Driver (X-Windows): The Xwin Driver [X-Windows].
* The Tk Driver::
* The AquaTerm Driver (Mac OS X): The AquaTerm Driver [Mac OS X].
* The wxWidgets Driver (Linux, Mac OS X, Windows): The wxWidgets Driver [Linux; Mac OS X; Windows].


File: plplotdoc.info,  Node: The Xwin Driver [X-Windows],  Next: The Tk Driver,  Up: The PLplot Display Driver Family

5.1 The Xwin Driver (X-Windows)
===============================

The Xwin driver draws plots in an X-window.  Although some of the newer
features are not supported, it remains the reference driver for PLplot.

   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.

   Anti-aliasing is not supported, and the Xwin driver is not
unicode-enabled.

   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 AquaTerm Driver [Mac OS X],  Prev: The Xwin Driver [X-Windows],  Up: The PLplot Display Driver Family

5.2 The Tk Driver
=================

is the prototype of a whole new interaction paradigm.  See next chapter.


File: plplotdoc.info,  Node: The AquaTerm Driver [Mac OS X],  Next: The wxWidgets Driver [Linux; Mac OS X; Windows],  Prev: The Tk Driver,  Up: The PLplot Display Driver Family

5.3 The AquaTerm Driver (Mac OS X)
==================================

The AquaTerm driver is a Mac OS X specific driver that is used with 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 [Linux; Mac OS X; Windows],  Prev: The AquaTerm Driver [Mac OS X],  Up: The PLplot Display Driver Family

5.4 The wxWidgets Driver (Linux, Mac OS X, Windows)
===================================================

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 [Linux; Mac OS X; Windows]

5.4.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: The PLplot Output Driver Family,  Next: Ada Language,  Prev: The PLplot Display Driver Family,  Up: Top

6 The PLplot Output Driver Family
*********************************

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 GD Driver::
* The PDF Driver::
* The PostScript Driver::
* The TrueType PostScript Driver::
* The LaTeX PostScript Driver::
* The SVG Driver::


File: plplotdoc.info,  Node: The GD Driver,  Next: The PDF Driver,  Up: The PLplot Output Driver Family

6.1 The GD Driver
=================

The GD driver produces png, jpeg, and gif images, using devices by the
same name.  The GD driver is unicode enabled.  Text is anti-aliased,
but lines and shades 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 PDF Driver,  Next: The PostScript Driver,  Prev: The GD Driver,  Up: The PLplot Output Driver Family

6.2 The PDF Driver
==================

A basic version of a pdf driver has been added to PLplot. This driver
is based on the libharu library see: libharu.org (http://libharu.org/).
At present only the Hershey fonts are used and 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. All these issues will be addressed in later
releases.

   Options?


File: plplotdoc.info,  Node: The PostScript Driver,  Next: The TrueType PostScript Driver,  Prev: The PDF Driver,  Up: The PLplot Output Driver Family

6.3 The PostScript Driver
=========================

The PostScript driver produces publication-quality PostScript output.
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.
Type I fonts do not have all of the available unicode symbols
represented.  For this reason, Hershey fonts are used for drawing
symbols by default, 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 TrueType PostScript Driver,  Next: The LaTeX PostScript Driver,  Prev: The PostScript Driver,  Up: The PLplot Output Driver Family

6.4 The TrueType PostScript Driver
==================================

This is a PostScript driver that supports TrueType fonts. This allows
access to a far greater range of fonts and characters than is possible
using Type 1 PostScript fonts (see *note The PostScript Driver::).  It
is the driver to use for generating publication quality output using
PLplot. The driver provides two devices: the ps-ttf device for
black-and-white plots and the ps-ttfc 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
http://www.unifont.org/lasi/. The library is small and easy to build
and install.  Make sure you use LASi-1.0.5.  The psttf device driver
uses new capabilities in this version of LASi and no longer works with
LASi-1.0.4.

   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 LaTeX PostScript Driver,  Next: The SVG Driver,  Prev: The TrueType PostScript Driver,  Up: The PLplot Output Driver Family

6.5 The LaTeX PostScript Driver
===============================

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: The SVG Driver,  Prev: The LaTeX PostScript Driver,  Up: The PLplot Output Driver Family

6.6 The SVG Driver
==================

The SVG driver produces Scalable Vector Graphics files that are
compliant with the SVG 1.1 specification as defined here:
http://www.w3.org/Graphics/SVG/. The driver is unicode enabled and both
text and lines are anti-aliased. As SVG is just an XML based graphics
language, the visual quality of the resulting plot will depend on the
SVG rendering engine that is used and what fonts that are available to
it.


File: plplotdoc.info,  Node: Ada Language,  Next: C Language,  Prev: The PLplot Output Driver Family,  Up: Top

7 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

7.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) pre-installed 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 pre-installed.)


      #!/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

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

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

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

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

7.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 pre-built 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 pre-built 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

     Pre-built color themes for color map 1:
     `Color_Themes_For_Map_1_Type'

     Quick application of pre-built color themes:
     `Quick_Set_Color_Map_1'

   * Other features

     A pre-built 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

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

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


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

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

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

7.8 Known Variances
===================

* Menu:

* Documentation::
* API::


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

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

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

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

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

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

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

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

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

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

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

7.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: C Language,  Next: A C++ Interface for PLplot,  Prev: Ada Language,  Up: Top

8 C Language
************

(OLD, NEEDS DOCUMENTATION UPDATING) The argument types given in this
manual (PLFLT and PLINT) are typedefs for the actual argument type.  A
PLINT is actually a type `long' and should not be changed.  A PLFLT can
be either a `float' or `double'; this choice is made when the package
is installed and on a Unix system (for example) may result in a PLplot
library named `libplplot.a' in single precision and `libplplotd.a' in
double precision.

   These and other constants used by PLplot are defined in the main
header file `plplot.h', which must be included by the user program.
This file also contains all of the function prototypes, machine
dependent defines, and redefinition of the C-language bindings that
conflict with the Fortran names (more on this later).  `plplot.h'
obtains its values for PLFLT, PLINT, and PLARGS (a macro for
conditionally generating prototype argument lists) from FLOAT
(typedef), INT (typedef), and PROTO (macro), respectively.  The latter
are defined in the file `chdr.h'.  The user is encouraged to use FLOAT,
INT, and PROTO in his/her own code, and modify `chdr.h' according to
taste.  It is not actually necessary to declare variables as FLOAT and
INT except when they are pointers, as automatic conversion to the right
type will otherwise occur (if using a Standard C compiler; else K&R
style automatic promotion will occur).  The only code in `plplot.h'
that directly depends on these settings is as follows:


           #include "plplot/chdr.h"

           /* change from chdr.h conventions to plplot ones */

           typedef FLOAT PLFLT;
           typedef INT   PLINT;
           #define PLARGS(a) PROTO(a)

   PLplot is capable of being compiled with Standard C (ANSI) mode on
or off.  This is toggled via the macro PLSTDC, and set automatically if
__STDC__ is defined.  If PLSTDC is defined, all functions are
prototyped as allowed under Standard C, and arguments passed exactly as
specified in the prototype.  If PLSTDC is not defined, however,
function prototypes are turned off and K&R automatic argument promotion
will occur, e.g.  ` float &rarr; double, int &rarr; long'.  There is no
middle ground!  A PLplot library built with PLSTDC defined will not
work (in general) with a program built with PLSTDC undefined, and vice
versa.  It is possible in principle to build a library that will work
under both Standard C and K&R compilers simultaneously (i.e.  by
duplicating the K&R promotion with the Standard C prototype), but this
seems to violate the spirit of the C standard and can be confusing.
Eventually we will drop support for non-standard C compilers but for
now have adopted this compromise.

   In summary, PLplot will work using either a Standard or non-standard
C compiler, provided that you :

   * Include the PLplot main header file `plplot.h'.

   * Make sure all pointer arguments are of the correct type (the
     compiler should warn you if you forget, so don't worry, be happy).

   * Do not link a code compiled with PLSTDC defined to a PLplot library
     compiled with PLSTDC undefined, or vice versa.

   * Use prototypes whenever possible to reduce type errors.

   Note that some Standard C compilers will give warnings when
converting a constant function argument to whatever is required by the
prototype.  These warnings can be ignored.

   The one additional complicating factor concerns the use of stub
routines to interface with Fortran (see the following section for more
explanation).  On some systems, the Fortran and C name spaces are set
up to clobber each other.  More reasonable (from our viewpoint) is to
agree on a standard map between name spaces, such as the appending of
an underscore to Fortran routine names as is common on many Unix-like
systems.  The only case where the shared Fortran/C name spaces do any
good is when passing a pointer to a like data type, which represents
only a small fraction of the cases that need to be handled (which
includes constant values passed on the stack, strings, and
two-dimensional arrays).

   There are several ways to deal with this situation, but the least
messy from a user's perspective is to redefine those PLplot C function
names which conflict with the Fortran-interface stub routines.  The
actual function names are the same as those described in this document,
but with a ‘c_’ prepended.  These macro definitions appear in the
`plplot.h' header file and are otherwise harmless.  Therefore you can
(and should) forget that most of the names are being redefined to avoid
the conflict and simply adhere to the bindings as described in this
manual.  Codes written under old versions of PLplot (previous to 5.0)
will require a recompile, however.

   For more information on calling PLplot from C, please see the
example C programs (`x01c.c' through `x19c.c') distributed with PLplot.


File: plplotdoc.info,  Node: A C++ Interface for PLplot,  Next: Fortran 95 Language,  Prev: C Language,  Up: Top

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::
* 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: Collapsing the API,  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: Collapsing the API,  Prev: Abstraction of Data Layout,  Up: Design of the PLplot C++ Interface

9.2.4 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 95 Language,  Next: OCaml Language,  Prev: A C++ Interface for PLplot,  Up: Top

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

As discussed in the preceding section, PLplot's integer representation
is a PLINT and its floating point representation is a PLFLT.  To the
Fortran 95 user, this most commonly translates to a type `integer' and
type `real', respectively.  This is somewhat system dependent (and up to
the installer of the package) so you should check the release notes to
be sure, or just try it and see what happens.

   Because the PLplot kernel is written in C, standard C syntax is used
in the description of each PLplot function.  Thus to understand this
manual it is helpful to know a little about C, but fortunately the
translation is very easy and can be summarized here.  As an example,
the routine `plline' (*note plline; Draw a line::) call from C would
look like:


           plline(n,x,y);

The argument `n' is the number of points that make up the line and the
arguments `x' and `y' are arrays of floating-point numbers containing
the x- and y-coordinates of the points.

   In C you need to specify the array dimensions explicitly, whereas in
Fortran 95 the array dimension can be implicit, which leads to less
mistakes. The interface to `plline' would ideally look like this:


           interface
           subroutine plline(x,y)
           real, dimension(:) :: x, y
           end subroutine plline
           end interface

   There is one slight complication: PLplot can be compiled with either
single-precision reals or double-precision reals. It is _very
important_ to keep the variables that are passed to PLplot in the same
precision. Fortunately, Fortran 95 provides the `KIND' mechanism for
this.

   The actual interface to `plline' therefore looks like:


           interface
           subroutine plline(x,y)
           real(kind=plflt), dimension(:) :: x, y
           end subroutine plline
           end interface

The parameter `plflt' is defined in the `PLplot' module and should be
used consistently with all real variables that you pass to PLplot
routines.

   Here is a short overview of how C data types correspond to Fortran 95
data types:

PLFLT                                real(kind=plflt)
PLINT                                integer
char *                               character
PLFLT *                              real(kind=plflt) or
                                     real(kind=plflt), dimension(:)
PLFLT **                             real(kind=plflt), dimension(:,:)
`"string"'                           `'string''
array[0]                             array(1)

In C there are two ways to pass a variable -- by value (the default) or
by reference (pointer), whereas only the latter is used by Fortran 95.
Therefore when you see references in the text to _either_ an ordinary
argument or a pointer argument (e.g.  `*data'), you simply use an
ordinary Fortran 95 variable or array name (the interfacing routines
take care of any transformations that may be necessary).

   The PLplot library comes with a set of Fortran 95 interface routines
that allow the same call semantics (usually) regardless of whether
calling from C or Fortran 95.  In some cases, the Fortran 95 interface
uses implicit array dimensions, so that it has fewer arguments than the
C counterpart.

   These ‘stub’ routines handle transforming the data from the normal
Fortran 95 representation to that typically used in C.  This includes:

   * Variables passed by value instead of by reference.

     Fortran 95 passes all subroutine arguments by reference, i.e., a
     pointer to the argument value is pushed on the stack.  In C all
     values, except for arrays (including char arrays), are passed by
     value, i.e., the argument value itself is pushed on the stack.
     The stub routine converts the Fortran 95 call by reference to a
     call by value.  As an example, here is how the plpoin stub routine
     works.  In your Fortran 95 program you might have a call to plpoin
     that looks something like


          	  real(kind=pllft), dimension(6) :: x, y
          	  x = ...
          	  y = ...
          	  call plpoin(x,y,9)

     where x and y are arrays with 6 elements and you want to plot
     symbol 9.  The routine `plpoin' calls the underlying routine
     `plpoinf95':


          	  subroutine plpoin( x, y, code )
          	  integer                        :: code
          	  real(kind=plflt), dimension(:) :: x, y

          	  call plpoinf95( size(x), x, y, code )
          	  end subroutine plpoin

     This takes care of the size of the arrays - it is not possible to
     transfer this information to C in an implicit way.

     The routine plpoinf95 is implemented in C to take care of the
     question pass by value or pass by reference: (1)


          	  #include "plplot/plstubs.h"

          	  void
          	  PLPOIN(n, x, y, code)
          	  PLINT *n, *code;
          	  PLFLT *x, *y;
          	  {
          	  c_plpoin(*n, x, y, *code);
          	  }

     All this stub routine does is convert the number of points (`*n'
     and the symbol `*code' to call by value (i.e.  pushes their value
     on the stack) and then calls the C plpoin library routine.

   * Get mapping between Fortran 95 and C namespace right (system
     dependent).

     The external symbols (i.e. function and subroutine names) as you
     see them in your program often appear differently to the linker.
     For example, the Fortran 95 routine names may be converted to
     uppercase or lowercase, and/or have an underscore appended or
     prepended.  This translation is handled entirely via redefinition
     of the stub routine names, which are macros.  During the build
     process, the properties of the build environment are detected and
     the correct compiler options are used.

     Once the name translation is established during installation, name
     translation is completely transparent to the user.

   * Translation of character string format from Fortran 95 to C.

     Fortran 95 character strings are passed differently than other
     quantities, in that a string descriptor is pushed on the stack
     along with the string address.  C doesn't want the descriptor, it
     wants a NULL terminated string.  For routines that handle strings
     two stub routines are necessary, one written in Fortran 95 and one
     written in C.  Your Fortran 95 program calls the Fortran 95 stub
     routine first.  This stub converts the character string to a null
     terminated integer array and then calls the C stub routine.  The C
     stub routine converts the integer array (type `long') to the usual
     C string representation (which may be different, depending on
     whether your machine uses a big endian or little endian byte
     ordering; in any case the way it is done in PLplot is portable).
     See the `plmtex' stubs for an example of this.

     Note that the portion of a Fortran 95 character string that
     exceeds 299 characters will not be plotted by the text routines
     (`plmtex' and `plptex').

   * Multidimensional array arguments are changed from row-dominant to
     column-dominant ordering through use of a temporary array.

     In Fortran 95, arrays are always stored so that the first index
     increases most rapidly as one steps through memory.  This is called
     ‘row-dominant’ storage.  In C, on the other hand, the first index
     increases _least_ rapidly, i.e. ‘column-dominant’ ordering.  Thus,
     two dimensional arrays (e.g.  as passed to the contour or surface
     plotting routines) passed into PLplot must be transposed in order
     to get the proper two-dimensional relationship to the world
     coordinates.  This is handled in the C stub routines by dynamic
     memory allocation of a temporary array.  This is then set equal to
     the transpose of the passed in array and passed to the appropriate
     PLplot routine.  The overhead associated with this is normally not
     important but could be a factor if you are using very large 2d
     arrays.

   This all seems a little messy, but is very user friendly.  Fortran
95 and C programmers can use the same basic interface to the library,
which is a powerful plus for this method.  The fact that stub routines
are being used is completely transparent to the Fortran 95 programmer.

   For more information on calling PLplot from Fortran 95, please see
the example Fortran 95 programs (`/examples/f95/x??f.f') distributed
with PLplot.

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

   (1) `PLPOIN' is a macro that get translated into the correct name
for this routine - various Fortran compilers use different conventions,
such as adding an underscore or translating the name into capitals.


File: plplotdoc.info,  Node: OCaml Language,  Next: Using PLplot from Perl,  Prev: Fortran 95 Language,  Up: Top

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 GODI,
a source-based distribution of OCaml and a number of OCaml libraries.
GODI can be retrieved from godi.camlcity.org
(http://godi.camlcity.org/).  GODI has support for building and
installing under Linux, Apple's OS X and MS Windows.


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) P.Greedy (P.Window P.Cairo)
               in

               (* Draw the parabola *)
               P.plot ~stream:p [P.func P.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: Top

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: Top

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: Top

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 5.0 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 100 x y

   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 was 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, an initializer may be specified, with a syntax familiar
from C.  For example:


     	matrix x f 4 = { 1.5, 2.5, 3.5, 4.5 }

   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 *]:"

   Note that the * provides a means of obtaining an index range, and
that it must be separated from the = by a space.  Future versions of the
Tcl Matrix extension may allow alternative ways of specifying index
ranges and may assign the obvious meaning to an expression of the form:


     	x *= 3

   However this has not been implemented yet...

   In any event, the `matrix' command also supports an `info'
subcommand which reports the number of elements in each dimension:


     	pltcl> x info
     	4
     	pltcl> matrix y i 8 10
     	pltcl> y info
     	8 10


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.


File: plplotdoc.info,  Node: Drawing a Shaded Plot from Tcl,  Prev: Drawing a Contour Plot from Tcl,  Up: Contouring and Shading from Tcl

14.4.2 Drawing a Shaded Plot from Tcl
-------------------------------------

The Tcl interface to shading works very much like the one for
contouring.  The command is:


     	plshade z xmin xmax ymin ymax \
     	sh_min sh_max sh_cmap sh_color sh_width \
     	min_col min_wid max_col max_wid \
     	rect [pltr x y] [wrap]

   where `nx' and `ny' were dropped since they are inferred from the
Tcl matrix `z', `defined' was dropped since it isn't supported anyway,
and `plfill' was dropped since it was the only valid choice anyway.
The `pltr' spec and `wrap' work exactly as described for the Tcl
`plcont' described above.

   The Tcl demo `x16.tcl' contains extensive demonstrations of use,
including a shaded polar plot which connects in the desirable way
without requiring special data preparation, again just like for
`plcont' described previously.


File: plplotdoc.info,  Node: Understanding the Performance Characteristics of Tcl,  Prev: Contouring and Shading from Tcl,  Up: Using PLplot from Tcl

14.5 Understanding the Performance Characteristics of Tcl
=========================================================

Newcomers to Tcl, and detractors (read, ‘proponents of other
paradigms’) often do not have a clear (newcomers) or truthful
(detractors) perspective on Tcl performance.  In this section we try to
convey a little orientation which may be helpful in working with the
PLplot Tcl interface.

   ‘Tcl is slow!’  ‘Yeah, so what?’

   Debates of this form frequently completely miss the point.  Yes, Tcl
is definitely slow.  It is fundamentally a string processing language,
is interpreted, and must perform substitutions and so forth on a
continual basis.  All of that takes time.  Think milliseconds instead
of microseconds for comparing Tcl code to equivalent C code.  On the
other hand, this does not have to be problematic, even for time
critical (interactive) applications, if the division of labor is done
correctly.  Even in an interactive program, you can use Tcl fairly
extensively for high level control type operations, as long as you do
the real work in a compiled Tcl command procedure.  If the high level
control code is slow, so what?  So it takes 100 milliseconds over the
life the process, as compared to the 100 microseconds it could have
taken if it were in C.  Big deal.  On an absolute time scale, measured
in units meaningful to humans, it's just not a lot of time.

   The problem comes when you try to do too much in Tcl.  For instance,
an interactive process should not be trying to evaluate a mathematical
expression inside a doubly nested loop structure, if performance is
going to be a concern.

   Case in point:  Compare x16.tcl to x16c.c.  The code looks very
similar, and the output looks very similar.  What is not so similar is
the execution time.  The Tcl code, which sets up the data entirely in
Tcl, takes a while to do so.  On the other hand, the actual plotting of
the data proceeds at a rate which is effectively indistinguishable from
that of the compiled example.  On human time scales, the difference is
not meaningful.  Conclusion:  If the computation of the data arrays
could be moved to compiled code, the two programs would have
performance close enough to identical that it really wouldn't be an
issue.  We left the Tcl demos coded in Tcl for two reasons.  First
because they provide some examples and tests of the use of the Tcl
Matrix extension, and secondly because they allow the Tcl demos to be
coded entirely in Tcl, without requiring special customized extended
shells for each one of them.  They are not, however, a good example of
you should do things in practice.

   Now look at `tk04' and `xtk04.c', you will see that if the data is
computed in compiled code, and shuffled into the Tcl matrix and then
plotted from Tcl, the performance is fine.  Almost all the time is
spent in plshade, in compiled code.  The time taken to do the small
amount of Tcl processing involved with plotting is dwarfed by the time
spent doing the actual drawing in C.  So using Tcl cost almost nothing
in this case.

   So, the point is, do your heavy numerical calculations in a compiled
language, and feel free to use Tcl for the plotting, if you want to.
You can of course mix it up so that some plotting is done from Tcl and
some from a compiled language.


File: plplotdoc.info,  Node: Building an Extended WISH,  Next: Embedding Plots in Graphical User Interfaces,  Prev: Using PLplot from Tcl,  Up: Top

15 Building an Extended WISH
****************************

Beginning with PLplot 5.0, a new and powerful paradigm for interaction
with PLplot is introduced.  This new paradigm consists of an
integration of PLplot with a powerful scripting language (Tcl), and
extensions to that language to support X Windows interface development
(Tk) and object oriented programming ([incr Tcl]).  Taken together,
these four software systems (Tcl/Tk/itcl/PLplot) comprise a powerful
environment for the rapid prototyping and development of sophisticated,
flexible, X Windows applications with access to the PLplot API.  Yet
that is only the beginning--Tcl was born to be extended.  The true
power of this paradigm is achieved when you add your own, powerful,
application specific extensions to the above quartet, thus creating an
environment for the development of wholly new applications with only a
few keystrokes of shell programming ...

* Menu:

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


File: plplotdoc.info,  Node: Introduction to Tcl,  Next: Introduction to Tk,  Up: Building an Extended WISH

15.1 Introduction to Tcl
========================

The Tool Command Language, or just Tcl (pronounced ‘tickle’) is an
embeddable script language which can be used to control a wide variety
of applications.  Designed by John Ousterhout of UC Berkeley, Tcl is
freely available under the standard Berkeley copyright.  Tcl and Tk
(described below) are extensively documented in a new book published by
Addison Wesley, entitled ‘Tcl and the Tk toolkit’ by John Ousterhout.
This book is a must have for those interested in developing powerful
extensible applications with high quality X Windows user interfaces.
The discussion in this chapter cannot hope to approach the level of
introduction provided by that book.  Rather we will concentrate on
trying to convey some of the excitement, and show the nuts and bolts of
using Tcl and some extensions to provide a powerful and flexible
interface to the PLplot library within your application.

* Menu:

* Motivation for Tcl::
* Capabilities of Tcl::
* Acquiring Tcl::


File: plplotdoc.info,  Node: Motivation for Tcl,  Next: Capabilities of Tcl,  Up: Introduction to Tcl

15.1.1 Motivation for Tcl
-------------------------

The central observation which led Ousterhout to create Tcl was the
realization that many applications require the use of some sort of a
special purpose, application specific, embedded ‘macro language’.
Application programmers cobble these ‘tiny languages’ into their codes
in order to provide flexibility and some modicum of high level control.
But the end result is frequently a quirky and fragile language.  And
each application has a different ‘tiny language’ associated with it.
The idea behind Tcl, then, was to create a single ‘core language’ which
could be easily embedded into a wide variety of applications.  Further,
it should be easily extensible so that individual applications can
easily provide application specific capabilities available in the macro
language itself, while still providing a robust, uniform syntax across
a variety of applications.  To say that Tcl satisfies these
requirements would be a spectacular understatement.


File: plplotdoc.info,  Node: Capabilities of Tcl,  Next: Acquiring Tcl,  Prev: Motivation for Tcl,  Up: Introduction to Tcl

15.1.2 Capabilities of Tcl
--------------------------

The mechanics of using Tcl are very straightforward.  Basically you
just have to include the file `tcl.h', issue some API calls to create a
Tcl interpreter, and then evaluate a script file or perform other
operations supported by the Tcl API.  Then just link against `libtcl.a'
and off you go.

   Having done this, you have essentially created a shell.  That is,
your program can now execute shell scripts in the Tcl language.  Tcl
provides support for basic control flow, variable substitution file i/o
and subroutines.  In addition to the built in Tcl commands, you can
define your own subroutines as Tcl procedures which effectively become
new keywords.

   But the real power of this approach is to add new commands to the
interpreter which are realized by compiled C code in your application.
Tcl provides a straightforward API call which allows you to register a
function in your code to be called whenever the interpreter comes
across a specific keyword of your choosing in the shell scripts it
executes.

   This facility allows you with tremendous ease, to endow your
application with a powerful, robust and full featured macro language,
trivially extend that macro language with new keywords which trigger
execution of compiled application specific commands, and thereby raise
the level of interaction with your code to one of essentially shell
programming via script editing.


File: plplotdoc.info,  Node: Acquiring Tcl,  Prev: Capabilities of Tcl,  Up: Introduction to Tcl

15.1.3 Acquiring Tcl
--------------------

There are several important sources of info and code for Tcl.
Definitely get the book mentioned above, and the source code for the
Tcl and Tk toolkits can be downloaded from The Tcl developer Xchange
(http://www.tcl.tk/software/tcltk/download.html).

   Additionally there is a newsgroup, `comp.lang.tcl' which is well
read, and an excellent place for people to get oriented, find help,
etc.  Highly recommended.

   In any event, in order to use the Tk driver in PLplot, you will need
Tcl-8.2 and Tk-8.2 (or higher versions). Additionally, in order to use
the extended WISH paradigm (described below) you will need iTcl-3.1 (or
a higher version).

   However, you will quite likely find Tcl/Tk to be very addictive, and
the great plethora of add-ons available at `harbor' will undoubtedly
attract no small amount of your attention.  It has been our experience
that all of these extensions fit together very well.  You will find
that there are large sectors of the Tcl user community which create
so-called ‘MegaWishes’ which combine many of the available extensions
into a single, heavily embellished, shell interpreter.  The benefits of
this approach will become apparent as you gain experience with Tcl and
Tk.


File: plplotdoc.info,  Node: Introduction to Tk,  Next: Introduction to [incr Tcl],  Prev: Introduction to Tcl,  Up: Building an Extended WISH

15.2 Introduction to Tk
=======================

As mentioned above, Tcl is designed to be extensible.  The first and
most basic Tcl extension is Tk, an X11 toolkit.  Tk provides the same
basic facilities that you may be familiar with from other X11 toolkits
such as Athena and Motif, except that they are provided in the context
of the Tcl language.  There are C bindings too, but these are seldom
needed--the vast majority of useful Tk applications can be coded using
Tcl scripts.

   If it has not become obvious already, it is worth noting at this
point that Tcl is one example of a family of languages known generally
as ‘Very High Level Languages’, or VHLL's.  Essentially a VHLL raises
the level of programming to a very high level, allowing very short
token streams to accomplish as much as would be required by many scores
of the more primitive actions available in a basic HLL.  Consider, for
example, the basic ‘Hello World!’ application written in Tcl/Tk.


     	#!/usr/local/bin/wish -f

     	button .hello -text "Hello World!"  -command "destroy ."
     	pack .hello

   That's it!  That's all there is to it.  If you have ever programmed X
using a traditional toolkit such as Athena or Motif, you can appreciate
how amazingly much more convenient this is.  If not, you can either
take our word for it that this is 20 times less code than you would
need to use a standard toolkit, or you can go write the same program in
one of the usual toolkits and see for yourself...

   We cannot hope to provide a thorough introduction to Tk programming
in this section.  Instead, we will just say that immensely complex
applications can be constructed merely by programming in exactly the
way shown in the above script.  By writing more complex scripts, and by
utilizing the additional widgets provided by Tk, one can create
beautiful, extensive user interfaces.  Moreover, this can be done in a
tiny fraction of the time it takes to do the same work in a
conventional toolkit.  Literally minutes versus days.

   Tk provides widgets for labels, buttons, radio buttons, frames with
or without borders, menubars, pull downs, toplevels, canvases, edit
boxes, scroll bars, etc.

   A look at the interface provided by the PLplot Tk driver should help
give you a better idea of what you can do with this paradigm.  Also
check out some of the contributed Tcl/Tk packages available at harbor.
There are high quality Tk interfaces to a great many familiar Unix
utilities ranging from mail to info, to SQL, to news, etc.  The list is
endless and growing fast...



Local Variables:
coding: utf-8
End:
