Format of the Cmgui API

The cmgui external API is located in the source/api directory. It consists of object-oriented-like C functions which take a main object as the first argument and whose type name forms the function prefix. Examples:

int Cmiss_scene_viewer_set_near_and_far_plane(Cmiss_scene_viewer_id scene_viewer, double near_plane, double far_plane);

Cmiss_field_id Cmiss_field_create_add(Cmiss_field_id source_field_one, Cmiss_field_id source_field_two);

The percentage of cmgui functionality exposed directly with such commands is under 25%. However it is being completed through planned work and by immediate request when needed, and the legacy command interface makes up much of the shortfall.

Legacy execute_command interface

Much of the remaining functionality is available via legacy 'gfx' commands which are invoked via the following single API call:

int Cmiss_command_data_execute_command(struct Cmiss_command_data *command_data, const char *command);

An example is the command to establish the graphical surfaces for the region 'heart' using field 'coordinates' and coloured by the 'temperature' field with spectrum 'default' modulating material 'white':

gfx modify g_element heart surfaces coordinate coordinates data temperature spectrum default material white;

Limitations of the legacy commands include:

• all arguments referred to by name not object reference, so less efficient and less flexible;
• fixed view of overall architecture based on standalone cmgui application;
• no ability to return values;

At the present time the execute command API incorporates a perl interpreter which remembers some state and permits expressions. Once we have a more complete API exposed via bindings to scripting languages the interpreter will be removed, to be followed by the removal of the legacy command interface altogether.

Specific API completion notes

Regions and Fields, including images: Around 30-40% of the region and field interfaces are exposed as direct API. Images are just structured fields within cmgui and are supported via the Cmiss_field_image API. The most significant omission is that there are few low-level APIs for creating finite element fields, which currently rely on being defined in Cmgui EX files (and soon FieldML). tracker item 1776 will complete needed group/selection field interfaces in Dec 2009 - Jan 2010 timeframe.

Scene viewer: Performs OpenGL rendering in a window with some input functionality. Essentially complete.

Graphics renditions: Conversions of fields to graphical visualisations must currently be established using legacy gfx commands. tracker item 1047 (in progress) is refactoring the graphical renditions and will be followed by tracker item 1046 to expose graphics rendition API. Timeframe: Dec 2009.

Time keeper: Used to synchronise and animate with cmgui timers. Essentially complete.

Materials, Spectrums: For controlling graphical materials and graphics colouration by field value. Legacy command interface only. Timeframe: not yet planned.

Known API issues:

• Some field and other APIs will be changing in the coming months to require a Cmgui object to be passed at all times. A particular change is that all field create functions will require either source fields or a region object to be supplied and will belong to that region or the source field's region.

Resolved API Issues:

• Some private headers have been accidentally included in the external headers and these will be removed. See tracker item 2036

Examples that use the API

We have two examples that use the API. Both are available from the examples svn repository here cmiss examples. The API examples are a/texture_viewer_api_demo and a/testing/cmiss_time_api. The cmiss_time_api example builds a program which links against the cmgui libraries to test time keeper and time object. The texture_viewer_api_demo example reads in (hard coded) images and uses wx to draw a static image. That image is loaded into a texture in Cmgui and displayed using the scene viewer. This example also uses computed fields to change the RGB component.

Cmgui legacy 'gfx' commands are used in the vast majority of other cmgui examples.

Cmgui Libraries

Currently Cmgui will build both shared object and static libraries with the names:

• shared object
  • cmgui - everything not in the remaining libraries, including cmgui application dialogs
  • cmgui_general - some core functions including memory allocation
  • cmgui_core_fields - basis fields and regions
  • cmgui_pass_through
• static
  • cmgui
  • passthroughinterpreter

To build these libraries do:

make cmgui-gtk TARGET=so_lib
make cmgui-gtk TARGET=static_lib

The first statement will build the shared libraries and the second statement will build the static libraries. The above libraries are used to build linux versions of Zinc - the Cmgui engine embedded in the Mozilla platform.

Which APIs with which shared libraries?

The effort to break cmgui into more reusable libraries is in its infancy. As a consequence, several of the API headers are not limited to working with just a specific shared library and until more work is done one must assume that all cmgui shared libraries must be present to work with the API.

Known issue with wx interface

Cmgui built with wxWidgets initialises its own instance of wxWidgets and this may cause a problem when an app initialises its own wx instance and uses the widgets modules provided by cmgui at the same time. This is the reason why api example a/texture_viewer_api_demo uses the wx instance from the cmgui library at this moment. However this part will be changed in the near future. Instead the app will provide its own wx instance and cmgui widgets modules will use the instance provided to it.