Chapter 23. 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.9.2 of PLplot, released on 2008-12-14.

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          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;