Argument Types for our C API

• Argument types for input scalars

  • Floating-point type (where the C macro PL_DOUBLE is #defined if the CMake variable PL_DOUBLE is set to ON [which occurs by default])

    #if defined ( PL_DOUBLE )
    typedef double PLFLT;
    #else
    typedef float PLFLT;
    #endif
        

  • Integer type

    typedef int32_t PLINT;
        

  • Boolean type

    typedef PLINT PLBOOL;
        

  • 32-bit type that contains either UCS4-encoded unicode or FCI (font characterization integer) data

    typedef uint32_t PLUNICODE;
        

• Argument types for input/output scalars

  • Input/output PLFLT scalar

    typedef PLFLT * PLFLT_NC_SCALAR;
        

  • Input/output PLINT scalar

    typedef PLINT * PLINT_NC_SCALAR;
        

  • Input/output PLBOOL scalar

    typedef PLBOOL * PLBOOL_NC_SCALAR;
        

  • Input/output PLUNICODE scalar

    typedef PLUNICODE * PLUNICODE_NC_SCALAR;
        

  • Input/output char scalar

    typedef char * PLCHAR_NC_SCALAR;
        

• Argument types for input vectors

  • Input PLFLT vector

    typedef const PLFLT * PLFLT_VECTOR;
        

  • Input PLINT vector

    typedef const PLINT * PLINT_VECTOR;
        

  • Input PLBOOL vector

    typedef const PLBOOL * PLBOOL_VECTOR;
        

  • Input character string

    typedef const char * PLCHAR_VECTOR;
        

    This string is NULL-terminated in C.

• Argument types for input/output vectors

  • Input/output PLFLT vector

    typedef PLFLT * PLFLT_NC_VECTOR;
        

  • Input/output character string

    typedef char * PLCHAR_NC_VECTOR;
        

    This string is NULL-terminated in C.

• Argument types for input 2D matrices

  • Input PLFLT 2D matrix

    typedef const PLFLT * const * PLFLT_MATRIX;
        

  • Input vector of character strings

    typedef const char * const * PLCHAR_MATRIX;
        

    These strings are NULL-terminated in C.

  Note that for the C language case the above input matrices must be organized as an Iliffe column vector of pointers to row vectors.

• Argument types for input/output 2D matrices

  • Input/output PLFLT 2D matrix

    typedef PLFLT ** PLFLT_NC_MATRIX;
      

  • Input/output vector of character strings

    typedef char ** PLCHAR_NC_MATRIX;
      

    These strings are NULL-terminated in C.

  Note that for the C language case the above input/output matrices must be organized as an Iliffe column vector of pointers to row vectors.

• Argument type for a generic pointer

  • Input/output generic pointer

    typedef void * PLPointer;
        

• Argument types for callback functions

  • Map transformation callback type

    typedef void ( *PLMAPFORM_callback )( PLINT n, PLFLT_NC_VECTOR x, PLFLT_NC_VECTOR y );
        

    where the callback arguments are the following:

    n (PLINT, input)

    Number of elements in the x and y vectors.

    x (PLFLT_NC_VECTOR, input/output)

    Vector of x coordinates of points to be transformed.

    y (PLFLT_NC_VECTOR, input/output)

    Vector of y coordinates of points to be transformed.

  • Coordinate transformation callback type

    typedef void ( *PLTRANSFORM_callback )( PLFLT x, PLFLT y, PLFLT_NC_SCALAR tx, PLFLT_NC_SCALAR ty, PLPointer data);
        

    where the callback arguments are the following:

    x (PLFLT, input)

    x-position to be transformed.

    y (PLFLT, input)

    y-position to be transformed.

    tx (PLFLT_NC_SCALAR, output)

    Transformed x-position.

    ty (PLFLT_NC_SCALAR, output)

    Transformed y-position.

    data (PLPointer, input)

    Generic pointer to additional input data that may be required by the callback routine in order to implement the transformation.

  • Custom label callback type

    typedef void ( *PLLABEL_FUNC_callback )( PLINT axis, PLFLT value, PLCHAR_NC_VECTOR label, PLINT length, PLPointer data);
        

    where the callback arguments are the following:

    axis (PLINT, input)

    An integer whose value is PL_X_AXIS = 1 if an x-axis label is being generated and PL_Y_AXIS = 2 if a y-axis label is being generated.

    value (PLFLT, input)

    Floating-point numerical value to be used to help generate the label.

    label (PLCHAR_NC_VECTOR, output)

    A pointer to a memory area suitable for containing the output NULL-terminated character string of maximum length (including the NULL-terminating byte) of length.

    length (PLINT, input)

    The maximum possible length (including NULL-terminating byte) of the output NULL-terminated character string.

    data (PLPointer, input)

    Generic pointer to additional input data that may be required by the callback routine in order to generate a label.

  • Two-dimensional function array lookup callback type

    typedef PLFLT ( *PLF2EVAL_callback )( PLINT ix, PLINT iy, PLPointer data);
        

    where the callback function returns the looked-up value, and the callback arguments are the following:

    ix (PLINT, input)

    The x index of the function array lookup.

    iy (PLINT, input)

    The y index of the function array lookup.

    data (PLPointer, input)

    Generic pointer to the two-dimensional function input data that are required by the callback routine. Since this is a generic pointer, these two-dimensional data can be arranged in any way that is desired by the user.

  • Fill callback type

    typedef void ( *PLFILL_callback )( PLINT n, PLFLT_VECTOR x, PLFLT_VECTOR y );
        

    where the callback arguments are the following:

    n (PLINT, input)

    Number of vertices in polygon to be filled.

    x (PLFLT_VECTOR, input)

    Vector of x-coordinates of vertices.

    y (PLFLT_VECTOR, input)

    Vector of y-coordinates of vertices.

  • Defined callback type

    typedef PLINT ( *PLDEFINED_callback )( PLFLT x, PLFLT y );
    

    where the callback function returns a 1 or 0 depending on whether the x and y arguments are within specified defined area, and the callback arguments are the following:

    x (PLFLT, input)

    x-coordinate to be tested for whether it is in the defined region.

    y (PLFLT, input)

    y-coordinate to be tested for whether it is in the defined region.

• Arguments of miscellaneous types

  • A struct containing output mouse/keyboard event data

    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;
        

  • Input/output pointer to a struct that holds pointers to functions that are used to get, set, modify, and test individual 2-D data points referenced by a PLPointer or PLPointer

    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 plf2ops_t * PLF2OPS;
        

  • Input/output pointer to first element of contiguous PLFLT array

    typedef PLFLT * PLFLT_FE_POINTER;
        

    Note the array must correspond to a contiguous block of memory but may be organized with arbitrary dimensions that conform to that block of memory.