What is in the API?
Prev | Chapter 21. API compatibility definition | Next

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

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
    {
        PLCHAR_VECTOR opt;
        int ( *handler )( PLCHAR_VECTOR, PLCHAR_VECTOR, PLPointer );
        PLPointer     client_data;
        PLPointer     var;
        long          mode;
        PLCHAR_VECTOR syntax;
        PLCHAR_VECTOR 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_FE_POINTER f;
        PLINT            nx, ny, nz;
    } PLfGrid;

    typedef struct
    {
        PLFLT_NC_MATRIX f;
        PLINT           nx, ny;
    } PLfGrid2;

    typedef struct
    {
        PLFLT_NC_FE_POINTER xg, yg, zg;
        PLINT nx, ny, nz;
    } PLcGrid;

    typedef struct
    {
        PLFLT_NC_MATRIX 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)
        PLCHAR_VECTOR 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_NC_SCALAR zmin, PLFLT_NC_SCALAR 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;
        PLPointer buffer;
    } plbuffer;

Prev | Up | Next
Chapter 21. API compatibility definition | Home | Regression test for backwards compatibility