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.9.9 of PLplot, released on 2011-10-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 plgcol0 plscmap1la plClearOpts plgcol0a plscmap1n plFindCommand plgcolbg plscol0 plFindName plgcolbga plscol0a plFree2dGrid plgcompression plscolbg plGetCursor plgdev plscolbga plGetFlt plgdidev plscolor plGetInt plgdiori plscompression plGetName plgdiplt plsdev plMergeOpts plgdrawmode plsdidev plMinMax2dGrid plgesc plsdimap plOptUsage plgfam plsdiori plResetOpts plgfci plsdiplt plSetUsage plgfile plsdiplz plTranslateCursor plgfnam plsdrawmode pl_cmd plgfont plseed pl_setcontlabelformat plglevel plseopH pl_setcontlabelparam plgpage plsesc pladv plgra plsetopt plarc plgradient plsexit plaxes plgriddata plsfam plbin plgspa plsfci plbop plgstrm plsfile plbox plgver plsfnam plbox3 plgvpd plsfont plbtime plgvpw plshade plcalc_world plgxax plshade1 plclear plgyax plshades plcol0 plgzax plslabelfunc plcol1 plhist plsmaj plcolorbar plhlsrgb plsmem plconfigtime plimage plsmema plcont plimagefr plsmin plcpstrm plinit plsori plctime pljoin plspage pldid2pc pllab plspal0 pldip2dc pllegend plspal1 plend pllightsource plspause plend1 plline plsstrm plenv plline3 plssub plenv0 pllsty plssym pleop plmap plstar plerrx plmeridians plstart plerry plmesh plstransform plf2eval plmeshc plstring plf2eval1 plmkstrm plstring3 plf2eval2 plmtex plstripa plf2evalr plmtex3 plstripc plf2ops_c plot3d plstripd plf2ops_grid_c plot3dc plstyl plf2ops_grid_col_major plot3dcl plsurf3d plf2ops_grid_row_major plparseopts plsurf3dl plfamadv plpat plsvect plfcont plpath plsvpa plfgriddata plpoin plsxax plfill plpoin3 plsxwin plfill3 plpoly3 plsyax plfimage plprec plsym plfimagefr plpsty plszax plflush plptex pltext plfmesh plptex3 pltimefmt plfmeshc plrandd pltr0 plfont plreplot pltr1 plfontld plrgbhls pltr2 plfplot3d plsButtonEH pltr2f plfplot3dc plsError pltr2p plfplot3dcl plsKeyEH plvasp plfshade plsabort plvect plfshade1 plsbopH plvpas plfshades plschr plvpor plfsurf3d plscmap0 plvsta plfsurf3dl plscmap0a plw3d plfvect plscmap0n plwid plgDevs plscmap1 plwind plgFileDevs plscmap1_range plxormod plgchr plscmap1a plgcmap1_range 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 { 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 rev; // 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; |