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.8.0 of PLplot, released on 2007-11-18.
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 plgdiori plscmap1n plClearOpts plgdiplt plscol0 plFindCommand plgesc plscolbg plFindName plgfam plscolor plFree2dGrid plgfci plscompression plGetCursor plgfile plsdev plGetFlt plgfnam plsdidev plGetInt plglevel plsdimap plGetName plgpage plsdiori plHLS_RGB plgra plsdiplt plMergeOpts plgriddata plsdiplz plMinMax2dGrid plgspa plseopH plOptUsage plgstrm plsesc plParseOpts plgver plsetopt plRGB_HLS plgvpd plsexit plResetOpts plgvpw plsfam plSetOpt plgxax plsfci plSetUsage plgyax plsfile plTranslateCursor plgzax plsfnam pl_cmd plhist plshade pl_setcontlabelformat plhls plshade1 pl_setcontlabelparam plhlsrgb plshades pladv plimage plsmaj plarrows plinit plsmem plaxes pljoin plsmin plbin pllab plsori plbop pllightsource plspage plbox plline plspause plbox3 plline3 plsstrm plcalc_world pllsty plssub plclear plmap plssym plcol0 plmeridians plstar plcol1 plmesh plstart plcont plmeshc plstr plcpstrm plmkstrm plstripa pldid2pc plmtex plstripc pldip2dc plmtex3 plstripd plend plot3d plstyl plend1 plot3dc plsurf3d plenv plot3dcl plsurf3dl plenv0 plparseopts plsvect pleop plpat plsvpa plerrx plpoin plsxax plerry plpoin3 plsxwin plf2eval plpoly3 plsyax plf2eval2 plprec plsym plf2evalr plpsty plszax plfamadv plptex pltext plfcont plptex3 pltr0 plfill plreplot pltr1 plfill3 plrgb pltr2 plflush plrgb1 pltr2p plfont plrgbhls plvasp plfontld plsButtonEH plvect plfshade plsError plvpas plgDevs plsKeyEH plvpor plgFileDevs plsabort plvsta plgchr plsbopH plw3d plgcol0 plschr plwid plgcolbg plscmap0 plwind plgcompression plscmap0n plxormod plgdev plscmap1 plgdidev 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 { 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; |