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: Introduction to [incr Tcl],  Next: PLplot Extensions to Tcl,  Prev: Introduction to Tk,  Up: Building an Extended WISH

15.3 Introduction to [incr Tcl]
===============================

Another extremely powerful and popular extension to Tcl is [incr Tcl].
[incr Tcl] is to Tcl what C++ is to C.  The analogy is very extensive.
Itcl provides an object oriented extension to Tcl supporting clustering
of procedures and data into what is called an `itcl_class'.  An
`itcl_class' can have methods as well as instance data.  And they
support inheritance.  Essentially if you know how C++ relates to C, and
if you know Tcl, then you understand the programming model provided by
Itcl.

   In particular, you can use Itcl to implement new widgets which are
composed of more basic Tk widgets.  A file selector is an example.
Using Tk, one can build up a very nice file selector comprised of more
basic Tk widgets such as entries, listboxes, scrollbars, etc.

   But what if you need two file selectors?  You have to do it all
again.  Or what if you need two different kinds of file selectors, you
get to do it again and add some incremental code.

   This is exactly the sort of thing object orientation is intended to
assist.  Using Itcl you can create an `itcl_class FileSelector' and
then you can instantiate them freely as easily as:


     	FileSelector .fs1
     	.fs1 -dir . -find "*.cc"

   and so forth.

   These high level widgets composed of smaller Tk widgets, are known as
‘megawidgets’.  There is a developing subculture of the Tcl/Tk
community for designing and implementing megawidgets, and [incr Tcl] is
the most popular enabling technology.

   In particular, it is the enabling technology which is employed for
the construction of the PLplot Tcl extensions, described below.


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

15.4 PLplot Extensions to Tcl
=============================

Following the paradigm described above, PLplot provides extensions to
Tcl as well, designed to allow the use of PLplot from Tcl/Tk programs.
Essentially the idea here is to allow PLplot programmers to achieve two
goals:

   * To access PLplot facilities from their own extended WISH and/or
     Tcl/Tk user interface scripts.

   * To have PLplot display its output in a window integrated directly
     into the rest of their Tcl/Tk interface.

   For instance, prior to PLplot 5.0, if a programmer wanted to use
PLplot in a Tcl/Tk application, the best he could manage was to call
the PLplot C API from compiled C code, and get the output via the Xwin
driver, which would display in it's own toplevel window.  In other
words, there was no integration, and the result was pretty sloppy.

   With PLplot 5.0, there is now a supported Tcl interface to PLplot
functionality.  This is provided through a ‘family’ of PLplot
megawidgets implemented in [incr Tcl].  Using this interface, a
programmer can get a PLplot window/widget into a Tk interface as easily
as:


     	PLWin .plw
     	pack .plw

   Actually, there's the update/init business--need to clear that up.

   The `PLWin' class then mirrors much of the PLplot C API, so that a
user can generate plots in the PLplot widget entirely from Tcl.  This
is demonstrated in the `tk02' demo,


File: plplotdoc.info,  Node: Custom Extensions to Tcl,  Prev: PLplot Extensions to Tcl,  Up: Building an Extended WISH

15.5 Custom Extensions to Tcl
=============================

By this point, you should have a pretty decent understanding of the
underlying philosophy of Tcl and Tk, and the whole concept of
extensions, of which [incr Tcl] and PLplot are examples.  These alone
are enough to allow the rapid prototyping and development of powerful,
flexible graphical applications.  Normally the programmer simply writes
a shell script to be executed by the Tk windowing shell, `wish'.  It is
in vogue for each Tcl/Tk extension package to build it's own ‘extended
WISH’.  There are many examples of this, and indeed even PLplot's
`plserver' program, described in an earlier chapter, could just as
easily have been called `plwish'.

   In any event, as exciting and useful as these standalone, extended
windowing shells may be, they are ultimately only the beginning of what
you can do.  The real benefit of this approach is realized when you
make your own ‘extended WISH’, comprised of Tcl, Tk, any of the
standard extensions you like, and finally embellished with a smattering
of application specific extensions designed to support your own
application domain.  In this section we give a detailed introduction to
the process of constructing your own WISH.  After that, you're on your
own...

* Menu:

* WISH Construction::
* WISH Linking::
* WISH Programming::


File: plplotdoc.info,  Node: WISH Construction,  Next: WISH Linking,  Up: Custom Extensions to Tcl

15.5.1 WISH Construction
------------------------

The standard way to make your own WISH, as supported by the Tcl/Tk
system, is to take a boilerplate file, `tkAppInit.c', edit to reflect
the Tcl/Tk extensions you will be requiring, add some commands to the
interpreter, and link it all together.

   Here for example is the important part of the `tk02' demo, extracted
from the file `xtk02.c', which is effectively the extended WISH
definition file for the `tk02' demo.  Comments and other miscellany are
omitted.


     	  #include "tk.h"
     	  #include "itcl.h"

     	  /* ... */

     	  int   myplotCmd        (ClientData, Tcl_Interp *, int, char **);

     	  int
     	  Tcl_AppInit(interp)
     	  Tcl_Interp *interp;		/* Interpreter for application. */
     	  {
     	  int   plFrameCmd        (ClientData, Tcl_Interp *, int, char **);

     	  Tk_Window main;

     	  main = Tk_MainWindow(interp);

     	  /*
     	  * Call the init procedures for included packages.  Each call should
     	  * look like this:
     	  *
     	  * if (Mod_Init(interp) == TCL_ERROR) {
     	  *     return TCL_ERROR;
     	  * }
     	  *
     	  * where "Mod" is the name of the module.
     	  */

     	  if (Tcl_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }
     	  if (Tk_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }
     	  if (Itcl_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }
     	  if (Pltk_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }

     	  /*
     	  * Call Tcl_CreateCommand for application-specific commands, if
     	  * they weren't already created by the init procedures called above.
     	  */

     	  Tcl_CreateCommand(interp, "myplot", myplotCmd,
     	  (ClientData) main, (void (*)(ClientData)) NULL);


     	  /*
     	  * Specify a user-specific start up file to invoke if the
     	  * application is run interactively.  Typically the start up
     	  * file is "~/.apprc" where "app" is the name of the application.
     	  * If this line is deleted then no user-specific start up file
     	  * will be run under any conditions.
     	  */

     	  tcl_RcFileName = "~/.wishrc";
     	  return TCL_OK;
     	  }

     	  /* ... myPlotCmd, etc ... */

   The calls to `Tcl_Init()' and `Tk_Init()' are in every WISH.  To
make an extended WISH, you add calls to the initialization routines for
any extension packages you want to use, in this [incr Tcl]
(`Itcl_Init()') and PLplot (`Pltk_Init()').  Finally you add keywords
to the interpreter, associating them with functions in your code using
`Tcl_CreateCommand()' as shown.

   In particular, PLplot has a number of [incr Tcl] classes in its Tcl
library.  If you want to be able to use those in your WISH, you need to
include the initialization of [incr Tcl].


File: plplotdoc.info,  Node: WISH Linking,  Next: WISH Programming,  Prev: WISH Construction,  Up: Custom Extensions to Tcl

15.5.2 WISH Linking
-------------------

Having constructed your `Tcl_AppInit()' function, you now merely need
to link this file with your own private files to provide the code for
any functions you registered via `Tcl_CreateCommand()' (and any they
depend on), against the Tcl, Tk and extension libraries you are using.


     	  cc -c tkAppInit.c
     	  cc -c mycommands.c
     	  cc -o my_wish tkAppInit.o mycommands.o
     	  -lplplotftk -ltcl -ltk -litcl -lX11 -lm

   Add any needed `-L' options as needed.

   Voila!  You have made a wish.


File: plplotdoc.info,  Node: WISH Programming,  Prev: WISH Linking,  Up: Custom Extensions to Tcl

15.5.3 WISH Programming
-----------------------

Now you are ready to put the genie to work.  The basic plan here is to
write shell scripts which use your new application specific windowing
shell as their interpreter, to implement X Windows user interfaces to
control and utilize the facilities made available in your extensions.

   Effectively this just comes down to writing Tcl/Tk code, embellished
as appropriate with calls to the extension commands you registered.
Additionally, since this wish includes the PLplot extensions, you can
instantiate any of the PLplot family of [incr Tcl] classes, and invoke
methods on those objects to effect the drawing of graphs.  Similarly,
you may have your extension commands (which are coded in C) call the
PLplot C programmers API to draw into the widget.  In this way you can
have the best of both worlds.  Use compiled C code when the
computational demands require the speed of compiled code, or use Tcl
when your programming convenience is more important than raw speed.


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

16 Embedding Plots in Graphical User Interfaces
***********************************************

This chapter should describe how to embed plots in graphical user
interfaces.  *note Building an Extended WISH:: does that for Tk, but
embedding plots in GTK+ and Qt GUI's NEEDS DOCUMENTATION.  Until that
GTK+ and QT4 documentation is prepared, look at examples/c/README.cairo
and examples/c++/README.qt_example for some proof-of-concept examples.


File: plplotdoc.info,  Node: Bibliography,  Next: The Common API for PLplot,  Prev: Embedding Plots in Graphical User Interfaces,  Up: Top

17 Bibliography
***************

These articles are descriptions of PLplot itself or else scientific
publications whose figures were generated with PLplot.

* Menu:

* References::


File: plplotdoc.info,  Node: References,  Up: Bibliography

17.1 References
===============

Furnish G., Das Graphikpaket PLplot (in German)
(http://www.linux-magazin.de/ausgabe/1996/12/Plplot/plplot.html), Linux
Magazin, 1996 December

   Furnish G., Horton W., Kishimoto Y., LeBrun M., Tajima T., Global
Gyrokinetic Simulation of Tokamak Transport, Physics of Plasmas, 6, 1,
1999

   Irwin A.W., Fukushima T., A Numerical Time Ephemeris of the Earth,
Astronomy and Astrophysics, 348, 642, 1999

   LeBrun M.J., Tajima T., Gray M., Furnish G., Horton W., Toroidal
Effects on Drift-Wave Turbulence, Physics of Fluids, B5, 752, 1993


File: plplotdoc.info,  Node: The Common API for PLplot,  Next: The Specialized C API for PLplot,  Prev: Bibliography,  Up: Top

18 The Common API for PLplot
****************************

The purpose of this chapter is to document the API for every PLplot
function that should be available across all PLplot language bindings.
This common API between the various languages constitutes the most
important part of the PLplot API that programmers need to know.  Note
that in C, these common API routines have a special ‘c_’ prefix name
assigned to them in `plplot.h'.

   What follows is a list of all common API functions of the latest
PLplot version with their arguments except for obsolete/deprecated API
functions which are listed in *note Obsolete/Deprecated API for
PLplot::. The following information is provided for each function:

  1. The function name and a brief description.

  2. The function as it would be called from C.

  3. A complete description of the function.

  4. A description of each argument that the function takes.

  5. The redacted argument form of the function, currently used by the
     programming languages Fortran95, Python, Java and Perl, as well as
     any language specific variations that might occur on the general
     calling scheme described in the following paragraph.

  6. A list of PLplot examples that demonstrate how to use the function.

Additional PLplot API specialized for each language binding is
documented in *note The Specialized C API for PLplot:: and subsequent
chapters.

   The general calling scheme for the other languages supported by
PLplot is as follows, using the function `plline' as an example.

   * C: `plline(n,x,y)'

   * F95: `plline(x,y)'

   * C++: `pls->line(n,x,y)'

   * Java: `pls.line(x,y)'

   * Perl/PDL: `plline($x,$y)'

   * Python: `plline(x,y)'

   * Tcl/Tk: `$w cmd plline $n x y'

Note that in some languages the argument n (which specifies the length
of the arrays x and y) is not necessary, this is what we refer to above
as the ‘redacted argument form’ of the function.

* Menu:

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


File: plplotdoc.info,  Node: pl_setcontlabelformat; Set format of numerical label for contours,  Next: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label,  Up: The Common API for PLplot

18.1 pl_setcontlabelformat: Set  format of numerical label for contours
=======================================================================

     pl_setcontlabelformat (lexp, sigdig);

   Set format of numerical label for contours.

`lexp'  (`PLINT', input)
     If the contour numerical label is greater than 10^(lexp) or less
     than 10^(-lexp), then the exponential format is used.  Default
     value of lexp is 4.

`sigdig'  (`PLINT', input)
     Number of significant digits.  Default value is 2.

   Redacted form: `pl_setcontlabelformat(lexp, sigdig)'

   This function is used example 9.


File: plplotdoc.info,  Node: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label,  Next: pladv; Advance the [sub-]page,  Prev: pl_setcontlabelformat; Set format of numerical label for contours,  Up: The Common API for PLplot

18.2 pl_setcontlabelparam: Set parameters of  contour labelling other than format of numerical label
====================================================================================================

     pl_setcontlabelparam (offset, size, spacing, active);

   Set parameters of contour labelling other than those handled by
`pl_setcontlabelformat' (*note pl_setcontlabelformat; Set format of
numerical label for contours::).

`offset'  (`PLFLT', input)
     Offset of label from contour line (if set to 0.0, labels are
     printed on the lines).  Default value is 0.006.

`size'  (`PLFLT', input)
     Font height for contour labels (normalized).  Default value is 0.3.

`spacing'  (`PLFLT', input)
     Spacing parameter for contour labels.  Default value is 0.1.

`active'  (`PLINT', input)
     Activate labels.  Set to 1 if you want contour labels on.  Default
     is off (0).

   Redacted form: `pl_setcontlabelparam(offset, size, spacing, active)'

   This function is used in example 9.


File: plplotdoc.info,  Node: pladv; Advance the [sub-]page,  Next: plarc; Draw a circular or elliptical arc,  Prev: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label,  Up: The Common API for PLplot

18.3 pladv: Advance the (sub-)page
==================================

     pladv (page);

   Advances to the next subpage if ``sub'=0', performing a page advance
if there are no remaining subpages on the current page.  If subpages
aren't being used, ``pladv' (*note pladv; Advance the [sub-]page::)(0)'
will always advance the page.  If ``page'>0', PLplot switches to the
specified subpage.  Note that this allows you to overwrite a plot on
the specified subpage; if this is not what you intended, use `pleop'
(*note pleop; Eject current page::) followed by `plbop' (*note plbop;
Begin a new page::) to first advance the page.  This routine is called
automatically (with ``page'=0') by `plenv' (*note plenv; Set up
standard window and draw box::), but if `plenv' (*note plenv; Set up
standard window and draw box::) is not used, `pladv' (*note pladv;
Advance the [sub-]page::) must be called after initializing PLplot but
before defining the viewport.

`page'  (`PLINT', input)
     Specifies the subpage number (starting from 1 in the top left
     corner and increasing along the rows) to which to advance.  Set to
     zero to advance to the next subpage (or to the next page if
     subpages are not being used).

   Redacted form: `pladv(page)'

   This function is used in examples 1,2,4,6-12,14-18,20,21,23-27,29,31.


File: plplotdoc.info,  Node: plarc; Draw a circular or elliptical arc,  Next: plaxes; Draw a box with axes; etc_ with arbitrary origin,  Prev: pladv; Advance the [sub-]page,  Up: The Common API for PLplot

18.4 plarc: Draw a circular or elliptical arc
=============================================

     plarc (x, y, a, b, angle1, angle2, rotate, fill);

   Draw a possibly filled arc centered at ``x'', ``y'' with semimajor
axis ``a'' and semiminor axis ``b'', starting at ``angle1'' and ending
at ``angle2''.

`x'  (`PLFLT', input)
     X coordinate of arc center.

`y'  (`PLFLT', input)
     Y coordinate of arc center.

`a'  (`PLFLT', input)
     Length of the semimajor axis of the arc.

`b'  (`PLFLT', input)
     Length of the semiminor axis of the arc.

`angle1'  (`PLFLT', input)
     Starting angle of the arc relative to the semimajor axis.

`angle2'  (`PLFLT', input)
     Ending angle of the arc relative to the semimajor axis.

`rotate'  (`PLFLT', input)
     Angle of the semimajor axis relative to the X-axis.

`fill'  (`PLBOOL', input)
     Draw a filled arc.

   Redacted form:

   * General: `plarc(x, y, a, b, angle1, angle2, rotate, fill)'

   This function is used in examples 3 and 27.


File: plplotdoc.info,  Node: plaxes; Draw a box with axes; etc_ with arbitrary origin,  Next: plbin; Plot a histogram from binned data,  Prev: plarc; Draw a circular or elliptical arc,  Up: The Common API for PLplot

18.5 plaxes: Draw a box with axes, etc. with arbitrary  origin
==============================================================

     plaxes (x0, y0, xopt, xtick, nxsub, yopt, ytick, nysub);

   Draws a box around the currently defined viewport with arbitrary
world-coordinate origin specified by ``x0'' and ``y0'' and labels it
with world coordinate values appropriate to the window.  Thus `plaxes'
(*note plaxes; Draw a box with axes; etc_ with arbitrary origin::)
should only be called after defining both viewport and window.  The
character strings ``xopt'' and ``yopt'' specify how the box should be
drawn as described below.  If ticks and/or subticks are to be drawn for
a particular axis, the tick intervals and number of subintervals may be
specified explicitly, or they may be defaulted by setting the
appropriate arguments to zero.

`x0'  (`PLFLT', input)
     World X coordinate of origin.

`y0'  (`PLFLT', input)
     World Y coordinate of origin.

`xopt'  (`const char *', input)
     Pointer to character string specifying options for horizontal
     axis.  The string can include any combination of the following
     letters (upper or lower case) in any order:

        * `a': Draws axis, X-axis is horizontal line (`y=0'), and
          Y-axis is vertical line (`x=0').

        * `b': Draws bottom (X) or left (Y) edge of frame.

        * `c': Draws top (X) or right (Y) edge of frame.

        * `d': Plot labels as date / time.  Values are assumed to be
          seconds since the epoch (as used by gmtime).

        * `f':  Always use fixed point numeric labels.

        * `g': Draws a grid at the major tick interval.

        * `h': Draws a grid at the minor tick interval.

        * `i': Inverts tick marks, so they are drawn outwards, rather
          than inwards.

        * `l': Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        * `m': Writes numeric labels at major tick intervals in the
          unconventional location (above box for X, right of box for Y).

        * `n': Writes numeric labels at major tick intervals in the
          conventional location (below box for X, left of box for Y).

        * `o': Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          `plslabelfunc' (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        * `s': Enables subticks between major ticks, only valid if `t'
          is also specified.

        * `t': Draws major ticks.

        * `u': Exactly like "b" except don't draw edge line.

        * `w': Exactly like "c" except don't draw edge line.

        * `x': Exactly like "t" (including the side effect of the
          numerical labels for the major ticks) except exclude drawing
          the major and minor tick marks.

`xtick'  (`PLFLT', input)
     World coordinate interval between major ticks on the x axis.  If
     it is set to zero, PLplot automatically generates a suitable tick
     interval.

`nxsub'  (`PLINT', input)
     Number of subintervals between major x axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

`yopt'  (`const char *', input)
     Pointer to character string specifying options for vertical axis.
     The string can include any combination of the letters defined
     above for ``xopt'', and in addition may contain:

        * `v': Write numeric labels for vertical axis parallel to the
          base of the graph, rather than parallel to the axis.

`ytick'  (`PLFLT', input)
     World coordinate interval between major ticks on the y axis.  If
     it is set to zero, PLplot automatically generates a suitable tick
     interval.

`nysub'  (`PLINT', input)
     Number of subintervals between major y axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

   Redacted form:

   * General: `plaxes(x0, y0, xopt, xtick, nxsub, yopt, ytick, nysub)'

   * Perl/PDL: `plaxes(x0, y0, xtick, nxsub, ytick, nysub, xopt, yopt)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plbin; Plot a histogram from binned data,  Next: plbop; Begin a new page,  Prev: plaxes; Draw a box with axes; etc_ with arbitrary origin,  Up: The Common API for PLplot

18.6 plbin: Plot a histogram from binned data
=============================================

     plbin (nbin, x, y, opt);

   Plots a histogram consisting of ``nbin'' bins.  The value associated
with the `i''th bin is placed in ``x'[i]', and the number of points in
the bin is placed in ``y'[i]'.  For proper operation, the values in
``x'[i]' must form a strictly increasing sequence.  By default,
``x'[i]' is the left-hand edge of the `i''th bin. If
``opt'=PL_BIN_CENTRED' is used, the bin boundaries are placed midway
between the values in the ``x'' array.  Also see `plhist' (*note
plhist; Plot a histogram from unbinned data::) for drawing histograms
from unbinned data.

`nbin'  (`PLINT', input)
     Number of bins (i.e., number of values in ``x'' and ``y'' arrays.)

`x'  (`const PLFLT *', input)
     Pointer to array containing values associated with bins.  These
     must form a strictly increasing sequence.

`y'  (`const PLFLT *', input)
     Pointer to array containing number of points in bin.  This is a
     `PLFLT' (instead of `PLINT') array so as to allow histograms of
     probabilities, etc.

`opt'  (`PLINT', input)
     Is a combination of several flags:

        * ``opt'=PL_BIN_DEFAULT': The ``x'' represent the lower bin
          boundaries, the outer bins are expanded to fill up the entire
          x-axis and bins of zero height are simply drawn.

        * ``opt'=PL_BIN_CENTRED|...': The bin boundaries are to be
          midway between the ``x'' values. If the values in ``x'' are
          equally spaced, the values are the center values of the bins.

        * ``opt'=PL_BIN_NOEXPAND|...': The outer bins are drawn with
          equal size as the ones inside.

        * ``opt'=PL_BIN_NOEMPTY|...': Bins with zero height are not
          drawn (there is a gap for such bins).

   Redacted form:

   * General: `plbin(x, y, opt)'

   * Perl/PDL: `plbin(nbin, x, y, opt)'

   * Python: `plbin(nbin, x, y, opt)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plbop; Begin a new page,  Next: plbox; Draw a box with axes; etc,  Prev: plbin; Plot a histogram from binned data,  Up: The Common API for PLplot

18.7 plbop: Begin a new page
============================

     plbop ();

   Begins a new page.  For a file driver, the output file is opened if
necessary.  Advancing the page via `pleop' (*note pleop; Eject current
page::) and `plbop' (*note plbop; Begin a new page::) is useful when a
page break is desired at a particular point when plotting to subpages.
Another use for `pleop' (*note pleop; Eject current page::) and `plbop'
(*note plbop; Begin a new page::) is when plotting pages to different
files, since you can manually set the file name by calling `plsfnam'
(*note plsfnam; Set output file name::) after the call to `pleop'
(*note pleop; Eject current page::).  (In fact some drivers may only
support a single page per file, making this a necessity.)  One way to
handle this case automatically is to page advance via `pladv' (*note
pladv; Advance the [sub-]page::), but enable familying (see `plsfam'
(*note plsfam; Set family file parameters::)) with a small limit on the
file size so that a new family member file will be created on each page
break.

   Redacted form: `plbop()'

   This function is used in examples 2,20.


File: plplotdoc.info,  Node: plbox; Draw a box with axes; etc,  Next: plbox3; Draw a box with axes; etc; in 3-d,  Prev: plbop; Begin a new page,  Up: The Common API for PLplot

18.8 plbox: Draw a box with axes, etc
=====================================

     plbox (xopt, xtick, nxsub, yopt, ytick, nysub);

   Draws a box around the currently defined viewport, and labels it with
world coordinate values appropriate to the window.  Thus `plbox' (*note
plbox; Draw a box with axes; etc::) should only be called after
defining both viewport and window.  The character strings ``xopt'' and
``yopt'' specify how the box should be drawn as described below.  If
ticks and/or subticks are to be drawn for a particular axis, the tick
intervals and number of subintervals may be specified explicitly, or
they may be defaulted by setting the appropriate arguments to zero.

`xopt'  (`const char *', input)
     Pointer to character string specifying options for horizontal
     axis.  The string can include any combination of the following
     letters (upper or lower case) in any order:

        * `a': Draws axis, X-axis is horizontal line (`y=0'), and
          Y-axis is vertical line (`x=0').

        * `b': Draws bottom (X) or left (Y) edge of frame.

        * `c': Draws top (X) or right (Y) edge of frame.

        * `d': Plot labels as date / time.  Values are assumed to be
          seconds since the epoch (as used by gmtime).

        * `f':  Always use fixed point numeric labels.

        * `g': Draws a grid at the major tick interval.

        * `h': Draws a grid at the minor tick interval.

        * `i': Inverts tick marks, so they are drawn outwards, rather
          than inwards.

        * `l': Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        * `m': Writes numeric labels at major tick intervals in the
          unconventional location (above box for X, right of box for Y).

        * `n': Writes numeric labels at major tick intervals in the
          conventional location (below box for X, left of box for Y).

        * `o': Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          `plslabelfunc' (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        * `s': Enables subticks between major ticks, only valid if `t'
          is also specified.

        * `t': Draws major ticks.

        * `u': Exactly like "b" except don't draw edge line.

        * `w': Exactly like "c" except don't draw edge line.

        * `x': Exactly like "t" (including the side effect of the
          numerical labels for the major ticks) except exclude drawing
          the major and minor tick marks.

`xtick'  (`PLFLT', input)
     World coordinate interval between major ticks on the x axis.  If
     it is set to zero, PLplot automatically generates a suitable tick
     interval.

`nxsub'  (`PLINT', input)
     Number of subintervals between major x axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

`yopt'  (`const char *', input)
     Pointer to character string specifying options for vertical axis.
     The string can include any combination of the letters defined
     above for ``xopt'', and in addition may contain:

        * `v': Write numeric labels for vertical axis parallel to the
          base of the graph, rather than parallel to the axis.

`ytick'  (`PLFLT', input)
     World coordinate interval between major ticks on the y axis.  If
     it is set to zero, PLplot automatically generates a suitable tick
     interval.

`nysub'  (`PLINT', input)
     Number of subintervals between major y axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

   Redacted form:

   * General: `plbox(xopt, xtick, nxsub, yopt, ytick, nysub)'

   * Perl/PDL: `plbox(xtick, nxsub, ytick, nysub, xopt, yopt)'

   This function is used in examples 1,2,4,6,6-12,14-18,21,23-26,29.


File: plplotdoc.info,  Node: plbox3; Draw a box with axes; etc; in 3-d,  Next: plbtime; Calculate broken-down time from continuous time for the current stream,  Prev: plbox; Draw a box with axes; etc,  Up: The Common API for PLplot

18.9 plbox3: Draw a box with axes, etc, in 3-d
==============================================

     plbox3 (xopt, xlabel, xtick, nxsub, yopt, ylabel, ytick, nysub,
     zopt, zlabel, ztick, nzsub);

   Draws axes, numeric and text labels for a three-dimensional surface
plot.  For a more complete description of three-dimensional plotting
see *note Three Dimensional Surface Plots::.

`xopt'  (`const char *', input)
     Pointer to character string specifying options for the x axis.
     The string can include any combination of the following letters
     (upper or lower case) in any order:

        * `b': Draws axis at base, at height `z=`zmin'' where ``zmin''
          is defined by call to `plw3d' (*note plw3d; Set up window for
          3-d plotting::).  This character must be specified in order
          to use any of the other options.

        * `f': Always use fixed point numeric labels.

        * `i': Inverts tick marks, so they are drawn downwards, rather
          than upwards.

        * `l': Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        * `n': Writes numeric labels at major tick intervals.

        * `o': Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          `plslabelfunc' (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        * `s': Enables subticks between major ticks, only valid if `t'
          is also specified.

        * `t': Draws major ticks.

        * `u': If this is specified, the text label for the axis is
          written under the axis.

`xlabel'  (`const char *', input)
     Pointer to character string specifying text label for the x axis.
     It is only drawn if `u' is in the ``xopt'' string.

`xtick'  (`PLFLT', input)
     World coordinate interval between major ticks on the x axis.  If
     it is set to zero, PLplot automatically generates a suitable tick
     interval.

`nxsub'  (`PLINT', input)
     Number of subintervals between major x axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

`yopt'  (`const char *', input)
     Pointer to character string specifying options for the y axis.
     The string is interpreted in the same way as ``xopt''.

`ylabel'  (`const char *', input)
     Pointer to character string specifying text label for the y axis.
     It is only drawn if `u' is in the ``yopt'' string.

`ytick'  (`PLFLT', input)
     World coordinate interval between major ticks on the y axis.  If
     it is set to zero, PLplot automatically generates a suitable tick
     interval.

`nysub'  (`PLINT', input)
     Number of subintervals between major y axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

`zopt'  (`const char *', input)
     Pointer to character string specifying options for the z axis.
     The string can include any combination of the following letters
     (upper or lower case) in any order:

        * `b': Draws z axis to the left of the surface plot.

        * `c': Draws z axis to the right of the surface plot.

        * `d': Draws grid lines parallel to the x-y plane behind the
          figure.  These lines are not drawn until after `plot3d'
          (*note plot3d; Plot 3-d surface plot::) or `plmesh' (*note
          plmesh; Plot surface mesh::) are called because of the need
          for hidden line removal.

        * `f': Always use fixed point numeric labels.

        * `i': Inverts tick marks, so they are drawn away from the
          center.

        * `l': Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        * `m': Writes numeric labels at major tick intervals on the
          right-hand vertical axis.

        * `n': Writes numeric labels at major tick intervals on the
          left-hand vertical axis.

        * `o': Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          `plslabelfunc' (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        * `s': Enables subticks between major ticks, only valid if `t'
          is also specified.

        * `t': Draws major ticks.

        * `u': If this is specified, the text label is written beside
          the left-hand axis.

        * `v': If this is specified, the text label is written beside
          the right-hand axis.

`zlabel'  (`const char *', input)
     Pointer to character string specifying text label for the z axis.
     It is only drawn if `u' or `v' are in the ``zopt'' string.

`ztick'  (`PLFLT', input)
     World coordinate interval between major ticks on the z axis.  If
     it is set to zero, PLplot automatically generates a suitable tick
     interval.

`nzsub'  (`PLINT', input)
     Number of subintervals between major z axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

   Redacted form:

   * General: `plbox3(xopt, xlabel, xtick, nxsub, yopt, ylabel, ytick,
     nysub, zopt, zlabel, ztick, nzsub)'

   * Perl/PDL: `plbox3(xtick, nxsub, ytick, nysub, ztick, nzsub, xopt,
     xlabel, yopt, ylabel, zopt, zlabel)'

   This function is used in examples 8,11,18,21.


File: plplotdoc.info,  Node: plbtime; Calculate broken-down time from continuous time for the current stream,  Next: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates,  Prev: plbox3; Draw a box with axes; etc; in 3-d,  Up: The Common API for PLplot

18.10 plbtime: Calculate broken-down time from  continuous time for the current stream
======================================================================================

     plbtime (year, month, day, hour, min, sec, ctime);

   Calculate broken-down time; ``year'', ``month'', ``day'', ``hour'',
