MusicKit  0.0.0
MKSynthPatch.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004   HEADER FILES: MusicKit.h
00005 
00006   Description:
00007     A MKSynthPatch contains an NSArray of unit generators which behave as
00008     a functional unit.
00009     
00010     MKSynthPatches are not created by the application. Rather, they
00011     are created by the MKOrchestra. The MKOrchestra is also
00012     responsible for filling the MKSynthPatch instance with MKUnitGenerator and
00013     MKSynthData instances. It does this on the basis of a template provided by the
00014     MKSynthPatch class method +patchTemplate. The subclass designer implements
00015     this method to provide a MKPatchTemplate which specifies what the mix of
00016     MKUnitGenerators and MKSynthData objects should
00017     be, in what order it should be allocated, and how to connect them up.
00018     (See MKPatchTemplate.)
00019     The MKSynthPatch instance, thus, is an NSArray containing the MKUnitGenerators
00020     and MKSynthData objects in the order they were specified in the template and
00021     connected as specified in the template.
00022 
00023     MKSynthPatches can be in one of three states:
00024     MK_running
00025     MK_finishing
00026     MK_idle
00027 
00028     The subclass may supply methods to be invoked at the initialiation
00029     (creation), noteOn, noteOff, noteUpdate and end-of-note (noteEnd) times, as
00030     described below.
00031 
00032     MKSynthPatches are ordinarily used in conjunction with a Conducted
00033     performance by using a MKSynthInstrument. The MKSynthInstrument manages the allocation
00034     of MKSynthPatches in response to incoming MKNotes. Alternatively, MKSynthPatches
00035     may be used in a stand-alone fashion. In this case, you must allocate the
00036     MKSynthPatch by sending the MKOrchestra the -allocSynthPatch: or
00037     allocSynthPatch:patchTemplate: method.
00038 
00039   Original Author: David A. Jaffe
00040 
00041   Copyright (c) 1988-1992, NeXT Computer, Inc.
00042   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00043   Portions Copyright (c) 1994 Stanford University
00044   Portions Copyright (c) 1999-2001, The MusicKit Project.
00045 */
00069 #ifndef __MK_SynthPatch_H___
00070 #define __MK_SynthPatch_H___
00071 
00072 #import <Foundation/NSObject.h>
00073 #import <Foundation/NSArray.h>
00074 #import "MKPatch.h"
00075 #import "MKConductor.h"
00076 #import "MKUnitGenerator.h"
00077 #import "orch.h"
00078 
00093 typedef enum _MKPhraseStatus {
00095     MK_phraseOn,
00099     MK_phraseOnPreempt,
00103     MK_phraseRearticulate,
00106     MK_phraseUpdate,
00108     MK_phraseOff,
00110     MK_phraseOffUpdate,
00112     MK_phraseEnd,
00115     MK_noPhraseActivity
00116 } MKPhraseStatus;
00117 
00118 @interface MKSynthPatch : MKPatch
00119 {
00121     NSMutableArray *synthElements;
00123     id synthInstrument;
00125     int noteTag;
00127     MKSynthStatus status;
00129     id patchTemplate;
00131     BOOL isAllocated;
00133     MKOrchestra *orchestra;
00134 
00135 @private
00136     unsigned short _whichList;  // Which list am I on?
00137     int _orchIndex;             // Which DSP?
00138     id _next;                   // Used internally for linked list of active MKSynthPatches.
00139 
00140     // Used to unqueue noteEnd request. If non-null, we have seen a noteOff but are not yet noteEnd.
00141     MKMsgStruct *_noteEndMsgPtr; 
00142 
00143     // Used to unqueue noteOff:aNote request. Non-null if we have seen a noteDur recently.
00144     // Used to remember tagged NoteOffs auto-generated from NoteDurs.
00145     MKMsgStruct *_noteDurMsgPtr;  
00146 
00147     id _sharedKey;
00148     MKMsgStruct *_notePreemptMsgPtr;
00149     short _phraseStatus;
00150 }
00151 
00152 + new;
00153 + allocWithZone:(NSZone *)zone;
00154 + alloc;
00155 - copy;
00156 - copyWithZone:(NSZone *)zone;
00157  /* These methods are overridden to return [self doesNotRecognize]. 
00158     You never create, free or copy MKSynthPatches directly. These operations
00159     are always done via an MKOrchestra object. */
00160 
00161 
00177 + patchTemplateFor: (MKNote *) currentNote;
00178 
00189 + orchestraClass;
00190 
00197 + defaultPatchTemplate;
00198 
00203 - synthInstrument;
00204 
00217 - init;
00218 
00226 - synthElementAt: (unsigned) anIndex;
00227 
00238 - (void) mkdealloc;
00239 
00254 - preemptFor: (MKNote *) aNote;
00255 
00270 - noteOnSelf: (MKNote *) aNote;
00271 
00282 - noteUpdateSelf: (MKNote *) aNote; 
00283 
00297 - (double) noteOffSelf: (MKNote *) aNote; 
00298 
00311 - noteEndSelf; 
00312 
00326 - noteOn: (MKNote *) aNote; 
00327 
00335 - noteUpdate: (MKNote *) aNote;
00336 
00344 - (double) noteOff: (MKNote *) aNote; 
00345 
00354 - noteEnd; 
00355 
00367 - moved: (MKUnitGenerator *) aUG; 
00368 
00377 - (int) status; 
00378 
00387 - (BOOL) isEqual: (MKSynthPatch *) anObject; 
00388 
00393 - (unsigned) hash;  
00394 
00399 - patchTemplate;
00400 
00406 - (int) noteTag; 
00407 
00416 - orchestra; 
00417 
00425 -(BOOL) isFreeable; 
00426 
00427 - (void) dealloc; /*sb: was -free before OS conversion. Maybe I should have left it alone... */
00428  /* Same as dealloc */
00429 
00430 
00450 - controllerValues: (id) controllers;
00451 
00463 - next;
00464 
00470 - freeSelf;
00471 
00481 - (MKPhraseStatus) phraseStatus;
00482 
00483  /* -read: and -write: 
00484   * Note that archiving is not supported in the MKSynthPatch object, since,
00485   * by definition the MKSynthPatch instance only exists when it is resident on
00486   * a DSP.
00487   */
00488 
00489 @end
00490 
00491 @interface MKSynthPatch(PatchLoad)
00492 
00542 + (Class) findPatchClass: (NSString *) name;
00543 
00544 @end
00545 
00546 #endif