Introduction
This page generally describes how I believe we should implement the core elements (no pun intended) for our protocol router. Some of the ideas originated from the GStreamer project (which in turn took its ideas from a number of other projects, including Microsoft's multimedia framework). I've adapted this idea towards what we want to do with the information we're going to be routing around. Feel free to send any comments to myself, or reproduce this document wherever you see fit (as long as you give credit). A large portion of the text comes from the third chapter of the GStreamer Application Development Manual.
Foundations
Element
An element is the most important class of objects. You will usually create a chain of elements linked together and let data flow through this chain of elements. An element has one specific function, which can be the reading of data from a device such as the monome or a file, decoding or modifying this data or outputting this data via OSC or MIDI (or anything else). By chaining together several such elements, you create a pipeline that can do a specific task.
For the application programmer, elements are best visualized as black boxes. On the one end, you might put something in, the element does something with it and something else comes out at the other side. For a decoder element, for example, you'd put in encoded data, and the element would output decoded data.
There are three basic types of elements. The first, is a source element. Source elements generate data for use by a pipeline, for example reading from a device or the network. Source elements do not accept data, they only generate data.
The second type of element is a filter (Ed: do we want to call them filters?). Filter elements have both input and outputs pads. They operate on data that they receive on their input (sink) pads, and will provide data on their output (source) pads.
The third and final basic type of element is a sink element. Sink elements are end points in a pipeline. They accept data but do not produce anything.
Pads
Pads are element's input and output, where you can connect other elements. They used to negotiate links and data flow between elements. A pad can be viewed as a "plug" or "port" on an element where links may be made with other elements, and through which data can flow to or from those elements. Pads have specific data handling capabilities: A pad can restrict the type of data that flows through it. Links are only allowed between two pads when the allowed data types of the two pads are compatible.
An analogy may be helpful here. A pad is similar to a plug or jack on a physical device. Consider, for example, a home theater system consisting of an amplifier, a DVD player, and a (silent) video projector. Linking the DVD player to the amplifier is allowed because both devices have audio jacks, and linking the projector to the DVD player is allowed because both devices have compatible video jacks. Links between the projector and the amplifier may not be made because the projector and amplifier have different types of jacks. Pads in GStreamer serve the same purpose as the jacks in the home theater system.
Data generally only flows in a single direction between the link of elements.
Examples
Please note that the 'JSON source' in the example is slightly wrong -- it should also mention which elements link to what under the properties section.