``min'', ``sec''; from continuous time, ``ctime'' for the current
stream.  This function is the inverse of `plctime' (*note plctime;
Calculate continuous time from broken-down time for the current
stream::).

   The PLplot definition of broken-down time is a calendar time that
completely ignores all time zone offsets, i.e., it is the user's
responsibility to apply those offsets (if so desired) before using the
PLplot time API.  By default broken-down time is defined using the
proleptic Gregorian calendar without the insertion of leap seconds and
continuous time is defined as the number of seconds since the Unix
epoch of 1970-01-01T00:00:00Z.  However, other definitions of
broken-down and continuous time are possible, see `plconfigtime' (*note
plconfigtime; Configure the transformation between continuous and
broken-down time for the current stream::).

`year'  (`PLINT *', output)
     Output year.

`month'  (`PLINT *', output)
     Output month in range from 0 (January) to 11 (December).

`day'  (`PLINT *', output)
     Output day in range from 1 to 31.

`hour'  (`PLINT *', output)
     Output hour in range from 0 to 23.

`min'  (`PLINT *', output)
     Output minute in range from 0 to 59

`sec'  (`PLFLT *', output)
     Output second in floating range from 0. to 60.

`ctime'  (`PLFLT', input)
     Continous time from which the broken-down time is calculated.

   Redacted form:

   * General: `plbtime(year, month, day, hour, min, sec, ctime)'

   * Perl/PDL: Not available?

   This function is used in example 29.


File: plplotdoc.info,  Node: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates,  Next: plclear; Clear current [sub]page,  Prev: plbtime; Calculate broken-down time from continuous time for the current stream,  Up: The Common API for PLplot

18.11 plcalc_world: Calculate world coordinates and  corresponding window index from relative device coordinates
================================================================================================================

     plcalc_world (rx, ry, wx, wy, window);

   Calculate world coordinates, ``wx'' and ``wy'', and corresponding
``window'' index from relative device coordinates, ``rx'' and ``ry''.

`rx'  (`PLFLT', input)
     Input relative device coordinate (ranging from 0. to 1.) for the x
     coordinate.

`ry'  (`PLFLT', input)
     Input relative device coordinate (ranging from 0. to 1.) for the y
     coordinate.

`wx'  (`PLFLT *', output)
     Pointer to the returned world coordinate for x corresponding to
     the relative device coordinates ``rx'' and ``ry''.

`wy'  (`PLFLT *', output)
     Pointer to the returned world coordinate for y corresponding to
     the relative device coordinates ``rx'' and ``ry''.

`window'  (`PLINT *', output)
     Pointer to the returned last defined window index that corresponds
     to the input relative device coordinates (and the returned world
     coordinates).  To give some background on the window index, for
     each page the initial window index is set to zero, and each time
     `plwind' (*note plwind; Specify world coordinates of viewport
     boundaries::) is called within the page, world and device
     coordinates are stored for the window and the window index is
     incremented.  Thus, for a simple page layout with non-overlapping
     viewports and one window per viewport, ``window'' corresponds to
     the viewport index (in the order which the viewport/windows were
     created) of the only viewport/window corresponding to ``rx'' and
     ``ry''.  However, for more complicated layouts with potentially
     overlapping viewports and possibly more than one window (set of
     world coordinates) per viewport, ``window'' and the corresponding
     output world coordinates corresponds to the last window created
     that fulfills the criterion that the relative device coordinates
     are inside it.  Finally, in all cases where the input relative
     device coordinates are not inside any viewport/window, then
     ``window'' is set to -1.

   Redacted form:

   * General: `plcalc_world(rx, ry, wx, wy, window)'

   * Perl/PDL: Not available?

   This function is used in example 31.


File: plplotdoc.info,  Node: plclear; Clear current [sub]page,  Next: plcol0; Set color; cmap0,  Prev: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates,  Up: The Common API for PLplot

18.12 plclear: Clear current (sub)page
======================================

     plclear ();

   Clears the current page, effectively erasing everything that have
been drawn.  This command only works with interactive drivers; if the
driver does not support this, the page is filled with the background
color in use.  If the current page is divided into subpages, only the
current subpage is erased.  The nth subpage can be selected with
`pladv' (*note pladv; Advance the [sub-]page::)(n).

   Redacted form:

   * General: `plclear()'

   * Perl/PDL: Not available?

   This function is not used in any examples.


File: plplotdoc.info,  Node: plcol0; Set color; cmap0,  Next: plcol1; Set color; cmap1,  Prev: plclear; Clear current [sub]page,  Up: The Common API for PLplot

18.13 plcol0: Set color, cmap0
==============================

     plcol0 (icol0);

   Sets the color index for cmap0 (see *note Color Map0::).

`icol0'  (`PLINT', input)
     Integer representing the color.  The defaults at present are
     (these may change):

     0 black (default background)       
     1 red (default foreground)         
     2 yellow                           
     3 green                            
     4 aquamarine                       
     5 pink                             
     6 wheat                            
     7 grey                             
     8 brown                            
     9 blue                             
     10 BlueViolet                      
     11 cyan                            
     12 turquoise                       
     13 magenta                         
     14 salmon                          
     15 white                           

     Use `plscmap0' (*note plscmap0; Set cmap0 colors by 8-bit RGB
     values::) to change the entire map0 color palette and `plscol0'
     (*note plscol0; Set 8-bit RGB values for given cmap0 color
     index::) to change an individual color in the map0 color palette.

   Redacted form: `plcol0(icol0)'

   This function is used in examples 1-9,11-16,18-27,29.


File: plplotdoc.info,  Node: plcol1; Set color; cmap1,  Next: plcolorbar; Plot color bar for image; shade or gradient plots,  Prev: plcol0; Set color; cmap0,  Up: The Common API for PLplot

18.14 plcol1: Set color, cmap1
==============================

     plcol1 (col1);

   Sets the color for cmap1 (see *note Color Map1::).

`col1'  (`PLFLT', input)
     This value must be in the range from 0. to 1. and is mapped to
     color using the continuous map1 color palette which by default
     ranges from blue to the background color to red.  The map1 palette
     can also be straightforwardly changed by the user with `plscmap1'
     (*note plscmap1; Set cmap1 colors using 8-bit RGB values::) or
     `plscmap1l' (*note plscmap1l; Set cmap1 colors using a piece-wise
     linear relationship::).

   Redacted form: `plcol1(col1)'

   This function is used in examples 12 and 21.


File: plplotdoc.info,  Node: plcolorbar; Plot color bar for image; shade or gradient plots,  Next: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream,  Prev: plcol1; Set color; cmap1,  Up: The Common API for PLplot

18.15 plcolorbar: Plot color bar for image, shade or gradient plots
===================================================================

     plcolorbar (p_colorbar_width, p_colorbar_height, opt, position, x,
     y, x_length, y_length, bg_color, bb_color, bb_style,
     low_cap_color, high_cap_color, cont_color, cont_width, n_labels,
     label_opts, labels, naxes, axis_opts, ticks, sub_ticks, n_values,
     values);

   Routine for creating a continuous color bar for image, shade, or
gradient plots.  (See `pllegend' (*note pllegend; Plot legend using
discretely annotated filled boxes; lines; and/or lines of symbols::)
for similar functionality for creating legends with discrete elements).
The arguments of plcolorbar provide control over the location and size
of the color bar as well as the location and characteristics of the
elements (most of which are optional) within that color bar.  The
resulting color bar is clipped at the boundaries of the current subpage.
(N.B. the adopted coordinate system used for some of the parameters is
defined in the documentation of the ``position'' parameter.)

`p_colorbar_width'  (`PLFLT *', output)
     Pointer to a location which contains (after the call) the labelled
     and decorated color bar width in adopted coordinates.

`p_colorbar_height'  (`PLFLT *', output)
     Pointer to a location which contains (after the call) the labelled
     and decorated color bar height in adopted coordinates.

`opt'  (`PLINT', input)
     ``opt'' contains bits controlling the overall color bar.  The
     orientation (direction of the maximum value) of the color bar is
     specified with `PL_ORIENT_RIGHT', `PL_ORIENT_TOP',
     `PL_ORIENT_LEFT', or `PL_ORIENT_BOTTOM'.  If none of these bits are
     specified, the default orientation is toward the top if the
     colorbar is placed on the left or right of the viewport or toward
     the right if the colorbar is placed on the top or bottom of the
     viewport. If the `PL_COLORBAR_BACKGROUND' bit is set, plot a
     (semi-transparent) background for the color bar. If the
     `PL_COLORBAR_BOUNDING_BOX' bit is set, plot a bounding box for the
     color bar. The type of color bar must be specified with one of
     `PL_COLORBAR_IMAGE', `PL_COLORBAR_SHADE', or
     `PL_COLORBAR_GRADIENT'. If more than one of those bits is set only
     the first one in the above list is honored. The position of the
     (optional) label/title can be specified with `PL_LABEL_RIGHT',
     `PL_LABEL_TOP', `PL_LABEL_LEFT', or `PL_LABEL_BOTTOM'.  If no
     label position bit is set then no label will be drawn. If more
     than one of this list of bits is specified, only the first one on
     the list is honored. End-caps for the color bar can added with
     `PL_COLORBAR_CAP_LOW' and `PL_COLORBAR_CAP_HIGH'. If a particular
     color bar cap option is not specified then no cap will be drawn
     for that end. As a special case for `PL_COLORBAR_SHADE', the option
     `PL_COLORBAR_SHADE_LABEL' can be specified. If this option is
     provided then any tick marks and tick labels will be placed at the
     breaks between shaded segments. TODO: This should be expanded to
     support custom placement of tick marks and tick labels at custom
     value locations for any color bar type.

`position'  (`PLINT', input)
     ``position'' contains bits which control the overall position of
     the color bar and the definition of the adopted coordinates used
     for positions just like what is done for the position argument for
     `pllegend' (*note pllegend; Plot legend using discretely annotated
     filled boxes; lines; and/or lines of symbols::). However, note
     that the defaults for the position bits (see below) are different
     than the `pllegend' (*note pllegend; Plot legend using discretely
     annotated filled boxes; lines; and/or lines of symbols::) case.
     The combination of the `PL_POSITION_LEFT', `PL_POSITION_RIGHT',
     `PL_POSITION_TOP', `PL_POSITION_BOTTOM', `PL_POSITION_INSIDE', and
     `PL_POSITION_OUTSIDE' bits specifies one of the 16 possible
     standard positions (the 4 corners and centers of the 4 sides for
     both the inside and outside cases) of the color bar relative to
     the adopted coordinate system. The corner positions are specified
     by the appropriate combination of two of the `PL_POSITION_LEFT',
     `PL_POSITION_RIGHT', `PL_POSITION_TOP', and `PL_POSITION_BOTTOM'
     bits while the sides are specified by a single value of one of
     those bits.  The adopted coordinates are normalized viewport
     coordinates if the `PL_POSITION_VIEWPORT' bit is set or normalized
     subpage coordinates if the `PL_POSITION_SUBPAGE' bit is set.
     Default position bits: If none of `PL_POSITION_LEFT',
     `PL_POSITION_RIGHT', `PL_POSITION_TOP', or `PL_POSITION_BOTTOM'
     are set, then use `PL_POSITION_RIGHT'. If neither of
     `PL_POSITION_INSIDE' or `PL_POSITION_OUTSIDE' is set, use
     `PL_POSITION_OUTSIDE'. If neither of `PL_POSITION_VIEWPORT' or
     `PL_POSITION_SUBPAGE' is set, use `PL_POSITION_VIEWPORT'.

`x'  (` PLFLT', input)
     X offset of the color bar position in adopted coordinates from the
     specified standard position of the color bar. For positive x, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard left
     or right positions if the
     `PL_POSITION_INSIDE'/`PL_POSITION_OUTSIDE' bit is set in
     ``position''.  For the standard top or bottom positions, the
     direction of motion is toward positive X.

`y'  (`PLFLT', input)
     Y offset of the color bar position in adopted coordinates from the
     specified standard position of the color bar. For positive y, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard top
     or bottom positions if the
     `PL_POSITION_INSIDE'/`PL_POSITION_OUTSIDE' bit is set in
     ``position''.  For the standard left or right positions, the
     direction of motion is toward positive Y.

`x_length'  (` PLFLT', input)
     Length of the body of the color bar in the X direction in adopted
     coordinates.

`y_length'  (`PLFLT', input)
     Length of the body of the color bar in the Y direction in adopted
     coordinates.

`bg_color'  (`PLINT', input)
     The cmap0 color of the background for the color bar
     (`PL_COLORBAR_BACKGROUND').

`bb_color'  (`PLINT', input)
     The cmap0 color of the bounding-box line for the color bar
     (`PL_COLORBAR_BOUNDING_BOX').

`bb_style'  (`PLINT', input)
     The `pllsty' (*note pllsty; Select line style::) style number for
     the bounding-box line for the color bar (`PL_COLORBAR_BACKGROUND').

`low_cap_color'  (`PLFLT', input)
     The cmap1 color of the low-end color bar cap, if it is drawn
     (`PL_COLORBAR_CAP_LOW').

`high_cap_color'  (`PLFLT', input)
     The cmap1 color of the high-end color bar cap, if it is drawn
     (`PL_COLORBAR_CAP_HIGH').

`cont_color'  (`PLINT', input)
     The cmap0 contour color for `PL_COLORBAR_SHADE' plots. This is
     passed directly to `plshades' (*note plshades; Shade regions on
     the basis of value::), so it will be interpreted according to the
     design of `plshades' (*note plshades; Shade regions on the basis
     of value::).

`cont_width'  (`PLFLT', input)
     Contour width for `PL_COLORBAR_SHADE' plots. This is passed
     directly to `plshades' (*note plshades; Shade regions on the basis
     of value::), so it will be interpreted according to the design of
     `plshades' (*note plshades; Shade regions on the basis of value::).

`n_labels'  (`PLINT', input)
     Number of labels to place around the color bar.

`label_opts'  (`const PLINT *', input)
     Options for each of `n_labels' labels.

`labels'  (`const char * const *', input)
     `n_labels' text labels for the color bar. No label is drawn if no
     label position is specified with one of the
     `PL_COLORBAR_LABEL_RIGHT', `PL_COLORBAR_LABEL_TOP',
     `PL_COLORBAR_LABEL_LEFT', or `PL_COLORBAR_LABEL_BOTTOM' bits in
     the corresponding label_opts field.

`n_axes'  (`PLINT', input)
     Number of axis definitions provided. This value must be greater
     than 0. It is typically 1 (numerical axis labels are provided for
     one of the long edges of the color bar), but it can be larger if
     multiple numerical axis labels for the long edges of the color bar
     are desired.

`axis_opts'  (`const char * const *', input)
     An array of n_axes axis options (interpreted as for `plbox' (*note
     plbox; Draw a box with axes; etc::)) for the color bar's axis
     definitions.

`ticks'  (`const PLFLT *', input)
     An array of n_axes values of the spacing of the major tick marks
     (interpreted as for `plbox' (*note plbox; Draw a box with axes;
     etc::)) for the color bar's axis definitions.

`sub_ticks'  (`const PLINT *', input)
     An array of n_axes values of the number of subticks (interpreted as
     for `plbox' (*note plbox; Draw a box with axes; etc::)) for the
     color bar's axis definitions.

`n_values'  (`const PLINT *', input)
     An array containing the number of elements in each of the
     ``n_axes'' rows of the two-dimensional ``values'' array.

`values'  (`const PLFLT * const *', input)
     A two-dimensional array containing the numeric values for the data
     range represented by the color bar. For a row index of ``i_axis''
     (where 0 < ``i_axis'' < ``n_axes''), the number of elements in the
     row is specified by ``n_values''[``i_axis'']. For
     `PL_COLORBAR_IMAGE' and `PL_COLORBAR_GRADIENT' the number of
     elements is 2, and the corresponding row elements of the
     ``values'' array are the minimum and maximum value represented by
     the colorbar.  For `PL_COLORBAR_SHADE', the number and values of
     the elements of a row of the ``values'' array is interpreted the
     same as the ``nlevel'' and ``clevel'' arguments of `plshades'
     (*note plshades; Shade regions on the basis of value::).

   Redacted form: `plcolorbar(p_colorbar_width, p_colorbar_height, opt,
position, x, y, x_length, y_length, bg_color, bb_color, bb_style,
low_cap_color, high_cap_color, cont_color, cont_width, label_opts,
labels, axis_opts, ticks, sub_ticks, values)'

   This function is used in examples 16 and 33.


File: plplotdoc.info,  Node: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream,  Next: plcont; Contour plot,  Prev: plcolorbar; Plot color bar for image; shade or gradient plots,  Up: The Common API for PLplot

18.16 plconfigtime: Configure the transformation  between continuous and broken-down time for the current stream
================================================================================================================

     plconfigtime (scale, offset1, offset2, ccontrol, ifbtime_offset,
     year, month, day, hour, min, sec);

   Configure the transformation between continuous and broken-down time
for the current stream.  This transformation is used by both ` plbtime'
(*note plbtime; Calculate broken-down time from continuous time for the
current stream::) and `plctime' (*note plctime; Calculate continuous
time from broken-down time for the current stream::).

`scale'  (`PLFLT', input)
     The number of days per continuous time unit.  As a special case,
     if `scale' is 0., then all other arguments are ignored, and the
     result (the default used by PLplot) is the equivalent of a call to
     plconfigtime(1./86400., 0., 0., 0x0, 1, 1970, 0, 1, 0, 0, 0.).
     That is, for this special case broken-down time is calculated with
     the proleptic Gregorian calendar with no leap seconds inserted,
     and the continuous time is defined as the number of seconds since
     the Unix epoch of 1970-01-01T00:00:00Z.

`offset1'  (`PLFLT', input)
     If `ifbtime_offset' is true, the parameters `offset1' and
     `offset2' are completely ignored.  Otherwise, the sum of these
     parameters (with units in days) specify the epoch of the
     continuous time relative to the MJD epoch corresponding to the
     Gregorian calendar date of 1858-11-17T00:00:00Z or JD = 2400000.5.
     Two PLFLT numbers are used to specify the origin to allow users (by
     specifying `offset1' as an integer that can be exactly represented
     by a floating-point variable and specifying `offset2' as a number
     in the range from 0. to 1) the chance to minimize the numerical
     errors of the continuous time representation.

`offset2'  (`PLFLT', input)
     See documentation of `offset1'.

`ccontrol'  (`PLINT', input)
     `ccontrol' contains bits controlling the transformation.  If the
     0x1 bit is set, then the proleptic Julian calendar is used for
     broken-down time rather than the proleptic Gregorian calendar.  If
     the 0x2 bit is set, then leap seconds that have been historically
     used to define UTC are inserted into the broken-down time.  Other
     possibilities for additional control bits for ccontrol exist such
     as making the historical time corrections in the broken-down time
     corresponding to ET (ephemeris time) or making the (slightly
     non-constant) corrections from international atomic time (TAI) to
     what astronomers define as terrestrial time (TT).  But those
     additional possibilities have not been implemented yet in the
     qsastime library (one of the PLplot utility libraries).

`ifbtime_offset'  (`PLBOOL', input)
     `ifbtime_offset' controls how the epoch of the continuous time
     scale is specified by the user. If `ifbtime_offset' is false, then
     `offset1' and `offset2' are used to specify the epoch, and the
     following broken-down time parameters are completely ignored.  If
     `ifbtime_offset' is true, then `offset1' and `offset2' are
     completely ignored, and the following broken-down time parameters
     are used to specify the epoch.

`year'  (`PLINT', input)
     Year of epoch.

`month'  (`PLINT', input)
     Month of epoch in range from 0 (January) to 11 (December).

`day'  (`PLINT', input)
     Day of epoch in range from 1 to 31.

`hour'  (`PLINT', input)
     Hour of epoch in range from 0 to 23

`min'  (`PLINT', input)
     Minute of epoch in range from 0 to 59.

`sec'  (`PLFLT', input)
     Second of epoch in floating range from 0. to 60.

   Redacted form:

   * General: `plconfigtime(scale, offset1, offset2, ccontrol,
     ifbtime_offset, year, month, day, hour, min, sec)'

   * Perl/PDL: Not available?

   This function is used in example 29.


File: plplotdoc.info,  Node: plcont; Contour plot,  Next: plcpstrm; Copy state parameters from the reference stream to the current stream,  Prev: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream,  Up: The Common API for PLplot

18.17 plcont: Contour plot
==========================

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

   Draws a contour plot of the data in ``f'[`nx'][`ny']', using the
``nlevel'' contour levels specified by ``clevel''.  Only the region of
the array from ``kx'' to ``lx'' and from ``ky'' to ``ly'' is plotted
out.  A transformation routine pointed to by ``pltr'' with a pointer
``pltr_data'' for additional data required by the transformation routine
is used to map indices within the array to the world coordinates.  See
the following discussion of the arguments and *note Contour and Shade
Plots:: for more information.

`f'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array containing data to be
     contoured.

`nx, ny'  (`PLINT', input)
     Physical dimensions of array ``f''.

`kx, lx'  (`PLINT', input)
     Range of `x' indices to consider.

`ky, ly'  (`PLINT', input)
     Range of `y' indices to consider.

`clevel'  (`const PLFLT *', input)
     Pointer to array specifying levels at which to draw contours.

`nlevel'  (`PLINT', input)
     Number of contour levels to draw.

`pltr'  (`void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)  ', input)
     Pointer to function that defines transformation between indices in
     array ``f'' and the world coordinates (C only).  Transformation
     functions are provided in the PLplot library: `pltr0' (*note
     pltr0; Identity transformation for grid to world mapping::) for
     identity mapping, and `pltr1' (*note pltr1; Linear interpolation
     for grid to world mapping using 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]::) for arbitrary
     mappings respectively defined by one- and two-dimensional arrays.
     In addition, user-supplied routines for the transformation can be
     used as well.  Examples of all of these approaches are given in
     *note Contour Plots from C::.  The transformation function should
     have the form given by any of `pltr0' (*note pltr0; Identity
     transformation for grid to world mapping::), `pltr1' (*note pltr1;
     Linear interpolation for grid to world mapping using singly
     dimensioned coordinate arrays::), or `pltr2' (*note pltr2; Linear
     interpolation for grid to world mapping using doubly dimensioned
     coordinate arrays [column dominant; as per normal C 2d arrays]::).
     Note that unlike `plshades' (*note plshades; Shade regions on the
     basis of value::) and similar PLplot functions which have a
     ``pltr'' argument, plcont requires that a transformation function
     be provided in the C interface.  Leaving ``pltr'' NULL will result
     in an error.

`pltr_data'  (`PLPointer', input)
     Extra parameter to help pass information to `pltr0' (*note pltr0;
     Identity transformation for grid to world mapping::), `pltr1'
     (*note pltr1; Linear interpolation for grid to world mapping using
     singly dimensioned coordinate arrays::), `pltr2' (*note pltr2;
     Linear interpolation for grid to world mapping using doubly
     dimensioned coordinate arrays [column dominant; as per normal C 2d
     arrays]::), or whatever routine that is externally supplied.

   Redacted form: [PLEASE UPDATE! ONLY PERL INFO IS LIKELY CORRECT!]

   * F95: `plcont(f, kx, lx, ky, ly, clevel, tr?)' or `plcont(f, kx,
     lx, ky, ly, clevel, xgrid, ygrid)'

   * Java: `pls.cont(f, kx, lx, ky, ly, clevel, xgrid, ygrid)'

   * Perl/PDL: `plcont(f, kx, lx, ky, ly, clevel, pltr, pltr_data)'

   * Python: `plcont2(f, kx, lx, ky, ly, clevel)'

   This function is used in examples 9,14,16,22.


File: plplotdoc.info,  Node: plcpstrm; Copy state parameters from the reference stream to the current stream,  Next: plctime; Calculate continuous time from broken-down time for the current stream,  Prev: plcont; Contour plot,  Up: The Common API for PLplot

18.18 plcpstrm: Copy state parameters from the  reference stream to the current stream
======================================================================================

     plcpstrm (iplsr, flags);

   Copies state parameters from the reference stream to the current
stream.  Tell driver interface to map device coordinates unless
``flags' == 1'.

   This function is used for making save files of selected plots (e.g.
from the TK driver).  After initializing, you can get a copy of the
current plot to the specified device by switching to this stream and
issuing a `plcpstrm' (*note plcpstrm; Copy state parameters from the
reference stream to the current stream::) and a `plreplot' (*note
plreplot; Replays contents of plot buffer to current device/file::),
with calls to `plbop' (*note plbop; Begin a new page::) and `pleop'
(*note pleop; Eject current page::) as appropriate.  The plot buffer
must have previously been enabled (done automatically by some display
drivers, such as X).

`iplsr'  (`PLINT', input)
     Number of reference stream.

`flags'  (`PLBOOL', input)
     If ``flags'' is set to true the device coordinates are _not_
     copied from the reference to current stream.

   Redacted form: `plcpstrm(iplsr, flags)'

   This function is used in example 1,20.


File: plplotdoc.info,  Node: plctime; Calculate continuous time from broken-down time for the current stream,  Next: plend; End plotting session,  Prev: plcpstrm; Copy state parameters from the reference stream to the current stream,  Up: The Common API for PLplot

18.19 plctime: Calculate continuous time from  broken-down time for the current stream
======================================================================================

     plctime (year, month, day, hour, min, sec, ctime);

   Calculate continuous time, ``ctime'', from broken-down time for the
current stream.  The broken-down time is specified by the following
parameters: ``year'', ``month'', ``day'', ``hour'', ``min'', and
``sec''.  This function is the inverse of ` plbtime' (*note plbtime;
Calculate broken-down time from continuous time for the current
stream::).

   The PLplot definition of broken-down time is a calendar time that
completely ignores all time zone offsets, i.e., it is the user's
responsibility to apply those offsets (if so desired) before using the
PLplot time API.  By default broken-down time is defined using the
proleptic Gregorian calendar without the insertion of leap seconds and
continuous time is defined as the number of seconds since the Unix
epoch of 1970-01-01T00:00:00Z.  However, other definitions of
broken-down and continuous time are possible, see `plconfigtime' (*note
plconfigtime; Configure the transformation between continuous and
broken-down time for the current stream::) which specifies that
transformation for the current stream.

`year'  (`PLINT', input)
     Input year.

`month'  (`PLINT', input)
     Input month in range from 0 (January) to 11 (December).

`day'  (`PLINT', input)
     Input day in range from 1 to 31.

`hour'  (`PLINT', input)
     Input hour in range from 0 to 23

`min'  (`PLINT', input)
     Input minute in range from 0 to 59.

`sec'  (`PLFLT', input)
     Input second in floating range from 0. to 60.

`ctime'  (`PLFLT *', output)
     Continous time calculated from the broken-down time specified by
     the previous parameters.

   Redacted form:

   * General: `plctime(year, month, day, hour, min, sec, ctime)'

   * Perl/PDL: Not available?

   This function is used in example 29.


File: plplotdoc.info,  Node: plend; End plotting session,  Next: plend1; End plotting session for current stream,  Prev: plctime; Calculate continuous time from broken-down time for the current stream,  Up: The Common API for PLplot

18.20 plend: End plotting session
=================================

     plend ();

   Ends a plotting session, tidies up all the output files, switches
interactive devices back into text mode and frees up any memory that
was allocated.  Must be called before end of program.

   By default, PLplot's interactive devices (Xwin, TK, etc.)  go into a
wait state after a call to plend or other functions which trigger the
end of a plot page.  To avoid this, use the `plspause' (*note plspause;
Set the pause [on end-of-page] status::) function.

   Redacted form: `plend()'

   This function is used in all of the examples.


File: plplotdoc.info,  Node: plend1; End plotting session for current stream,  Next: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it,  Prev: plend; End plotting session,  Up: The Common API for PLplot

18.21 plend1: End plotting session for current stream
=====================================================

     plend1 ();

   Ends a plotting session for the current output stream only.  See
`plsstrm' (*note plsstrm; Set current output stream::) for more info.

   Redacted form: `plend1()'

   This function is used in examples 1,20.


File: plplotdoc.info,  Node: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it,  Next: plenv; Set up standard window and draw box,  Prev: plend1; End plotting session for current stream,  Up: The Common API for PLplot

18.22 plenv0: Same as `plenv' but if in multiplot  mode does not advance the subpage, instead clears it
=======================================================================================================

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

   Sets up plotter environment for simple graphs by calling `pladv'
(*note pladv; Advance the [sub-]page::) and setting up viewport and
window to sensible default values.  `plenv0' (*note plenv0; Same as
plenv but if in multiplot mode does not advance the subpage; instead
clears it::) leaves enough room around most graphs for axis labels and
a title.  When these defaults are not suitable, use the individual
routines `plvpas' (*note plvpas; Specify viewport using coordinates and
aspect ratio::), `plvpor' (*note plvpor; Specify viewport using
coordinates::), or `plvasp' (*note plvasp; Specify viewport using
aspect ratio only::) for setting up the viewport, `plwind' (*note
plwind; Specify world coordinates of viewport boundaries::) for
defining the window, and `plbox' (*note plbox; Draw a box with axes;
etc::) for drawing the box.

`xmin'  (`PLFLT', input)
     Value of x at left-hand edge of window (in world coordinates).

`xmax'  (`PLFLT', input)
     Value of x at right-hand edge of window (in world coordinates).

`ymin'  (`PLFLT', input)
     Value of y at bottom edge of window (in world coordinates).

`ymax'  (`PLFLT', input)
     Value of y at top edge of window (in world coordinates).

`just'  (`PLINT', input)
     Controls how the axes will be scaled:

        * `-1': the scales will not be set, the user must set up the
          scale before calling `plenv0' (*note plenv0; Same as plenv
          but if in multiplot mode does not advance the subpage;
          instead clears it::) using `plsvpa' (*note plsvpa; Specify
          viewport in absolute coordinates::), `plvasp' (*note plvasp;
          Specify viewport using aspect ratio only::) or other.

        * `0': the x and y axes are scaled independently to use as much
          of the screen as possible.

        * `1': the scales of the x and y axes are made equal.

        * `2': the axis of the x and y axes are made equal, and the
          plot box will be square.

`axis'  (`PLINT', input)
     Controls drawing of the box around the plot:

        * `-2': draw no box, no tick marks, no numeric tick labels, no
          axes.

        * `-1': draw box only.

        * `0': draw box, ticks, and numeric tick labels.

        * `1': also draw coordinate axes at `x=0' and `y=0'.

        * `2': also draw a grid at major tick positions in both
          coordinates.

        * `3': also draw a grid at minor tick positions in both
          coordinates.

        * `10': same as 0 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `11': same as 1 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `12': same as 2 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `13': same as 3 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `20': same as 0 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `21': same as 1 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `22': same as 2 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `23': same as 3 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `30': same as 0 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `31': same as 1 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `32': same as 2 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `33': same as 3 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `40': same as 0 except date / time `x' labels.

        * `41': same as 1 except date / time `x' labels.

        * `42': same as 2 except date / time `x' labels.

        * `43': same as 3 except date / time `x' labels.

        * `50': same as 0 except date / time `y' labels.

        * `51': same as 1 except date / time `y' labels.

        * `52': same as 2 except date / time `y' labels.

        * `53': same as 3 except date / time `y' labels.

        * `60': same as 0 except date / time `x' and `y' labels.

        * `61': same as 1 except date / time `x' and `y' labels.

        * `62': same as 2 except date / time `x' and `y' labels.

        * `63': same as 3 except date / time `x' and `y' labels.

        * `70': same as 0 except custom `x' and `y' labels.

        * `71': same as 1 except custom `x' and `y' labels.

        * `72': same as 2 except custom `x' and `y' labels.

        * `73': same as 3 except custom `x' and `y' labels.

   Redacted form: `plenv0(xmin, xmax, ymin, ymax, just, axis)'

   This function is used in example 21.


File: plplotdoc.info,  Node: plenv; Set up standard window and draw box,  Next: pleop; Eject current page,  Prev: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it,  Up: The Common API for PLplot

18.23 plenv: Set up standard window and draw box
================================================

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

   Sets up plotter environment for simple graphs by calling `pladv'
