Inter-library communications (draft)

Communication between GUI, engine and Integra server (typical use case)

The GUI has two main functions: to act as a GUI that generates control messages to be sent via Integra OSC to Integra modules, and to act as a GUI builder for instantiating GUI widgets (graphical Integra modules). These widgets in turn send OSC to other Integra modules.

In order to function, the GUI needs to know what Integra modules are available, and what the interfaces to those modules are. This information can be obtained by querying an Integra library instance via OSC. If the instance is a master, then the information should be read from the modules' definitions which are provided by locally stored XML files. These XML files can be obtained by visiting the Integra database UI and downloading them in an archive, or by querying the remote Integra server directly via XML-RPC. If the instance is a slave then it will proxy the UI's request for the module definitions.

Functionality for querying the server, reading XML files and instantiating module instances is provided by the Integra library (libIntegra). In the current GUI implementation, which uses Max/MSP, library functions are accessed by sending OSC messages to a Max 'external' that provides bindings to the library.

The purpose of the engine is to act as a host for non-graphical Integra modules. The engine should be able to function with or without a GUI. The engine may also need to read and write module state data. This is stored as module instance data in archives containing multiple XML files, one for each module class.

In standalone (no-gui) mode, the engine has the capability to read Integra XML files, and query the remote Integra server (i.e. using libIntegra functions provided by a Max external). The Integra library instance in the engine can receive OSC messages from the GUI (or other application) in order to instantiate Integra modules in its host environment (e.g. Max/MSP). This instantiation process is performed by a plugin that acts like a translator between the Integra library, and the module host.

Integra modules consist of three elements:

• The module definition: this is defined using the web interface to the database. It defines the module's interface, and cannot be changed.
• The module implementation: this is developed by an Integra module developer, and it must conform to the module definition and implement the Integra protocol. The module implementation is commonly a plain text file, which can be loaded by a DSP environment to create an in-memory DSP unit. For each module definition there can be an arbitrary number of module implementations.
• The module instance data: this is numerical and textual data that represents the module's current state. A module instance only stores one set of state data, and it is the module's 'last saved' state that gets committed to the Integra database. If it is necessary to store changes of state over time, another module (a Player) must be used to hold the states.

On the remote Integra server, the library is used only for reading and generating Integra XML. No module instantiation takes place (for now).

The server can be accessed directly by the library using XML-RPC, or accessed 'manually' by the user via a web interface. The user is entitled to download as many Integra module definitions or module instances as they like. The number of module definitions downloaded will determine how many modules are available for use in the GUI and/or engine.

In the engine there is a full library implementation, both instance host and serialisation layer are used. In the UI we have only an instance host, on the remote web server we have only the serialisation layer.

The library could be thought of as having three modes of operation:

Master: The library can read and write XML files. Instantiation messages are sent to the slave followed by state messages, i.e. modules are instantiated using XML module definitions, and then their state is restored.

Slave: The library cannot read or write XML files. The slave acts as a proxy to its associated master. The slave hosts an instantiation plugin for creating module instances in the GUI (e.g. GUI widgets), but instantiation messages are expected from a master. Module state data is received via OSC and passed through to the master.

Standalone: The library can read and write XML files. Instantiation is handled 'internally' with no OSC communication involved.

libIntegra instances must be kept in sync both in terms of event scheduling and in terms of data consistency.

explanation coming soon!