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