(*note pladv; Advance the [sub-]page::) and setting up viewport and
window to sensible default values.  `plenv' (*note plenv; Set up
standard window and draw box::) leaves enough room around most graphs
for axis labels and a title.  When these defaults are not suitable, use
the individual routines `plvpas' (*note plvpas; Specify viewport using
coordinates and aspect ratio::), `plvpor' (*note plvpor; Specify
viewport using coordinates::), or `plvasp' (*note plvasp; Specify
viewport using aspect ratio only::) for setting up the viewport,
`plwind' (*note plwind; Specify world coordinates of viewport
boundaries::) for defining the window, and `plbox' (*note plbox; Draw a
box with axes; etc::) for drawing the box.

`xmin'  (`PLFLT', input)
     Value of x at left-hand edge of window (in world coordinates).

`xmax'  (`PLFLT', input)
     Value of x at right-hand edge of window (in world coordinates).

`ymin'  (`PLFLT', input)
     Value of y at bottom edge of window (in world coordinates).

`ymax'  (`PLFLT', input)
     Value of y at top edge of window (in world coordinates).

`just'  (`PLINT', input)
     Controls how the axes will be scaled:

        * `-1': the scales will not be set, the user must set up the
          scale before calling `plenv' (*note plenv; Set up standard
          window and draw box::) using `plsvpa' (*note plsvpa; Specify
          viewport in absolute coordinates::), `plvasp' (*note plvasp;
          Specify viewport using aspect ratio only::) or other.

        * `0': the x and y axes are scaled independently to use as much
          of the screen as possible.

        * `1': the scales of the x and y axes are made equal.

        * `2': the axis of the x and y axes are made equal, and the
          plot box will be square.

`axis'  (`PLINT', input)
     Controls drawing of the box around the plot:

        * `-2': draw no box, no tick marks, no numeric tick labels, no
          axes.

        * `-1': draw box only.

        * `0': draw box, ticks, and numeric tick labels.

        * `1': also draw coordinate axes at `x=0' and `y=0'.

        * `2': also draw a grid at major tick positions in both
          coordinates.

        * `3': also draw a grid at minor tick positions in both
          coordinates.

        * `10': same as 0 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `11': same as 1 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `12': same as 2 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `13': same as 3 except logarithmic `x' tick marks. (The `x'
          data have to be converted to logarithms separately.)

        * `20': same as 0 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `21': same as 1 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `22': same as 2 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `23': same as 3 except logarithmic `y' tick marks. (The `y'
          data have to be converted to logarithms separately.)

        * `30': same as 0 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `31': same as 1 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `32': same as 2 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `33': same as 3 except logarithmic `x' and `y' tick marks.
          (The `x' and `y' data have to be converted to logarithms
          separately.)

        * `40': same as 0 except date / time `x' labels.

        * `41': same as 1 except date / time `x' labels.

        * `42': same as 2 except date / time `x' labels.

        * `43': same as 3 except date / time `x' labels.

        * `50': same as 0 except date / time `y' labels.

        * `51': same as 1 except date / time `y' labels.

        * `52': same as 2 except date / time `y' labels.

        * `53': same as 3 except date / time `y' labels.

        * `60': same as 0 except date / time `x' and `y' labels.

        * `61': same as 1 except date / time `x' and `y' labels.

        * `62': same as 2 except date / time `x' and `y' labels.

        * `63': same as 3 except date / time `x' and `y' labels.

        * `70': same as 0 except custom `x' and `y' labels.

        * `71': same as 1 except custom `x' and `y' labels.

        * `72': same as 2 except custom `x' and `y' labels.

        * `73': same as 3 except custom `x' and `y' labels.

   Redacted form: `plenv(xmin, xmax, ymin, ymax, just, axis)'

   This function is used in example 1,3,9,13,14,19-22,29.


File: plplotdoc.info,  Node: pleop; Eject current page,  Next: plerrx; Draw x error bar,  Prev: plenv; Set up standard window and draw box,  Up: The Common API for PLplot

18.24 pleop: Eject current page
===============================

     pleop ();

   Clears the graphics screen of an interactive device, or ejects a page
on a plotter.  See `plbop' (*note plbop; Begin a new page::) for more
information.

   Redacted form: `pleop()'

   This function is used in example 2,14.


File: plplotdoc.info,  Node: plerrx; Draw x error bar,  Next: plerry; Draw y error bar,  Prev: pleop; Eject current page,  Up: The Common API for PLplot

18.25 plerrx: Draw x error bar
==============================

     plerrx (n, xmin, xmax, y);

   Draws a set of ``n'' horizontal error bars, the `i''th error bar
extending from ``xmin'[i]' to ``xmax'[i]' at y coordinate ``y'[i]'.
The terminals of the error bar are of length equal to the minor tick
length (settable using `plsmin' (*note plsmin; Set length of minor
ticks::)).

`n'  (`PLINT', input)
     Number of error bars to draw.

`xmin'  (`const PLFLT *', input)
     Pointer to array with x coordinates of left-hand endpoint of error
     bars.

`xmax'  (`const PLFLT *', input)
     Pointer to array with x coordinates of right-hand endpoint of
     error bars.

`y'  (`const PLFLT *', input)
     Pointer to array with y coordinates of error bar.

   Redacted form:

   * General: `plerrx(xmin, ymax, y)'

   * Perl/PDL: `plerrx(n, xmin, xmax, y)'

   This function is used in example 29.


File: plplotdoc.info,  Node: plerry; Draw y error bar,  Next: plfamadv; Advance to the next family file on the next new page,  Prev: plerrx; Draw x error bar,  Up: The Common API for PLplot

18.26 plerry: Draw y error bar
==============================

     plerry (n, x, ymin, ymax);

   Draws a set of ``n'' vertical error bars, the `i''th error bar
extending from ``ymin'[i]' to ``ymax'[i]' at x coordinate ``x'[i]'.
The terminals of the error bar are of length equal to the minor tick
length (settable using `plsmin' (*note plsmin; Set length of minor
ticks::)).

`n'  (`PLINT', input)
     Number of error bars to draw.

`x'  (`const PLFLT *', input)
     Pointer to array with x coordinates of error bars.

`ymin'  (`const PLFLT *', input)
     Pointer to array with y coordinates of lower endpoint of error
     bars.

`ymax'  (`const PLFLT *', input)
     Pointer to array with y coordinate of upper endpoint of error bar.

   Redacted form:

   * General: `plerry(x, ymin, ymax)'

   * Perl/PDL: `plerry(n, x, ymin, ymax)'

   This function is used in example 29.


File: plplotdoc.info,  Node: plfamadv; Advance to the next family file on the next new page,  Next: plfill; Draw filled polygon,  Prev: plerry; Draw y error bar,  Up: The Common API for PLplot

18.27 plfamadv: Advance to the next family file on the  next new page
=====================================================================

     plfamadv ();

   Advance to the next family file on the next new page.

   Redacted form: `plfamadv()'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plfill; Draw filled polygon,  Next: plfill3; Draw filled polygon in 3D,  Prev: plfamadv; Advance to the next family file on the next new page,  Up: The Common API for PLplot

18.28 plfill: Draw filled polygon
=================================

     plfill (n, x, y);

   Fills the polygon defined by the ``n'' points `(`x'[i], `y'[i])'
using the pattern defined by `plpsty' (*note plpsty; Select area fill
pattern::) or `plpat' (*note plpat; Set area fill pattern::).  The
default fill style is a solid fill.  The routine will automatically
close the polygon between the last and first vertices.  If multiple
closed polygons are passed in ``x'' and ``y'' then `plfill' (*note
plfill; Draw filled polygon::) will fill in between them.

`n'  (`PLINT', input)
     Number of vertices in polygon.

`x'  (`const PLFLT *', input)
     Pointer to array with x coordinates of vertices.

`y'  (`const PLFLT *', input)
     Pointer to array with y coordinates of vertices.

   Redacted form: `plfill(x,y)'

   This function is used in examples 12,13,15,16,21,24,25.


File: plplotdoc.info,  Node: plfill3; Draw filled polygon in 3D,  Next: plflush; Flushes the output stream,  Prev: plfill; Draw filled polygon,  Up: The Common API for PLplot

18.29 plfill3: Draw filled polygon in 3D
========================================

     plfill3 (n, x, y, z);

   Fills the 3D polygon defined by the ``n'' points in the ``x'',
``y'', and ``z'' arrays using the pattern defined by `plpsty' (*note
plpsty; Select area fill pattern::) or `plpat' (*note plpat; Set area
fill pattern::).  The routine will automatically close the polygon
between the last and first vertices.  If multiple closed polygons are
passed in ``x'', ``y'', and ``z'' then `plfill3' (*note plfill3; Draw
filled polygon in 3D::) will fill in between them.

`n'  (`PLINT', input)
     Number of vertices in polygon.

`x'  (`const PLFLT *', input)
     Pointer to array with x coordinates of vertices.

`y'  (`const PLFLT *', input)
     Pointer to array with y coordinates of vertices.

`z'  (`const PLFLT *', input)
     Pointer to array with z coordinates of vertices.

   Redacted form:

   * General: `plfill3(x, y, z)'

   * Perl/PDL: `plfill3(n, x, y, z)'

   This function is used in example 15.


File: plplotdoc.info,  Node: plflush; Flushes the output stream,  Next: plfont; Set character font,  Prev: plfill3; Draw filled polygon in 3D,  Up: The Common API for PLplot

18.30 plflush: Flushes the output stream
========================================

     plflush ();

   Flushes the output stream. Use sparingly, if at all.

   Redacted form: `plflush()'

   This function is used in examples 1,14.


File: plplotdoc.info,  Node: plfont; Set character font,  Next: plfontld; Load character font,  Prev: plflush; Flushes the output stream,  Up: The Common API for PLplot

18.31 plfont: Set character font
================================

     plfont (ifont);

   Sets the default character font for subsequent character drawing.
Also affects symbols produced by `plpoin' (*note plpoin; Plot a glyph
at the specified points::).  This routine has no effect unless the
extended character set is loaded (see `plfontld' (*note plfontld; Load
character font::)).

`ifont'  (`PLINT', input)
     Specifies the font:

        * `1': Normal font (simplest and fastest)

        * `2': Roman font

        * `3': Italic font

        * `4': Script font

   Redacted form: `plfont(ifont)'

   This function is used in examples 1,2,4,7,13,24,26.


File: plplotdoc.info,  Node: plfontld; Load character font,  Next: plgchr; Get character default height and current [scaled] height,  Prev: plfont; Set character font,  Up: The Common API for PLplot

18.32 plfontld: Load character font
===================================

     plfontld (fnt);

   Sets the character set to use for subsequent character drawing.  May
be called before initializing PLplot.

`fnt'  (`PLINT', input)
     Specifies the character set to load:

        * `0': Standard character set

        * `1': Extended character set

   Redacted form: `plfontld(fnt)'

   This function is used in examples 1,7.


File: plplotdoc.info,  Node: plgchr; Get character default height and current [scaled] height,  Next: plgcmap1_range; Get the cmap1 argument range for continuous color plots,  Prev: plfontld; Load character font,  Up: The Common API for PLplot

18.33 plgchr: Get character default height and current  (scaled) height
=======================================================================

     plgchr (p_def, p_ht);

   Get character default height and current (scaled) height.

`p_def'  (`PLFLT *', output)
     Pointer to default character height (mm).

`p_ht'  (`PLFLT *', output)
     Pointer to current (scaled) character height (mm).

   Redacted form: `plgchr(p_def, p_ht)'

   This function is used in example 23.


File: plplotdoc.info,  Node: plgcmap1_range; Get the cmap1 argument range for continuous color plots,  Next: plgcol0; Returns 8-bit RGB values for given color index from cmap0,  Prev: plgchr; Get character default height and current [scaled] height,  Up: The Common API for PLplot

18.34 plgcmap1_range: Get the cmap1 argument  range for continuous color plots
==============================================================================

     plgcmap1_range (min_color, max_color);

   Get the cmap1 argument range for continuous color plots.  (Use
`plgsmap1_range' (*note plscmap1_range; Set the cmap1 argument range
for continuous color plots::) to set the cmap1 argument range.)

`min_color'  (`PLFLT *', output)
     Pointer to the current minimum cmap1 floating point argument.

`max_color'  (`PLFLT *', output)
     Pointer to the current maximum cmap1 floating point argument.

   Redacted form: `plgcmap1_range(min_color, max_color)'

   This function is currently not used in any example.


File: plplotdoc.info,  Node: plgcol0; Returns 8-bit RGB values for given color index from cmap0,  Next: plgcol0a; Returns 8-bit RGB values and double alpha transparency value for given color index from cmap0,  Prev: plgcmap1_range; Get the cmap1 argument range for continuous color plots,  Up: The Common API for PLplot

18.35 plgcol0: Returns 8-bit RGB values for given color  index from cmap0
=========================================================================

     plgcol0 (icol0, r, g, b);

   Returns 8-bit RGB values (0-255) for given color from cmap0 (see
*note Color Map0::).  Values are negative if an invalid color id is
given.

`icol0'  (`PLINT', input)
     Index of desired cmap0 color.

`r'  (`PLINT *', output)
     Pointer to 8-bit red value.

`g'  (`PLINT *', output)
     Pointer to 8-bit green value.

`b'  (`PLINT *', output)
     Pointer to 8-bit blue value.

   Redacted form: `plgcol0(icol0, r, g, b)'

   This function is used in example 2.


File: plplotdoc.info,  Node: plgcol0a; Returns 8-bit RGB values and double alpha transparency value for given color index from cmap0,  Next: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value,  Prev: plgcol0; Returns 8-bit RGB values for given color index from cmap0,  Up: The Common API for PLplot

18.36 plgcol0a: Returns 8-bit RGB values and double alpha  transparency value for given color index from cmap0
==============================================================================================================

     plgcol0a (icol0, r, g, b, alpha);

   Returns 8-bit RGB values (0-255) and double alpha transparency value
(0.0 - 1.0) for given color from cmap0 (see *note Color Map0::).  Values
are negative if an invalid color id is given.

`icol0'  (`PLINT', input)
     Index of desired cmap0 color.

`r'  (`PLINT *', output)
     Pointer to 8-bit red value.

`g'  (`PLINT *', output)
     Pointer to 8-bit green value.

`b'  (`PLINT *', output)
     Pointer to 8-bit blue value.

`alpha'  (`PLFLT *', output)
     Pointer to PLFLT alpha transparency value.

   This function is used in example 30.


File: plplotdoc.info,  Node: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value,  Next: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and double alpha transparency value,  Prev: plgcol0a; Returns 8-bit RGB values and double alpha transparency value for given color index from cmap0,  Up: The Common API for PLplot

18.37 plgcolbg: Returns the background color  (cmap0[0]) by 8-bit RGB value
===========================================================================

     plgcolbg (r, g, b);

   Returns the background color (cmap0[0]) by 8-bit RGB value.

`r'  (`PLINT *', output)
     Pointer to an unsigned 8-bit integer (0-255) representing the
     degree of red in the color.

`g'  (`PLINT *', output)
     Pointer to an unsigned 8-bit integer (0-255) representing the
     degree of green in the color.

`b'  (`PLINT *', output)
     Pointer to an unsigned 8-bit integer (0-255) representing the
     degree of blue in the color.

   Redacted form: `plgcolbg(r, g, b)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and double alpha transparency value,  Next: plgcompression; Get the current device-compression setting,  Prev: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value,  Up: The Common API for PLplot

18.38 plgcolbga: Returns the background color (cmap0[0])   by 8-bit RGB value and double alpha transparency value
=================================================================================================================

     plgcolbga (r, g, b, alpha);

   Returns the background color (cmap0[0]) by 8-bit RGB value and double
alpha transparency value.

`r'  (`PLINT *', output)
     Pointer to an unsigned 8-bit integer (0-255) representing the
     degree of red in the color.

`g'  (`PLINT *', output)
     Pointer to an unsigned 8-bit integer (0-255) representing the
     degree of green in the color.

`b'  (`PLINT *', output)
     Pointer to an unsigned 8-bit integer (0-255) representing the
     degree of blue in the color.

`alpha'  (`PLFLT *', output)
     Pointer to PLFLT alpha transparency value.

   This function is used in example 31.


File: plplotdoc.info,  Node: plgcompression; Get the current device-compression setting,  Next: plgdev; Get the current device [keyword] name,  Prev: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and double alpha transparency value,  Up: The Common API for PLplot

18.39 plgcompression: Get the current  device-compression setting
=================================================================

     plgcompression (compression);

   Get the current device-compression setting.  This parameter is only
used for drivers that provide compression.

`compression'  (`PLINT *', output)
     Pointer to a variable to be filled with the current
     device-compression setting.

   Redacted form: `plgcompression(compression)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgdev; Get the current device [keyword] name,  Next: plgdidev; Get parameters that define current device-space window,  Prev: plgcompression; Get the current device-compression setting,  Up: The Common API for PLplot

18.40 plgdev: Get the current device (keyword) name
===================================================

     plgdev (p_dev);

   Get the current device (keyword) name.  Note: you _must_ have
allocated space for this (80 characters is safe).

`p_dev'  (`char *', output)
     Pointer to device (keyword) name string.

   Redacted form: `plgdev(p_dev)'

   This function is used in example 14.


File: plplotdoc.info,  Node: plgdidev; Get parameters that define current device-space window,  Next: plgdiori; Get plot orientation,  Prev: plgdev; Get the current device [keyword] name,  Up: The Common API for PLplot

18.41 plgdidev: Get parameters that define current  device-space window
=======================================================================

     plgdidev (p_mar, p_aspect, p_jx, p_jy);

   Get relative margin width, aspect ratio, and relative justification
that define current device-space window.  If `plsdidev' (*note
plsdidev; Set parameters that define current device-space window::) has
not been called the default values pointed to by ``p_mar'',
``p_aspect'', ``p_jx'', and ``p_jy'' will all be 0.

`p_mar'  (`PLFLT *', output)
     Pointer to relative margin width.

`p_aspect'  (`PLFLT *', output)
     Pointer to aspect ratio.

`p_jx'  (`PLFLT *', output)
     Pointer to relative justification in x.

`p_jy'  (`PLFLT *', output)
     Pointer to relative justification in y.

   Redacted form: `plgdidev(p_mar, p_aspect, p_jx, p_jy)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgdiori; Get plot orientation,  Next: plgdiplt; Get parameters that define current plot-space window,  Prev: plgdidev; Get parameters that define current device-space window,  Up: The Common API for PLplot

18.42 plgdiori: Get plot orientation
====================================

     plgdiori (p_rot);

   Get plot orientation parameter which is multiplied by 90 degrees to
obtain the angle of rotation.  Note, arbitrary rotation parameters such
as 0.2 (corresponding to 18 degrees) are possible, but the usual values
for the rotation parameter are 0., 1., 2., and 3. corresponding to 0
degrees (landscape mode), 90 degrees (portrait mode), 180 degrees
(seascape mode), and 270 degrees (upside-down mode).  If `plsdiori'
(*note plsdiori; Set plot orientation::) has not been called the
default value pointed to by ``p_rot'' will be 0.

`p_rot'  (`PLFLT *', output)
     Pointer to orientation parameter.

   Redacted form: `plgdiori(p_rot)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plgdiplt; Get parameters that define current plot-space window,  Next: plgdrawmode; Get drawing mode [depends on device support!],  Prev: plgdiori; Get plot orientation,  Up: The Common API for PLplot

18.43 plgdiplt: Get parameters that define current  plot-space window
=====================================================================

     plgdiplt (p_xmin, p_ymin, p_xmax, p_ymax);

   Get relative minima and maxima that define current plot-space window.
If `plsdiplt' (*note plsdiplt; Set parameters that define current
plot-space window::) has not been called the default values pointed to
by ``p_xmin'', ``p_ymin'', ``p_xmax'', and ``p_ymax'' will be 0., 0.,
1., and 1.

`p_xmin'  (`PLFLT *', output)
     Pointer to relative minimum in x.

`p_ymin'  (`PLFLT *', output)
     Pointer to relative minimum in y.

`p_xmax'  (`PLFLT *', output)
     Pointer to relative maximum in x.

`p_ymax'  (`PLFLT *', output)
     Pointer to relative maximum in y.

   Redacted form: `plgdiplt(p_xmin, p_ymin, p_xmax, p_ymax)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgdrawmode; Get drawing mode [depends on device support!],  Next: plgfam; Get family file parameters,  Prev: plgdiplt; Get parameters that define current plot-space window,  Up: The Common API for PLplot

18.44 plgdrawmode: Get drawing mode (depends on device support!)
================================================================

     plgdrawmode ();

   Get drawing mode.  Note only one device driver (cairo) currently
supports this at the moment, and for that case the PLINT value returned
by this function is one of `PL_DRAWMODE_DEFAULT', `PL_DRAWMODE_REPLACE',
`PL_DRAWMODE_XOR', or `PL_DRAWMODE_UNKNOWN'. This function returns
`PL_DRAWMODE_UNKNOWN' for the rest of the device drivers.  See also
`plsdrawmode' (*note plsdrawmode; Set drawing mode [depends on device
support!]::).

   Redacted form: `plgdrawmode()'

   This function is used in example 34.


File: plplotdoc.info,  Node: plgfam; Get family file parameters,  Next: plgfci; Get FCI [font characterization integer],  Prev: plgdrawmode; Get drawing mode [depends on device support!],  Up: The Common API for PLplot

18.45 plgfam: Get family file parameters
========================================

     plgfam (p_fam, p_num, p_bmax);

   Gets information about current family file, if familying is enabled.
See *note Family File Output:: for more information.

`p_fam'  (`PLINT *', output)
     Pointer to variable with the Boolean family flag value.  If
     nonzero, familying is enabled.

`p_num'  (`PLINT *', output)
     Pointer to variable with the current family file number.

`p_bmax'  (`PLINT *', output)
     Pointer to variable with the maximum file size (in bytes) for a
     family file.

   Redacted form: `plgfam(p_fam, p_num, p_bmax)'

   This function is used in examples 14,31.


File: plplotdoc.info,  Node: plgfci; Get FCI [font characterization integer],  Next: plgfnam; Get output file name,  Prev: plgfam; Get family file parameters,  Up: The Common API for PLplot

18.46 plgfci: Get FCI (font characterization integer)
=====================================================

     plgfci (p_fci);

   Gets information about the current font using the FCI approach.  See
*note FCI:: for more information.

`p_fci'  (`PLUNICODE *', output)
     Pointer to PLUNICODE (unsigned 32-bit integer) variable which is
     updated with current FCI value.

   Redacted form: `plgfci(p_fci)'

   This function is used in example 23.


File: plplotdoc.info,  Node: plgfnam; Get output file name,  Next: plgfont; Get family; style and weight of the current font,  Prev: plgfci; Get FCI [font characterization integer],  Up: The Common API for PLplot

18.47 plgfnam: Get output file name
===================================

     plgfnam (fnam);

   Gets the current output file name, if applicable.

`fnam'  (`char *', output)
     Pointer to file name string (a preallocated string of 80
     characters or more).

   Redacted form: `plgfnam(fnam)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgfont; Get family; style and weight of the current font,  Next: plglevel; Get the [current] run level,  Prev: plgfnam; Get output file name,  Up: The Common API for PLplot

18.48 plgfont: Get family, style and weight of the  current font
================================================================

     plgfont (p_family, p_style, p_weight);

   Gets information about current font.  See *note FCI:: for more
information on font selection.

`p_family'  (`PLINT *', output)
     Pointer to variable with the current font family. The available
     values are given by the PL_FCI_* constants in plplot.h. Current
     options are PL_FCI_SANS, PL_FCI_SERIF, PL_FCI_MONO, PL_FCI_SCRIPT
     and PL_FCI_SYMBOL. If p_family is NULL then the font family is not
     returned.

`p_style'  (`PLINT *', output)
     Pointer to variable with the current font style. The available
     values are given by the PL_FCI_* constants in plplot.h. Current
     options are PL_FCI_UPRIGHT, PL_FCI_ITALIC and PL_FCI_OBLIQUE. If
     p_style is NULL then the font style is not returned.

`p_weight'  (`PLINT *', output)
     Pointer to variable with the current font weight. The available
     values are given by the PL_FCI_* constants in plplot.h. Current
     options are PL_FCI_MEDIUM and PL_FCI_BOLD. If p_weight is NULL
     then the font weight is not returned.

   Redacted form: `plgfont(p_family, p_style, p_weight)'

   This function is used in example 23.


File: plplotdoc.info,  Node: plglevel; Get the [current] run level,  Next: plgpage; Get page parameters,  Prev: plgfont; Get family; style and weight of the current font,  Up: The Common API for PLplot

18.49 plglevel: Get the (current) run level
===========================================

     plglevel (p_level);

   Get the (current) run level. Valid settings are:

   * 0,  uninitialized

   * 1,  initialized

   * 2,  viewport defined

   * 3,  world coordinates defined

`p_level'  (`PLINT *', output)
     Pointer to the run level.

   Redacted form: `plglevel(p_level)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgpage; Get page parameters,  Next: plgra; Switch to graphics screen,  Prev: plglevel; Get the [current] run level,  Up: The Common API for PLplot

18.50 plgpage: Get page parameters
==================================

     plgpage (p_xp, p_yp, p_xleng, p_yleng, p_xoff, p_yoff);

   Gets the current page configuration. The length and offset values
are expressed in units that are specific to the current driver. For
instance: screen drivers will usually interpret them as number of
pixels, whereas printer drivers will usually use mm.

`p_xp'  (`PLFLT *', output)
     Pointer to number of pixels/inch (DPI), x.

`p_yp'  (`PLFLT *', output)
     Pointer to number of pixels/inch (DPI) in y.

`p_xleng'  (`PLINT *', output)
     Pointer to x page length value.

`p_yleng'  (`PLINT *', output)
     Pointer to y page length value.

`p_xoff'  (`PLINT *', output)
     Pointer to x page offset.

`p_yoff'  (`PLINT *', output)
     Pointer to y page offset.

   Redacted form: `plgpage(p_xp, p_yp, p_xleng, p_yleng, p_xoff,
p_yoff)'

   This function is used in examples 14 and 31.


File: plplotdoc.info,  Node: plgra; Switch to graphics screen,  Next: plgradient; Draw linear gradient inside polygon,  Prev: plgpage; Get page parameters,  Up: The Common API for PLplot

18.51 plgra: Switch to graphics screen
======================================

     plgra ();

   Sets an interactive device to graphics mode, used in conjunction with
`pltext' (*note pltext; Switch to text screen::) to allow graphics and
text to be interspersed.  On a device which supports separate text and
graphics windows, this command causes control to be switched to the
graphics window.  If already in graphics mode, this command is ignored.
It is also ignored on devices which only support a single window or use
a different method for shifting focus.  See also `pltext' (*note
pltext; Switch to text screen::).

   Redacted form: `plgra()'

   This function is used in example 1.


File: plplotdoc.info,  Node: plgradient; Draw linear gradient inside polygon,  Next: plgriddata; Grid data from irregularly sampled data,  Prev: plgra; Switch to graphics screen,  Up: The Common API for PLplot

18.52 plgradient: Draw linear gradient inside polygon
=====================================================

     plgradient (n, x, y, angle);

   Draw a linear gradient using colour map 1 inside the polygon defined
by the ``n'' points `(`x'[i], `y'[i])'.  Interpretation of the polygon
is the same as for `plfill' (*note plfill; Draw filled polygon::).  The
polygon coordinates and the gradient angle are all expressed in world
coordinates.  The angle from the ``x'' axis for both the rotated
coordinate system and the gradient vector is specified by ``angle''.
The magnitude of the gradient vector is the difference between the
maximum and minimum values of ``x'' for the vertices in the rotated
coordinate system.  The origin of the gradient vector can be
interpreted as being anywhere on the line corresponding to the minimum
``x'' value for the vertices in the rotated coordinate system.  The
distance along the gradient vector is linearly transformed to the
independent variable of colour map 1 which ranges from 0. at the tail
of the gradient vector to 1. at the head of the gradient vector.  What
is drawn is the RGBA colour corresponding to the independent variable
of colour map 1.  For more information about colour map 1 (see *note
Color Map1::).

`n'  (`PLINT', input)
     Number of vertices in polygon.

`x'  (`const PLFLT *', input)
     Pointer to array with x coordinates of vertices.

`y'  (`const PLFLT *', input)
     Pointer to array with y coordinates of vertices.

`angle'  (`PLFLT', input)
     Angle (degrees) of gradient vector from x axis.

   Redacted form: `plgradient(x,y,angle)'

   This function is used in examples 25,30.


File: plplotdoc.info,  Node: plgriddata; Grid data from irregularly sampled data,  Next: plgspa; Get current subpage parameters,  Prev: plgradient; Draw linear gradient inside polygon,  Up: The Common API for PLplot

18.53 plgriddata: Grid data from irregularly sampled  data
==========================================================

     plgriddata (x, y, z, npts, xg, nptsx, yg, nptsy, zg, type, data);

   Real world data is frequently irregularly sampled, but all PLplot 3D
plots require data placed in a uniform grid. This function takes
irregularly sampled data from three input arrays `x[npts]', `y[npts]',
and `z[npts]', reads the desired grid location from input arrays
`xg[nptsx]' and `yg[nptsy]', and returns the gridded data into output
array `zg[nptsx][nptsy]'.  The algorithm used to grid the data is
specified with the argument `type' which can have one parameter
specified in argument `data'.

`x'  (`const PLFLT *', input)
     The input `x' array.

`y'  (`const PLFLT *', input)
     The input `y' array.

`z'  (`const PLFLT *', input)
     The input `z' array. Each triple `x[i]', `y[i]', `z[i]' represents
     one data sample coordinate.

`npts'  (`PLINT', input)
     The number of data samples in the `x', `y' and `z' arrays.

