Chapter 21. API compatibility definition

Table of Contents
What is in the API?
Regression test for backwards compatibility

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.6.1 of PLplot, released on 2006-05-29.

What is in the API?

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          plgdidev               plscmap1n
plClearOpts            plgdiori               plscol0
plFindCommand          plgdiplt               plscolbg
plFindName             plgesc                 plscolor
plFree2dGrid           plgfam                 plscompression
plGetCursor            plgfci                 plsdev
plGetFlt               plgfile                plsdidev
plGetInt               plgfnam                plsdimap
plGetName              plglevel               plsdiori
plHLS_RGB              plgpage                plsdiplt
plMergeOpts            plgra                  plsdiplz
plMinMax2dGrid         plgriddata             plseopH
plOptUsage             plgspa                 plsesc
plParseOpts            plgstrm                plsetopt
plRGB_HLS              plgver                 plsexit
plResetOpts            plgvpd                 plsfam
plSetOpt               plgvpw                 plsfci
plSetUsage             plgxax                 plsfile
plTranslateCursor      plgyax                 plsfnam
pl_cmd                 plgzax                 plshade
pl_setcontlabelformat  plhist                 plshade1
pl_setcontlabelparam   plhls                  plshades
pladv                  plhlsrgb               plsmaj
plarrows               plimage                plsmem
plaxes                 plinit                 plsmin
plbin                  pljoin                 plsori
plbop                  pllab                  plspage
plbox                  pllightsource          plspause
plbox3                 plline                 plsstrm
plcalc_world           plline3                plssub
plclear                pllsty                 plssym
plcol0                 plmap                  plstar
plcol1                 plmeridians            plstart
plcont                 plmesh                 plstr
plcpstrm               plmeshc                plstripa
pldid2pc               plmkstrm               plstripc
pldip2dc               plmtex                 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                plreplot               pltr0
plfill                 plrgb                  pltr1
plfill3                plrgb1                 pltr2
plflush                plrgbhls               pltr2p
plfont                 plsButtonEH            plvasp
plfontld               plsError               plvect
plfshade               plsKeyEH               plvpas
plgDevs                plsabort               plvpor
plgFileDevs            plsbopH                plvsta
plgchr                 plschr                 plw3d
plgcol0                plscmap0               plwid
plgcolbg               plscmap0n              plwind
plgcompression         plscmap1               plxormod
plgdev                 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;