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