`xg'  (`const PLFLT *', input)
     The input array that specifies the grid spacing in the x
     direction. Usually `xg' has `nptsx' equally spaced values from the
     minimum to the maximum values of the `x' input array.

`nptsx'  (`PLINT', input)
     The number of points in the `xg' array.

`yg'  (`const PLFLT *', input)
     The input array that specifies the grid spacing in the y
     direction. Similar to the `xg' parameter.

`nptsy'  (`PLINT', input)
     The number of points in the `yg' array.

`zg'  (`PLFLT **', output)
     The output array, where data lies in the regular grid specified by
     `xg' and `yg.' the `zg' array must exist or be allocated by the
     user prior to the call, and must have dimension `zg[nptsx][nptsy]'.

`type'  (`PLINT', input)
     The type of gridding algorithm to use, which can be:

        * `GRID_CSA': Bivariate Cubic Spline approximation

        * `GRID_DTLI': Delaunay Triangulation Linear Interpolation

        * `GRID_NNI': Natural Neighbors Interpolation

        * `GRID_NNIDW': Nearest Neighbors Inverse Distance Weighted

        * `GRID_NNLI': Nearest Neighbors Linear Interpolation

        * `GRID_NNAIDW':  Nearest Neighbors Around Inverse Distance
          Weighted

     For details of the algorithms read the source file `plgridd.c'.

`data'  (`PLFLT', input)
     Some gridding algorithms require extra data, which can be
     specified through this argument. Currently, for algorithm:

        * `GRID_NNIDW', `data' specifies the number of neighbors to
          use, the lower the value, the noisier (more local) the
          approximation is.

        * `GRID_NNLI', `data' specifies what a thin triangle is, in the
          range [1. .. 2.]. High values enable the usage of very thin
          triangles for interpolation, possibly resulting in error in
          the approximation.

        * `GRID_NNI', only weights greater than `data' will be
          accepted. If 0, all weights will be accepted.

   Redacted form:

   * General: `plgriddata(x, y, z, xg, yg, zg, type, data)'

   * Perl/PDL: Not available?

   * Python: ``zg'=`plgriddata(x, y, z, xg, yg, type, data)''

   This function is used in example 21.


File: plplotdoc.info,  Node: plgspa; Get current subpage parameters,  Next: plgstrm; Get current stream number,  Prev: plgriddata; Grid data from irregularly sampled data,  Up: The Common API for PLplot

18.54 plgspa: Get current subpage parameters
============================================

     plgspa (xmin, xmax, ymin, ymax);

   Gets the size of the current subpage in millimeters measured from the
bottom left hand corner of the output device page or screen.  Can be
used in conjunction with `plsvpa' (*note plsvpa; Specify viewport in
absolute coordinates::) for setting the size of a viewport in absolute
coordinates (millimeters).

`xmin'  (`PLFLT *', output)
     Pointer to variable with position of left hand edge of subpage in
     millimeters.

`xmax'  (`PLFLT *', output)
     Pointer to variable with position of right hand edge of subpage in
     millimeters.

`ymin'  (`PLFLT *', output)
     Pointer to variable with position of bottom edge of subpage in
     millimeters.

`ymax'  (`PLFLT *', output)
     Pointer to variable with position of top edge of subpage in
     millimeters.

   Redacted form: `plgspa(xmin, xmax, ymin, ymax)'

   This function is used in example 23.


File: plplotdoc.info,  Node: plgstrm; Get current stream number,  Next: plgver; Get the current library version number,  Prev: plgspa; Get current subpage parameters,  Up: The Common API for PLplot

18.55 plgstrm: Get current stream number
========================================

     plgstrm (p_strm);

   Gets the number of the current output stream. See also `plsstrm'
(*note plsstrm; Set current output stream::).

`p_strm'  (`PLINT *', output)
     Pointer to current stream value.

   Redacted form: `plgstrm(p_strm)'

   This function is used in example 1,20.


File: plplotdoc.info,  Node: plgver; Get the current library version number,  Next: plgvpd; Get viewport limits in normalized device coordinates,  Prev: plgstrm; Get current stream number,  Up: The Common API for PLplot

18.56 plgver: Get the current library version number
====================================================

     plgver (p_ver);

   Get the current library version number.  Note: you _must_ have
allocated space for this (80 characters is safe).

`p_ver'  (`char *', output)
     Pointer to the current library version number.

   Redacted form: `plgver(p_ver)'

   This function is used in example 1.


File: plplotdoc.info,  Node: plgvpd; Get viewport limits in normalized device coordinates,  Next: plgvpw; Get viewport limits in world coordinates,  Prev: plgver; Get the current library version number,  Up: The Common API for PLplot

18.57 plgvpd: Get viewport limits in normalized  device coordinates
===================================================================

     plgvpd (p_xmin, p_xmax, p_ymin, p_ymax);

   Get viewport limits in normalized device coordinates.

`p_xmin'  (`PLFLT *', output)
     Lower viewport limit of the normalized device coordinate in x.

`p_xmax'  (`PLFLT *', output)
     Upper viewport limit of the normalized device coordinate in x.

`p_ymin'  (`PLFLT *', output)
     Lower viewport limit of the normalized device coordinate in y.

`p_ymax'  (`PLFLT *', output)
     Upper viewport limit of the normalized device coordinate in y.

   Redacted form:

   * General: `plgvpd(p_xmin, p_xmax, p_ymin, p_ymax)'

   * Perl/PDL: Not available?

   This function is used in example 31.


File: plplotdoc.info,  Node: plgvpw; Get viewport limits in world coordinates,  Next: plgxax; Get x axis parameters,  Prev: plgvpd; Get viewport limits in normalized device coordinates,  Up: The Common API for PLplot

18.58 plgvpw: Get viewport limits in world coordinates
======================================================

     plgvpw (p_xmin, p_xmax, p_ymin, p_ymax);

   Get viewport limits in world coordinates.

`p_xmin'  (`PLFLT *', output)
     Lower viewport limit of the world coordinate in x.

`p_xmax'  (`PLFLT *', output)
     Upper viewport limit of the world coordinate in x.

`p_ymin'  (`PLFLT *', output)
     Lower viewport limit of the world coordinate in y.

`p_ymax'  (`PLFLT *', output)
     Upper viewport limit of the world coordinate in y.

   Redacted form:

   * General: `plgvpw(p_xmin, p_xmax, p_ymin, p_ymax)'

   * Perl/PDL: Not available?

   This function is used in example 31.


File: plplotdoc.info,  Node: plgxax; Get x axis parameters,  Next: plgyax; Get y axis parameters,  Prev: plgvpw; Get viewport limits in world coordinates,  Up: The Common API for PLplot

18.59 plgxax: Get x axis parameters
===================================

     plgxax (p_digmax, p_digits);

   Returns current values of the ``p_digmax'' and ``p_digits'' flags
for the x axis.  ``p_digits'' is updated after the plot is drawn, so
this routine should only be called _after_ the call to `plbox' (*note
plbox; Draw a box with axes; etc::) (or ` plbox3' (*note plbox3; Draw a
box with axes; etc; in 3-d::)) is complete.  See *note Annotating the
Viewport:: for more information.

`p_digmax'  (`PLINT *', output)
     Pointer to variable with the maximum number of digits for the x
     axis.  If nonzero, the printed label has been switched to a
     floating point representation when the number of digits exceeds
     ``p_digmax''.

`p_digits'  (`PLINT *', output)
     Pointer to variable with the actual number of digits for the
     numeric labels (x axis) from the last plot.

   Redacted form: `plgxax(p_digmax, p_digits)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgyax; Get y axis parameters,  Next: plgzax; Get z axis parameters,  Prev: plgxax; Get x axis parameters,  Up: The Common API for PLplot

18.60 plgyax: Get y axis parameters
===================================

     plgyax (p_digmax, p_digits);

   Identical to `plgxax' (*note plgxax; Get x axis parameters::),
except that arguments are flags for y axis.  See the description of
`plgxax' (*note plgxax; Get x axis parameters::) for more detail.

`p_digmax'  (`PLINT *', output)
     Pointer to variable with the maximum number of digits for the y
     axis.  If nonzero, the printed label has been switched to a
     floating point representation when the number of digits exceeds
     ``p_digmax''.

`p_digits'  (`PLINT *', output)
     Pointer to variable with the actual number of digits for the
     numeric labels (y axis) from the last plot.

   Redacted form: `plgyax(p_digmax, p_digits)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plgzax; Get z axis parameters,  Next: plhist; Plot a histogram from unbinned data,  Prev: plgyax; Get y axis parameters,  Up: The Common API for PLplot

18.61 plgzax: Get z axis parameters
===================================

     plgzax (p_digmax, p_digits);

   Identical to `plgxax' (*note plgxax; Get x axis parameters::),
except that arguments are flags for z axis.  See the description of
`plgxax' (*note plgxax; Get x axis parameters::) for more detail.

`p_digmax'  (`PLINT *', output)
     Pointer to variable with the maximum number of digits for the z
     axis.  If nonzero, the printed label has been switched to a
     floating point representation when the number of digits exceeds
     ``p_digmax''.

`p_digits'  (`PLINT *', output)
     Pointer to variable with the actual number of digits for the
     numeric labels (z axis) from the last plot.

   Redacted form: `plgzax(p_digmax, p_digits)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plhist; Plot a histogram from unbinned data,  Next: plhlsrgb; Convert HLS color to RGB,  Prev: plgzax; Get z axis parameters,  Up: The Common API for PLplot

18.62 plhist: Plot a histogram from unbinned data
=================================================

     plhist (n, data, datmin, datmax, nbin, opt);

   Plots a histogram from ``n'' data points stored in the array
``data''.  This routine bins the data into ``nbin'' bins equally spaced
between ``datmin'' and ``datmax'', and calls `plbin' (*note plbin; Plot
a histogram from binned data::) to draw the resulting histogram.
Parameter ``opt'' allows, among other things, the histogram either to
be plotted in an existing window or causes `plhist' (*note plhist; Plot
a histogram from unbinned data::) to call `plenv' (*note plenv; Set up
standard window and draw box::) with suitable limits before plotting
the histogram.

`n'  (`PLINT', input)
     Number of data points.

`data'  (`const PLFLT *', input)
     Pointer to array with values of the ``n'' data points.

`datmin'  (`PLFLT', input)
     Left-hand edge of lowest-valued bin.

`datmax'  (`PLFLT', input)
     Right-hand edge of highest-valued bin.

`nbin'  (`PLINT', input)
     Number of (equal-sized) bins into which to divide the interval
     ``xmin'' to ``xmax''.

`opt'  (`PLINT', input)
     Is a combination of several flags:

        * ``opt'=PL_HIST_DEFAULT': The axes are automatically rescaled
          to fit the histogram data, the outer bins are expanded to
          fill up the entire x-axis, data outside the given extremes
          are assigned to the outer bins and bins of zero height are
          simply drawn.

        * ``opt'=PL_HIST_NOSCALING|...': The existing axes are not
          rescaled to fit the histogram data, without this flag,
          `plenv' (*note plenv; Set up standard window and draw box::)
          is called to set the world coordinates.

        * ``opt'=PL_HIST_IGNORE_OUTLIERS|...': Data outside the given
          extremes are not taken into account.  This option should
          probably be combined with ``opt'=PL_HIST_NOEXPAND|...', so as
          to properly present the data.

        * ``opt'=PL_HIST_NOEXPAND|...': The outer bins are drawn with
          equal size as the ones inside.

        * ``opt'=PL_HIST_NOEMPTY|...': Bins with zero height are not
          drawn (there is a gap for such bins).

   Redacted form: `plhist(data, datmin, datmax, nbin, opt)'

   This function is used in example 5.


File: plplotdoc.info,  Node: plhlsrgb; Convert HLS color to RGB,  Next: plimagefr; Plot a 2D matrix using cmap1,  Prev: plhist; Plot a histogram from unbinned data,  Up: The Common API for PLplot

18.63 plhlsrgb: Convert HLS color to RGB
========================================

     plhlsrgb (h, l, s, p_r, p_g, p_b);

   Convert HLS color coordinates to RGB.

`h'  (`PLFLT', input)
     Hue, in degrees on the colour cone (0.0-360.0)

`l'  (`PLFLT', input)
     Lightness, expressed as a fraction of the axis of the colour cone
     (0.0-1.0)

`s'  (`PLFLT', input)
     Saturation, expressed as a fraction of the radius of the colour
     cone (0.0-1.0)

`p_r'  (`PLFLT *', output)
     Pointer to red intensity (0.0-1.0) of the colour

`p_g'  (`PLFLT *', output)
     Pointer to green intensity (0.0-1.0) of the colour

`p_b'  (`PLFLT *', output)
     Pointer to blue intensity (0.0-1.0) of the colour

   Redacted form:

   * General: `plhlsrgb(h, l, s, p_r, p_g, p_b)'

   * Perl/PDL: Not available? Implemented as plhls?

   This function is used in example 2.


File: plplotdoc.info,  Node: plimagefr; Plot a 2D matrix using cmap1,  Next: plimage; Plot a 2D matrix using cmap1 with automatic colour adjustment,  Prev: plhlsrgb; Convert HLS color to RGB,  Up: The Common API for PLplot

18.64 plimagefr: Plot a 2D matrix using cmap1
=============================================

     plimagefr (idata, nx, ny, xmin, xmax, ymin, ymax, zmin, zmax,
     valuemin, valuemax, pltr, pltr_data);

   Plot a 2D matrix using cmap1.

`idata'  (`const PLFLT * const *', input)
     A 2D array of values (intensities) to plot.  Should have
     dimensions idata[nx][ny].

`nx, ny'  (`PLINT', input)
     Dimensions of idata

`xmin, xmax, ymin, ymax'  (`PLFLT', input)
     Stretch image data to these Plot coordinates.  idata[0][0]
     corresponds to (xmin, ymin) and idata[nx - 1][ny - 1] corresponds
     to (xmax, ymax).

`zmin, zmax'  (`PLFLT', input)
     Only data between zmin and zmax (inclusive) will be plotted.

`valuemin, valuemax'  (`PLFLT', input)
     The minimum and maximum data values to use for value to color
     mappings.  A datum equal to or less than valuemin will be plotted
     with color 0.0, while a datum equal to or greater than valuemax
     will be plotted with color 1.0.  Data between valuemin and
     valuemax map linearly to colors between 0.0 and 1.0.

`pltr'  (`void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)  ', input)
     Pointer to function that defines a transformation between the data
     in the array ``idata'' and world coordinates.  An input coordinate
     of `(0, 0)' corresponds to the "top-left" corner of ``idata'' while
     `(nx, ny)' corresponds to the "bottom-right" corner of ``idata''.
     Some transformation functions are provided in the PLplot library:
     `pltr0' (*note pltr0; Identity transformation for grid to world
     mapping::) for identity mapping, and `pltr1' (*note pltr1; Linear
     interpolation for grid to world mapping using 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]::)
     for arbitrary mappings respectively defined by one- and
     two-dimensional arrays.  In addition, user-supplied routines for
     the transformation can be used as well.  Examples of all of these
     approaches are given in *note Contour Plots from C::.  The
     transformation function should have the form given by any of
     `pltr0' (*note pltr0; Identity transformation for grid to world
     mapping::), `pltr1' (*note pltr1; Linear interpolation for grid to
     world mapping using singly dimensioned coordinate arrays::), or
     `pltr2' (*note pltr2; Linear interpolation for grid to world
     mapping using doubly dimensioned coordinate arrays [column
     dominant; as per normal C 2d arrays]::).

`pltr_data'  (`PLPointer', input)
     Extra parameter to help pass information to `pltr0' (*note pltr0;
     Identity transformation for grid to world mapping::), `pltr1'
     (*note pltr1; Linear interpolation for grid to world mapping using
     singly dimensioned coordinate arrays::), `pltr2' (*note pltr2;
     Linear interpolation for grid to world mapping using doubly
     dimensioned coordinate arrays [column dominant; as per normal C 2d
     arrays]::), or whatever routine is externally supplied.

   Redacted form:

   * General: ` plimagefr(idata, xmin, xmax, ymin, ymax, zmin, zmax,
     valuemin, valuemax, pltr, pltr_data) '

   This function is used in example 20.


File: plplotdoc.info,  Node: plimage; Plot a 2D matrix using cmap1 with automatic colour adjustment,  Next: plinit; Initialize PLplot,  Prev: plimagefr; Plot a 2D matrix using cmap1,  Up: The Common API for PLplot

18.65 plimage: Plot a 2D matrix using cmap1 with  automatic colour adjustment
=============================================================================

     plimage (idata, nx, ny, xmin, xmax, ymin, ymax, zmin, zmax, Dxmin,
     Dxmax, Dymin, Dymax);

   Plot a 2D matrix using color palette 1.  The color scale is
automatically adjusted to use the maximum and minimum values in idata
as valuemin and valuemax in a call to `plimagefr' (*note plimagefr;
Plot a 2D matrix using cmap1::).

`idata'  (`const PLFLT * const *', input)
     A 2D array of values (intensities) to plot.  Should have
     dimensions idata[nx][ny].

`nx, ny'  (`PLINT', input)
     Dimensions of idata

`xmin, xmax, ymin, ymax'  (`PLFLT', input)
     Plot coordinates to stretch the image data to.  idata[0][0]
     corresponds to (xmin, ymin) and idata[nx - 1][ny - 1] corresponds
     to (xmax, ymax).

`zmin, zmax'  (`PLFLT', input)
     Only data between zmin and zmax (inclusive) will be plotted.

`Dxmin, Dxmax, Dymin, Dymax'  (`PLFLT', input)
     Plot only the window of points whose plot coordinates fall inside
     the window of (Dxmin, Dymin) to (Dxmax, Dymax).

   Redacted form:

   * General: ` plimage(idata, xmin, xmax, ymin, ymax, zmin, zmax,
     Dxmin, Dxmax, Dymin, Dymax) '

   This function is used in example 20.


File: plplotdoc.info,  Node: plinit; Initialize PLplot,  Next: pljoin; Draw a line between two points,  Prev: plimage; Plot a 2D matrix using cmap1 with automatic colour adjustment,  Up: The Common API for PLplot

18.66 plinit: Initialize PLplot
===============================

     plinit ();

   Initializing the plotting package.  The program prompts for the
device keyword or number of the desired output device.  Hitting a
RETURN in response to the prompt is the same as selecting the first
device.  `plinit' (*note plinit; Initialize PLplot::) will issue no
prompt if either the device was specified previously (via command line
flag, the `plsetopt' (*note plsetopt; Set any command-line option::)
function, or the `plsdev' (*note plsdev; Set the device [keyword]
name::) function), or if only one device is enabled when PLplot is
installed.  If subpages have been specified, the output device is
divided into `nx' by `ny' subpages, each of which may be used
independently.  If `plinit' (*note plinit; Initialize PLplot::) is
called again during a program, the previously opened file will be
closed.  The subroutine `pladv' (*note pladv; Advance the [sub-]page::)
is used to advance from one subpage to the next.

   Redacted form: `plinit()'

   This function is used in all of the examples.


File: plplotdoc.info,  Node: pljoin; Draw a line between two points,  Next: pllab; Simple routine to write labels,  Prev: plinit; Initialize PLplot,  Up: The Common API for PLplot

18.67 pljoin: Draw a line between two points
============================================

     pljoin (x1, y1, x2, y2);

   Joins the point `(`x1', `y1')' to `(`x2', `y2')'.

`x1'  (`PLFLT', input)
     x coordinate of first point.

`y1'  (`PLFLT', input)
     y coordinate of first point.

`x2'  (`PLFLT', input)
     x coordinate of second point.

`y2'  (`PLFLT', input)
     y coordinate of second point.

   Redacted form: `pljoin(x1,y1,x2,y2)'

   This function is used in examples 3,14.


File: plplotdoc.info,  Node: pllab; Simple routine to write labels,  Next: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols,  Prev: pljoin; Draw a line between two points,  Up: The Common API for PLplot

18.68 pllab: Simple routine to write labels
===========================================

     pllab (xlabel, ylabel, tlabel);

   Routine for writing simple labels. Use `plmtex' (*note plmtex; Write
text relative to viewport boundaries::) for more complex labels.

`xlabel'  (`const char *', input)
     Label for horizontal axis.

`ylabel'  (`const char *', input)
     Label for vertical axis.

`tlabel'  (`const char *', input)
     Title of graph.

   Redacted form: `pllab(xlabel, ylabel, tlabel)'

   This function is used in examples 1,5,9,12,14-16,20-22,29.


File: plplotdoc.info,  Node: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols,  Next: pllightsource; Sets the 3D position of the light source,  Prev: pllab; Simple routine to write labels,  Up: The Common API for PLplot

18.69 pllegend: Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols
===================================================================================================

     pllegend (p_legend_width, p_legend_height, opt, position, x, y,
     plot_width, bg_color, bb_color, bb_style, nrow, ncolumn, nlegend,
     opt_array, text_offset, text_scale, text_spacing,
     test_justification, text_colors, text, box_colors, box_patterns,
     box_scales, box_line_widths, line_colors, line_styles,
     line_widths, symbol_colors, symbol_scales, symbol_numbers,
     symbols);

   Routine for creating a discrete plot legend with a plotted filled
box, line, and/or line of symbols for each annotated legend entry.
(See `plcolorbar' (*note plcolorbar; Plot color bar for image; shade or
gradient plots::) for similar functionality for creating continuous
color bars.)  The arguments of pllegend provide control over the
location and size of the legend as well as the location and
characteristics of the elements (most of which are optional) within
that legend.  The resulting legend is clipped at the boundaries of the
current subpage.  (N.B. the adopted coordinate system used for some of
the parameters is defined in the documentation of the ``position''
parameter.)

`p_legend_width'  (`PLFLT *', output)
     Pointer to a location which contains (after the call) the legend
     width in adopted coordinates. This quantity is calculated from
     ``plot_width'', ``text_offset'', ``ncolumn'' (possibly modified
     inside the routine depending on ``nlegend'' and ``nrow''), and the
     length (calculated internally) of the longest text string.

`p_legend_height'  (`PLFLT *', output)
     Pointer to a location which contains (after the call) the legend
     height in adopted coordinates. This quantity is calculated from
     ``text_scale'', ``text_spacing'', and ``nrow'' (possibly modified
     inside the routine depending on ``nlegend'' and ``nrow'').

`opt'  (`PLINT', input)
     ``opt'' contains bits controlling the overall legend. If the
     `PL_LEGEND_TEXT_LEFT' bit is set, put the text area on the left of
     the legend and the plotted area on the right. Otherwise, put the
     text area on the right of the legend and the plotted area on the
     left. If the `PL_LEGEND_BACKGROUND' bit is set, plot a
     (semi-transparent) background for the legend. If the
     `PL_LEGEND_BOUNDING_BOX' bit is set, plot a bounding box for the
     legend. If the `PL_LEGEND_ROW_MAJOR' bit is set and (both of the
     possibly internally transformed) ``nrow'' > 1 and ``ncolumn'' > 1,
     then plot the resulting array of legend entries in row-major order.
     Otherwise, plot the legend entries in column-major order.

`position'  (`PLINT', input)
     ``position'' contains bits which control the overall position of
     the legend and the definition of the adopted coordinates used for
     positions just like what is done for the position argument for
     `plcolorbar' (*note plcolorbar; Plot color bar for image; shade or
     gradient plots::). However, note that the defaults for the
     position bits (see below) are different than the `plcolorbar'
     (*note plcolorbar; Plot color bar for image; shade or gradient
     plots::) case.  The combination of the `PL_POSITION_LEFT',
     `PL_POSITION_RIGHT', `PL_POSITION_TOP', `PL_POSITION_BOTTOM',
     `PL_POSITION_INSIDE', and `PL_POSITION_OUTSIDE' bits specifies one
     of the 16 possible standard positions (the 4 corners and centers
     of the 4 sides for both the inside and outside cases) of the
     legend relative to the adopted coordinate system. The corner
     positions are specified by the appropriate combination of two of
     the `PL_POSITION_LEFT', `PL_POSITION_RIGHT', `PL_POSITION_TOP', and
     `PL_POSITION_BOTTOM' bits while the sides are specified by a
     single value of one of those bits.  The adopted coordinates are
     normalized viewport coordinates if the `PL_POSITION_VIEWPORT' bit
     is set or normalized subpage coordinates if the
     `PL_POSITION_SUBPAGE' bit is set. Default position bits: If none of
     `PL_POSITION_LEFT', `PL_POSITION_RIGHT', `PL_POSITION_TOP', or
     `PL_POSITION_BOTTOM' are set, then use the combination of
     `PL_POSITION_RIGHT' and `PL_POSITION_TOP'. If neither of
     `PL_POSITION_INSIDE' or `PL_POSITION_OUTSIDE' is set, use
     `PL_POSITION_INSIDE'. If neither of `PL_POSITION_VIEWPORT' or
     `PL_POSITION_SUBPAGE' is set, use `PL_POSITION_VIEWPORT'.

`x'  (` PLFLT', input)
     X offset of the legend position in adopted coordinates from the
     specified standard position of the legend. For positive x, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard left
     or right positions if the
     `PL_POSITION_INSIDE'/`PL_POSITION_OUTSIDE' bit is set in
     ``position''.  For the standard top or bottom positions, the
     direction of motion is toward positive X.

`y'  (`PLFLT', input)
     Y offset of the legend position in adopted coordinates from the
     specified standard position of the legend. For positive y, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard top
     or bottom positions if the
     `PL_POSITION_INSIDE'/`PL_POSITION_OUTSIDE' bit is set in
     ``position''.  For the standard left or right positions, the
     direction of motion is toward positive Y.

`plot_width'  (`PLFLT', input)
     Horizontal width in adopted coordinates of the plot area (where
     the colored boxes, lines, and/or lines of symbols are drawn) of
     the legend.

`bg_color'  (`PLINT', input)
     The cmap0 color of the background for the legend
     (`PL_LEGEND_BACKGROUND').

`bb_color'  (`PLINT', input)
     The cmap0 color of the bounding-box line for the legend
     (`PL_LEGEND_BOUNDING_BOX').

`bb_style'  (`PLINT', input)
     The pllsty style number for the bounding-box line for the legend
     (`PL_LEGEND_BACKGROUND').

`nrow'  (`PLINT', input)
     The cmap0 index of the background color for the legend
     (`PL_LEGEND_BACKGROUND').

`ncolumn'  (`PLINT', input)
     The cmap0 index of the background color for the legend
     (`PL_LEGEND_BACKGROUND').

`nlegend'  (`PLINT', input)
     Number of legend entries.  N.B.  The total vertical height of the
     legend in adopted coordinates is calculated internally from
     ``nlegend'', ``text_scale'' (see below), and ``text_spacing'' (see
     below).

`opt_array'  (`const PLINT *', input)
     Array of nlegend values of options to control each individual
     plotted area corresponding to a legend entry.  If the
     `PL_LEGEND_NONE' bit is set, then nothing is plotted in the
     plotted area.  If the `PL_LEGEND_COLOR_BOX', `PL_LEGEND_LINE',
     and/or `PL_LEGEND_SYMBOL' bits are set, the area corresponding to
     a legend entry is plotted with a colored box; a line; and/or a
     line of symbols.

`text_offset'  (`PLFLT', input)
     Offset of the text area from the plot area in units of character
     width.  N.B.  The total horizontal width of the legend in adopted
     coordinates is calculated internally from `plot_width' (see above),
     `text_offset', and length (calculated internally) of the longest
     text string.

`text_scale'  (`PLFLT', input)
     Character height scale for text annotations.  N.B.  The total
     vertical height of the legend in adopted coordinates is calculated
     internally from `nlegend' (see above), `text_scale', and
     `text_spacing' (see below).

`text_spacing'  (`PLFLT', input)
     Vertical spacing in units of the character height from one legend
     entry to the next.  N.B.  The total vertical height of the legend
     in adopted coordinates is calculated internally from `nlegend'
     (see above), `text_scale' (see above), and `text_spacing'.

`text_justification'  (`PLFLT', input)
     Justification parameter used for text justification.  The most
     common values of text_justification are 0., 0.5, or 1.
     corresponding to a text that is left justified, centred, or right
     justified within the text area, but other values are allowed as
     well.

`text_colors'  (`const PLINT *', input)
     Array of nlegend cmap0 text colors.

`text'  (`const char * const *', input)
     Array of nlegend text string annotations.

`box_colors'  (`const PLINT *', input)
     Array of nlegend cmap0 colors for the discrete colored boxes
     (`PL_LEGEND_COLOR_BOX').

`box_patterns'  (`const PLINT *', input)
     Array of nlegend patterns (plpsty indices) for the discrete colored
     boxes (`PL_LEGEND_COLOR_BOX').

`box_scales'  (`const PLFLT *', input)
     Array of nlegend scales (units of fraction of character height) for
     the height of the discrete colored boxes (`PL_LEGEND_COLOR_BOX').

`box_line_widths'  (`const PLFLT *', input)
     Array of nlegend line widths for the patterns specified by
     box_patterns (`PL_LEGEND_COLOR_BOX').

`line_colors'  (`const PLINT *', input)
     Array of nlegend cmap0 line colors (`PL_LEGEND_LINE').

`line_styles'  (`const PLINT *', input)
     Array of nlegend line styles (plsty indices) (`PL_LEGEND_LINE').

`line_widths'  (`const PLFLT *', input)
     Array of nlegend line widths (`PL_LEGEND_LINE').

`symbol_colors'  (`const PLINT *', input)
     Array of nlegend cmap0 symbol colors (`PL_LEGEND_SYMBOL').

`symbol_scales'  (`const PLFLT *', input)
     Array of nlegend scale values for the symbol height
     (`PL_LEGEND_SYMBOL').

`symbol_numbers'  (`const PLINT *', input)
     Array of nlegend numbers of symbols to be drawn across the width of
     the plotted area (`PL_LEGEND_SYMBOL').

`symbols'  (`const char * const *', input)
     Array of nlegend symbols (plpoin indices) (`PL_LEGEND_SYMBOL').

   Redacted form: `pllegend(p_legend_width, p_legend_height, opt,
position, x, y, plot_width, bg_color, bb_color, bb_style, nrow, ncolumn,
opt_array, text_offset, text_scale, text_spacing, test_justification,
text_colors, text, box_colors, box_patterns, box_scales,
box_line_widths, line_colors, line_styles, line_widths, symbol_colors,
symbol_scales, symbol_numbers, symbols)'

   This function is used in examples 4, 26, and 33.


File: plplotdoc.info,  Node: pllightsource; Sets the 3D position of the light source,  Next: plline; Draw a line,  Prev: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols,  Up: The Common API for PLplot

18.70 pllightsource: Sets the 3D position of the light  source
==============================================================

     pllightsource (x, y, z);

   Sets the 3D position of the light source for use with `plsurf3d'
(*note plsurf3d; Plot shaded 3-d surface plot::).

`x'  (`PLFLT', input)
     X-coordinate of the light source.

