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.9 of PLplot, released on 2011-10-12.

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

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