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.10.0 of PLplot, released on 2014-02-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 plscmap1a plClearOpts plgcolbga plscmap1l plFindCommand plgcompression plscmap1la plFindName plgdev plscmap1n plFree2dGrid plgdidev plscol0 plGetCursor plgdiori plscol0a plGetFlt plgdiplt plscolbg plGetInt plgdrawmode plscolbga plGetName plgesc plscolor plMergeOpts plgfam plscompression plMinMax2dGrid plgfci plsdev plOptUsage plgfile plsdidev plResetOpts plgfnam plsdimap plSetOpt plgfont plsdiori plSetUsage plglevel plsdiplt plTranslateCursor plgpage plsdiplz pl_cmd plgra plsdrawmode pl_setcontlabelformat plgradient plseed pl_setcontlabelparam plgriddata plseopH pladv plgspa plsesc plarc plgstrm plsetopt plaxes plgver plsexit plbin plgvpd plsfam plbop plgvpw plsfci plbox plgxax plsfile plbox3 plgyax plsfnam plbtime plgzax plsfont plcalc_world plhist plshade plclear plhls 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 plrgb pltr2 plfplot3dcl plrgb1 pltr2f plfshade plrgbhls pltr2p plfshade1 plsButtonEH plvasp plfshades plsError plvect plfsurf3d plsKeyEH plvpas plfsurf3dl plsabort plvpor plfvect plsbopH plvsta plgDevs plschr plw3d plgFileDevs plscmap0 plwid plgchr plscmap0a plwidth plgcmap1_range plscmap0n plwind plgcol0 plscmap1 plxormod plgcol0a plscmap1_range
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;