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.3.0.rc2.5.3.1 of PLplot, released on 2004-06-17.

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