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