Chapter 7. C Language
Prev | Part III. Supported computer languages | Next

## Chapter 7. C Language

The C computer language is fundamental to PLplot because our core plotting library and our definitive set of standard examples are written in that language, and the remainder of the computer languages that we support are implemented as bindings for our core C library. The C standard we use is C99, and our experience is that all C compilers accessible to our users support that standard sufficiently to have no trouble building PLplot.

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.

For more information on calling PLplot from C, please consult the example C programs in `examples/c` that are distributed with PLplot. For more information on building your own PLplot-related C routines, please consult either the traditional (Makefile + pkg-config) or CMake-based build systems that are created as part of the install step for our C (and other language) examples.

Prev | Up | Next
Part III. Supported computer languages | Home | Chapter 8. Ada Language