MusicKit  0.0.0
MKSynthInstrument Class Reference

An MKSynthInstrument realizes MKNotes by synthesizing them on the DSP. More...

#include <MKSynthInstrument.h>


Detailed Description

An MKSynthInstrument realizes MKNotes by synthesizing them on the DSP.

It does this by forwarding each MKNote it receives to a MKSynthPatch object, which translates the parameter information in the MKNote into DSP instructions. A MKSynthInstrument can manage any number of MKSynthPatch objects (limited by the speed and size of the DSP). However, all of its MKSynthPatches are instances of the same MKSynthPatch subclass. You assign a particular MKSynthPatch subclass to a MKSynthInstrument through the latter's setSynthPatchClass: method. A MKSynthInstrument can change its MKSynthPatch at any time, even during a performance.

Each MKSynthPatch managed by the MKSynthInstrument corresponds to a particular noteTag. As the MKSynthInstrument receives MKNotes, it compares the MKNote's noteTag to the noteTags of the MKSynthPatches that it's managing. If a MKSynthPatch already exists for the noteTag, the MKNote is forwarded to that object; otherwise, the MKSynthInstrument either asks the MKOrchestra to allocate another MKSynthPatch, or it preempts an allocated MKSynthPatch to accommodate the MKNote. Which action it takes depends on the SynthInstrument's allocation mode and the available DSP resources.

A MKSynthInstrument can either be in automatic allocation mode (MK_AUTOALLOC) or manual mode (MK_MANUALALLOC). In automatic mode, MKSynthPatches are allocated directly from the MKOrchestra as MKNotes are received by the MKSynthInstrument and released when it's no longer needed. Automatic allocation is the default.

In manual mode, the MKSynthInstrument pre-allocates a fixed number of MKSynthPatch objects through the setSynthPatchCount: method. If it receives more simultaneously sounding MKNotes than it has MKSynthPatches, the MKSynthInstrument preempt its oldest running MKSynthPatch (by sending it the preemptFor: message).

The MKSynthInstrument has a "noteUpdate state", a MKNote object containing the most recent parameter values that the MKSynthInstrument has received from noteUpdates without noteTags. For example, the current value of MIDI pitch bend would be stored there. Additionally, the MKSynthInstrument has a "controllerTable." This is used to map MIDI controller numbers to the most recent controller values that the MKSynthInstrument has received from noteUpdates without noteTags. This information cannot be stored in the noteUpdate state because the noteUpdate state has room for only one controller/value pair.

By default, the update state is cleared after each performance. However, you can request that it be retained with the setRetainUpdates: method. You can examine the updates and controllerTable with the method getUpdates:controllerValues:.


The documentation for this class was generated from the following file: