Chapter 19. The Common API for PLplot

Table of Contents
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
plarc: 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 page
plbox: Draw a box with axes, etc
plbox3: Draw a box with axes, etc, in 3-d
plcalc_world: Calculate world coordinates and corresponding window index from relative device coordinates
plclear: Clear current (sub)page
plcol0: Set color, map0
plcol1: Set color, map1
plcont: Contour plot
plcpstrm: Copy state parameters from the reference stream to 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 x error bar
plerry: Draw y error bar
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 character font
plfontld: Load character font
plgchr: Get character default height and current (scaled) height
plgcol0: Returns 8-bit RGB values for given color from color map0
plgcol0a: Returns 8-bit RGB values and double alpha value for given color from color map0.
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 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
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 color map1
plimage: Plot a 2D matrix using color map1 with automatic colour adjustment
plinit: Initialize PLplot
pljoin: Draw a line between two points
pllab: Simple routine to write labels
pllegend: Create a discrete annotated legend using 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 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.
plparseopts: Parse command-line arguments
plpat: Set area fill pattern
plpath: Draw a line between two points, accounting for coordinate transforms.
plpoin: Plots a character at the specified points
plpoin3: Plots a character at the specified points in 3 space
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 color map0 colors by 8-bit RGB values
plscmap0a: Set color map0 colors by 8-bit RGB values and double alpha value.
plscmap0n: Set number of colors in color map0
plscmap1: Set color map1 colors using 8-bit RGB values
plscmap1a: Set color map1 colors using 8-bit RGB values and double alpha values.
plscmap1l: Set color map1 colors using a piece-wise linear relationship
plscmap1la: Set color map1 colors using a piece-wise linear relationship
plscmap1n: Set number of colors in color map1
plscol0: Set a given color from color map0 by 8 bit RGB value
plscol0a: Set a given color from color map0 by 8 bit RGB value and double alpha value.
plscolbg: Set the background color by 8-bit RGB value
plscolbga: Set the background color by 8-bit RGB value and double alpha 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
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
plshade1: 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 colors for color table 0 from a cmap0 file
plspal1: Set the colors for color table 1 from a cmap1 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
plstripa: Add a point to a stripchart
plstripc: Create a 4-pen stripchart
plstripd: Deletes and releases memory used by a stripchart
plstyl: Set line style
plsurf3d: Plot shaded 3-d surface plot
plfsurf3d: Plot shaded 3-d surface plot
plsvect: Set arrow style for vector plots
plsvpa: Specify viewport in absolute coordinates
plsxax: Set x axis parameters
plsyax: Set y axis parameters
plsym: Plots a symbol 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 coordinates
plvsta: Select standard viewport
plw3d: Set up window for 3-d plotting
plwid: Set pen width
plwind: Specify world coordinates of viewport boundaries
plxormod: Enter or leave xor mode

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 current CVS HEAD with their arguments except for obsolete/deprecated API functions which are listed in Chapter 24. 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 Chapter 20 and subsequent chapters.

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

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.

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.