Table of Contents
pl_setcontlabelformat: Set
format of numerical label for contourspl_setcontlabelparam: Set parameters of
contour labelling other than format of numerical labelpladv: Advance the (sub-)pageplarc: Draw a circular or elliptical arc
plaxes: Draw a box with axes, etc. with arbitrary
origin
plbin: Plot a histogram from binned data
plbop: Begin a new pageplbox: Draw a box with axes, etcplbox3: Draw a box with axes, etc, in 3-d
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
plclear: Clear current (sub)page
plcol0: Set color, cmap0
plcol1: Set color, cmap1
plcolorbar: Plot color bar for image, shade or gradient plots
plconfigtime: Configure the transformation
between continuous and broken-down time for the current stream
plcont: Contour plot
plcpstrm: Copy state parameters from the
reference stream to the current stream
plctime: Calculate continuous time from
broken-down time for the current stream
plend: End plotting session
plend1: End plotting session for current stream
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
pleop: Eject current page
plerrx: Draw error bars in x direction
plerry: Draw error bars in the y direction
plfamadv: Advance to the next family file on the
next new page
plfill: Draw filled polygon
plfill3: Draw filled polygon in 3D
plflush: Flushes the output stream
plfont: Set font
plfontld: Load Hershey fonts
plGetCursor: Wait for graphics input event and translate to world coordinates.
plgchr: Get character default height and current
(scaled) height
plgcmap1_range: Get the cmap1 argument
range for continuous color plots
plgcol0: Returns 8-bit RGB values for given color
index from cmap0
plgcol0a: Returns 8-bit RGB values and PLFLT alpha
transparency value for given color index from cmap0
plgcolbg: Returns the background color
(cmap0[0]) by 8-bit RGB value
plgcolbga: Returns the background color (cmap0[0])
by 8-bit RGB value and PLFLT alpha transparency value
plgcompression: Get the current
device-compression setting
plgdev: Get the current device (keyword) name
plgdidev: Get parameters that define current
device-space window
plgdiori: Get plot orientation
plgdiplt: Get parameters that define current
plot-space window
plgdrawmode: Get drawing mode (depends on
device support!)
plgfam: Get family file parameters
plgfci: Get FCI (font characterization integer)
plgfnam: Get output file name
plgfont: Get family, style and weight of the
current font
plglevel: Get the (current) run level
plgpage: Get page parameters
plgra: Switch to graphics screen
plgradient: Draw linear gradient inside polygon
plgriddata: Grid data from irregularly sampled
data
plgspa: Get current subpage parameters
plgstrm: Get current stream number
plgver: Get the current library version number
plgvpd: Get viewport limits in normalized
device coordinates
plgvpw: Get viewport limits in world coordinates
plgxax: Get x axis parameters
plgyax: Get y axis parameters
plgzax: Get z axis parameters
plhist: Plot a histogram from unbinned data
plhlsrgb: Convert HLS color to RGB
plimagefr: Plot a 2D matrix using cmap1
plimage: Plot a 2D matrix using cmap1 with
automatic color adjustment
plinit: Initialize PLplot
pljoin: Draw a line between two points
pllab: Simple routine to write labels
pllegend: Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols
pllightsource: Sets the 3D position of the light
source
plline: Draw a line
plline3: Draw a line in 3 space
pllsty: Select line style
plmap: Plot continental outline or shapefile
data in world coordinates
plmapfill: Plot all or a subset of
Shapefile data, filling the polygons
plmapline: Plot all or a subset of
Shapefile data using lines in world coordinates
plmapstring: Plot all or a subset of
Shapefile data using strings or points in world coordinates
plmaptex: Draw text at points defined by
Shapefile data in world coordinates
plmeridians: Plot latitude and longitude lines
plmesh: Plot surface mesh
plmeshc: Magnitude colored plot surface mesh with contour
plmkstrm: Creates a new stream and makes it the
default
plmtex: Write text relative to viewport boundaries
plmtex3: Write text relative to viewport boundaries
in 3D plots
plot3d: Plot 3-d surface plot
plot3dc: Magnitude colored plot surface with contour
plot3dcl: Magnitude colored plot surface
with contour for z[x][y] with y index limits
plparseopts: Parse command-line arguments
plpat: Set area line fill pattern
plpath: Draw a line between two points, accounting
for coordinate transforms
plpoin: Plot a glyph at the specified points
plpoin3: Plot a glyph at the specified 3D points
plpoly3: Draw a polygon in 3 space
plprec: Set precision in numeric labels
plpsty: Select area fill pattern
plptex: Write text inside the viewport
plptex3: Write text inside the viewport of a 3D plot
plrandd: Random number generator
returning a real random number in the range [0,1]
plreplot: Replays contents of plot buffer to
current device/file
plrgbhls: Convert RGB color to HLS
plschr: Set character size
plscmap0: Set cmap0 colors by 8-bit RGB values
plscmap0a: Set cmap0 colors by 8-bit RGB values and
PLFLT alpha transparency value
plscmap0n: Set number of colors in cmap0
plscmap1_range: Set the cmap1 argument
range for continuous color plots
plscmap1: Set opaque RGB cmap1 colors
values
plscmap1a: Set semitransparent cmap1 RGBA colors.
plscmap1l: Set cmap1 colors 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
plscol0: Set 8-bit RGB values for given
cmap0 color index
plscol0a: Set 8-bit
RGB values and PLFLT alpha transparency value for given
cmap0 color index
plscolbg: Set the background color
by 8-bit RGB value
plscolbga: Set the background color
by 8-bit RGB value and PLFLT alpha transparency value.
plscolor: Used to globally turn color output on/off
plscompression: Set device-compression level
plsdev: Set the device (keyword) name
plsdidev: Set parameters that define current
device-space window
plsdimap: Set up transformation from metafile
coordinates
plsdiori: Set plot orientation
plsdiplt: Set parameters 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!)
plseed: Set seed for internal random
number generator.
plsesc: Set the escape character for text strings
plsetopt: Set any command-line option
plsfam: Set family file parameters
plsfci: Set FCI (font characterization integer)
plsfnam: Set output file name
plsfont: Set family, style and weight of the
current font
plshades: Shade regions on the basis of value
plshade: Shade individual region on the basis of value
plslabelfunc: Assign a function to use for generating custom axis labels
plsmaj: Set length of major ticks
plsmem: Set the memory area to be plotted (RGB)
plsmema: Set the memory area to be plotted (RGBA)
plsmin: Set length of minor ticks
plsori: Set orientation
plspage: Set page parameters
plspal0: Set the cmap0 palette using the
specified cmap0*.pal format file
plspal1: Set the cmap1 palette using the
specified cmap1*.pal format file
plspause: Set the pause (on end-of-page) status
plsstrm: Set current output stream
plssub: Set the number of subpages in x and y
plssym: Set symbol size
plstar: Initialization
plstart: Initialization
plstransform: Set a global coordinate transform
function
plstring: Plot a glyph at the specified points
plstring3: Plot a glyph at the specified 3D points
plstripa: Add a point to a strip chart
plstripc: Create a 4-pen strip chart
plstripd: Deletes and releases memory used by a
strip chart
plstyl: Set line style
plsurf3d: Plot shaded 3-d surface plot
plsurf3dl: Plot shaded 3-d surface plot for
z[x][y] with y index limits
plsvect: Set arrow style for vector plots
plsvpa: Specify viewport in absolute coordinates
plsxax: Set x axis parameters
plsyax: Set y axis parameters
plsym: Plot a glyph at the specified points
plszax: Set z axis parameters
pltext: Switch to text screen
pltimefmt: Set format for date / time labels
plvasp: Specify viewport using aspect ratio only
plvect: Vector plot
plvpas: Specify viewport using coordinates and aspect ratio
plvpor: Specify viewport using normalized subpage coordinates
plvsta: Select standard viewport
plw3d: Configure the transformations required for projecting a 3D surface on a 2D window
plwidth: Set pen width
plwind: Specify window
plxormod: Enter or leave xor mode
The purpose of this chapter is to document the common API for every PLplot function that should be available across all PLplot language bindings. Therefore, this chapter excludes obsolete/deprecated API functions which are listed in Chapter 21, Obsolete/Deprecated API for PLplot and also excludes API specialized for each language binding that is documented in Chapter 18, The Specialized C/C++ API for PLplot and subsequent chapters.
The common API constitutes the most important part of the PLplot API that programmers need to know.
For the C case, these common API routines have prototypes
defined in plplot.h using PLplot C types for arguments. The names
for these types have been chosen to be self-documenting. So
PLINT refers to the PLplot integer type, and
PLFLT refers to the PLplot floating-point type.
If the name has a _VECTOR or
_MATRIX suffix the type corresponds to the
one-dimensional or two-dimensional array argument type native to the
language being supported by PLplot. If the name does not have either
of those two suffixes or if it has a suffix of
_SCALAR, then it refers to a scalar quantity.
Finally, note that most of our common API arguments are input only and
are guaranteed not to be changed by the PLplot routine. However, in
some cases the argument is used for output quantities which
are changed by the PLplot routine, and in this
case we include _NC (standing for
"non-constant") in the argument type name.
We document our common API below for the C case, but it should be fairly straightforward to infer the corresponding API for any of our supported languages from these results because of the self-documenting names we use for the PLplot C types for arguments. Of course, the best way to learn how to use our common API for the language of your choice is to look at our standard set of examples. For additional language documentation you should consult the various chapters in Part III, “ Supported computer languages ” as well.
What follows is a list of all common API functions of the latest PLplot version. The following information is provided for each function:
The function name and a brief description.
The function as it would be called from C.
A complete description of the function.
A description of each argument that the function takes.
The redacted argument form of the function as well as any language specific variations that might occur on the general calling scheme described in the following paragraph.
A list of PLplot examples that demonstrate how to use the function.
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 );
Ada/standard: Draw_Curve( x, y );
Ada/traditional: plline( x, y );
C++: pls->line(n, x, y );
D: plline( x, y );
Fortran: plline( x, y )
Java: pls.line( x, y );
Lua: pl.line( x, y )
OCaml: plline x y;
Octave: plline( x', y' );
Python: plline( x, y )
Tcl/Tk: $w cmd plline x y
Note that in all our supported languages other than C and C++, the
argument nxy