Interactive Swarm Space
About      Projects      Downloads      Documentation      Wiki      
Basics      ISO Flock      ISO Synth      Networking      API      Publications      
Introduction     How to Code     Basic Units     Unit Ports     Math Units     Filters     Basic Synthesis     Events
Patch Building     Multi-Channel     Spatialisation     Glossary

Control Ports and Switch Ports

Almost all units can be parameterized either after creating them or during the runtime of the synth (see chapter Events). In the "Hello World" example in the introduction, we adjusted the parameters "frequency", "amplitude" and "phase". This parameters can be accessed over so called ports. Each port is responsible of receiving control values for a certain parameter. There are two types of ports, ControlPorts and SwitchPorts:

ControlPorts Continuously changing control input. Optional: linear interpolation for smooth transitions.
SwitchPorts One-shot control input. No interpolation available. For rare control instances like e.g. loading a new audio file. The rate at which SwitchPort is evaluated follows follows the equation: sample rate / buffer size (by default this is 44100/512 = 86.13 times per second.
Input-/OutputPorts Main receiving and sending ports for audio data in and out of the unit


Ports

inputs and outputs of a unit

Absence of a control rate

If you are familiar with Music N languages like Csound or even Max/MSP, you are used to think of a control input as being much slower than audio input. This distinction has been known under the name a-rate (audio data rate or sampling rate, most commonly 44100 Hz) and k-rate (control data rate, often around 100 Hz). ISOSynth has no k-rate! Every unit to unit interaction via a ControlPort is done at the sampling rate's resolution. This not only allows you to very precisely control your units, but also to supply your units with continuous audio rate control input. Please note that there is no such thing as a ControlPort output port - A unit in ISOSynth doesn't actually care, if you connect its output port to another unit's audio input port or control input port - however you cannot connect the output port to a switch port.

ControlPort vs. SwitchPort

The next two tables should help you to decide when to use either a ControlPort or a SwitchPort, when programming your own units.

ControlPort SwitchPort
continuous data flow (at sampling rate) sparse data flow ("one change event every ones in a while")
very timing sensitive (resolution = 1 / sampling freq.) relatively timing insensitive (resolution = 1/86 s)
straight-forward unit to unit communication inside ISOsynth event-based communication (via TCP/IP, MIDI, from other programs like e.g. the ISOFlock or ISOTracker)
only datatype Frame allowed for communication any datatype is possible - but not automatic conversion possible*
buffered data communication (i.e. 512 values in one chunk) single value communication
unit-to-unit forwarding of received data buffers limited and in some cases even computationally expensive - e.g. when copies need to be made, so that each receiver has their own version of the buffer. processing, copying and forwarding of received data is easy.

In order for full data type compatibility to work, a call to a SwitchPort looks slightly more complicated than you might expect. Let's look at two examples to clarify this:

noise->set("active", false); // won't work - compiler error
noise->set("active", data::Values(false)); // that's more like it

There are two flavors of Switch Ports: Data Switch Ports and Fading Switch Ports. While the first one is by far the more common of the two, a call to a Fading Switch Port looks slightly different, due the an added argument for fade duration:

noise->set("fadeable", data::Values(0.4f), 20.0f);
  // the first float needs to be put in this special format,
  // since it's the actual switch port parameter.
  // The second parameter is the fade duration, which for this argument needs
  // to be a float.

We have implemented units that are able to translate between the two ports

EventToAudioUnit translates an incoming event signal into a continuous stream of data (->ControlPort)
AudioToEventUnit translates a audio-rate control data stream into individual events (->SwitchPort)

Please note that these two units are merely base class units of a whole tree of subclasses which might be a better fit for your specific conversion need. Especially the AudioToEventUnit is the base class of a bunch of statistical units. We advice you to implement your own child classes. [TODO reference]