UNOFFICIAL
This is a non-normative, unofficial summary of the GMPI requirements collection discussions.
Notes are in grey serif text and open questions are boxed.
Version 1.0 collated by Steve Harris <steve AT plugin.org.uk>, 2003-10-01
What processors, O/S, addressing models and programming languages do we need to support?
taken from http://www.freelists.org/archives/gmpi/02-2003/msg00383.html.
Note: 1/2 are not meant to imply that GMPI isn't usable in other contexts, such as game consoles or cell phones. It simply means that the specification is primarily targeting the listed applications and platforms.
Anyone who develops software to process or synthesize audio or music. This includes commercial developers, academic computer music researchers, and independent shareware or freeware developers.
Plugins that produce and/or consume musical data and/or control data and/or digital audio data. In the most general case a plugin can have arbitrary numbers of incoming and outgoing music/audio/control data connections, including no connections at all.
Some examples of contemporary plugin input/output connections include, but are not restricted to:
Audio and/or MIDI processors, sure, but what about driver plugins, controllers, visuaulization plugins?
Taken from http://www.freelists.org/archives/gmpi/03-2003/msg00012.html.
Covered by 1.5
Taken from http://www.freelists.org/archives/gmpi/03-2003/msg00195.html
The API should fully support 64 bit processors, and either be portable to such processors or explicitly utilize 64 types where possible. Also, standard ANSI C type names (stdint.h) should be used instead of platform-specific type names such as DWORD.
In general, all popular contemporary O/S, leaning towards more recent versions: Windows 2000, Windows XP, Mac OS-X, Linux, other Unix variants, Windows CE, Palm O/S, BeOS.
In order to help simplify the porting of plug-ins to different platforms, the GMPI specification should include the definition of a standard mechanism for accessing a limited set of basic host system services, including at a minimum memory and file system services, and perhaps also time and thread services. If a suitable specification for this already exists and has reliable implementations across the targeted platforms, it should be given consideration; otherwise a new minimal specification will need to be developed.
The plugin and the host are assumed to share the same memory address space. If a plugin needs to run in another space, i.e. out of process or an an external DSP accelerator, it is the plugins responsibility to perform the necessary translations on its side of the interface.
ANSI C (which supports C++ by extension), with very clearly specified application binary interface (ABI). The actual calling convention may vary from platform to platform, though the "default" calling convention is ANSI C.
In-process or out-of-process? What kinds of special needs are there in events to/from a plugin? Is the host a plugin too?
No summary could be found. Thread was closed in this mail: http://www.freelists.org/archives/gmpi/04-2003/msg00071.html.
Taken from http://www.freelists.org/archives/gmpi/04-2003/msg00204.html.
i.e., how do we handle plugins that run at > 100% of realtime?
No strategy was developed to guarantee glitch-free operation in the case of the plug-in graph taking too long to generate output. It is up to the host implementation to detect and respond to the graph consuming too much CPU. Professional DAW hosts may stop the graph and mute audio. A streaming media player host may decide to forge ahead, possibly bypassing CPU-hungry plugs. GMPI may provide means for hosts to notify plug-ins (or for plug-ins to query hosts) about CPU consumption.
Initially divided into two strategies:
Strategy 1 was refined. Only one DSP function is called at a time from the host, though the functions may be called from different host threads. This means the host is the arbiter of all access to the DSP object from other objects. So the GUI object, for example, must communicate with the DSP object via the host. This implies an architecture where the host queues all asynchronous events for the DSP object, and sends them to the DSP object from the processing thread prior to calling the plug's process method. The DSP object must process all events in a timely manner, deferring time-consuming tasks such as sample bank loading to a low priority thread which can be polled for completion. Presumably the host would provide an interface to create and synchronize such helper threads.
Advantages of strategy 1 are primarily that the plug-in developer need not deal with thread synchronization in the DSP object (ease of development), and it is a clean, unambiguous design. A possible disadvantage is difficulty in implementing plug-in adaptors while maintaining the constraints. Strategy 1 seemed to be generally accepted.
Samples or "ticks" or both/neither? How are discontinuities expressed?
Taken from http://www.freelists.org/archives/gmpi/05-2003/msg00318.html - probably not definitive.
Several time formats are required:
Notes:
Outstanding issues:
What do we prefer for interleave, audio sample data types, allocation, timestamping?
Taken from http://www.freelists.org/archives/gmpi/06-2003/msg00483.html and http://www.freelists.org/archives/gmpi/07-2003/msg00039.html.
All hosts and plugins MUST support non-interleaved data for plugin I/O.
TBD: Based on as-yet-unknown benchmarks, this specification might be extended to include a per-plugin preference for interleaved data. This extension will be included if and only if sufficient net performance gains can be demonstrated for some class of plugins. Should this needed, the following additional issues must be resolved:
A single datatype is not sufficient to support all the platforms GMPI is intended to support. In very general terms, a plugin MUST identify the datatype it expects for I/O. This datatype is used for all I/O to and from the plugin.
TBD: It is unclear at this point whether there is a need for different data-types within a single plugin. If and only if the need is justified, this specification might be extended to include multiple data-types, at a granularity finer than the entire plugin.
TBD: An ancillary API might be desirable to convert GMPI-standard data-types in a host-transparent way.
All GMPI data streams are PCM data. Groups of streams may represent trivial encodings (e.g. 2 streams == left and right channels) or non-trivial encodings (e.g. 2 streams = 4 channels, encoded in LtRt). Streams are flagged with both the number of streams and the encoding.
It may be desirable for plugins to explicitly define which encodings they support, which enables the host to notice or disallow incompatible connections. This may be saved for a later release of GMPI.
All connections between plugins are bundles of mono streams with defined relationships to each other. For example, a mono connection is one stream, while a stereo connection is a left stream and a right stream and a 5.1 connection is a group of left, right, center, surround-left, surround-right, and LFE streams. Connections are handled atomically - all streams [in one bundle] are connected or disconnected together.
If a plugin is capable of doing in-place processing of buffers (reusing an input for an output), then that functionality will be supported.
Plugins may indicate a global 'capable' flag or there may be some other plan for buffer re-use.
Taken from http://www.freelists.org/archives/gmpi/08-2003/msg00040.html.
Silence optimizations will be supported. Plugins that do not care to handle silent input specially will not have to do any extra work, or the extra work will be encapsulated somehow. Hosts that do not care to handle silence will not have to do any extra work.
Taken from http://www.freelists.org/archives/gmpi/08-2003/msg00214.html.
A "Parameter" is an abstract way for a plugin to present some control to the host. Anything that is changeable in real-time is a Parameter. When the operation of the plugin is manipulated (by a GUI, a control surface, another plugin, etc) the change is communicated to the plugin using Parameters.
Parameters have all sorts of meta-data, such as datatype, range, etc. This alone is not sufficient, however. Parameters need to be able to receive changes from a number of sources. Similar to Parameters, and usually related are Control-Inputs. Control-Inputs are where user actions are delivered.
Every Parameter has a Control-Input, which is how Parameters get changed. Because we want to be able to connect plugins together, there must also exist Control-Outputs.
It seems reasonable that we might want to generate very specific data (e.g. a tempo controller) or very generic data (e.g. a generic sine controller which can be connected to any Parameter). Therefore, it seems not unreasonable to have the Control-Outputs identify themselves as outputting normalized or natural data. Perhaps Control-Inputs can flag themselves as such, too.
Because of the simple Control-Input model, any number of sources can manipulate Parameters. This includes automation playback, which is really just another event source. All Parameters can be automated.
Because there are likely to be more than a single interface for a Parameter (e.g. GUI and motorized MIDI control), the current state of a Parameter must be sent to all listeners when that state changes. This may actually be handled by the host, rather than the plugin.
Plugins may want to retain compatibility with older plugins while evolving. Parameters may be marked as hidden, so they are present, but not displayed to the user.
When saving and restoring state, the majority of the state of the majority of plugins can be represented by taking a snapshot of the state of all Parameters. Sometimes, however, it is useful to save and restore opaque blobs of data (e.g. Parameters which have an ordering dependency, data which does not map well onto Parameters). Therefore, saving and restoring of plugin state involves Stata. Generally, a Statum will correspond to a Parameter, but a Statum may be also be a blob of opaque data. Not all Parameters will have associated Stata, and therefore will not be saved with the Plugin state.
For the purpose of saving and restoring state, the abstraction of stata (sing. statum) is introduced. A statum is a single atomic unit of state. A plugin's state is completely represented by it's stata. When a host wants to save the state of a plugin (for a preset, for a project file, etc.), the host can iterate over all the stata exposed by the plugin, and retrieve the current values. When restoring state, the host can set the values of the stata. Stata may be opaque blobs, which are unintelligible to the host. Whether or not stata are actually entities in the GMPI system is.
It may be decided that stata are actually abstracted from parameters, with a common (but not mandatory) 1-to-1 mapping, or it may be decided that stata and parameters are the same thing.
Attempted summary by Steve Harris while composing this document.
Some types are generally believed to be required:
All the sections from here on have been renumbered to make room for the added sections.
Whose responsibility? How do we deal with endian issues?
What kind of realtime guarantees? Does the host provide some kind of threading environment?
Can GUI be avoided at this point? What does the interface boundary to the GUI need to be?
How important is it? How do we ensure something new is still backwards compatible?
Is there a "base level" possible that's still cross platform? How do we support all target platforms?
Create for use vs. query, what can a plugin do at creation time, RT safety?
How should plugins address DRM streams? How to sign OpenSource plugins?
How does the host specify its language? Logical vs. human-readable names?
When and how does a plugin reset? How to respond to format changes?
How are headers and host libraries/source licensed? What kind of sample code is required?