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 plgcmap1_range plscmap1l plClearOpts plgcol0 plscmap1la plFindCommand plgcol0a plscmap1n plFindName plgcolbg plscol0 plFree2dGrid plgcolbga plscol0a plGetCursor plgcompression plscolbg plGetFlt plgdev plscolbga plGetInt plgdidev plscolor plGetName plgdiori plscompression plMergeOpts plgdiplt plsdev plMinMax2dGrid plgdrawmode plsdidev plOptUsage plgesc plsdimap plResetOpts plgfam plsdiori plSetOpt 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 plstr plf2eval plmeshc plstransform plf2eval1 plmkstrm plstring plf2eval2 plmtex plstring3 plf2evalr plmtex3 plstripa plf2ops_c plot3d plstripc plf2ops_grid_c plot3dc plstripd plf2ops_grid_col_major plot3dcl plstyl plf2ops_grid_row_major plparseopts plsurf3d plfamadv plpat plsurf3dl plfcont plpath plsvect plfgriddata plpoin plsvpa plfill plpoin3 plsxax plfill3 plpoly3 plsxwin plfimage plprec plsyax plfimagefr plpsty plsym plflush plptex plszax plfmesh plptex3 pltext plfmeshc plrandd pltimefmt plfont plreplot pltr0 plfontld plrgbhls pltr1 plfplot3d plsButtonEH pltr2 plfplot3dc plsError pltr2f plfplot3dcl plsKeyEH pltr2p plfshade plsabort plvasp plfshade1 plsbopH plvect plfshades plschr plvpas plfsurf3d plscmap0 plvpor plfsurf3dl plscmap0a plvsta plfvect plscmap0n plw3d plgDevs plscmap1 plwid plgFileDevs plscmap1_range plwind plgchr plscmap1a plxormod |
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; |