MusicKit  0.0.0
MKSynthInstrument.h
00001 /*
00002   $Id$
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