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.7 of PLplot, released on 2010-10-03.
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:
labelform plgDevs plscmap1 mapform plgFileDevs plscmap1a plAlloc2dGrid plgchr 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 plHLS_RGB plgdiplt plsdev plMergeOpts plgesc plsdidev plMinMax2dGrid plget plsdimap plOptUsage plgfam plsdiori plParseOpts plgfci plsdiplt plRGB_HLS plgfile plsdiplz plResetOpts plgfnam plseed plSetOpt plgfont plseopH plSetUsage plglevel plsesc plTranslateCursor plgpage plset pl_cmd plgra plsetopt pl_setcontlabelformat plgradient plsexit pl_setcontlabelparam plgriddata plsfam pladv plgspa plsfci plarc plgstrm plsfile plarrows plgver plsfnam plaxes plgvpd plsfont plbin plgvpw plshade plbop plgxax plshade1 plbox plgyax plshades plbox3 plgzax plslabelfunc plbtime plhist plsmaj plcalc_world plhls plsmem plclear plhlsrgb plsmema plcol0 plimage plsmin plcol1 plimagefr plsori plconfigtime plinit plspage plcont pljoin plspal0 plcpstrm pllab plspal1 plctime pllegend plspause pldid2pc pllightsource plsstrm pldip2dc plline plssub plend plline3 plssym plend1 pllsty plstar plenv plmap plstart plenv0 plmeridians plstr pleop plmesh plstransform plerrx plmeshc plstripa plerry plmkstrm plstripc plf2eval plmtex plstripd plf2eval1 plmtex3 plstyl plf2eval2 plot3d plsurf3d plf2evalr plot3dc plsurf3dl plf2ops_c plot3dcl plsvect plf2ops_grid_c plparseopts plsvpa plf2ops_grid_col_major plpat plsxax plf2ops_grid_row_major plpath plsxwin plfamadv plpoin plsyax plfcont plpoin3 plsym plfgriddata plpoly3 plszax plfill plprec pltext plfill3 plpsty pltimefmt plfimage plptex pltr0 plfimagefr plptex3 pltr1 plflush plrandd pltr2 plfmesh plreplot pltr2f plfmeshc plrgb pltr2p plfont plrgb1 plvasp plfontld plrgbhls plvect plfplot3d plsButtonEH plvpas plfplot3dc plsError plvpor plfplot3dcl plsKeyEH plvsta plfshade plsabort plw3d plfshade1 plsbopH plwid plfshades plschr plwind plfsurf3d plscmap0 plxormod plfsurf3dl plscmap0a plfvect plscmap0n |
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 { PLINT attributeType; PLINT intValue; PLINT *intValues; PLFLT fltValue; PLFLT *fltValues; PLColor colorValue; PLColor *colorValues; PLINT nValues; } PLAttribute; 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; |