`y'  (`PLFLT', input)
     Y-coordinate of the light source.

`z'  (`PLFLT', input)
     Z-coordinate of the light source.

   Redacted form: `pllightsource(x, y, z)'

   This function is used in example 8.


File: plplotdoc.info,  Node: plline; Draw a line,  Next: plline3; Draw a line in 3 space,  Prev: pllightsource; Sets the 3D position of the light source,  Up: The Common API for PLplot

18.71 plline: Draw a line
=========================

     plline (n, x, y);

   Draws line defined by ``n'' points in ``x'' and ``y''.

`n'  (`PLINT', input)
     Number of points defining line.

`x'  (`const PLFLT *', input)
     Pointer to array with x coordinates of points.

`y'  (`const PLFLT *', input)
     Pointer to array with y coordinates of points.

   Redacted form: `plline(x, y)'

   This function is used in examples 1,3,4,9,12-14,16,18,20,22,25-27,29.


File: plplotdoc.info,  Node: plline3; Draw a line in 3 space,  Next: pllsty; Select line style,  Prev: plline; Draw a line,  Up: The Common API for PLplot

18.72 plline3: Draw a line in 3 space
=====================================

     plline3 (n, x, y, z);

   Draws line in 3 space defined by ``n'' points in ``x'', ``y'', and
``z''.  You must first set up the viewport, the 2d viewing window (in
world coordinates), and the 3d normalized coordinate box.  See `x18c.c'
for more info.

`n'  (`PLINT', input)
     Number of points defining line.

`x'  (`const PLFLT *', input)
     Pointer to array with x coordinates of points.

`y'  (`const PLFLT *', input)
     Pointer to array with y coordinates of points.

`z'  (`const PLFLT *', input)
     Pointer to array with z coordinates of points.

   Redacted form: `plline3(x, y, z)'

   This function is used in example 18.


File: plplotdoc.info,  Node: pllsty; Select line style,  Next: plmap; Plot continental outline in world coordinates,  Prev: plline3; Draw a line in 3 space,  Up: The Common API for PLplot

18.73 pllsty: Select line style
===============================

     pllsty (lin);

   This sets the line style according to one of eight predefined
patterns (also see `plstyl' (*note plstyl; Set line style::)).

`lin'  (`PLINT', input)
     Integer value between 1 and 8. Line style 1 is a continuous line,
     line style 2 is a line with short dashes and gaps, line style 3 is
     a line with long dashes and gaps, line style 4 has long dashes and
     short gaps and so on.

   Redacted form: `pllsty(lin)'

   This function is used in examples 9,12,22,25.


File: plplotdoc.info,  Node: plmap; Plot continental outline in world coordinates,  Next: plmeridians; Plot latitude and longitude lines,  Prev: pllsty; Select line style,  Up: The Common API for PLplot

18.74 plmap: Plot continental outline in world coordinates
==========================================================

     plmap (mapform, type, minlong, maxlong, minlat, maxlat);

   Plots continental outlines in world coordinates.  examples/c/x19c
demonstrates how to use this function to create different projections.

`mapform'  (`void (*) (PLINT, PLFLT *, PLFLT *)', input)
     A user supplied function to transform the coordinate longitudes
     and latitudes to a plot coordinate system.  By using this
     transform, we can change from a longitude, latitude coordinate to
     a polar stereographic project, for example.  Initially,
     x[0]..[n-1] are the longitudes and y[0]..y[n-1] are the
     corresponding latitudes.  After the call to mapform(), x[] and y[]
     should be replaced by the corresponding plot coordinates.  If no
     transform is desired, mapform can be replaced by NULL.

`type'  (`const char *', input)
     type is a character string. The value of this parameter determines
     the type of background. The possible values are:

        * `"globe"' - continental outlines

        * `"usa"' - USA and state boundaries

        * `"cglobe"' - continental outlines and countries

        * `"usaglobe"' - USA, state boundaries and continental outlines

`minlong'  (`PLFLT', input)
     The value of the longitude on the left side of the plot.  The
     value of minlong must be less than the value of maxlong, and the
     quantity maxlong-minlong must be less than or equal to 360.

`maxlong'  (`PLFLT', input)
     The value of the longitude on the right side of the plot.

`minlat'  (`PLFLT', input)
     The minimum latitude to be plotted on the background.  One can
     always use -90.0 as the boundary outside the plot window will be
     automatically eliminated.  However, the program will be faster if
     one can reduce the size of the background plotted.

`maxlat'  (`PLFLT', input)
     The maximum latitudes to be plotted on the background.  One can
     always use 90.0 as the boundary outside the plot window will be
     automatically eliminated.

   Redacted form:

   * General: `plmap(mapform, type, minlong, maxlong, minlat, maxlat)'

   * F95, Java, Perl/PDL, Python: Not implemented?

   This function is used in example 19.


File: plplotdoc.info,  Node: plmeridians; Plot latitude and longitude lines,  Next: plmesh; Plot surface mesh,  Prev: plmap; Plot continental outline in world coordinates,  Up: The Common API for PLplot

18.75 plmeridians: Plot latitude and longitude lines
====================================================

     plmeridians (mapform, dlong, dlat, minlong, maxlong, minlat,
     maxlat);

   Displays latitude and longitude on the current plot.  The lines are
plotted in the current color and line style.

`mapform'  (`void (*) (PLINT, PLFLT *, PLFLT *)', input)
     A user supplied function to transform the coordinate longitudes
     and latitudes to a plot coordinate system.  By using this
     transform, we can change from a longitude, latitude coordinate to
     a polar stereographic project, for example.  Initially,
     x[0]..[n-1] are the longitudes and y[0]..y[n-1] are the
     corresponding latitudes.  After the call to mapform(), x[] and y[]
     should be replaced by the corresponding plot coordinates.  If no
     transform is desired, mapform can be replaced by NULL.

`dlong'  (`PLFLT', input)
     The interval in degrees at which the longitude lines are to be
     plotted.

`dlat'  (`PLFLT', input)
     The interval in degrees at which the latitude lines are to be
     plotted.

`minlong'  (`PLFLT', input)
     The value of the longitude on the left side of the plot.  The
     value of minlong must be less than the value of maxlong, and the
     quantity maxlong-minlong must be less than or equal to 360.

`maxlong'  (`PLFLT', input)
     The value of the longitude on the right side of the plot.

`minlat'  (`PLFLT', input)
     The minimum latitude to be plotted on the background.  One can
     always use -90.0 as the boundary outside the plot window will be
     automatically eliminated.  However, the program will be faster if
     one can reduce the size of the background plotted.

`maxlat'  (`PLFLT', input)
     The maximum latitudes to be plotted on the background.  One can
     always use 90.0 as the boundary outside the plot window will be
     automatically eliminated.

   Redacted form:

   * General: `plmeridians(mapform, dlong, dlat, minlong, maxlong,
     minlat, maxlat)'

   * F95, Java, Perl/PDL, Python: Not implemented?

   This function is used in example 19.


File: plplotdoc.info,  Node: plmesh; Plot surface mesh,  Next: plmeshc; Magnitude colored plot surface mesh with contour,  Prev: plmeridians; Plot latitude and longitude lines,  Up: The Common API for PLplot

18.76 plmesh: Plot surface mesh
===============================

     plmesh (x, y, z, nx, ny, opt);

   Plots a surface mesh within the environment set up by `plw3d' (*note
plw3d; Set up window for 3-d plotting::).  The surface is defined by
the two-dimensional array ``z'[`nx'][`ny']', the point ``z'[i][j]'
being the value of the function at `(`x'[i], `y'[j])'.  Note that the
points in arrays ``x'' and ``y'' do not need to be equally spaced, but
must be stored in ascending order.  The parameter ``opt'' controls the
way in which the surface is displayed.  For further details see *note
Three Dimensional Surface Plots::.

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`z'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array with set of function
     values.

`nx'  (`PLINT', input)
     Number of ``x'' values at which function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented:

        * ``opt'=DRAW_LINEX': Lines are drawn showing ``z'' as a
          function of ``x'' for each value of ``y'[j]'.

        * ``opt'=DRAW_LINEY': Lines are drawn showing ``z'' as a
          function of ``y'' for each value of ``x'[i]'.

        * ``opt'=DRAW_LINEXY': Network of lines is drawn connecting
          points at which function is defined.

   Redacted form: `plmesh(x, y, z, opt)'

   This function is used in example 11.


File: plplotdoc.info,  Node: plmeshc; Magnitude colored plot surface mesh with contour,  Next: plmkstrm; Creates a new stream and makes it the default,  Prev: plmesh; Plot surface mesh,  Up: The Common API for PLplot

18.77 plmeshc: Magnitude colored plot surface mesh with contour
===============================================================

     plmeshc (x, y, z, nx, ny, opt, clevel, nlevel);

   A more powerful form of ``plmesh' (*note plmesh; Plot surface
mesh::)': the surface mesh can be colored accordingly to the current z
value being plotted, a contour plot can be drawn at the base XY plane,
and a curtain can be drawn between the plotted function border and the
base XY plane.

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`z'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array with set of function
     values.

`nx'  (`PLINT', input)
     Number of ``x'' values at which function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented. To specify
     more than one option just add the options, e.g. DRAW_LINEXY +
     MAG_COLOR

        * ``opt'=DRAW_LINEX': Lines are drawn showing ``z'' as a
          function of ``x'' for each value of ``y'[j]'.

        * ``opt'=DRAW_LINEY': Lines are drawn showing ``z'' as a
          function of ``y'' for each value of ``x'[i]'.

        * ``opt'=DRAW_LINEXY': Network of lines is drawn connecting
          points at which function is defined.

        * ``opt'=MAG_COLOR': Each line in the mesh is colored according
          to the z value being plotted. The color is used from the
          current color map 1.

        * ``opt'=BASE_CONT': A contour plot is drawn at the base XY
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=DRAW_SIDES': draws a curtain between the base XY plane
          and the borders of the plotted function.

`clevel'  (`const PLFLT *', input)
     Pointer to the array that defines the contour level spacing.

`nlevel'  (`PLINT', input)
     Number of elements in the `clevel' array.

   Redacted form: `plmeshc(x, y, z, opt, clevel)'

   This function is used in example 11.


File: plplotdoc.info,  Node: plmkstrm; Creates a new stream and makes it the default,  Next: plmtex; Write text relative to viewport boundaries,  Prev: plmeshc; Magnitude colored plot surface mesh with contour,  Up: The Common API for PLplot

18.78 plmkstrm: Creates a new stream and makes it the  default
==============================================================

     plmkstrm (p_strm);

   Creates a new stream and makes it the default.  Differs from using
`plsstrm' (*note plsstrm; Set current output stream::), in that a free
stream number is found, and returned.  Unfortunately, I _have_ to start
at stream 1 and work upward, since stream 0 is preallocated.  One of
the _big_ flaws in the PLplot API is that no initial, library-opening
call is required.  So stream 0 must be preallocated, and there is no
simple way of determining whether it is already in use or not.

`p_strm'  (`PLINT *', output)
     Pointer to stream number of the created stream.

   Redacted form: `plmkstrm(p_strm)'

   This function is used in examples 1,20.


File: plplotdoc.info,  Node: plmtex; Write text relative to viewport boundaries,  Next: plmtex3; Write text relative to viewport boundaries in 3D plots,  Prev: plmkstrm; Creates a new stream and makes it the default,  Up: The Common API for PLplot

18.79 plmtex: Write text relative to viewport boundaries
========================================================

     plmtex (side, disp, pos, just, text);

   Writes text at a specified position relative to the viewport
boundaries.  Text may be written inside or outside the viewport, but is
clipped at the subpage boundaries.  The reference point of a string
lies along a line passing through the string at half the height of a
capital letter.  The position of the reference point along this line is
determined by ``just'', and the position of the reference point
relative to the viewport is set by ``disp'' and ``pos''.

`side'  (`const char *', input)
     Specifies the side of the viewport along which the text is to be
     written. The string must be one of:

        * `b': Bottom of viewport, text written parallel to edge.

        * `bv': Bottom of viewport, text written at right angles to
          edge.

        * `l': Left of viewport, text written parallel to edge.

        * `lv': Left of viewport, text written at right angles to edge.

        * `r': Right of viewport, text written parallel to edge.

        * `rv': Right of viewport, text written at right angles to edge.

        * `t': Top of viewport, text written parallel to edge.

        * `tv': Top of viewport, text written at right angles to edge.

`disp'  (`PLFLT', input)
     Position of the reference point of string, measured outwards from
     the specified viewport edge in units of the current character
     height.  Use negative ``disp'' to write within the viewport.

`pos'  (`PLFLT', input)
     Position of the reference point of string along the specified
     edge, expressed as a fraction of the length of the edge.

`just'  (`PLFLT', input)
     Specifies the position of the string relative to its reference
     point.  If ``just'=0.', the reference point is at the left and if
     ``just'=1.', it is at the right of the string.  Other values of
     ``just'' give intermediate justifications.

`text'  (`const char *', input)
     The string to be written out.

   Redacted form:

   * General: `plmtex(side, disp, pos, just, text)'

   * Perl/PDL: `plmtex(disp, pos, just, side, text)'

   This function is used in examples 3,4,6-8,11,12,14,18,23,26.


File: plplotdoc.info,  Node: plmtex3; Write text relative to viewport boundaries in 3D plots,  Next: plot3d; Plot 3-d surface plot,  Prev: plmtex; Write text relative to viewport boundaries,  Up: The Common API for PLplot

18.80 plmtex3: Write text relative to viewport boundaries  in 3D plots
======================================================================

     plmtex3 (side, disp, pos, just, text);

   Writes text at a specified position relative to the viewport
boundaries.  Text may be written inside or outside the viewport, but is
clipped at the subpage boundaries.  The reference point of a string
lies along a line passing through the string at half the height of a
capital letter.  The position of the reference point along this line is
determined by ``just'', and the position of the reference point
relative to the viewport is set by ``disp'' and ``pos''.

`side'  (`const char *', input)
     Specifies the side of the viewport along which the text is to be
     written. The string should contain one or more of the following
     characters: `[xyz][ps][v]'.  Only one label is drawn at a time,
     i.e. `xyp' will only label the X axis, not both the X and Y axes.

        * `x': Label the X axis.

        * `y': Label the Y axis.

        * `z': Label the Z axis.

        * `p': Label the ‘primary’ axis. For Z this is the leftmost Z
          axis. For X it is the axis that starts at y-min. For Y it is
          the axis that starts at x-min.

        * `s': Label the ‘secondary’ axis.

        * `v': Draw the text perpendicular to the axis.

`disp'  (`PLFLT', input)
     Position of the reference point of string, measured outwards from
     the specified viewport edge in units of the current character
     height.  Use negative ``disp'' to write within the viewport.

`pos'  (`PLFLT', input)
     Position of the reference point of string along the specified
     edge, expressed as a fraction of the length of the edge.

`just'  (`PLFLT', input)
     Specifies the position of the string relative to its reference
     point.  If ``just'=0.', the reference point is at the left and if
     ``just'=1.', it is at the right of the string.  Other values of
     ``just'' give intermediate justifications.

`text'  (`const char *', input)
     The string to be written out.

   Redacted form: `plmtex3(side, disp, pos, just, text)'

   This function is used in example 28.


File: plplotdoc.info,  Node: plot3d; Plot 3-d surface plot,  Next: plot3dc; Magnitude colored plot surface with contour,  Prev: plmtex3; Write text relative to viewport boundaries in 3D plots,  Up: The Common API for PLplot

18.81 plot3d: Plot 3-d surface plot
===================================

     plot3d (x, y, z, nx, ny, opt, side);

   Plots a three dimensional surface plot within the environment set up
by `plw3d' (*note plw3d; Set up window for 3-d plotting::).  The
surface is defined by the two-dimensional array ``z'[`nx'][`ny']', the
point ``z'[i][j]' being the value of the function at `(`x'[i],
`y'[j])'.  Note that the points in arrays ``x'' and ``y'' do not need
to be equally spaced, but must be stored in ascending order.  The
parameter ``opt'' controls the way in which the surface is displayed.
For further details see *note Three Dimensional Surface Plots::.  The
only difference between `plmesh' (*note plmesh; Plot surface mesh::)
and `plot3d' (*note plot3d; Plot 3-d surface plot::) is that `plmesh'
(*note plmesh; Plot surface mesh::) draws the bottom side of the
surface, while `plot3d' (*note plot3d; Plot 3-d surface plot::) only
draws the surface as viewed from the top.

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`z'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array with set of function
     values.

`nx'  (`PLINT', input)
     Number of ``x'' values at which function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented:

        * ``opt'=DRAW_LINEX': Lines are drawn showing ``z'' as a
          function of ``x'' for each value of ``y'[j]'.

        * ``opt'=DRAW_LINEY': Lines are drawn showing ``z'' as a
          function of ``y'' for each value of ``x'[i]'.

        * ``opt'=DRAW_LINEXY': Network of lines is drawn connecting
          points at which function is defined.

`side'  (`PLBOOL', input)
     Flag to indicate whether or not "sides" should be draw on the
     figure.  If ``side'' is true sides are drawn, otherwise no sides
     are drawn.

   Redacted form: `plot3d(x, y, z, opt, side)'

   This function is used in examples 11,21.


File: plplotdoc.info,  Node: plot3dc; Magnitude colored plot surface with contour,  Next: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits,  Prev: plot3d; Plot 3-d surface plot,  Up: The Common API for PLplot

18.82 plot3dc: Magnitude colored plot surface with contour
==========================================================

     plot3dc (x, y, z, nx, ny, opt, clevel, nlevel);

   Aside from dropping the `side' functionality this is a more powerful
form of ``plot3d' (*note plot3d; Plot 3-d surface plot::)': the surface
mesh can be colored accordingly to the current z value being plotted, a
contour plot can be drawn at the base XY plane, and a curtain can be
drawn between the plotted function border and the base XY plane.  The
arguments are identical to those of ``plmeshc' (*note plmeshc;
Magnitude colored plot surface mesh with contour::)'. The only
difference between `plmeshc' (*note plmeshc; Magnitude colored plot
surface mesh with contour::) and `plot3dc' (*note plot3dc; Magnitude
colored plot surface with contour::) is that `plmeshc' (*note plmeshc;
Magnitude colored plot surface mesh with contour::) draws the bottom
side of the surface, while `plot3dc' (*note plot3dc; Magnitude colored
plot surface with contour::) only draws the surface as viewed from the
top.

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`z'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array with set of function
     values.

`nx'  (`PLINT', input)
     Number of ``x'' values at which function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented. To specify
     more than one option just add the options, e.g. DRAW_LINEXY +
     MAG_COLOR

        * ``opt'=DRAW_LINEX': Lines are drawn showing ``z'' as a
          function of ``x'' for each value of ``y'[j]'.

        * ``opt'=DRAW_LINEY': Lines are drawn showing ``z'' as a
          function of ``y'' for each value of ``x'[i]'.

        * ``opt'=DRAW_LINEXY': Network of lines is drawn connecting
          points at which function is defined.

        * ``opt'=MAG_COLOR': Each line in the mesh is colored according
          to the z value being plotted. The color is used from the
          current color map 1.

        * ``opt'=BASE_CONT': A contour plot is drawn at the base XY
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=DRAW_SIDES': draws a curtain between the base XY plane
          and the borders of the plotted function.

`clevel'  (`const PLFLT *', input)
     Pointer to the array that defines the contour level spacing.

`nlevel'  (`PLINT', input)
     Number of elements in the `clevel' array.

   Redacted form:

   * General: `plot3dc(x, y, z, opt, clevel)'

   * Perl/PDL: Not available?

   This function is used in example 21.


File: plplotdoc.info,  Node: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits,  Next: plparseopts; Parse command-line arguments,  Prev: plot3dc; Magnitude colored plot surface with contour,  Up: The Common API for PLplot

18.83 plot3dcl: Magnitude colored plot surface  with contour for z[x][y] with y index limits
============================================================================================

     plot3dcl (x, y, z, nx, ny, opt, clevel, nlevel, indexxmin,
     indexxmax, indexymin, indexymax);

   When the implementation is completed this variant of `plot3dc'
(*note plot3dc; Magnitude colored plot surface with contour::) (see
that function's documentation for more details) should be suitable for
the case where the area of the ``x'', ``y'' coordinate grid where ``z''
is defined can be non-rectangular. The implementation is incomplete so
the last 4 parameters of plot3dcl; ``indexxmin'', ``indexxmax'',
``indexymin'', and ``indexymax''; are currently ignored and the
functionality is otherwise identical to that of `plot3dc' (*note
plot3dc; Magnitude colored plot surface with contour::).

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`z'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array with set of function
     values.

`nx'  (`PLINT', input)
     Number of ``x'' values at which the function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which the function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented. To specify
     more than one option just add the options, e.g. DRAW_LINEXY +
     MAG_COLOR

        * ``opt'=DRAW_LINEX': Lines are drawn showing ``z'' as a
          function of ``x'' for each value of ``y'[j]'.

        * ``opt'=DRAW_LINEY': Lines are drawn showing ``z'' as a
          function of ``y'' for each value of ``x'[i]'.

        * ``opt'=DRAW_LINEXY': Network of lines is drawn connecting
          points at which function is defined.

        * ``opt'=MAG_COLOR': Each line in the mesh is colored according
          to the z value being plotted. The color is used from the
          current color map 1.

        * ``opt'=BASE_CONT': A contour plot is drawn at the base XY
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=DRAW_SIDES': draws a curtain between the base XY plane
          and the borders of the plotted function.

`clevel'  (`const PLFLT *', input)
     Pointer to the array that defines the contour level spacing.

`nlevel'  (`PLINT', input)
     Number of elements in the `clevel' array.

`indexxmin'  (`PLINT', input)
     The index value (which must be ≥ 0) that corresponds to the first
     ``x'' index where ``z'' is defined.

`indexxmax'  (`PLINT', input)
     The index value (which must be ≤ ``nx'') which corresponds (by
     convention) to one more than the last ``x'' index value where
     ``z'' is defined.

`indexymin'  (`const PLINT *', input)
     Array of ``y'' index values which all must be ≥ 0.  These values
     are the first ``y'' index where ``z'' is defined for a particular
     ``x'' index in the range from ``indexxmin'' to ``indexxmax - 1''.
     The dimension of ``indexymin'' is ``indexxmax''.

`indexymax'  (`const PLINT *', input)
     Array of ``y'' index values which all must be ≤ ``ny''.  These
     values correspond (by convention) to one more than the last ``y''
     index where ``z'' is defined for a particular ``x'' index in the
     range from ``indexxmin'' to ``indexxmax - 1''.  The dimension of
     ``indexymax'' is ``indexxmax''.

   Redacted form:

   * General: `plot3dcl(x, y, z, opt, clevel, indexxmin, indexymin,
     indexymax)'

   * Perl/PDL: Not available?

   This function is not used in any example.


File: plplotdoc.info,  Node: plparseopts; Parse command-line arguments,  Next: plpat; Set area fill pattern,  Prev: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits,  Up: The Common API for PLplot

18.84 plparseopts: Parse command-line arguments
===============================================

     int plparseopts (p_argc, argv, mode);

   Parse command-line arguments.

`p_argc'  (`int *', input)
     pointer to number of arguments.

`argv'  (`const char **', input)
     Pointer to character array containing ``*p_argc'' command-line
     arguments.

`mode'  (`PLINT', input)
     Parsing mode with the following possibilities:

        * PL_PARSE_FULL (1) - Full parsing of command line and all
          error messages enabled, including program exit when an error
          occurs.  Anything on the command line that isn't recognized
          as a valid option or option argument is flagged as an error.

        * PL_PARSE_QUIET (2) - Turns off all output except in the case
          of errors.

        * PL_PARSE_NODELETE (4) - Turns off deletion of processed
          arguments.

        * PL_PARSE_SHOWALL (8) - Show invisible options

        * PL_PARSE_NOPROGRAM (32) - Specified if argv[0] is NOT a
          pointer to the program name.

        * PL_PARSE_NODASH (64) - Set if leading dash is NOT required.

        * PL_PARSE_SKIP (128) - Set to quietly skip over any
          unrecognized arguments.

   `plparseopts' (*note plparseopts; Parse command-line arguments::)
removes all recognized flags (decreasing argc accordingly), so that
invalid input may be readily detected.  It can also be used to process
user command line flags.  The user can merge an option table of type
PLOptionTable into the internal option table info structure using
`plMergeOpts' (*note plMergeOpts; Merge use option table into internal
info structure_::).  Or, the user can specify that ONLY the external
table(s) be parsed by calling `plClearOpts' (*note plClearOpts; Clear
internal option table info structure_::) before `plMergeOpts' (*note
plMergeOpts; Merge use option table into internal info structure_::).

   The default action taken by `plparseopts' (*note plparseopts; Parse
command-line arguments::) is as follows:

Returns with an error if an unrecognized option or badly formed
option-value pair are encountered.
Returns immediately (return code 0) when the first non-option command
line argument is found.
Returns with the return code of the option handler, if one was called.
Deletes command line arguments from argv list as they are found, and
decrements argc accordingly.
Does not show "invisible" options in usage or help messages.
Assumes the program name is contained in argv[0].

   These behaviors may be controlled through the `mode' argument.

   Redacted form:

   * General: `plparseopts(argv, mode)'

   * Perl/PDL: Not available?

   This function is used in all of the examples.


File: plplotdoc.info,  Node: plpat; Set area fill pattern,  Next: plpath; Draw a line between two points; accounting for coordinate transforms,  Prev: plparseopts; Parse command-line arguments,  Up: The Common API for PLplot

18.85 plpat: Set area fill pattern
==================================

     plpat (nlin, inc, del);

   Sets 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.
(also see `plpsty' (*note plpsty; Select area fill pattern::))

`nlin'  (`PLINT', input)
     Number of sets of lines making up the pattern, either 1 or 2.

`inc'  (`const PLINT *', input)
     Pointer to array with ``nlin'' elements.  Specifies the line
     inclination in tenths of a degree.  (Should be between -900 and
     900).

`del'  (`const PLINT *', input)
     Pointer to array with ``nlin'' elements.  Specifies the spacing in
     micrometers between the lines making up the pattern.

   Redacted form:

   * General: `plpat(inc, del)'

   * Perl/PDL: `plpat(nlin, inc, del)'

   This function is used in example 15.


File: plplotdoc.info,  Node: plpath; Draw a line between two points; accounting for coordinate transforms,  Next: plpoin; Plot a glyph at the specified points,  Prev: plpat; Set area fill pattern,  Up: The Common API for PLplot

18.86 plpath: Draw a line between two points, accounting  for coordinate transforms
===================================================================================

     plpath (n, x1, y1, x2, y2);

   Joins the point `(`x1', `y1')' to `(`x2', `y2')'.  If a global
coordinate transform is defined then the line is broken in to ``n''
segments to approximate the path.  If no transform is defined then this
simply acts like a call to `pljoin' (*note pljoin; Draw a line between
two points::).

`n'  (`PLINT', input)
     number of points to use to approximate the path.

`x1'  (`PLFLT', input)
     x coordinate of first point.

`y1'  (`PLFLT', input)
     y coordinate of first point.

`x2'  (`PLFLT', input)
     x coordinate of second point.

`y2'  (`PLFLT', input)
     y coordinate of second point.

   Redacted form: `plpath(n,x1,y1,x2,y2)'

   This function is used in example 22.


File: plplotdoc.info,  Node: plpoin; Plot a glyph at the specified points,  Next: plpoin3; Plot a glyph at the specified 3D points,  Prev: plpath; Draw a line between two points; accounting for coordinate transforms,  Up: The Common API for PLplot

18.87 plpoin: Plot a glyph at the specified points
==================================================

     plpoin (n, x, y, code);

   Plot a glyph at the specified points.  (This function is largely
superseded by `plstring' (*note plstring; Plot a glyph at the specified
points::) which gives access to many[!] more glyphs.)  ``code'=-1'
means try to just draw a point.  Right now it's just a move and a draw
at the same place.  Not ideal, since a sufficiently intelligent output
device may optimize it away, or there may be faster ways of doing it.
This is OK for now, though, and offers a 4X speedup over drawing a
Hershey font "point" (which is actually diamond shaped and therefore
takes 4 strokes to draw).  If 0 < code < 32, then a useful (but small
subset) of Hershey symbols is plotted.  If 32 <= code <= 127 the
corresponding printable ASCII character is plotted.

`n'  (`PLINT', input)
     Number of points in the ``x'' and ``y'' arrays.

`x'  (`const PLFLT *', input)
     Pointer to an array with X coordinates of points.

`y'  (`const PLFLT *', input)
     Pointer to an array with Y coordinates of points.

`code'  (`PLINT', input)
     Hershey symbol code (in "ascii-indexed" form with -1 <= code <=
     127) corresponding to a glyph to be plotted at each of the ``n''
     points.

   Redacted form: `plpoin(x, y, code)'

   This function is used in examples 1,6,14,29.


File: plplotdoc.info,  Node: plpoin3; Plot a glyph at the specified 3D points,  Next: plpoly3; Draw a polygon in 3 space,  Prev: plpoin; Plot a glyph at the specified points,  Up: The Common API for PLplot

18.88 plpoin3: Plot a glyph at the specified 3D points
======================================================

     plpoin3 (n, x, y, z, code);

   Plot a glyph at the specified 3D points.  (This function is largely
superseded by `plstring3' (*note plstring3; Plot a glyph at the
specified 3D points::) which gives access to many[!] more glyphs.)  Set
up the call to this function similar to what is done for `plline3'
(*note plline3; Draw a line in 3 space::).  ``code'=-1' means try to
just draw a point.  Right now it's just a move and a draw at the same
place.  Not ideal, since a sufficiently intelligent output device may
optimize it away, or there may be faster ways of doing it.  This is OK
for now, though, and offers a 4X speedup over drawing a Hershey font
"point" (which is actually diamond shaped and therefore takes 4 strokes
to draw).  If 0 < code < 32, then a useful (but small subset) of
Hershey symbols is plotted.  If 32 <= code <= 127 the corresponding
printable ASCII character is plotted.

`n'  (`PLINT', input)
     Number of points in the ``x'' and ``y'' arrays.

`x'  (`const PLFLT *', input)
     Pointer to an array with X coordinates of points.

`y'  (`const PLFLT *', input)
     Pointer to an array with Y coordinates of points.

`z'  (`const PLFLT *', input)
     Pointer to an array with Z coordinates of points.

