API compatibility definition

The PLplot Plotting Library: Programmer's Reference Manual
Prev |  | 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.8.0 of PLplot, released on 2007-11-18.

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

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