1.6.1 C interface

The C interface is a base for many other interfaces. It contains the pure C functions for most of the methods of MathGL classes. In distinction to C++ classes, C functions must have an argument HMGL (for graphics) and/or HMDT (for data arrays), which specifies the object for drawing or manipulating (changing). So, firstly, the user has to create this object by the function mgl_create_*() and has to delete it after the use by function mgl_delete_*().

All C functions are described in the header file #include <mgl/mgl_c.h> and use variables of the following types:

• HMGL — Pointer to class mglGraph (see section MathGL core).
• HMDT — Pointer to class mglData (see section mglData class).
• HMPR — Pointer to class mglParse (see section mglParse class)..

These variables contain identifiers for graphics drawing objects and for the data objects.

Fortran functions/subroutines have the same names as C functions. However, there is a difference. Variable of type HMGL, HMDT must be an integer with sufficient size (integer*4 in the 32-bit operating system or integer*8 in the 64-bit operating system). All C functions are subroutines in Fortran, which are called by operator call. The exceptions are functions, which return variables of types HMGL or HMDT. These functions should be declared as integer in Fortran code. Also, one should keep in mind that strings in Fortran are denoted by </samp>&rsquo; symbol, not the " symbol.

Create and delete objects

• Functions for non-visual “grapher” creation:

  C function: HMGL mgl_create_graph_gl ()

  Create the instance of class mglGraphGL.

  C function: HMGL mgl_create_graph_zb (int width, int height)

  Create the instance of class mglGraphZB with specified sizes.

  C function: HMGL mgl_create_graph_ps (int width, int height)

  Create the instance of class mglGraphPS with specified sizes.

  C function: HMGL mgl_create_graph_idtf ()

  Create the instance of class mglGraphIDTF.

• Function for windowed “grapher” creation:

  C function: HMGL mgl_create_graph_glut (int (*draw)(HMGL gr, void *p), const char *title, void *par)

  Create the instance of class mglGraphGLUT and the connected GLUT window. Only one GLUT window can be opened at once. Argument description can be found in mglGraphAB class.

  C function: HMGL mgl_create_graph_fltk (int (*draw)(HMGL gr, void *p), const char *title, void *par)

  Create the instance of class mglGraphFLTK and the connected FLTK window. Several windows can be opened at the same time. However user must call mgl_fltk_run() function to start the message handling cycle. Argument description can be found in mglGraphAB class. Note that draw can be NULL for displaying static bitmaps only (no animation or slides).

  C function: HMGL mgl_create_graph_qt (int (*draw)(HMGL gr, void *p), const char *title, void *par)

  Create the instance of class mglGraphQT and the connected Qt window. Several windows can be opened at the same time. However user must call mgl_qt_run() function to start the message handling cycle. Arguments description can be found in mglGraphAB class. Note, that draw can be NULL for displaying static bitmaps only (no animation or slides).

  C function: void mgl_fltk_run ()

  Start FLTK message handling cycle. A normal program will end main() function with return mgl_fltk_run();.

  C function: void mgl_fltk_thread ()

  Start FLTK message handling cycle. In distinction to mgl_fltk_run() the loop is started in a separate thread, so that program continues immediately.

  C function: void mgl_qt_run ()

  Start Qt message handling cycle. A normal program will end main() function with return mgl_qt_run();. Alternatively, the user may setup Qt application by direct Qt function calls.

  C function: void mgl_qt_thread ()

  Start Qt message handling cycle. In distinction to mgl_qt_run() the loop is started in separate thread so that the program continues immediately.

  C function: void mgl_update (HMGL graph)

  Manually update contents of the window.

  C function: void mgl_set_show_mouse_pos (HMGL graph, int enable)

  Switch to show or not in the widget the last mouse click position.

  C function: void mgl_get_last_mouse_pos (HMGL graph, float *x, float *y, float *z)

  Last position of mouse click.

  C function: void mgl_calc_xyz (HMGL graph, int xs, int ys, float *x, float *y, float *z)

  Calculate 3D coordinate {x,y,z} for screen point {xs,ys}. At this moment, it ignores perspective and transformation formulas (curvilinear coordinates). The calculations are done for the last used InPlot (see section Transformation matrix).

• Functions for data creation:

  C function: HMDT mgl_create_data ()

  Create a simple instance of class mglData.

  C function: HMDT mgl_create_data_size (int nx, int ny, int nz)

  Create an instance of class mglData with specified sizes.

  C function: HMDT mgl_create_data_file (const char *fname)

  Create an instance of class mglData and fill it by data from text file.

• Each created object must be deleted after usage by functions:

  C function: void mgl_delete_graph (HMGL graph)

  Delete the instance of a class. Must be used after plotting for every created graphical object.

  C function: void mgl_delete_data (HMDT dat)

  Delete the instance of a class. Must be used after the use of every created data object.