`code'  (`PLINT', input)
     Hershey symbol code (in "ascii-indexed" form with -1 <= code <=
     127) corresponding to a glyph to be plotted at each of the ``n''
     points.

   Redacted form: `plpoin3(x, y, z, code)'

   This function is not used in any example.


File: plplotdoc.info,  Node: plpoly3; Draw a polygon in 3 space,  Next: plprec; Set precision in numeric labels,  Prev: plpoin3; Plot a glyph at the specified 3D points,  Up: The Common API for PLplot

18.89 plpoly3: Draw a polygon in 3 space
========================================

     plpoly3 (n, x, y, z, draw, ifcc);

   Draws a polygon in 3 space defined by ``n'' points in ``x'', ``y'',
and ``z''.  Setup like `plline3' (*note plline3; Draw a line in 3
space::), but differs from that function in that `plpoly3' (*note
plpoly3; Draw a polygon in 3 space::) attempts to determine if the
polygon is viewable depending on the order of the points within the
arrays and the value of ``ifcc''.  If the back of polygon is facing the
viewer, then it isn't drawn.  If this isn't what you want, then use
`plline3' (*note plline3; Draw a line in 3 space::) instead.

   The points are assumed to be in a plane, and the directionality of
the plane is determined from the first three points.  Additional points
do not _have_ to lie on the plane defined by the first three, but if
they do not, then the determination of visibility obviously can't be
100% accurate... So if you're 3 space polygons are too far from planar,
consider breaking them into smaller polygons.  ‘3 points define a
plane’ :-).

   _Bugs_:  If one of the first two segments is of zero length, or if
they are co-linear, the calculation of visibility has a 50/50 chance of
being correct.  Avoid such situations :-).  See `x18c.c' for an example
of this problem.  (Search for ‘20.1’).

`n'  (`PLINT', input)
     Number of points defining line.

`x'  (`const PLFLT *', input)
     Pointer to array with x coordinates of points.

`y'  (`const PLFLT *', input)
     Pointer to array with y coordinates of points.

`z'  (`const PLFLT *', input)
     Pointer to array with z coordinates of points.

`draw'  (`const PLBOOL *', input)
     Pointer to array which controls drawing the segments of the
     polygon.  If ``draw[i]'' is true, then the polygon segment from
     index ``[i]'' to ``[i+1]'' is drawn, otherwise, not.

`ifcc'  (`PLBOOL', input)
     If ``ifcc'' is true the directionality of the polygon is
     determined by assuming the points are laid out in a
     counter-clockwise order.  Otherwise, the directionality of the
     polygon is determined by assuming the points are laid out in a
     clockwise order.

   Redacted form: `plpoly3(x, y, z, code)'

   This function is used in example 18.


File: plplotdoc.info,  Node: plprec; Set precision in numeric labels,  Next: plpsty; Select area fill pattern,  Prev: plpoly3; Draw a polygon in 3 space,  Up: The Common API for PLplot

18.90 plprec: Set precision in numeric labels
=============================================

     plprec (setp, prec);

   Sets the number of places after the decimal point in numeric labels.

`setp'  (`PLINT', input)
     If ``setp'' is equal to 0 then PLplot automatically determines the
     number of places to use after the decimal point in numeric labels
     (like those used to label axes).  If ``setp'' is 1 then ``prec''
     sets the number of places.

`prec'  (`PLINT', input)
     The number of characters to draw after the decimal point in
     numeric labels.

   Redacted form: `plprec(setp, prec)'

   This function is used in example 29.


File: plplotdoc.info,  Node: plpsty; Select area fill pattern,  Next: plptex; Write text inside the viewport,  Prev: plprec; Set precision in numeric labels,  Up: The Common API for PLplot

18.91 plpsty: Select area fill pattern
======================================

     plpsty (patt);

   Select one of eight predefined area fill patterns to use (also see
`plpat' (*note plpat; Set area fill pattern::)). Setting the fill style
to 0 gives a solid fill.

`patt'  (`PLINT', input)
     The desired pattern. Pattern 1 consists of horizontal lines,
     pattern 2 consists of vertical lines, pattern 3 consists of lines
     at 45 degrees angle (upward), and so on.

   Redacted form: `plpsty(patt)'

   This function is used in examples 12,13,15,16,25.


File: plplotdoc.info,  Node: plptex; Write text inside the viewport,  Next: plptex3; Write text inside the viewport of a 3D plot,  Prev: plpsty; Select area fill pattern,  Up: The Common API for PLplot

18.92 plptex: Write text inside the viewport
============================================

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

   Writes text at a specified position and inclination within the
viewport.  Text is clipped at the viewport boundaries.  The reference
point of a string lies along a line passing through the string at half
the height of a capital letter.  The position of the reference point
along this line is determined by ``just'', the reference point is
placed at world coordinates `(`x', `y')' within the viewport.  The
inclination of the string is specified in terms of differences of world
coordinates making it easy to write text parallel to a line in a graph.

`x'  (`PLFLT', input)
     x coordinate of reference point of string.

`y'  (`PLFLT', input)
     y coordinate of reference point of string.

`dx'  (`PLFLT', input)
     Together with ``dy'', this specifies the inclination of the
     string.  The baseline of the string is parallel to a line joining
     `(`x', `y')' to `(`x'+`dx', `y'+`dy')'.

`dy'  (`PLFLT', input)
     Together with ``dx'', this specifies the inclination of the string.

`just'  (`PLFLT', input)
     Specifies the position of the string relative to its reference
     point.  If ``just'=0.', the reference point is at the left and if
     ``just'=1.', it is at the right of the string.  Other values of
     ``just'' give intermediate justifications.

`text'  (`const char *', input)
     The string to be written out.

   Redacted form: `plptex(x, y, dx, dy, just, text)'

   This function is used in example 2-4,10,12-14,20,23,24,26.


File: plplotdoc.info,  Node: plptex3; Write text inside the viewport of a 3D plot,  Next: plrandd; Random number generator returning a real random number in the range [0;1],  Prev: plptex; Write text inside the viewport,  Up: The Common API for PLplot

18.93 plptex3: Write text inside the viewport of a 3D plot
==========================================================

     plptex3 (wx, wy, wz, dx, dy, dz, sx, sy, sz, just, text);

   Writes text at a specified position and inclination and with a
specified shear within the viewport.  Text is clipped at the viewport
boundaries.  The reference point of a string lies along a line passing
through the string at half the height of a capital letter.  The
position of the reference point along this line is determined by
``just'', and the reference point is placed at world coordinates
`(`wx', `wy', `wz')' within the viewport. The inclination and shear of
the string is specified in terms of differences of world coordinates
making it easy to write text parallel to a line in a graph.

`wx'  (`PLFLT', input)
     x world coordinate of reference point of string.

`wy'  (`PLFLT', input)
     y world coordinate of reference point of string.

`wz'  (`PLFLT', input)
     z world coordinate of reference point of string.

`dx'  (`PLFLT', input)
     Together with ``dy' and ` dz'', this specifies the inclination of
     the string.  The baseline of the string is parallel to a line
     joining `(`x', `y', `z')' to ` (`x'+`dx', `y'+`dy', `z'+`dz')'.

`dy'  (`PLFLT', input)
     Together with ``dx' and `dz'', this specifies the inclination of
     the string.

`dz'  (`PLFLT', input)
     Together with ``dx' and `dy'', this specifies the inclination of
     the string.

`sx'  (`PLFLT', input)
     Together with ``sy' and ` sz'', this specifies the shear of the
     string.  The string is sheared so that the characters are
     vertically parallel to a line joining ` (`x', `y', `z')' to `
     (`x'+`sx', `y'+`sy', `z'+`sz')'.  If ``sx' = `sy' = `sz' = 0.)'
     then the text is not sheared.

`sy'  (`PLFLT', input)
     Together with ``sx' and `sz'', this specifies shear of the string.

`sz'  (`PLFLT', input)
     Together with ``sx' and `sy'', this specifies shear of the string.

`just'  (`PLFLT', input)
     Specifies the position of the string relative to its reference
     point.  If ``just'=0.', the reference point is at the left and if
     ``just'=1.', it is at the right of the string.  Other values of
     ``just'' give intermediate justifications.

`text'  (`const char *', input)
     The string to be written out.

   Redacted form: `plptex3(x, y, z, dx, dy, dz, sx, sy, sz, just, text)'

   This function is used in example 28.


File: plplotdoc.info,  Node: plrandd; Random number generator returning a real random number in the range [0;1],  Next: plreplot; Replays contents of plot buffer to current device/file,  Prev: plptex3; Write text inside the viewport of a 3D plot,  Up: The Common API for PLplot

18.94 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]. The generator is based on the Mersenne Twister.  Most languages
/ compilers provide their own random number generator, and so this is
provided purely for convenience and to give a consistent random number
generator across all languages supported by PLplot. This is
particularly useful for comparing results from the test suite of
examples.

   Redacted form: `plrandd()'

   This function is used in examples 17,21.


File: plplotdoc.info,  Node: plreplot; Replays contents of plot buffer to current device/file,  Next: plrgbhls; Convert RGB color to HLS,  Prev: plrandd; Random number generator returning a real random number in the range [0;1],  Up: The Common API for PLplot

18.95 plreplot: Replays contents of plot buffer to  current device/file
=======================================================================

     plreplot ();

   Replays contents of plot buffer to current device/file.

   Redacted form: `plreplot()'

   This function is used in example 1,20.


File: plplotdoc.info,  Node: plrgbhls; Convert RGB color to HLS,  Next: plschr; Set character size,  Prev: plreplot; Replays contents of plot buffer to current device/file,  Up: The Common API for PLplot

18.96 plrgbhls: Convert RGB color to HLS
========================================

     plrgbhls (r, g, b, p_h, p_l, p_s);

   Convert RGB color coordinates to HLS

`r'  (`PLFLT', input)
     Red intensity (0.0-1.0) of the colour

`g'  (`PLFLT', input)
     Green intensity (0.0-1.0) of the colour

`b'  (`PLFLT', input)
     Blue intensity (0.0-1.0) of the colour

`p_h'  (`PLFLT *', output)
     Pointer to hue, in degrees on the colour cone (0.0-360.0)

`p_l'  (`PLFLT *', output)
     Pointer to lightness, expressed as a fraction of the axis of the
     colour cone (0.0-1.0)

`p_s'  (`PLFLT *', output)
     Pointer to saturation, expressed as a fraction of the radius of the
     colour cone (0.0-1.0)

   Redacted form:

   * General: `plrgbhls(r, g, b, p_h, p_l, p_s)'

   * Perl/PDL: Not available? Implemented as plrgb/plrgb1?

   This function is used in example 2.


File: plplotdoc.info,  Node: plschr; Set character size,  Next: plscmap0; Set cmap0 colors by 8-bit RGB values,  Prev: plrgbhls; Convert RGB color to HLS,  Up: The Common API for PLplot

18.97 plschr: Set character size
================================

     plschr (def, scale);

   This sets up the size of all subsequent characters drawn.  The actual
height of a character is the product of the default character size and
a scaling factor.

`def'  (`PLFLT', input)
     The default height of a character in millimeters, should be set to
     zero if the default height is to remain unchanged.

`scale'  (`PLFLT', input)
     Scale factor to be applied to default to get actual character
     height.

   Redacted form: `plschr(def, scale)'

   This function is used in example 2,13,23,24.


File: plplotdoc.info,  Node: plscmap0; Set cmap0 colors by 8-bit RGB values,  Next: plscmap0a; Set cmap0 colors by 8-bit RGB values and double alpha transparency value,  Prev: plschr; Set character size,  Up: The Common API for PLplot

18.98 plscmap0: Set cmap0 colors by 8-bit RGB values
====================================================

     plscmap0 (r, g, b, ncol0);

   Set cmap0 colors using 8-bit RGB values (see *note Color Map0::).
This sets the entire color map - only as many colors as specified will
be allocated.

`r'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of red in the color.

`g'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of green in the color.

`b'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of blue in the color.

`ncol0'  (`PLINT', input)
     Number of items in the ``r'', ``g'', and ``b'' arrays.

   Redacted form: `plscmap0(r, g, b)'

   This function is used in examples 2,24.


File: plplotdoc.info,  Node: plscmap0a; Set cmap0 colors by 8-bit RGB values and double alpha transparency value,  Next: plscmap0n; Set number of colors in cmap0,  Prev: plscmap0; Set cmap0 colors by 8-bit RGB values,  Up: The Common API for PLplot

18.99 plscmap0a: Set cmap0 colors by 8-bit RGB values and   double alpha transparency value
===========================================================================================

     plscmap0a (r, g, b, alpha, ncol0);

   Set cmap0 colors using 8-bit RGB values (see *note Color Map0::) and
floating point alpha transparency value.  This sets the entire color
map - only as many colors as specified will be allocated.

`r'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of red in the color.

`g'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of green in the color.

`b'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of blue in the color.

`alpha'  (`const PLFLT *', input)
     Pointer to array with set of PLFLT values (0.0 - 1.0) representing
     the alpha transparency of the color.

`ncol0'  (`PLINT', input)
     Number of items in the ``r'', ``g'', ``b'', and ``alpha'' arrays.

   Redacted form: `plscmap0a(r, g, b, alpha)'

   This function is used in examples 30.


File: plplotdoc.info,  Node: plscmap0n; Set number of colors in cmap0,  Next: plscmap1_range; Set the cmap1 argument range for continuous color plots,  Prev: plscmap0a; Set cmap0 colors by 8-bit RGB values and double alpha transparency value,  Up: The Common API for PLplot

18.100 plscmap0n: Set number of colors in cmap0
===============================================

     plscmap0n (ncol0);

   Set number of colors in color map0 (see *note Color Map0::).
Allocate (or reallocate) color map0, and fill with default values for
those colors not previously allocated.  The first 16 default colors are
given in the `plcol0' (*note plcol0; Set color; cmap0::) documentation.
For larger indices the default color is red.

   The drivers are not guaranteed to support more than 16 colors.

`ncol0'  (`PLINT', input)
     Number of colors that will be allocated in the map0 palette.  If
     this number is zero or less, then the value from the previous call
     to `plscmap0n' (*note plscmap0n; Set number of colors in cmap0::)
     is used and if there is no previous call, then a default value is
     used.

   Redacted form: `plscmap0n(ncol0)'

   This function is used in examples 15,16,24.


File: plplotdoc.info,  Node: plscmap1_range; Set the cmap1 argument range for continuous color plots,  Next: plscmap1; Set cmap1 colors using 8-bit RGB values,  Prev: plscmap0n; Set number of colors in cmap0,  Up: The Common API for PLplot

18.101 plscmap1_range: Set the cmap1 argument  range for continuous color plots
===============================================================================

     plscmap1_range (min_color, max_color);

   Set the cmap1 argument range for continuous color plots. If
`min_color' is greater than `max_color' or `max_color' is greater than
1.0 or `min_color' is less than 0.0 then no change is made.  (Use
`plgcmap1_range' (*note plgcmap1_range; Get the cmap1 argument range
for continuous color plots::) to get the cmap1 argument range.)

`min_color'  (`PLFLT', input)
     The minimum cmap1 floating point argument.

`max_color'  (`PLFLT', input)
     The maximum cmap1 floating point argument.

   Redacted form: `plscmap1_range(min_color, max_color)'

   This function is currently used in example 33.


File: plplotdoc.info,  Node: plscmap1; Set cmap1 colors using 8-bit RGB values,  Next: plscmap1a; Set cmap1 colors using 8-bit RGB values and double alpha transparency values,  Prev: plscmap1_range; Set the cmap1 argument range for continuous color plots,  Up: The Common API for PLplot

18.102 plscmap1: Set cmap1 colors using 8-bit RGB  values
=========================================================

     plscmap1 (r, g, b, ncol1);

   Set cmap1 colors using 8-bit RGB values (see *note Color Map1::).
This also sets the number of colors.

`r'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of red in the color.

`g'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of green in the color.

`b'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of blue in the color.

`ncol1'  (`PLINT', input)
     Number of items in the ``r'', ``g'', and ``b'' arrays.

   Redacted form: `plscmap1(r, g, b)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plscmap1a; Set cmap1 colors using 8-bit RGB values and double alpha transparency values,  Next: plscmap1l; Set cmap1 colors using a piece-wise linear relationship,  Prev: plscmap1; Set cmap1 colors using 8-bit RGB values,  Up: The Common API for PLplot

18.103 plscmap1a: Set cmap1 colors using 8-bit RGB values  and double alpha transparency values
===============================================================================================

     plscmap1a (r, g, b, alpha, ncol1);

   Set cmap1 colors using 8-bit RGB values (see *note Color Map1::) and
double alpha transparency values.  This also sets the number of colors.

`r'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of red in the color.

`g'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of green in the color.

`b'  (`const PLINT *', input)
     Pointer to array with set of unsigned 8-bit integers (0-255)
     representing the degree of blue in the color.

`alpha'  (`const PLFLT *', input)
     Pointer to array with set of double values (0.0-1.0) representing
     the alpha transparency value of the color.

`ncol1'  (`PLINT', input)
     Number of items in the ``r'', ``g'', ``b'', and ``alpha'' arrays.

   Redacted form: `plscmap1a(r, g, b, alpha)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plscmap1l; Set cmap1 colors using a piece-wise linear relationship,  Next: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship,  Prev: plscmap1a; Set cmap1 colors using 8-bit RGB values and double alpha transparency values,  Up: The Common API for PLplot

18.104 plscmap1l: Set cmap1 colors using a  piece-wise linear relationship
==========================================================================

     plscmap1l (itype, npts, intensity, coord1, coord2, coord3,
     alt_hue_path);

   Set cmap1 colors using a piece-wise linear relationship between
intensity index (from 0. to 1.) of cmap1 and position in HLS or RGB
color space (see *note Color Map1::).  May be called at any time.

   The idea here is to specify a number of control points that define
the mapping between input cmap1 intensity indices and HLS (or RGB).
Between these points, linear interpolation is used which gives a smooth
variation of color with intensity index.  Any number of control points
may be specified, located at arbitrary positions, although typically 2
- 4 are enough. Another way of stating this is that we are traversing a
given number of lines through HLS (or RGB) space as we move through
cmap1 intensity indices.  The control points at the minimum and maximum
position (0 and 1) must always be specified.  By adding more control
points you can get more variation.  One good technique for plotting
functions that vary about some expected average is to use an additional
2 control points in the center (position ~= 0.5) that are the same
lightness as the background (typically white for paper output, black
for crt), and same hue as the boundary control points.  This allows the
highs and lows to be very easily distinguished.

   Each control point must specify the cmap1 intensity index and the
associated three coordinates in HLS or RGB space.  The first point
_must_ correspond to position = 0, and the last to position = 1.

   The default behaviour is for the hue to be linearly interpolated
between the control points. Since the hue lies in the range [0, 360]
this corresponds to interpolation around the "front" of the color wheel
(red<->green<->blue<->red). If `alt_hue_path[i]' is true, then an
alternative interpolation is used between control points `i' and `i+1'.
If `hue[i+1]-hue[i] > 0' then interpolation is between `hue[i]' and
`hue[i+1] - 360', otherwise between `hue[i]' and `hue[i+1] + 360'.  You
can consider this as interpolation around the "back" or "reverse" of
the color wheel. Specifying `alt_hue_path=NULL' is equivalent to
setting `alt_hue_path[] = false' for every control point.

   * Examples of interpolation *

Hue                      alt_hue_path             color scheme
[120 240]                false                    green-cyan-blue
[240 120]                false                    blue-cyan-green
[120 240]                true                     green-yellow-red-magenta-blue
[240 120]                true                     blue-magenta-red-yellow-green

   * Bounds on coordinates*

RGB                R                  [0, 1]             magnitude
RGB                G                  [0, 1]             magnitude
RGB                B                  [0, 1]             magnitude
HLS                hue                [0, 360]           degrees
HLS                lightness          [0, 1]             magnitude
HLS                saturation         [0, 1]             magnitude

`itype'  (`PLBOOL', input)
     true: RGB, false: HLS.

`npts'  (`PLINT', input)
     number of control points

`intensity'  (`const PLFLT *', input)
     intensity index for each control point (between 0.0 and 1.0, in
     ascending order)

`coord1'  (`const PLFLT *', input)
     first coordinate (H or R) for each control point

`coord2'  (`const PLFLT *', input)
     second coordinate (L or G) for each control point

`coord3'  (`const PLFLT *', input)
     third coordinate (S or B) for each control point

`alt_hue_path'  (`const PLBOOL *', input)
     alternative interpolation method flag for each control point.
     (`alt_hue_path[i]' refers to the interpolation interval between
     the `i' and `i + 1' control points).

   Redacted form: `plscmap1l(itype, intensity, coord1, coord2, coord3,
alt_hue_path)'

   This function is used in examples 8,11,12,15,20,21.


File: plplotdoc.info,  Node: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship,  Next: plscmap1n; Set number of colors in cmap1,  Prev: plscmap1l; Set cmap1 colors using a piece-wise linear relationship,  Up: The Common API for PLplot

18.105 plscmap1la: Set cmap1 colors and alpha  transparency using a piece-wise linear relationship
==================================================================================================

     plscmap1la (itype, npts, intensity, coord1, coord2, coord3, alpha,
     alt_hue_path);

   This is a variant of `plscmap1l' (*note plscmap1l; Set cmap1 colors
using a piece-wise linear relationship::) that supports alpha channel
transparency. It sets cmap1 colors using a piece-wise linear
relationship between cmap1 intensity index (from 0. to 1.) and position
in HLS or RGB color space (see *note Color Map1::) with ``alpha''
transparency value (0.0 - 1.0). It may be called at any time.

`itype'  (`PLBOOL', input)
     true: RGB, false: HLS.

`npts'  (`PLINT', input)
     number of control points

`intensity'  (`const PLFLT *', input)
     position for each control point (between 0.0 and 1.0, in ascending
     order)

`coord1'  (`const PLFLT *', input)
     first coordinate (H or R) for each control point

`coord2'  (`const PLFLT *', input)
     second coordinate (L or G) for each control point

`coord3'  (`const PLFLT *', input)
     third coordinate (S or B) for each control point

`alpha'  (`const PLFLT *', input)
     the alpha transparency value for each control point

`alt_hue_path'  (`const PLBOOL *', input)
     alternative interpolation method flag for each control point.
     (`alt_hue_path[i]' refers to the interpolation interval between
     the `i' and `i + 1' control points).

   Redacted form: `plscmap1la(itype, intensity, coord1, coord2, coord3,
alpha, alt_hue_path)'

   This function is used in example 30.


File: plplotdoc.info,  Node: plscmap1n; Set number of colors in cmap1,  Next: plscol0; Set 8-bit RGB values for given cmap0 color index,  Prev: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship,  Up: The Common API for PLplot

18.106 plscmap1n: Set number of colors in cmap1
===============================================

     plscmap1n (ncol1);

   Set number of colors in cmap1, (re-)allocate color map1, and set
default values if this is the first allocation (see *note Color Map1::).

`ncol1'  (`PLINT', input)
     Number of colors that will be allocated in the map1 palette.  If
     this number is zero or less, then the value from the previous call
     to `plscmap1n' (*note plscmap1n; Set number of colors in cmap1::)
     is used and if there is no previous call, then a default value is
     used.

   Redacted form: `plscmap1n(ncol1)'

   This function is used in examples 8,11,20,21.


File: plplotdoc.info,  Node: plscol0; Set 8-bit RGB values for given cmap0 color index,  Next: plscol0a; Set 8-bit RGB values and double alpha transparency value for given cmap0 color index,  Prev: plscmap1n; Set number of colors in cmap1,  Up: The Common API for PLplot

18.107 plscol0: Set 8-bit RGB values for given  cmap0 color index
=================================================================

     plscol0 (icol0, r, g, b);

   Set 8-bit RGB values for given cmap0 (see *note Color Map0::) index.
Overwrites the previous color value for the given index and, thus, does
not result in any additional allocation of space for colors.

`icol0'  (`PLINT', input)
     Color index.  Must be less than the maximum number of colors
     (which is set by default, by `plscmap0n' (*note plscmap0n; Set
     number of colors in cmap0::), or even by `plscmap0' (*note
     plscmap0; Set cmap0 colors by 8-bit RGB values::)).

`r'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

`g'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

`b'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

   Redacted form: `plscol0(icol0, r, g, b)'

   This function is used in any example 31.


File: plplotdoc.info,  Node: plscol0a; Set 8-bit RGB values and double alpha transparency value for given cmap0 color index,  Next: plscolbg; Set the background color by 8-bit RGB value,  Prev: plscol0; Set 8-bit RGB values for given cmap0 color index,  Up: The Common API for PLplot

18.108 plscol0a: Set 8-bit   RGB values and double alpha transparency value for given  cmap0 color index
========================================================================================================

     plscol0a (icol0, r, g, b, alpha);

   Set 8-bit RGB value and double alpha transparency value for given
cmap0 (see *note Color Map0::) index.  Overwrites the previous color
value for the given index and, thus, does not result in any additional
allocation of space for colors.

`icol0'  (`PLINT', input)
     Color index.  Must be less than the maximum number of colors
     (which is set by default, by `plscmap0n' (*note plscmap0n; Set
     number of colors in cmap0::), or even by `plscmap0' (*note
     plscmap0; Set cmap0 colors by 8-bit RGB values::)).

`r'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

`g'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

`b'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

`alpha'  (`PLFLT', input)
     double value (0.0-1.0) representing the alpha transparency value
     of the color.

   This function is used in example 30.


File: plplotdoc.info,  Node: plscolbg; Set the background color by 8-bit RGB value,  Next: plscolbga; Set the background color by 8-bit RGB value and double alpha transparency value_,  Prev: plscol0a; Set 8-bit RGB values and double alpha transparency value for given cmap0 color index,  Up: The Common API for PLplot

18.109 plscolbg: Set the background color  by 8-bit RGB value
=============================================================

     plscolbg (r, g, b);

   Set the background color (color 0 in color map 0) by 8-bit RGB value
(see *note Color Map0::).

`r'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

`g'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

`b'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

   Redacted form: `plscolbg(r, g, b)'

   This function is used in examples 15,31.


File: plplotdoc.info,  Node: plscolbga; Set the background color by 8-bit RGB value and double alpha transparency value_,  Next: plscolor; Used to globally turn color output on/off,  Prev: plscolbg; Set the background color by 8-bit RGB value,  Up: The Common API for PLplot

18.110 plscolbga: Set the background color  by 8-bit RGB value and double alpha transparency value.
===================================================================================================

     plscolbga (r, g, b, alpha);

   Set the background color (color 0 in color map 0) by 8-bit RGB value
(see *note Color Map0::) and double alpha transparency value.

`r'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

`g'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

`b'  (`PLINT', input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

`alpha'  (`PLFLT', input)
     double value (0.0-1.0) representing the alpha transparency value
     of the color.

   This function is used in example 31.


File: plplotdoc.info,  Node: plscolor; Used to globally turn color output on/off,  Next: plscompression; Set device-compression level,  Prev: plscolbga; Set the background color by 8-bit RGB value and double alpha transparency value_,  Up: The Common API for PLplot

18.111 plscolor: Used to globally turn color output on/off
==========================================================

     plscolor (color);

   Used to globally turn color output on/off for those drivers/devices
that support it.

`color'  (`PLINT', input)
     Color flag (Boolean).  If zero, color is turned off.  If non-zero,
     color is turned on.

   Redacted form: `plscolor(color)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plscompression; Set device-compression level,  Next: plsdev; Set the device [keyword] name,  Prev: plscolor; Used to globally turn color output on/off,  Up: The Common API for PLplot

18.112 plscompression: Set device-compression level
===================================================

     plscompression (compression);

   Set device-compression level.  Only used for drivers that provide
compression.  This function, if used, should be invoked before a call
to `plinit' (*note plinit; Initialize PLplot::).

`compression'  (`PLINT', input)
     The desired compression level. This is a device-dependent value.
     Currently only the jpeg and png devices use these values. For jpeg
     value is the jpeg quality which should normally be in the range
     0-95.  Higher values denote higher quality and hence larger image
     sizes. For png values are in the range -1 to 99. Values of 0-9 are
     taken as the compression level for zlib. A value of -1 denotes the
     default zlib compression level. Values in the range 10-99 are
     divided by 10 and then used as the zlib compression level. Higher
     compression levels correspond to greater compression and small
     file sizes at the expense of more computation.

   Redacted form: `plscompression(compression)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plsdev; Set the device [keyword] name,  Next: plsdidev; Set parameters that define current device-space window,  Prev: plscompression; Set device-compression level,  Up: The Common API for PLplot

18.113 plsdev: Set the device (keyword) name
============================================

     plsdev (devname);

   Set the device (keyword) name.

`devname'  (`const char *', input)
     Pointer to device (keyword) name string.

   Redacted form: `plsdev(devname)'

   This function is used in examples 1,14,20.


File: plplotdoc.info,  Node: plsdidev; Set parameters that define current device-space window,  Next: plsdimap; Set up transformation from metafile coordinates,  Prev: plsdev; Set the device [keyword] name,  Up: The Common API for PLplot

18.114 plsdidev: Set parameters that define current  device-space window
========================================================================

     plsdidev (mar, aspect, jx, jy);

   Set relative margin width, aspect ratio, and relative justification
that define current device-space window.  If you want to just use the
previous value for any of these, just pass in the magic value
PL_NOTSET. It is unlikely that one should ever need to change the
aspect ratio but it's in there for completeness.  If `plsdidev' (*note
plsdidev; Set parameters that define current device-space window::) is
not called the default values of ``mar'', ``jx'', and ``jy'' are all 0.
``aspect'' is set to a device-specific value.

`mar'  (`PLFLT', input)
     Relative margin width.

`aspect'  (`PLFLT', input)
     Aspect ratio.

`jx'  (`PLFLT', input)
     Relative justification in x. Value must lie in the range -0.5 to
     0.5.

`jy'  (`PLFLT', input)
     Relative justification in y. Value must lie in the range -0.5 to
     0.5.

   Redacted form: `plsdidev(mar, aspect, jx, jy)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plsdimap; Set up transformation from metafile coordinates,  Next: plsdiori; Set plot orientation,  Prev: plsdidev; Set parameters that define current device-space window,  Up: The Common API for PLplot

18.115 plsdimap: Set up transformation from metafile  coordinates
=================================================================

     plsdimap (dimxmin, dimxmax, dimymin, dimymax, dimxpmm, dimypmm);

   Set up transformation from metafile coordinates.  The size of the
plot is scaled so as to preserve aspect ratio.  This isn't intended to
be a general-purpose facility just yet (not sure why the user would need
it, for one).

`dimxmin'  (`PLINT', input)
     NEEDS DOCUMENTATION

`dimxmax'  (`PLINT', input)
     NEEDS DOCUMENTATION

`dimymin'  (`PLINT', input)
     NEEDS DOCUMENTATION

`dimymax'  (`PLINT', input)
     NEEDS DOCUMENTATION

`dimxpmm'  (`PLFLT', input)
     NEEDS DOCUMENTATION

