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.5.2 of PLplot, released on 2005-04-20.
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 plgdiplt plscol0 plClearOpts plgesc plscolbg plFindCommand plgfam plscolor plFindName plgfci plscompression plFree2dGrid plgfile plsdev plGetCursor plgfnam plsdidev plGetFlt plglevel plsdimap plGetInt plgpage plsdiori plGetName plgra plsdiplt plMergeOpts plgriddata plsdiplz plMinMax2dGrid plgspa plseopH plOptUsage plgstrm plsesc plResetOpts plgver plsetopt plSetOpt plgvpd plsexit plSetUsage plgvpw plsfam plTranslateCursor plgxax plsfci pl_cmd plgyax plsfile pl_setcontlabelformat plgzax plsfnam pl_setcontlabelparam plhist plshade pladv plhls plshade1 plarrows plhlsrgb plshades plaxes plimage plsmaj plbin plinit plsmem plbop pljoin plsmin plbox pllab plsori plbox3 pllightsource plspage plcalc_world plline plspause plclear plline3 plsstrm plcol0 pllsty plssub plcol1 plmap plssym plcont plmeridians plstar plcpstrm plmesh plstart pldid2pc plmeshc plstr pldip2dc plmkstrm plstripa plend plmtex plstripc plend1 plot3d plstripd plenv plot3dc plstyl plenv0 plot3dcl plsurf3d pleop plparseopts plsurf3dl plerrx plpat plsvect plerry plpoin plsvpa plf2eval plpoin3 plsxax plf2eval2 plpoly3 plsxwin plf2evalr plprec plsyax plfamadv plpsty plsym plfcont plptex plszax plfill plreplot pltext plfill3 plrgb pltr0 plflush plrgb1 pltr1 plfont plrgbhls pltr2 plfontld plsButtonEH pltr2p plfshade plsError plvasp plgDevs plsKeyEH plvect plgFileDevs plsabort plvpas plgchr plsbopH plvpor plgcol0 plschr plvsta plgcolbg plscmap0 plw3d plgcompression plscmap0n plwid plgdev plscmap1 plwind plgdidev plscmap1l plxormod plgdiori plscmap1n |
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 { char *opt; int (*handler) (char *, char *, void *); void *client_data; void *var; long mode; char *syntax; 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 */ char *name; } PLColor; typedef struct { PLFLT h; /* hue */ PLFLT l; /* lightness */ PLFLT s; /* saturation */ PLFLT p; /* position */ int rev; /* if set, interpolate through h=0 */ } PLControlPt; typedef struct { PLINT cmd; PLINT result; } PLBufferingCB; |