Chapter 19. 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.5.2 of PLplot, released on 2005-04-20.

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

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;