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