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.4 of PLplot, released on 2009-05-10.

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:

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