00001 /* 00002 $Id: MKSynthInstrument.h 3519 2009-04-18 09:23:57Z leighsmith $ 00003 Defined In: The MusicKit 00004 00005 Description: 00006 An MKSynthInstrument realizes MKNotes by synthesizing them on the DSP. It 00007 does this by forwarding each MKNote it receives to a MKSynthPatch object, 00008 which translates the parameter information in the MKNote into DSP 00009 instructions. A MKSynthInstrument can manage any number of MKSynthPatch 00010 objects (limited by the speed and size of the DSP). However, all of 00011 its MKSynthPatches are instances of the same MKSynthPatch subclass. You 00012 assign a particular MKSynthPatch subclass to a MKSynthInstrument through 00013 the latter's setSynthPatchClass: method. A MKSynthInstrument can't 00014 change its MKSynthPatch class during a performance. 00015 00016 Each MKSynthPatch managed by the MKSynthInstrument corresponds to a 00017 particular noteTag. As the MKSynthInstrument receives MKNotes, it 00018 compares the MKNote's noteTag to the noteTags of the MKSynthPatches that 00019 it's managing. If a MKSynthPatch already exists for the noteTag, the 00020 MKNote is forwarded to that object; otherwise, the MKSynthInstrument 00021 either asks the MKOrchestra to allocate another MKSynthPatch, or it 00022 preempts an allocated MKSynthPatch to accommodate the MKNote. Which 00023 action it takes depends on the MKSynthInstrument's allocation mode and 00024 the available DSP resources. 00025 00026 A MKSynthInstrument can either be in automatic allocation mode 00027 (MK_AUTOALLOC) or manual mode (MK_MANUALALLOC). In automatic mode, 00028 MKSynthPatches are allocated directly from the MKOrchestra as MKNotes are 00029 received by the MKSynthInstrument and released when it's no longer 00030 needed. Automatic allocation is the default. 00031 00032 In manual mode, the MKSynthInstrument pre-allocates a fixed number of 00033 MKSynthPatch objects through the setSynthPatchCount: method. If it 00034 receives more simultaneously sounding MKNotes than it has MKSynthPatches, 00035 the MKSynthInstrument preempt its oldest running MKSynthPatch (by sending 00036 it the preemptFor: message). 00037 00038 Original Author: David A. Jaffe 00039 00040 Copyright (c) 1988-1992, NeXT Computer, Inc. 00041 Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT 00042 Portions Copyright (c) 1994 Stanford University 00043 Portions Copyright (c) 1999-2001, The MusicKit Project. 00044 */ 00092 #ifndef __MK_SynthInstrument_H___ 00093 #define __MK_SynthInstrument_H___ 00094 00127 00129 #define MK_AUTOALLOC 0 00130 00131 #define MK_MANUALALLOC 1 00132 00133 #define MK_MIXEDALLOC 2 00134 00137 #import "MKInstrument.h" 00138 #import "MKNote.h" 00139 #import "MKSynthPatch.h" 00140 00141 @interface MKSynthInstrument : MKInstrument 00142 { 00143 id synthPatchClass; 00144 unsigned short allocMode; 00145 NSMutableDictionary *taggedPatches; 00146 NSMutableDictionary *controllerTable; 00147 MKNote *updates; 00148 BOOL retainUpdates; 00149 Class orchestra; 00151 @private 00152 NSMutableArray *_patchLists; 00153 } 00154 00162 - init; 00163 00181 - (int) setSynthPatchCount: (int) voices patchTemplate: (id) aTemplate; 00182 00194 - (int) setSynthPatchCount: (int) voices; 00195 00201 - (int) synthPatchCountForPatchTemplate: (id) aTemplate; 00202 00208 - (int) synthPatchCount; 00209 00216 - realizeNote: (MKNote *) aNote fromNoteReceiver: (MKNoteReceiver *) aNoteReceiver; 00217 00222 - synthPatchClass; 00223 00233 - setSynthPatchClass: (Class) aSynthPatchClass; 00234 00246 - setSynthPatchClass: (Class) aSynthPatchClass orchestra: (Class) anOrch; 00247 00254 - (Class) orchestra; 00255 00274 - preemptSynthPatchFor: (MKNote *) aNote patches: (MKSynthPatch *) firstPatch; 00275 00292 - activeSynthPatches: (id) aTemplate; 00293 00305 - mute: (id) aMute; 00306 00316 - autoAlloc; 00317 00323 - (unsigned short) allocMode; 00324 00333 - abort; 00334 00343 - copyWithZone: (NSZone *) zone; 00344 00353 - clearUpdates; 00354 00363 - setRetainUpdates: (BOOL) yesOrNo; 00364 00370 - (BOOL) doesRetainUpdates; 00371 00386 - getUpdates: (MKNote **) aNoteUpdate controllerValues: (NSMutableDictionary **) controllers; 00387 00388 /* 00389 You never send this message directly. 00390 Invokes superclass write: method. Also archives allocMode, retainUpdates 00391 and, if retainUpdates is YES, the controllerTable and updates. 00392 */ 00393 - (void) encodeWithCoder: (NSCoder *) aCoder; 00394 00395 /* 00396 You never send this message directly. 00397 Note that -init is not sent to newly unarchived objects. 00398 See write:. 00399 */ 00400 - (id) initWithCoder: (NSCoder *) aDecoder; 00401 00407 - allNotesOff; 00408 00409 @end 00410 00411 #endif
1.5.6