`dimypmm'  (`PLFLT', input)
     NEEDS DOCUMENTATION

   Redacted form: `plsdimap(dimxmin, dimxmax, dimymin, dimymax,
dimxpmm, dimypmm)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plsdiori; Set plot orientation,  Next: plsdiplt; Set parameters that define current plot-space window,  Prev: plsdimap; Set up transformation from metafile coordinates,  Up: The Common API for PLplot

18.116 plsdiori: Set plot orientation
=====================================

     plsdiori (rot);

   Set plot orientation parameter which is multiplied by 90 degrees to
obtain the angle of rotation.  Note, arbitrary rotation parameters such
as 0.2 (corresponding to 18 degrees) are possible, but the usual values
for the rotation parameter are 0., 1., 2., and 3. corresponding to 0
degrees (landscape mode), 90 degrees (portrait mode), 180 degrees
(seascape mode), and 270 degrees (upside-down mode).  If `plsdiori'
(*note plsdiori; Set plot orientation::) is not called the default
value of ``rot'' is 0.

   N.B. aspect ratio is unaffected by calls to `plsdiori' (*note
plsdiori; Set plot orientation::).  So you will probably want to change
the aspect ratio to a value suitable for the plot orientation using a
call to `plsdidev' (*note plsdidev; Set parameters that define current
device-space window::) or the command-line options ``-a'' or
``-freeaspect''.  For more documentation of those options see *note
Command Line Arguments::.  Such command-line options can be set
internally using `plsetopt' (*note plsetopt; Set any command-line
option::) or set directly using the command line and parsed using a
call to `plparseopts' (*note plparseopts; Parse command-line
arguments::).

`rot'  (`PLFLT', input)
     Plot orientation parameter.

   Redacted form: `plsdiori(rot)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plsdiplt; Set parameters that define current plot-space window,  Next: plsdiplz; Set parameters incrementally [zoom mode] that define current plot-space window,  Prev: plsdiori; Set plot orientation,  Up: The Common API for PLplot

18.117 plsdiplt: Set parameters that define current  plot-space window
======================================================================

     plsdiplt (xmin, ymin, xmax, ymax);

   Set relative minima and maxima that define the current plot-space
window.  If `plsdiplt' (*note plsdiplt; Set parameters that define
current plot-space window::) is not called the default values of
``xmin'', ``ymin'', ``xmax'', and ``ymax'' are 0., 0., 1., and 1.

`xmin'  (`PLFLT', input)
     Relative minimum in x.

`ymin'  (`PLFLT', input)
     Relative minimum in y.

`xmax'  (`PLFLT', input)
     Relative maximum in x.

`ymax'  (`PLFLT', input)
     Relative maximum in y.

   Redacted form: `plsdiplt(xmin, ymin, xmax, ymax)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plsdiplz; Set parameters incrementally [zoom mode] that define current plot-space window,  Next: plsdrawmode; Set drawing mode [depends on device support!],  Prev: plsdiplt; Set parameters that define current plot-space window,  Up: The Common API for PLplot

18.118 plsdiplz: Set parameters incrementally (zoom mode)  that define current plot-space window
================================================================================================

     plsdiplz (xmin, ymin, xmax, ymax);

   Set relative minima and maxima incrementally (zoom mode) that define
the current plot-space window.  This function has the same effect as
`plsdiplt' (*note plsdiplt; Set parameters that define current
plot-space window::) if that function has not been previously called.
Otherwise, this function implements zoom mode using the transformation
`min_used = old_min + old_length*min ' and `max_used = old_min +
old_length*max ' for each axis.  For example, if `min = 0.05' and `max
= 0.95' for each axis, repeated calls to `plsdiplz' (*note plsdiplz;
Set parameters incrementally [zoom mode] that define current plot-space
window::) will zoom in by 10 per cent for each call.

`xmin'  (`PLFLT', input)
     Relative (incremental) minimum in x.

`ymin'  (`PLFLT', input)
     Relative (incremental) minimum in y.

`xmax'  (`PLFLT', input)
     Relative (incremental) maximum in x.

`ymax'  (`PLFLT', input)
     Relative (incremental) maximum in y.

   Redacted form: `plsdiplz(xmin, ymin, xmax, ymax)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plsdrawmode; Set drawing mode [depends on device support!],  Next: plseed; Set seed for internal random number generator_,  Prev: plsdiplz; Set parameters incrementally [zoom mode] that define current plot-space window,  Up: The Common API for PLplot

18.119 plsdrawmode: Set drawing mode (depends on device support!)
=================================================================

     plsdrawmode (mode);

   Set drawing mode.  Note only one device driver (cairo) currently
supports this at the moment.  See also `plgdrawmode' (*note
plgdrawmode; Get drawing mode [depends on device support!]::).

`mode'  (`PLINT', input)
     Control variable which species the drawing mode (one of
     `PL_DRAWMODE_DEFAULT', `PL_DRAWMODE_REPLACE', or
     `PL_DRAWMODE_XOR') to use.

   Redacted form: `plsdrawmode(mode)'

   This function is used in example 34.


File: plplotdoc.info,  Node: plseed; Set seed for internal random number generator_,  Next: plsesc; Set the escape character for text strings,  Prev: plsdrawmode; Set drawing mode [depends on device support!],  Up: The Common API for PLplot

18.120 plseed: Set seed for internal random   number generator.
===============================================================

     plseed (seed);

   Set the seed for the internal random number generator. See `plrandd'
(*note plrandd; Random number generator returning a real random number
in the range [0;1]::) for further details.

`seed'  (`unsigned int', input)
     Seed for random number generator.

   Redacted form: `plseed(seed)'

   This function is used in example 21.


File: plplotdoc.info,  Node: plsesc; Set the escape character for text strings,  Next: plsetopt; Set any command-line option,  Prev: plseed; Set seed for internal random number generator_,  Up: The Common API for PLplot

18.121 plsesc: Set the escape character for text strings
========================================================

     plsesc (esc);

   Set the escape character for text strings.  From C (in contrast to
Fortran 95, see `plsescfortran95' (*note plsesc; Set the escape
character for text strings for Fortran 95::)) you pass ``esc'' as a
character.  Only selected characters are allowed to prevent the user
from shooting himself in the foot (For example, a ‘\’ isn't allowed
since it conflicts with C's use of backslash as a character escape).
Here are the allowed escape characters and their corresponding decimal
ASCII values:

   * ‘!’, ASCII 33

   * ‘#’, ASCII 35

   * ‘$’, ASCII 36

   * ‘%’, ASCII 37

   * ‘&’, ASCII 38

   * ‘*’, ASCII 42

   * ‘@’, ASCII 64

   * ‘^’, ASCII 94

   * ‘~’, ASCII 126

`esc'  (`char', input)
     Escape character.

   Redacted form:

   * General: `plsesc(esc)'

   * Perl/PDL: Not available?

   This function is used in example 29.


File: plplotdoc.info,  Node: plsetopt; Set any command-line option,  Next: plsfam; Set family file parameters,  Prev: plsesc; Set the escape character for text strings,  Up: The Common API for PLplot

18.122 plsetopt: Set any command-line option
============================================

     int plsetopt (opt, optarg);

   Set any command-line option internally from a program before it
invokes `plinit' (*note plinit; Initialize PLplot::). `opt' is the name
of the command-line option and `optarg' is the corresponding
command-line option argument.

`opt'  (`const char *', input)
     Pointer to string containing the command-line option.

`optarg'  (`const char *', input)
     Pointer to string containing the argument of the command-line
     option.

   This function returns 0 on success.

   Redacted form: `plsetopt(opt, optarg)'

   This function is used in example 14.


File: plplotdoc.info,  Node: plsfam; Set family file parameters,  Next: plsfci; Set FCI [font characterization integer],  Prev: plsetopt; Set any command-line option,  Up: The Common API for PLplot

18.123 plsfam: Set family file parameters
=========================================

     plsfam (fam, num, bmax);

   Sets variables dealing with output file familying.  Does nothing if
familying not supported by the driver.  This routine, if used, must be
called before initializing PLplot.  See *note Family File Output:: for
more information.

`fam'  (`PLINT', input)
     Family flag (Boolean).  If nonzero, familying is enabled.

`num'  (`PLINT', input)
     Current family file number.

`bmax'  (`PLINT', input)
     Maximum file size (in bytes) for a family file.

   Redacted form: `plsfam(fam, num, bmax)'

   This function is used in examples 14,31.


File: plplotdoc.info,  Node: plsfci; Set FCI [font characterization integer],  Next: plsfnam; Set output file name,  Prev: plsfam; Set family file parameters,  Up: The Common API for PLplot

18.124 plsfci: Set FCI (font characterization integer)
======================================================

     plsfci (fci);

   Sets font characteristics to be used at the start of the next string
using the FCI approach.  See *note FCI:: for more information.

`fci'  (`PLUNICODE', input)
     PLUNICODE (unsigned 32-bit integer) value of FCI.

   Redacted form:

   * General: `plsfci(fci)'

   * Perl/PDL: Not available?

   This function is used in example 23.


File: plplotdoc.info,  Node: plsfnam; Set output file name,  Next: plsfont; Set family; style and weight of the current font,  Prev: plsfci; Set FCI [font characterization integer],  Up: The Common API for PLplot

18.125 plsfnam: Set output file name
====================================

     plsfnam (fnam);

   Sets the current output file name, if applicable.  If the file name
has not been specified and is required by the driver, the user will be
prompted for it.  If using the X-windows output driver, this sets the
display name.  This routine, if used, must be called before
initializing PLplot.

`fnam'  (`const char *', input)
     Pointer to file name string.

   Redacted form: `plsfnam(fnam)'

   This function is used in examples 1,20.


File: plplotdoc.info,  Node: plsfont; Set family; style and weight of the current font,  Next: plshades; Shade regions on the basis of value,  Prev: plsfnam; Set output file name,  Up: The Common API for PLplot

18.126 plsfont: Set family, style and weight of the  current font
=================================================================

     plsfont (family, style, weight);

   Sets the current font.  See *note FCI:: for more information on font
selection.

`family'  (`PLINT', input)
     Font family to select for the current font. The available values
     are given by the PL_FCI_* constants in plplot.h. Current options
     are PL_FCI_SANS, PL_FCI_SERIF, PL_FCI_MONO, PL_FCI_SCRIPT and
     PL_FCI_SYMBOL. A negative value signifies that the font family
     should not be altered.

`style'  (`PLINT', input)
     Font style to select for the current font. The available values
     are given by the PL_FCI_* constants in plplot.h. Current options
     are PL_FCI_UPRIGHT, PL_FCI_ITALIC and PL_FCI_OBLIQUE. A negative
     value signifies that the font style should not be altered.

`weight'  (`PLINT', input)
     Font weight to select for the current font. The available values
     are given by the PL_FCI_* constants in plplot.h. Current options
     are PL_FCI_MEDIUM and PL_FCI_BOLD.  A negative value signifies
     that the font weight should not be altered.

   Redacted form: `plsfont(family, style, weight)'

   This function is used in example 23.


File: plplotdoc.info,  Node: plshades; Shade regions on the basis of value,  Next: plshade; Shade individual region on the basis of value,  Prev: plsfont; Set family; style and weight of the current font,  Up: The Common API for PLplot

18.127 plshades: Shade regions on the basis of value
====================================================

     plshades (a, nx, ny, defined, xmin, xmax, ymin, ymax, clevel,
     nlevel, fill_width, cont_color, cont_width, fill, rectangular,
     pltr, pltr_data);

   Shade regions on the basis of value.  This is the high-level routine
for making continuous color shaded plots with cmap1 while `plshade'
(*note plshade; Shade individual region on the basis of value::) (or
`plshade1' (*note plshade1; Shade individual region on the basis of
value::)) are used for individual shaded regions using either cmap0 or
cmap1.  `examples/c/x16c.c' shows a number of examples for using this
function.  See the following discussion of the arguments and *note
Contour and Shade Plots:: for more information.

`a'  (`const PLFLT * const *', input)
     Contains ** pointer to array to be plotted. The array must have
     been declared as PLFLT a[nx][ny].

`nx'  (`PLINT', input)
     First dimension of array "a".

`ny'  (`PLINT', input)
     Second dimension of array "a".

`defined'  (`PLINT (*) (PLFLT, PLFLT)', input)
     User function specifying regions excluded from the shading plot.
     This function accepts x and y coordinates as input arguments and
     must return 0 if the point is in the excluded region or 1
     otherwise. This argument can be NULL if all the values are valid.

`xmin'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`xmax'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`ymin'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`ymax'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`clevel'  (`const PLFLT *', input)
     Pointer to array containing the data levels corresponding to the
     edges of each shaded region that will be plotted by this function.
     To work properly the levels should be monotonic.

`nlevel'  (`PLINT', input)
     Number of shades plus 1 (i.e., the number of shade edge values in
     ``clevel'').

`fill_width'  (`PLFLT', input)
     Defines line width used by the fill pattern.

`cont_color'  (`PLINT', input)
     Defines pen color used for contours defining edges of shaded
     regions.  The pen color is only temporary set for the contour
     drawing.  Set this value to zero or less if no shade edge contours
     are wanted.

`cont_width'  (`PLFLT', input)
     Defines line width used for contours defining edges of shaded
     regions.  This value may not be honored by all drivers.  The pen
     width is only temporary set for the contour drawing.  Set this
     value to zero or less if no shade edge contours are wanted.

`fill'  (`void (*) (PLINT, const PLFLT *, const PLFLT *)', input)
     Routine used to fill the region.  Use `plfill' (*note plfill; Draw
     filled polygon::).  Future version of PLplot may have other fill
     routines.

`rectangular'  (`PLBOOL', input)
     Set ``rectangular'' to true if rectangles map to rectangles after
     coordinate transformation with ``pltrl''.  Otherwise, set
     ``rectangular'' to false.  If ``rectangular'' is set to true,
     plshade tries to save time by filling large rectangles.  This
     optimization fails if the coordinate transformation distorts the
     shape of rectangles.  For example a plot in polar coordinates has
     to have ``rectangular'' set to false.

`pltr'  (`void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)  ', input)
     Pointer to function that defines transformation between indices in
     array ``z'' and the world coordinates (C only).  Transformation
     functions are provided in the PLplot library: `pltr0' (*note
     pltr0; Identity transformation for grid to world mapping::) for
     identity mapping, and `pltr1' (*note pltr1; Linear interpolation
     for grid to world mapping using 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]::) for arbitrary
     mappings respectively defined by one- and two-dimensional arrays.
     In addition, user-supplied routines for the transformation can be
     used as well.  Examples of all of these approaches are given in
     *note Contour Plots from C::.  The transformation function should
     have the form given by any of `pltr0' (*note pltr0; Identity
     transformation for grid to world mapping::), `pltr1' (*note pltr1;
     Linear interpolation for grid to world mapping using singly
     dimensioned coordinate arrays::), or `pltr2' (*note pltr2; Linear
     interpolation for grid to world mapping using doubly dimensioned
     coordinate arrays [column dominant; as per normal C 2d arrays]::).

`pltr_data'  (`PLPointer', input)
     Extra parameter to help pass information to `pltr0' (*note pltr0;
     Identity transformation for grid to world mapping::), `pltr1'
     (*note pltr1; Linear interpolation for grid to world mapping using
     singly dimensioned coordinate arrays::), `pltr2' (*note pltr2;
     Linear interpolation for grid to world mapping using doubly
     dimensioned coordinate arrays [column dominant; as per normal C 2d
     arrays]::), or whatever routine that is externally supplied.

   Redacted form:

   * General: `plshades(a, defined, xmin, xmax, ymin, ymax, clevel,
     fill_width, cont_color, cont_width, fill, rectangular, pltr,
     pltr_data)'

   * Perl/PDL: `plshades(a, xmin, xmax, ymin, ymax, clevel, fill_width,
     cont_color, cont_width, fill, rectangular, defined, pltr,
     pltr_data)'

   This function is used in examples 16,21.


File: plplotdoc.info,  Node: plshade; Shade individual region on the basis of value,  Next: plshade1; Shade individual region on the basis of value,  Prev: plshades; Shade regions on the basis of value,  Up: The Common API for PLplot

18.128 plshade: Shade individual region on the basis of value
=============================================================

     plshade (a, nx, ny, defined, xmin, xmax, ymin, ymax, shade_min,
     shade_max, sh_cmap, sh_color, sh_width, min_color, min_width,
     max_color, max_width, fill, rectangular, pltr, pltr_data);

   Shade individual region on the basis of value.  Use `plshades'
(*note plshades; Shade regions on the basis of value::) if you want to
shade a number of regions using continuous colors.  `plshade' (*note
plshade; Shade individual region on the basis of value::) is identical
to `plshade1' (*note plshade1; Shade individual region on the basis of
value::) except for the type of the first parameter.  See `plshade1'
(*note plshade1; Shade individual region on the basis of value::) for
further discussion.

`a'  (`const PLFLT * const *', input)

`nx'  (`PLINT', input)

`ny'  (`PLINT', input)

`defined'  (`PLINT (*) (PLFLT, PLFLT)', input)

`xmin'  (`PLFLT', input)

`xmax'  (`PLFLT', input)

`ymin'  (`PLFLT', input)

`ymax'  (`PLFLT', input)

`shade_min'  (`PLFLT', input)

`shade_max'  (`PLFLT', input)

`sh_cmap'  (`PLINT', input)

`sh_color'  (`PLFLT', input)

`sh_width'  (`PLFLT', input)

`min_color'  (`PLINT', input)

`min_width'  (`PLFLT', input)

`max_color'  (`PLINT', input)

`max_width'  (`PLFLT', input)

`fill'  (`void (*) (PLINT, const PLFLT *, const PLFLT *)', input)

`rectangular'  (`PLBOOL', input)

`pltr'  (`void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)  ', input)

`pltr_data'  (`PLPointer', input)

   Redacted form:

   * General: `plshade(a, defined, xmin, xmax, ymin, ymax, shade_min,
     shade_max, sh_cmap, sh_color, sh_width, min_color, min_width,
     max_color, max_width, fill, rectangular, pltr, pltr_data)'

   * Perl/PDL: Not available?

   This function is used in example 15.


File: plplotdoc.info,  Node: plshade1; Shade individual region on the basis of value,  Next: plslabelfunc; Assign a function to use for generating custom axis labels,  Prev: plshade; Shade individual region on the basis of value,  Up: The Common API for PLplot

18.129 plshade1: Shade individual region on the basis of value
==============================================================

     plshade1 (a, nx, ny, defined, xmin, xmax, ymin, ymax, shade_min,
     shade_max, sh_cmap, sh_color, sh_width, min_color, min_width,
     max_color, max_width, fill, rectangular, pltr, pltr_data);

   Shade individual region on the basis of value.  Use `plshades'
(*note plshades; Shade regions on the basis of value::) if you want to
shade a number of contiguous regions using continuous colors.  In
particular the edge contours are treated properly in `plshades' (*note
plshades; Shade regions on the basis of value::).  If you attempt to do
contiguous regions with `plshade1' (*note plshade1; Shade individual
region on the basis of value::) (or `plshade' (*note plshade; Shade
individual region on the basis of value::)) the contours at the edge of
the shade are partially obliterated by subsequent plots of contiguous
shaded regions.  `plshade1' (*note plshade1; Shade individual region on
the basis of value::) differs from `plshade' (*note plshade; Shade
individual region on the basis of value::) by the type of the first
argument.  Look at the argument list below, `plcont' (*note plcont;
Contour plot::) and *note Contour and Shade Plots:: for more
information about the transformation from grid to world coordinates.
Shading NEEDS DOCUMENTATION, but as a stopgap look at how `plshade'
(*note plshade; Shade individual region on the basis of value::) is
used in `examples/c/x15c.c'

`a'  (`const PLFLT *', input)
     Contains array to be plotted. The array must have been declared as
     PLFLT a[nx][ny].

`nx'  (`PLINT', input)
     First dimension of array "a".

`ny'  (`PLINT', input)
     Second dimension of array "a".

`defined'  (`PLINT (*) (PLFLT, PLFLT)', input)
     User function specifying regions excluded from the shading plot.
     This function accepts x and y coordinates as input arguments and
     must return 0 if the point is in the excluded region or 1
     otherwise. This argument can be NULL if all the values are valid.

`xmin'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`xmax'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`ymin'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`ymax'  (`PLFLT', input)
     Defines the "grid" coordinates.  The data a[0][0] has a position
     of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so on.

`shade_min'  (`PLFLT', input)
     Defines the lower end of the interval to be shaded. If shade_max ≤
     shade_min, `plshade1' (*note plshade1; Shade individual region on
     the basis of value::) does nothing.

`shade_max'  (`PLFLT', input)
     Defines the upper end of the interval to be shaded. If shade_max ≤
     shade_min, `plshade1' (*note plshade1; Shade individual region on
     the basis of value::) does nothing.

`sh_cmap'  (`PLINT', input)
     Defines color map. If ``sh_cmap'=0', then ``sh_color'' is
     interpreted as a color map 0 (integer) index.  If ``sh_cmap'=1',
     then ``sh_color'' is interpreted as a color map 1 floating-point
     index which ranges from 0. to 1.

`sh_color'  (`PLFLT', input)
     Defines color map index if cmap0 or color map input value (ranging
     from 0. to 1.) if cmap1.

`sh_width'  (`PLFLT', input)
     Defines width used by the fill pattern.

`min_color'  (`PLINT', input)
     Defines pen color, width used by the boundary of shaded region.
     The min values are used for the shade_min boundary, and the max
     values are used on the shade_max boundary.  Set color and width to
     zero for no plotted boundaries.

`min_width'  (`PLFLT', input)
     Defines pen color, width used by the boundary of shaded region.
     The min values are used for the shade_min boundary, and the max
     values are used on the shade_max boundary.  Set color and width to
     zero for no plotted boundaries.

`max_color'  (`PLINT', input)
     Defines pen color, width used by the boundary of shaded region.
     The min values are used for the shade_min boundary, and the max
     values are used on the shade_max boundary.  Set color and width to
     zero for no plotted boundaries.

`max_width'  (`PLFLT', input)
     Defines pen color, width used by the boundary of shaded region.
     The min values are used for the shade_min boundary, and the max
     values are used on the shade_max boundary.  Set color and width to
     zero for no plotted boundaries.

`fill'  (`void (*) (PLINT, const PLFLT *, const PLFLT *)', input)
     Routine used to fill the region.  Use `plfill' (*note plfill; Draw
     filled polygon::).  Future version of plplot may have other fill
     routines.

`rectangular'  (`PLBOOL', input)
     Set ``rectangular'' to true if rectangles map to rectangles after
     coordinate transformation with ``pltrl''.  Otherwise, set
     ``rectangular'' to false.  If ``rectangular'' is set to true,
     plshade tries to save time by filling large rectangles.  This
     optimization fails if the coordinate transformation distorts the
     shape of rectangles.  For example a plot in polar coordinates has
     to have ``rectangular'' set to false.

`pltr'  (`void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)  ', input)
     Pointer to function that defines transformation between indices in
     array ``z'' and the world coordinates (C only).  Transformation
     functions are provided in the PLplot library: `pltr0' (*note
     pltr0; Identity transformation for grid to world mapping::) for
     identity mapping, and `pltr1' (*note pltr1; Linear interpolation
     for grid to world mapping using 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]::) for arbitrary
     mappings respectively defined by one- and two-dimensional arrays.
     In addition, user-supplied routines for the transformation can be
     used as well.  Examples of all of these approaches are given in
     *note Contour Plots from C::.  The transformation function should
     have the form given by any of `pltr0' (*note pltr0; Identity
     transformation for grid to world mapping::), `pltr1' (*note pltr1;
     Linear interpolation for grid to world mapping using singly
     dimensioned coordinate arrays::), or `pltr2' (*note pltr2; Linear
     interpolation for grid to world mapping using doubly dimensioned
     coordinate arrays [column dominant; as per normal C 2d arrays]::).

`pltr_data'  (`PLPointer', input)
     Extra parameter to help pass information to `pltr0' (*note pltr0;
     Identity transformation for grid to world mapping::), `pltr1'
     (*note pltr1; Linear interpolation for grid to world mapping using
     singly dimensioned coordinate arrays::), `pltr2' (*note pltr2;
     Linear interpolation for grid to world mapping using doubly
     dimensioned coordinate arrays [column dominant; as per normal C 2d
     arrays]::), or whatever routine that is externally supplied.

   Redacted form:

   * General: `plshade1(a, defined, xmin, xmax, ymin, ymax, shade_min,
     shade_max, sh_cmap, sh_color, sh_width, min_color, min_width,
     max_color, max_width, fill, rectangular, pltr, pltr_data)'

   * Perl/PDL: `plshade1(a, xmin, xmax, ymin, ymax, shade_min,
     shade_max, sh_cmap, sh_color, sh_width, min_color, min_width,
     max_color, max_width, fill, rectangular, defined, pltr, pltr_data)'

   This function is used in example 15.


File: plplotdoc.info,  Node: plslabelfunc; Assign a function to use for generating custom axis labels,  Next: plsmaj; Set length of major ticks,  Prev: plshade1; Shade individual region on the basis of value,  Up: The Common API for PLplot

18.130 plslabelfunc: Assign a function to use for generating custom axis labels
===============================================================================

     plslabelfunc (label_func, label_data);

   This function allows a user to provide their own function to provide
axis label text.  The user function is given the numeric value for a
point on an axis and returns a string label to correspond with that
value.  Custom axis labels can be enabled by passing appropriate
arguments to `plenv' (*note plenv; Set up standard window and draw
box::), `plbox' (*note plbox; Draw a box with axes; etc::), ` plbox3'
(*note plbox3; Draw a box with axes; etc; in 3-d::) and similar
functions.

`label_func'  (`void (*) (PLINT, PLFLT, char *, PLINT, PLPointer)', input)
     This is the custom label function.  In order to reset to the
     default labelling, set this to `NULL'.  The labelling function
     parameters are, in order:

    `axis'
          This indicates which axis a label is being requested for.
          The value will be one of `PL_X_AXIS', `PL_Y_AXIS' or
          `PL_Z_AXIS'.

    `value'
          This is the value along the axis which is being labelled.

    `label_text'
          The string representation of the label `value'.

    `length'
          The maximum length in characters allowed for `label_text'.

`label_data'  (`PLPointer', input)
     This parameter may be used to pass data to the `label_func'
     function.

   This function is used in example 19.


File: plplotdoc.info,  Node: plsmaj; Set length of major ticks,  Next: plsmem; Set the memory area to be plotted [RGB],  Prev: plslabelfunc; Assign a function to use for generating custom axis labels,  Up: The Common API for PLplot

18.131 plsmaj: Set length of major ticks
========================================

     plsmaj (def, scale);

   This sets up the length of the major ticks.  The actual length is the
product of the default length and a scaling factor as for character
height.

`def'  (`PLFLT', input)
     The default length of a major tick in millimeters, should be set
     to zero if the default length is to remain unchanged.

`scale'  (`PLFLT', input)
     Scale factor to be applied to default to get actual tick length.

   Redacted form: `plsmaj(def, scale)'

   This function is used in example 29.


File: plplotdoc.info,  Node: plsmem; Set the memory area to be plotted [RGB],  Next: plsmema; Set the memory area to be plotted [RGBA],  Prev: plsmaj; Set length of major ticks,  Up: The Common API for PLplot

18.132 plsmem: Set the memory area to be plotted (RGB)
======================================================

     plsmem (maxx, maxy, plotmem);

   Set the memory area to be plotted (with the ‘mem’ or ‘memcairo’
driver) as the `dev' member of the stream structure.  Also set the
number of pixels in the memory passed in `plotmem', which is a block of
memory `maxy' by `maxx' by 3 bytes long, say: 480 x 640 x 3 (Y, X, RGB)

   This memory will have to be freed by the user!

`maxx'  (`PLINT', input)
     Size of memory area in the X coordinate.

`maxy'  (`PLINT', input)
     Size of memory area in the Y coordinate.

`plotmem'  (`void *', input)
     Pointer to the beginning of the user-supplied memory area.

   Redacted form: `plsmem(maxx, maxy, plotmem)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plsmema; Set the memory area to be plotted [RGBA],  Next: plsmin; Set length of minor ticks,  Prev: plsmem; Set the memory area to be plotted [RGB],  Up: The Common API for PLplot

18.133 plsmema: Set the memory area to be plotted (RGBA)
========================================================

     plsmema (maxx, maxy, plotmem);

   Set the memory area to be plotted (with the ‘memcairo’ driver) as
the `dev' member of the stream structure.  Also set the number of
pixels in the memory passed in `plotmem', which is a block of memory
`maxy' by `maxx' by 4 bytes long, say: 480 x 640 x 4 (Y, X, RGBA)

   This memory will have to be freed by the user!

`maxx'  (`PLINT', input)
     Size of memory area in the X coordinate.

`maxy'  (`PLINT', input)
     Size of memory area in the Y coordinate.

`plotmem'  (`void *', input)
     Pointer to the beginning of the user-supplied memory area.

   Redacted form: `plsmema(maxx, maxy, plotmem)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plsmin; Set length of minor ticks,  Next: plsori; Set orientation,  Prev: plsmema; Set the memory area to be plotted [RGBA],  Up: The Common API for PLplot

18.134 plsmin: Set length of minor ticks
========================================

     plsmin (def, scale);

   This sets up the length of the minor ticks and the length of the
terminals on error bars.  The actual length is the product of the
default length and a scaling factor as for character height.

`def'  (`PLFLT', input)
     The default length of a minor tick in millimeters, should be set
     to zero if the default length is to remain unchanged.

`scale'  (`PLFLT', input)
     Scale factor to be applied to default to get actual tick length.

   Redacted form: `plsmin(def, scale)'

   This function is used in example 29.


File: plplotdoc.info,  Node: plsori; Set orientation,  Next: plspage; Set page parameters,  Prev: plsmin; Set length of minor ticks,  Up: The Common API for PLplot

18.135 plsori: Set orientation
==============================

     plsori (ori);

   Set integer plot orientation parameter.  This function is identical
to `plsdiori' (*note plsdiori; Set plot orientation::) except for the
type of the argument, and should be used in the same way.  See *note
plsdiori: Set plot orientation: plsdiori; Set plot orientation. for
details.

`ori'  (`PLINT', input)
     Orientation value (0 for landscape, 1 for portrait, etc.)  The
     value is multiplied by 90 degrees to get the angle.

   Redacted form: `plsori(ori)'

   This function is used in example 3.


File: plplotdoc.info,  Node: plspage; Set page parameters,  Next: plspal0; Set the colors for color table 0 from a cmap0 file,  Prev: plsori; Set orientation,  Up: The Common API for PLplot

18.136 plspage: Set page parameters
===================================

     plspage (xp, yp, xleng, yleng, xoff, yoff);

   Sets the page configuration (optional).  If an individual parameter
is zero then that parameter value is not updated.  Not all parameters
are recognized by all drivers and the interpretation is
device-dependent.  The X-window driver uses the length and offset
parameters to determine the window size and location.  The length and
offset values are expressed in units that are specific to the current
driver. For instance: screen drivers will usually interpret them as
number of pixels, whereas printer drivers will usually use mm.  This
routine, if used, must be called before initializing PLplot.

`xp'  (`PLFLT', input)
     Number of pixels/inch (DPI), x.

