Table of Contents
This chapter presents the formal definition of what is considered to be in the PLplot library API. It is assumed that major new releases of PLplot will have substantial backwards incompatible changes in the API, but the PLplot developers commit to introducing as few as possible of such incompatibilities between minor releases such that stability across those minor releases is practically guaranteed. In all cases where backwards incompatible changes have been introduced, then the library soname will be changed (for operating systems such as Linux that support versioned shared libraries).
The information in this chapter regards version 5.11.0 of PLplot, released on 2015-04-12.
The formal definition of the PLplot C API is everything that is defined
in the include file plplot.h
. This includes all
the function prototypes, the defined structures and the semantics of
the constants. The list of symbols currently exported by the shared
library libplplot.h
that are declared in
plplot.h
is the following:
plAlloc2dGrid plgcolbg plscmap1la plClearOpts plgcolbga plscmap1n plFindCommand plgcompression plscol0 plFindName plgdev plscol0a plFree2dGrid plgdidev plscolbg plGetCursor plgdiori plscolbga plGetFlt plgdiplt plscolor plGetInt plgdrawmode plscompression plGetName plgesc plsdev plMergeOpts plgfam plsdevdata plMinMax2dGrid plgfci plsdidev plOptUsage plgfile plsdimap plResetOpts plgfnam plsdiori plSetUsage plgfont plsdiplt plTranslateCursor plglevel plsdiplz pl_cmd plgpage plsdrawmode pl_setcontlabelformat plgra plseed pl_setcontlabelparam plgradient plseopH pladv plgriddata plsesc plarc plgspa plsetopt plaxes plgstrm plsexit plbin plgver plsfam plbop plgvpd plsfci plbox plgvpw plsfile plbox3 plgxax plsfnam plbtime plgyax plsfont plcalc_world plgzax plshade plclear plhist plshade1 plcol0 plhlsrgb plshades plcol1 plimage plslabelfunc plcolorbar plimagefr plsmaj plconfigtime plinit plsmem plcont pljoin plsmema plcpstrm pllab plsmin plctime pllegend plsori pldid2pc pllightsource plspage pldip2dc plline plspal0 plend plline3 plspal1 plend1 pllsty plspause plenv plmap plsstrm plenv0 plmapfill plssub pleop plmapline plssym plerrx plmapstring plstar plerry plmaptex plstart plf2eval plmeridians plstr plf2eval1 plmesh plstransform plf2eval2 plmeshc plstring plf2evalr plmkstrm plstring3 plf2ops_c plmtex plstripa plf2ops_grid_c plmtex3 plstripc plf2ops_grid_col_major plot3d plstripd plf2ops_grid_row_major plot3dc plstyl plfamadv plot3dcl plsurf3d plfcont plparseopts plsurf3dl plfgriddata plpat plsvect plfill plpath plsvpa plfill3 plpoin plsxax plfimage plpoin3 plsxwin plfimagefr plpoly3 plsyax plflush plprec plsym plfmesh plpsty plszax plfmeshc plptex pltext plfont plptex3 pltimefmt plfontld plrandd pltr0 plfplot3d plreplot pltr1 plfplot3dc plrgbhls pltr2 plfplot3dcl plsButtonEH pltr2f plfshade plsError pltr2p plfshade1 plsKeyEH plvasp plfshades plsabort plvect plfsurf3d plsbopH plvpas plfsurf3dl plschr plvpor plfvect plscmap0 plvsta plgDevs plscmap0a plw3d plgFileDevs plscmap0n plwidth plgchr plscmap1 plwind plgcmap1_range plscmap1_range plxormod plgcol0 plscmap1a plgcol0a plscmap1l
Another important aspect of compatibility regard the Application
Binary Interface (ABI). Backwards compatibility can be broken by
changes in the C structures made public through
plplot.h
. Currently, they are:
typedef struct { const char *opt; int ( *handler )( const char *, const char *, void * ); void *client_data; void *var; long mode; const char *syntax; const char *desc; } PLOptionTable; typedef struct { int type; // of event (CURRENTLY UNUSED) unsigned int state; // key or button mask unsigned int keysym; // key selected unsigned int button; // mouse button selected PLINT subwindow; // subwindow (alias subpage, alias subplot) number char string[PL_MAXKEY]; // translated string int pX, pY; // absolute device coordinates of pointer PLFLT dX, dY; // relative device coordinates of pointer PLFLT wX, wY; // world coordinates of pointer } PLGraphicsIn; typedef struct { PLFLT dxmi, dxma, dymi, dyma; // min, max window rel dev coords PLFLT wxmi, wxma, wymi, wyma; // min, max window world coords } PLWindow; typedef struct { unsigned int x, y; // upper left hand corner unsigned int width, height; // window dimensions } PLDisplay; typedef struct { const PLFLT *f; PLINT nx, ny, nz; } PLfGrid; typedef struct { PLFLT **f; PLINT nx, ny; } PLfGrid2; typedef struct { PLFLT *xg, *yg, *zg; PLINT nx, ny, nz; } PLcGrid; typedef struct { PLFLT **xg, **yg, **zg; PLINT nx, ny; } PLcGrid2; typedef struct { unsigned char r; // red unsigned char g; // green unsigned char b; // blue PLFLT a; // alpha (or transparency) const char *name; } PLColor; typedef struct { PLFLT h; // hue PLFLT l; // lightness PLFLT s; // saturation PLFLT p; // position PLFLT a; // alpha (or transparency) int alt_hue_path; // if set, interpolate through h=0 } PLControlPt; typedef struct { PLINT cmd; PLINT result; } PLBufferingCB; typedef struct { PLFLT exp_label_disp; PLFLT exp_label_pos; PLFLT exp_label_just; } PLLabelDefaults; typedef struct { PLFLT ( *get )( PLPointer p, PLINT ix, PLINT iy ); PLFLT ( *set )( PLPointer p, PLINT ix, PLINT iy, PLFLT z ); PLFLT ( *add )( PLPointer p, PLINT ix, PLINT iy, PLFLT z ); PLFLT ( *sub )( PLPointer p, PLINT ix, PLINT iy, PLFLT z ); PLFLT ( *mul )( PLPointer p, PLINT ix, PLINT iy, PLFLT z ); PLFLT ( *div )( PLPointer p, PLINT ix, PLINT iy, PLFLT z ); PLINT ( *is_nan )( PLPointer p, PLINT ix, PLINT iy ); void ( *minmax )( PLPointer p, PLINT nx, PLINT ny, PLFLT *zmim, PLFLT *zmax ); // // f2eval is backwards compatible signature for "f2eval" functions that // existed before plf2ops "operator function families" were used. // PLFLT ( *f2eval )( PLINT ix, PLINT iy, PLPointer p ); } plf2ops_t; typedef struct { size_t size; void * buffer; } plbuffer;