What is in the API?
Prev | Chapter 20. 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           plgcol0                 plscmap1_range
    plClearOpts             plgcol0a                plscmap1a
    plFindCommand           plgcolbg                plscmap1l
    plFindName              plgcolbga               plscmap1la
    plFree2dGrid            plgcompression          plscmap1n
    plGetCursor             plgdev                  plscol0
    plGetFlt                plgdidev                plscol0a
    plGetInt                plgdiori                plscolbg
    plGetName               plgdiplt                plscolbga
    plMergeOpts             plgdrawmode             plscolor
    plMinMax2dGrid          plgesc                  plscompression
    plOptUsage              plgfam                  plsdev
    plResetOpts             plgfci                  plsdevdata
    plSetUsage              plgfile                 plsdidev
    plStatic2dGrid          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                plshades
    plcolorbar              plimage                 plslabelfunc
    plconfigtime            plimagefr               plsmaj
    plcont                  plinit                  plsmem
    plcpstrm                pljoin                  plsmema
    plctime                 pllab                   plsmin
    pldid2pc                pllegend                plsori
    pldip2dc                pllightsource           plspage
    plend                   plline                  plspal0
    plend1                  plline3                 plspal1
    plenv                   pllsty                  plspause
    plenv0                  plmap                   plsstrm
    pleop                   plmapfill               plssub
    plerrx                  plmapline               plssym
    plerry                  plmapstring             plstar
    plf2eval                plmaptex                plstart
    plf2eval1               plmeridians             plstransform
    plf2eval2               plmesh                  plstring
    plf2evalr               plmeshc                 plstring3
    plf2ops_c               plmkstrm                plstripa
    plf2ops_grid_c          plmtex                  plstripc
    plf2ops_grid_col_major  plmtex3                 plstripd
    plf2ops_grid_row_major  plot3d                  plstyl
    plfamadv                plot3dc                 plsurf3d
    plfcont                 plot3dcl                plsurf3dl
    plfgriddata             plparseopts             plsvect
    plfill                  plpat                   plsvpa
    plfill3                 plpath                  plsxax
    plfimage                plpoin                  plsxwin
    plfimagefr              plpoin3                 plsyax
    plflush                 plpoly3                 plsym
    plfmesh                 plprec                  plszax
    plfmeshc                plpsty                  pltext
    plfont                  plptex                  pltimefmt
    plfontld                plptex3                 pltr0
    plfplot3d               plrandd                 pltr1
    plfplot3dc              plreplot                pltr2
    plfplot3dcl             plrgbhls                pltr2f
    plfshade                plsButtonEH             pltr2p
    plfshade1               plsError                plvasp
    plfshades               plsKeyEH                plvect
    plfsurf3d               plsabort                plvpas
    plfsurf3dl              plsbopH                 plvpor
    plfvect                 plschr                  plvsta
    plgDevs                 plscmap0                plw3d
    plgFileDevs             plscmap0a               plwidth
    plgchr                  plscmap0n               plwind
    plgcmap1_range          plscmap1                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 c1;                   // hue or red
        PLFLT c2;                   // lightness or green
        PLFLT c3;                   // saturation or blue
        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 20. API compatibility definition | Home | Regression test for backwards compatibility