`yp'  (`PLFLT', input)
     Number of pixels/inch (DPI), y.

`xleng'  (`PLINT ', input)
     Page length, x.

`yleng'  (`PLINT', input)
     Page length, y.

`xoff'  (`PLINT', input)
     Page offset, x.

`yoff'  (`PLINT', input)
     Page offset, y.

   Redacted form: `plspage(xp, yp, xleng, yleng, xoff, yoff)'

   This function is used in examples 14 and 31.


File: plplotdoc.info,  Node: plspal0; Set the colors for color table 0 from a cmap0 file,  Next: plspal1; Set the palette for cmap1 using the specified cmap1*_pal format file,  Prev: plspage; Set page parameters,  Up: The Common API for PLplot

18.137 plspal0: Set the colors for color table 0  from a cmap0 file
===================================================================

     plspal0 (filename);

   Set the colors for color table 0 from a cmap0 file

`filename'  (`const char *', input)
     The name of the cmap0 file, or a empty to string to specify the
     default cmap0 file.

   Redacted form: `plspal0(filename)'

   This function is in example 16.


File: plplotdoc.info,  Node: plspal1; Set the palette for cmap1 using the specified cmap1*_pal format file,  Next: plspause; Set the pause [on end-of-page] status,  Prev: plspal0; Set the colors for color table 0 from a cmap0 file,  Up: The Common API for PLplot

18.138 plspal1: Set the palette for cmap1  using the specified cmap1*.pal format file
=====================================================================================

     plspal1 (filename, interpolate);

   Set the palette for cmap1 using the specified cmap1*.pal format file.

`filename'  (`const char *', input)
     The name of the cmap1*.pal file, or an empty string to specify the
     default cmap1.pal file.

`interpolate'  (`PLBOOL', input)
     If this parameter is true, the columns containing the intensity
     index, r, g, b, alpha and alt_hue_path in the cmap1*.pal file are
     used to set the cmap1 palette with a call to `plscmap1la' (*note
     plscmap1la; Set cmap1 colors and alpha transparency using a
     piece-wise linear relationship::).  (The cmap1*.pal header
     contains a flag which controls whether the r, g, b data sent to
     `plscmap1la' (*note plscmap1la; Set cmap1 colors and alpha
     transparency using a piece-wise linear relationship::) are
     interpreted as HLS or RGB.)

     If this parameter is false, the intensity index and alt_hue_path
     columns are ignored and the r, g, b (interpreted as RGB), and
     alpha columns of the cmap1*.pal file are used instead to set the
     cmap1 palette directly with a call to `plscmap1a' (*note
     plscmap1a; Set cmap1 colors using 8-bit RGB values and double
     alpha transparency values::).

   Redacted form: `plspal1(filename, interpolate)'

   This function is used in example 16.


File: plplotdoc.info,  Node: plspause; Set the pause [on end-of-page] status,  Next: plsstrm; Set current output stream,  Prev: plspal1; Set the palette for cmap1 using the specified cmap1*_pal format file,  Up: The Common API for PLplot

18.139 plspause: Set the pause (on end-of-page) status
======================================================

     plspause (pause);

   Set the pause (on end-of-page) status.

`pause'  (`PLBOOL', input)
     If ``pause'' is true there will be a pause on end-of-page for
     those drivers which support this.  Otherwise there is no pause.

   Redacted form: `plspause(pause)'

   This function is in examples 14,20.


File: plplotdoc.info,  Node: plsstrm; Set current output stream,  Next: plssub; Set the number of subpages in x and y,  Prev: plspause; Set the pause [on end-of-page] status,  Up: The Common API for PLplot

18.140 plsstrm: Set current output stream
=========================================

     plsstrm (strm);

   Sets the number of the current output stream.  The stream number
defaults to 0 unless changed by this routine.  The first use of this
routine must be followed by a call initializing PLplot (e.g. `plstar'
(*note plstar; Initialization::)).

`strm'  (`PLINT', input)
     The current stream number.

   Redacted form: `plsstrm(strm)'

   This function is examples 1,14,20.


File: plplotdoc.info,  Node: plssub; Set the number of subpages in x and y,  Next: plssym; Set symbol size,  Prev: plsstrm; Set current output stream,  Up: The Common API for PLplot

18.141 plssub: Set the number of subpages in x and y
====================================================

     plssub (nx, ny);

   Set the number of subpages in x and y.

`nx'  (`PLINT', input)
     Number of windows in x direction (i.e., number of window columns).

`ny'  (`PLINT', input)
     Number of windows in y direction (i.e., number of window rows).

   Redacted form: `plssub(nx, ny)'

   This function is examples 1,2,14,21,25,27.


File: plplotdoc.info,  Node: plssym; Set symbol size,  Next: plstar; Initialization,  Prev: plssub; Set the number of subpages in x and y,  Up: The Common API for PLplot

18.142 plssym: Set symbol size
==============================

     plssym (def, scale);

   This sets up the size of all subsequent symbols drawn by `plpoin'
(*note plpoin; Plot a glyph at the specified points::) and `plsym'
(*note plsym; Plot a glyph at the specified points::).  The actual
height of a symbol is the product of the default symbol size and a
scaling factor as for the character height.

`def'  (`PLFLT', input)
     The default height of a symbol in millimeters, should be set to
     zero if the default height is to remain unchanged.

`scale'  (`PLFLT', input)
     Scale factor to be applied to default to get actual symbol height.

   Redacted form: `plssym(def, scale)'

   This function is used in example 29.


File: plplotdoc.info,  Node: plstar; Initialization,  Next: plstart; Initialization,  Prev: plssym; Set symbol size,  Up: The Common API for PLplot

18.143 plstar: Initialization
=============================

     plstar (nx, ny);

   Initializing the plotting package.  The program prompts for the
device keyword or number of the desired output device.  Hitting a
RETURN in response to the prompt is the same as selecting the first
device.  If only one device is enabled when PLplot is installed,
`plstar' (*note plstar; Initialization::) will issue no prompt.  The
output device is divided into ``nx'' by ``ny'' subpages, each of which
may be used independently.  The subroutine `pladv' (*note pladv;
Advance the [sub-]page::) is used to advance from one subpage to the
next.

`nx'  (`PLINT', input)
     Number of subpages to divide output page in the horizontal
     direction.

`ny'  (`PLINT', input)
     Number of subpages to divide output page in the vertical direction.

   Redacted form: `plstar(nx, ny)'

   This function is used in example 1.


File: plplotdoc.info,  Node: plstart; Initialization,  Next: plstransform; Set a global coordinate transform function,  Prev: plstar; Initialization,  Up: The Common API for PLplot

18.144 plstart: Initialization
==============================

     plstart (devname, nx, ny);

   Alternative to `plstar' (*note plstar; Initialization::) for
initializing the plotting package.  The device name keyword for the
desired output device must be supplied as an argument.  These keywords
are the same as those printed out by `plstar' (*note plstar;
Initialization::).  If the requested device is not available, or if the
input string is empty or begins with "?", the prompted start up of
`plstar' (*note plstar; Initialization::) is used.  This routine also
divides the output device page into ``nx'' by ``ny'' subpages, each of
which may be used independently.  The subroutine `pladv' (*note pladv;
Advance the [sub-]page::) is used to advance from one subpage to the
next.

`devname'  (`const char *', input)
     Device name keyword of the required output device.  If NULL or if
     the first character is a "?", the normal (prompted) start up is
     used.

`nx'  (`PLINT', input)
     Number of subpages to divide output page in the horizontal
     direction.

`ny'  (`PLINT', input)
     Number of subpages to divide output page in the vertical direction.

   Redacted form:

   * General: `plstart(devname, nx, ny)'

   * Perl/PDL: `plstart(nx, ny, devname)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plstransform; Set a global coordinate transform function,  Next: plstring; Plot a glyph at the specified points,  Prev: plstart; Initialization,  Up: The Common API for PLplot

18.145 plstransform: Set a global coordinate transform  function
================================================================

     plstransform (coordinate_transform, coordinate_transform_data);

   This function can be used to define a coordinate transformation
which affects all elements drawn within the current plot window.  The
``coordinate_transform'' function is similar to that provided for the
`plmap' (*note plmap; Plot continental outline in world coordinates::)
and `plmeridians' (*note plmeridians; Plot latitude and longitude
lines::) functions.  The ``coordinate_transform_data'' parameter may be
used to pass extra data to ``coordinate_transform''.

`coordinate_transform'  (`void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)  ', input)
     Pointer to a function that defines a transformation from the input
     (x, y) coordinate to a new plot world coordinate. A NULL pointer
     means that no transform is applied.

`coordinate_transform_data'  (`PLPointer', input)
     Optional extra data for ``coordinate_transform''.

   Redacted form:

   * General: `plstransform(coordinate_transform,
     coordinate_transform_data)'

   This function is used in examples 19 and 22.


File: plplotdoc.info,  Node: plstring; Plot a glyph at the specified points,  Next: plstring3; Plot a glyph at the specified 3D points,  Prev: plstransform; Set a global coordinate transform function,  Up: The Common API for PLplot

18.146 plstring: Plot a glyph at the specified points
=====================================================

     plstring (n, x, y, string);

   Plot a glyph at the specified points. (Supersedes `plpoin' (*note
plpoin; Plot a glyph at the specified points::) and `plsym' (*note
plsym; Plot a glyph at the specified points::) because many[!] more
glyphs are accessible with `plstring' (*note plstring; Plot a glyph at
the specified points::).)  The glyph is specified with a PLplot user
string.  Note that the user string is not actually limited to one glyph
so it is possible (but not normally useful) to plot more than one glyph
at the specified points with this function.  As with `plmtex' (*note
plmtex; Write text relative to viewport boundaries::) and `plptex'
(*note plptex; Write text inside the viewport::), the user string can
contain FCI escapes to determine the font, UTF-8 code to determine the
glyph or else PLplot escapes for Hershey or unicode text to determine
the glyph.

`n'  (`PLINT', input)
     Number of points in the ``x'' and ``y'' arrays.

`x'  (`const PLFLT *', input)
     Pointer to an array with X coordinates of points.

`y'  (`const PLFLT *', input)
     Pointer to an array with Y coordinates of points.

`string'  (`const char *', input)
     PLplot user string corresponding to the glyph to be plotted at
     each of the ``n'' points.

   Redacted form: `plstring(x, y, string)'

   This function is used in examples 4, 21 and 26.


File: plplotdoc.info,  Node: plstring3; Plot a glyph at the specified 3D points,  Next: plstripa; Add a point to a strip chart,  Prev: plstring; Plot a glyph at the specified points,  Up: The Common API for PLplot

18.147 plstring3: Plot a glyph at the specified 3D points
=========================================================

     plstring3 (n, x, y, z, string);

   Plot a glyph at the specified 3D points. (Supersedes `plpoin3'
(*note plpoin3; Plot a glyph at the specified 3D points::) because
many[!] more glyphs are accessible with `plstring3' (*note plstring3;
Plot a glyph at the specified 3D points::).)  Set up the call to this
function similar to what is done for `plline3' (*note plline3; Draw a
line in 3 space::).  The glyph is specified with a PLplot user string.
Note that the user string is not actually limited to one glyph so it is
possible (but not normally useful) to plot more than one glyph at the
specified points with this function.  As with `plmtex' (*note plmtex;
Write text relative to viewport boundaries::) and `plptex' (*note
plptex; Write text inside the viewport::), the user string can contain
FCI escapes to determine the font, UTF-8 code to determine the glyph or
else PLplot escapes for Hershey or unicode text to determine the glyph.

`n'  (`PLINT', input)
     Number of points in the ``x'', ``y'', and ``z'' arrays.

`x'  (`const PLFLT *', input)
     Pointer to an array with X coordinates of points.

`y'  (`const PLFLT *', input)
     Pointer to an array with Y coordinates of points.

`z'  (`const PLFLT *', input)
     Pointer to an array with Z coordinates of points.

`string'  (`const char *', input)
     PLplot user string corresponding to the glyph to be plotted at
     each of the ``n'' points.

   Redacted form: `plstring3(x, y, z, string)'

   This function is used in example 18.


File: plplotdoc.info,  Node: plstripa; Add a point to a strip chart,  Next: plstripc; Create a 4-pen strip chart,  Prev: plstring3; Plot a glyph at the specified 3D points,  Up: The Common API for PLplot

18.148 plstripa: Add a point to a strip chart
=============================================

     plstripa (id, pen, x, y);

   Add a point to a given pen of a given strip chart.  There is no need
for all pens to have the same number of points or to be equally sampled
in the x coordinate.  Allocates memory and rescales as necessary.

`id'  (`PLINT', input)
     Identification number of the strip chart (set up in `plstripc'
     (*note plstripc; Create a 4-pen strip chart::)).

`pen'  (`PLINT', input)
     Pen number (ranges from 0 to 3).

`x'  (`PLFLT', input)
     X coordinate of point to plot.

`y'  (`PLFLT', input)
     Y coordinate of point to plot.

   Redacted form: `plstripa(id, pen, x, y)'

   This function is used in example 17.


File: plplotdoc.info,  Node: plstripc; Create a 4-pen strip chart,  Next: plstripd; Deletes and releases memory used by a strip chart,  Prev: plstripa; Add a point to a strip chart,  Up: The Common API for PLplot

18.149 plstripc: Create a 4-pen strip chart
===========================================

     plstripc (id, xspec, yspec, xmin, xmax, xjump, ymin, ymax, xlpos,
     ylpos, y_ascl, acc, colbox, collab, colline, styline, legline[],
     labx, laby, labtop);

   Create a 4-pen strip chart, to be used afterwards by `plstripa'
(*note plstripa; Add a point to a strip chart::)

`id'  (`PLINT *', output)
     Identification number of strip chart to use on `plstripa' (*note
     plstripa; Add a point to a strip chart::) and `plstripd' (*note
     plstripd; Deletes and releases memory used by a strip chart::).

`xspec'  (`const char *', input)
     X-axis specification as in `plbox' (*note plbox; Draw a box with
     axes; etc::).

`yspec'  (`const char *', input)
     Y-axis specification as in `plbox' (*note plbox; Draw a box with
     axes; etc::).

`xmin'  (`PLFLT', input)
     Initial coordinates of plot box; they will change as data are
     added.

`xmax'  (`PLFLT', input)
     Initial coordinates of plot box; they will change as data are
     added.

`xjump'  (`PLFLT', input)
     When x attains ``xmax'', the length of the plot is multiplied by
     the factor `(1 + `xjump')'.

`ymin'  (`PLFLT', input)
     Initial coordinates of plot box; they will change as data are
     added.

`ymax'  (`PLFLT', input)
     Initial coordinates of plot box; they will change as data are
     added.

`xlpos'  (`PLFLT', input)
     X legend box position (range from 0 to 1).

`ylpos'  (`PLFLT', input)
     Y legend box position (range from 0 to 1).

`y_ascl'  (`PLBOOL', input)
     Autoscale y between x jumps if ``y_ascl'' is true, otherwise not.

`acc'  (`PLBOOL', input)
     Accumulate strip plot if ``acc'' is true, otherwise slide display.

`colbox'  (`PLINT', input)
     Plot box color index (cmap0).

`collab'  (`PLINT', input)
     Legend color index (cmap0).

`colline'  (`const PLINT *', input)
     Pointer to array with color indices (cmap0) for the 4 pens.

`styline'  (`const PLINT *', input)
     Pointer to array with line styles for the 4 pens.

`legline'  (`const char **', input)
     Pointer to character array containing legends for the 4 pens.

`labx'  (`const char *', input)
     X-axis label.

`laby'  (`const char *', input)
     Y-axis label.

`labtop'  (`const char *', input)
     Plot title.

   Redacted form:

   * General: `plstripc(id, xspec, yspec, xmin, xmax, xjump, ymin,
     ymax, xlpos, ylpos, y_ascl, acc, colbox, collab, colline, styline,
     legline, labx, laby, labz)'

   * Perl/PDL: `plstripc(xmin, xmax, xjump, ymin, ymax, xlpos, ylpos,
     y_ascl, acc, colbox, collab, colline, styline, id, xspec, ypsec,
     legline, labx, laby, labtop)'

   This function is used in example 17.


File: plplotdoc.info,  Node: plstripd; Deletes and releases memory used by a strip chart,  Next: plstyl; Set line style,  Prev: plstripc; Create a 4-pen strip chart,  Up: The Common API for PLplot

18.150 plstripd: Deletes and releases memory used by a  strip chart
===================================================================

     plstripd (id);

   Deletes and releases memory used by a strip chart.

`id'  (`PLINT', input)
     Identification number of strip chart to delete.

   Redacted form: `plstripd(id)'

   This function is used in example 17.


File: plplotdoc.info,  Node: plstyl; Set line style,  Next: plsurf3d; Plot shaded 3-d surface plot,  Prev: plstripd; Deletes and releases memory used by a strip chart,  Up: The Common API for PLplot

18.151 plstyl: Set line style
=============================

     plstyl (nms, mark, space);

   This sets up the line style for all lines subsequently drawn.  A line
consists of segments in which the pen is alternately down and up.  The
lengths of these segments are passed in the arrays ``mark'' and
``space'' respectively.  The number of mark-space pairs is specified by
``nms''.  In order to return the line style to the default continuous
line, `plstyl' (*note plstyl; Set line style::) should be called with
``nms'=0'.(see also `pllsty' (*note pllsty; Select line style::))

`nms'  (`PLINT', input)
     The number of ``mark'' and ``space'' elements in a line.  Thus a
     simple broken line can be obtained by setting ``nms'=1'.  A
     continuous line is specified by setting ``nms'=0'.

`mark'  (`const PLINT *', input)
     Pointer to array with the lengths of the segments during which the
     pen is down, measured in micrometers.

`space'  (`const PLINT *', input)
     Pointer to array with the lengths of the segments during which the
     pen is up, measured in micrometers.

   Redacted form: `plstyl(mark, space)'

   This function is used in examples 1,9,14.


File: plplotdoc.info,  Node: plsurf3d; Plot shaded 3-d surface plot,  Next: plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits,  Prev: plstyl; Set line style,  Up: The Common API for PLplot

18.152 plsurf3d: Plot shaded 3-d surface plot
=============================================

     plsurf3d (x, y, z, nx, ny, opt, clevel, nlevel);

   Plots a three dimensional shaded surface plot within the environment
set up by `plw3d' (*note plw3d; Set up window for 3-d plotting::).  The
surface is defined by the two-dimensional array ``z'[`nx'][`ny']', the
point ``z'[i][j]' being the value of the function at `(`x'[i],
`y'[j])'.  Note that the points in arrays ``x'' and ``y'' do not need
to be equally spaced, but must be stored in ascending order.  For
further details see *note Three Dimensional Surface Plots::.

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`z'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array with set of function
     values.

`nx'  (`PLINT', input)
     Number of ``x'' values at which function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented. To specify
     more than one option just add the options, e.g. FACETED + SURF_CONT

        * ``opt'=FACETED': Network of lines is drawn connecting points
          at which function is defined.

        * ``opt'=BASE_CONT': A contour plot is drawn at the base XY
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=SURF_CONT': A contour plot is drawn at the surface
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=DRAW_SIDES': draws a curtain between the base XY plane
          and the borders of the plotted function.

        * ``opt'=MAG_COLOR': the surface is colored according to the
          value of Z; if `MAG_COLOR' is not used, then the default the
          surface is colored according to the intensity of the
          reflected light in the surface from a light source whose
          position is set using `pllightsource' (*note pllightsource;
          Sets the 3D position of the light source::).

`clevel'  (`const PLFLT *', input)
     Pointer to the array that defines the contour level spacing.

`nlevel'  (`PLINT', input)
     Number of elements in the `clevel' array.

   Redacted form: `plsurf3d(x, y, z, opt, clevel)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits,  Next: plfsurf3d; Plot shaded 3-d surface plot,  Prev: plsurf3d; Plot shaded 3-d surface plot,  Up: The Common API for PLplot

18.153 plsurf3dl: Plot shaded 3-d surface plot for  z[x][y] with y index limits
===============================================================================

     plsurf3dl (x, y, z, nx, ny, opt, clevel, nlevel, indexxmin,
     indexxmax, indexymin, indexymax);

   This variant of `plsurf3d' (*note plsurf3d; Plot shaded 3-d surface
plot::) (see that function's documentation for more details) should be
suitable for the case where the area of the ``x'', ``y'' coordinate
grid where ``z'' is defined can be non-rectangular.  The limits of that
grid are provided by the parameters ``indexxmin'', ``indexxmax'',
``indexymin'', and ``indexymax''.

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`z'  (`const PLFLT * const *', input)
     Pointer to a vectored two-dimensional array with set of function
     values.

`nx'  (`PLINT', input)
     Number of ``x'' values at which function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented. To specify
     more than one option just add the options, e.g. FACETED + SURF_CONT

        * ``opt'=FACETED': Network of lines is drawn connecting points
          at which function is defined.

        * ``opt'=BASE_CONT': A contour plot is drawn at the base XY
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=SURF_CONT': A contour plot is drawn at the surface
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=DRAW_SIDES': draws a curtain between the base XY plane
          and the borders of the plotted function.

        * ``opt'=MAG_COLOR': the surface is colored according to the
          value of Z; if `MAG_COLOR' is not used, then the default the
          surface is colored according to the intensity of the
          reflected light in the surface from a light source whose
          position is set using `pllightsource' (*note pllightsource;
          Sets the 3D position of the light source::).

`clevel'  (`const PLFLT *', input)
     Pointer to the array that defines the contour level spacing.

`nlevel'  (`PLINT', input)
     Number of elements in the `clevel' array.

`indexxmin'  (`PLINT', input)
     The index value (which must be ≥ 0) that corresponds to the first
     ``x'' index where ``z'' is defined.

`indexxmax'  (`PLINT', input)
     The index value (which must be ≤ ``nx'') which corresponds (by
     convention) to one more than the last ``x'' index value where
     ``z'' is defined.

`indexymin'  (`const PLINT *', input)
     Array of ``y'' index values which all must be ≥ 0.  These values
     are the first ``y'' index where ``z'' is defined for a particular
     ``x'' index in the range from ``indexxmin'' to ``indexxmax - 1''.
     The dimension of ``indexymin'' is ``indexxmax''.

`indexymax'  (`const PLINT *', input)
     Array of ``y'' index values which all must be ≤ ``ny''.  These
     values correspond (by convention) to one more than the last ``y''
     index where ``z'' is defined for a particular ``x'' index in the
     range from ``indexxmin'' to ``indexxmax - 1''.  The dimension of
     ``indexymax'' is ``indexxmax''.

   Redacted form: `plsurf3dl(x, y, z, opt, clevel, indexxmin,
indexymin, indexymax)'

   This function is not used in any examples.


File: plplotdoc.info,  Node: plfsurf3d; Plot shaded 3-d surface plot,  Next: plsvect; Set arrow style for vector plots,  Prev: plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits,  Up: The Common API for PLplot

18.154 plfsurf3d: Plot shaded 3-d surface plot
==============================================

     plfsurf3d (x, y, zops, zp, nx, ny, opt, clevel, nlevel);

   Plots a three dimensional shaded surface plot within the environment
set up by `plw3d' (*note plw3d; Set up window for 3-d plotting::). The
surface is defined by the data contained in the 2D `const PLFLT * const
*' matrix or the `PLfGrid2' structure ``zp''. How the data in ``zp'' is
rendered is determined by the ``zops'' parameter.  ``zops'' is a
pointer to a function that reads the data out of the grid structure.
The following functions in PLplot core will return an appropriate
function pointer: `plf2ops_c()' (use when ``zp'' is of type `const
PLFLT * const *'), `plf2ops_grid_c()' (use when ``zp'' is a pointer to
a row-major `PLfGrid2' structure), `plf2ops_grid_row_major()' (same as
`plf2ops_grid_c()'?) and `plf2ops_grid_col_major()' (use when ``zp'' is
a pointer to a column-major `PLfGrid2' structure).  ``nx'', ``ny''
``opt'' ``clevel'' and ``nlevel'' are the same as in for example
`plsurf3d' (*note plsurf3d; Plot shaded 3-d surface plot::).

`x'  (`const PLFLT *', input)
     Pointer to set of x coordinate values at which the function is
     evaluated.

`y'  (`const PLFLT *', input)
     Pointer to set of y coordinate values at which the function is
     evaluated.

`zops'  (`PLF2OPS', input)
     Pointer to a function for processing the data contained in zp.

`zp'  (`PLPointer', input)
     Pointer to the data to be plotted, either as a vectored
     two-dimensional array with set of function values or as a PLfGrid2
     structure.

`nx'  (`PLINT', input)
     Number of ``x'' values at which function is evaluated.

`ny'  (`PLINT', input)
     Number of ``y'' values at which function is evaluated.

`opt'  (`PLINT', input)
     Determines the way in which the surface is represented. To specify
     more than one option just add the options, e.g. FACETED + SURF_CONT

        * ``opt'=FACETED': Network of lines is drawn connecting points
          at which function is defined.

        * ``opt'=BASE_CONT': A contour plot is drawn at the base XY
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=SURF_CONT': A contour plot is drawn at the surface
          plane using parameters `nlevel' and `clevel'.

        * ``opt'=DRAW_SIDES': draws a curtain between the base XY plane
          and the borders of the plotted function.

        * ``opt'=MAG_COLOR': the surface is colored according to the
          value of Z; if `MAG_COLOR' is not used, then the default the
          surface is colored according to the intensity of the
          reflected light in the surface from a light source whose
          position is set using `pllightsource' (*note pllightsource;
          Sets the 3D position of the light source::).

`clevel'  (`const PLFLT *', input)
     Pointer to the array that defines the contour level spacing.

`nlevel'  (`PLINT', input)
     Number of elements in the `clevel' array.

   Redacted form? `plfsurf3d(x, y, zops, zp, opt, clevel)'

   This function is used in example 8.


File: plplotdoc.info,  Node: plsvect; Set arrow style for vector plots,  Next: plsvpa; Specify viewport in absolute coordinates,  Prev: plfsurf3d; Plot shaded 3-d surface plot,  Up: The Common API for PLplot

18.155 plsvect: Set arrow style for vector plots
================================================

     plsvect (arrowx, arrowy, npts, fill);

   Set the style for the arrow used by `plvect' (*note plvect; Vector
plot::) to plot vectors.

`arrowx, arrowy'  (`const PLFLT *',input)
     Pointers to a pair of arrays containing the x and y points which
     make up the arrow. The arrow is plotted by joining these points to
     form a polygon. The scaling assumes that the x and y points in the
     arrow lie in the range `-0.5 <= x,y <= 0.5'. If both ``arrowx'' and
     ``arrowy'' are NULL then the arrow style will be reset to its
     default.

`npts'  (`PLINT',input)
     Number of points in the arrays ``arrowx'' and ``arrowy''.

`fill'  (`PLBOOL',input)
     If ``fill'' is true then the arrow is closed, if ``fill'' is false
     then the arrow is open.

   Redacted form: `plsvect(arrowx, arrowy, fill)'

   This function is used in example 22.


File: plplotdoc.info,  Node: plsvpa; Specify viewport in absolute coordinates,  Next: plsxax; Set x axis parameters,  Prev: plsvect; Set arrow style for vector plots,  Up: The Common API for PLplot

18.156 plsvpa: Specify viewport in absolute coordinates
=======================================================

     plsvpa (xmin, xmax, ymin, ymax);

   Alternate routine to `plvpor' (*note plvpor; Specify viewport using
coordinates::) for setting up the viewport.  This routine should be
used only if the viewport is required to have a definite size in
millimeters.  The routine `plgspa' (*note plgspa; Get current subpage
parameters::) is useful for finding out the size of the current subpage.

`xmin'  (`PLFLT', input)
     The distance of the left-hand edge of the viewport from the
     left-hand edge of the subpage in millimeters.

`xmax'  (`PLFLT', input)
     The distance of the right-hand edge of the viewport from the
     left-hand edge of the subpage in millimeters.

`ymin'  (`PLFLT', input)
     The distance of the bottom edge of the viewport from the bottom
     edge of the subpage in millimeters.

`ymax'  (`PLFLT', input)
     The distance of the top edge of the viewport from the bottom edge
     of the subpage in millimeters.

   Redacted form: `plsvpa(xmin, xmax, ymin, ymax)'

   This function is used in example 10.


File: plplotdoc.info,  Node: plsxax; Set x axis parameters,  Next: plsyax; Set y axis parameters,  Prev: plsvpa; Specify viewport in absolute coordinates,  Up: The Common API for PLplot

18.157 plsxax: Set x axis parameters
====================================

     plsxax (digmax, digits);

   Sets values of the ``digmax'' and ``digits'' flags for the x axis.
See *note Annotating the Viewport:: for more information.

`digmax'  (`PLINT', input)
     Variable to set the maximum number of digits for the x axis.  If
     nonzero, the printed label will be switched to a floating point
     representation when the number of digits exceeds ``digmax''.

`digits'  (`PLINT', input)
     Field digits value.  Currently, changing its value here has no
     effect since it is set only by `plbox' (*note plbox; Draw a box
     with axes; etc::) or ` plbox3' (*note plbox3; Draw a box with
     axes; etc; in 3-d::).  However, the user may obtain its value
     after a call to either of these functions by calling `plgxax'
     (*note plgxax; Get x axis parameters::).

   Redacted form: `plsxax(digmax, digits)'

   This function is used in example 31.


File: plplotdoc.info,  Node: plsyax; Set y axis parameters,  Next: plsym; Plot a glyph at the specified points,  Prev: plsxax; Set x axis parameters,  Up: The Common API for PLplot

18.158 plsyax: Set y axis parameters
====================================

     plsyax (digmax, digits);

   Identical to `plsxax' (*note plsxax; Set x axis parameters::),
except that arguments are flags for y axis.  See the description of
`plsxax' (*note plsxax; Set x axis parameters::) for more detail.

`digmax'  (`PLINT', input)
     Variable to set the maximum number of digits for the y axis.  If
     nonzero, the printed label will be switched to a floating point
     representation when the number of digits exceeds ``digmax''.

`digits'  (`PLINT', input)
     Field digits value.  Currently, changing its value here has no
     effect since it is set only by `plbox' (*note plbox; Draw a box
     with axes; etc::) or ` plbox3' (*note plbox3; Draw a box with
     axes; etc; in 3-d::).  However, the user may obtain its value
     after a call to either of these functions by calling `plgyax'
     (*note plgyax; Get y axis parameters::).

   Redacted form: `plsyax(digmax, digits)'

   This function is used in examples 1,14,31.



Local Variables:
coding: utf-8
End:
