Chapter 21. API compatibility definition
Prev | Part IV. Reference | Next

## Chapter 21. API compatibility definition

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.10.0 of PLplot, released on 2014-02-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               plwidth
    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
    {
        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;

Prev | Up | Next
`plsesc`: Set the escape character for text strings for Fortran 95 | Home | Regression test for backwards compatibility