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.7 of PLplot, released on 2010-10-03.

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:

labelform               plgDevs                 plscmap1
mapform                 plgFileDevs             plscmap1a
plAlloc2dGrid           plgchr                  plscmap1l
plClearOpts             plgcol0                 plscmap1la
plFindCommand           plgcol0a                plscmap1n
plFindName              plgcolbg                plscol0
plFree2dGrid            plgcolbga               plscol0a
plGetCursor             plgcompression          plscolbg
plGetFlt                plgdev                  plscolbga
plGetInt                plgdidev                plscolor
plGetName               plgdiori                plscompression
plHLS_RGB               plgdiplt                plsdev
plMergeOpts             plgesc                  plsdidev
plMinMax2dGrid          plget                   plsdimap
plOptUsage              plgfam                  plsdiori
plParseOpts             plgfci                  plsdiplt
plRGB_HLS               plgfile                 plsdiplz
plResetOpts             plgfnam                 plseed
plSetOpt                plgfont                 plseopH
plSetUsage              plglevel                plsesc
plTranslateCursor       plgpage                 plset
pl_cmd                  plgra                   plsetopt
pl_setcontlabelformat   plgradient              plsexit
pl_setcontlabelparam    plgriddata              plsfam
pladv                   plgspa                  plsfci
plarc                   plgstrm                 plsfile
plarrows                plgver                  plsfnam
plaxes                  plgvpd                  plsfont
plbin                   plgvpw                  plshade
plbop                   plgxax                  plshade1
plbox                   plgyax                  plshades
plbox3                  plgzax                  plslabelfunc
plbtime                 plhist                  plsmaj
plcalc_world            plhls                   plsmem
plclear                 plhlsrgb                plsmema
plcol0                  plimage                 plsmin
plcol1                  plimagefr               plsori
plconfigtime            plinit                  plspage
plcont                  pljoin                  plspal0
plcpstrm                pllab                   plspal1
plctime                 pllegend                plspause
pldid2pc                pllightsource           plsstrm
pldip2dc                plline                  plssub
plend                   plline3                 plssym
plend1                  pllsty                  plstar
plenv                   plmap                   plstart
plenv0                  plmeridians             plstr
pleop                   plmesh                  plstransform
plerrx                  plmeshc                 plstripa
plerry                  plmkstrm                plstripc
plf2eval                plmtex                  plstripd
plf2eval1               plmtex3                 plstyl
plf2eval2               plot3d                  plsurf3d
plf2evalr               plot3dc                 plsurf3dl
plf2ops_c               plot3dcl                plsvect
plf2ops_grid_c          plparseopts             plsvpa
plf2ops_grid_col_major  plpat                   plsxax
plf2ops_grid_row_major  plpath                  plsxwin
plfamadv                plpoin                  plsyax
plfcont                 plpoin3                 plsym
plfgriddata             plpoly3                 plszax
plfill                  plprec                  pltext
plfill3                 plpsty                  pltimefmt
plfimage                plptex                  pltr0
plfimagefr              plptex3                 pltr1
plflush                 plrandd                 pltr2
plfmesh                 plreplot                pltr2f
plfmeshc                plrgb                   pltr2p
plfont                  plrgb1                  plvasp
plfontld                plrgbhls                plvect
plfplot3d               plsButtonEH             plvpas
plfplot3dc              plsError                plvpor
plfplot3dcl             plsKeyEH                plvsta
plfshade                plsabort                plw3d
plfshade1               plsbopH                 plwid
plfshades               plschr                  plwind
plfsurf3d               plscmap0                plxormod
plfsurf3dl              plscmap0a               
plfvect                 plscmap0n               

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;

typedef struct
{
    PLFLT exp_label_disp;
    PLFLT exp_label_pos;
    PLFLT exp_label_just;
} PLLabelDefaults;

typedef struct
{
    PLINT   attributeType;
    PLINT   intValue;
    PLINT   *intValues;
    PLFLT   fltValue;
    PLFLT   *fltValues;
    PLColor colorValue;
    PLColor *colorValues;
    PLINT   nValues;
} PLAttribute;

typedef struct
{
    PLFLT ( *get )( PLPointer p, PLINT ix, PLINT iy );
    PLFLT ( *set )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
    PLFLT ( *add )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
    PLFLT ( *sub )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
    PLFLT ( *mul )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
    PLFLT ( *div )( PLPointer p, PLINT ix, PLINT iy, PLFLT z );
    PLINT ( *is_nan )( PLPointer p, PLINT ix, PLINT iy );
    void ( *minmax )( PLPointer p, PLINT nx, PLINT ny, PLFLT *zmim, PLFLT *zmax );
    /*
     * f2eval is backwards compatible signature for "f2eval" functions that
     * existed before plf2ops "operator function families" were used.
     */
    PLFLT ( *f2eval )( PLINT ix, PLINT iy, PLPointer p );
} plf2ops_t;