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

typedef struct
{
    size_t size;
    void   * buffer;
} plbuffer;