MKSynthPatch.h

Go to the documentation of this file.

/*
  $Id: MKSynthPatch.h 3529 2009-04-28 20:15:37Z leighsmith $
  Defined In: The MusicKit
  HEADER FILES: MusicKit.h

  Description:
    A MKSynthPatch contains an NSArray of unit generators which behave as
    a functional unit.
    
    MKSynthPatches are not created by the application. Rather, they
    are created by the MKOrchestra. The MKOrchestra is also
    responsible for filling the MKSynthPatch instance with MKUnitGenerator and
    MKSynthData instances. It does this on the basis of a template provided by the
    MKSynthPatch class method +patchTemplate. The subclass designer implements
    this method to provide a MKPatchTemplate which specifies what the mix of
    MKUnitGenerators and MKSynthData objects should
    be, in what order it should be allocated, and how to connect them up.
    (See MKPatchTemplate.)
    The MKSynthPatch instance, thus, is an NSArray containing the MKUnitGenerators
    and MKSynthData objects in the order they were specified in the template and
    connected as specified in the template.

    MKSynthPatches can be in one of three states:
    MK_running
    MK_finishing
    MK_idle

    The subclass may supply methods to be invoked at the initialiation
    (creation), noteOn, noteOff, noteUpdate and end-of-note (noteEnd) times, as
    described below.

    MKSynthPatches are ordinarily used in conjunction with a Conducted
    performance by using a MKSynthInstrument. The MKSynthInstrument manages the allocation
    of MKSynthPatches in response to incoming MKNotes. Alternatively, MKSynthPatches
    may be used in a stand-alone fashion. In this case, you must allocate the
    MKSynthPatch by sending the MKOrchestra the -allocSynthPatch: or
    allocSynthPatch:patchTemplate: method.

  Original Author: David A. Jaffe

  Copyright (c) 1988-1992, NeXT Computer, Inc.
  Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
  Portions Copyright (c) 1994 Stanford University
  Portions Copyright (c) 1999-2001, The MusicKit Project.
*/
#ifndef __MK_SynthPatch_H___
#define __MK_SynthPatch_H___

#import <Foundation/NSObject.h>
#import <Foundation/NSArray.h>
#import "MKPatch.h"
#import "MKConductor.h"
#import "MKUnitGenerator.h"
#import "orch.h"

typedef enum _MKPhraseStatus {
    MK_phraseOn,
    MK_phraseOnPreempt,
    MK_phraseRearticulate,
    MK_phraseUpdate,
    MK_phraseOff,
    MK_phraseOffUpdate,
    MK_phraseEnd,
    MK_noPhraseActivity
} MKPhraseStatus;

@interface MKSynthPatch : MKPatch
{
    NSMutableArray *synthElements;
    id synthInstrument;
    int noteTag;
    MKSynthStatus status;
    id patchTemplate;
    BOOL isAllocated;
    MKOrchestra *orchestra;

@private
    unsigned short _whichList;  // Which list am I on?
    int _orchIndex;             // Which DSP?
    id _next;                   // Used internally for linked list of active MKSynthPatches.

    // Used to unqueue noteEnd request. If non-null, we have seen a noteOff but are not yet noteEnd.
    MKMsgStruct *_noteEndMsgPtr; 

    // Used to unqueue noteOff:aNote request. Non-null if we have seen a noteDur recently.
    // Used to remember tagged NoteOffs auto-generated from NoteDurs.
    MKMsgStruct *_noteDurMsgPtr;  

    id _sharedKey;
    MKMsgStruct *_notePreemptMsgPtr;
    short _phraseStatus;
}

+ new;
+ allocWithZone:(NSZone *)zone;
+ alloc;
- copy;
- copyWithZone:(NSZone *)zone;
 /* These methods are overridden to return [self doesNotRecognize]. 
    You never create, free or copy MKSynthPatches directly. These operations
    are always done via an MKOrchestra object. */


+ patchTemplateFor: (MKNote *) currentNote;

+ orchestraClass;

+ defaultPatchTemplate;

- synthInstrument;

- init;

- synthElementAt: (unsigned) anIndex;

- (void) mkdealloc;

- preemptFor: (MKNote *) aNote;

- noteOnSelf: (MKNote *) aNote;

- noteUpdateSelf: (MKNote *) aNote; 

- (double) noteOffSelf: (MKNote *) aNote; 

- noteEndSelf; 

- noteOn: (MKNote *) aNote; 

- noteUpdate: (MKNote *) aNote;

- (double) noteOff: (MKNote *) aNote; 

- noteEnd; 

- moved: (MKUnitGenerator *) aUG; 

- (int) status; 

- (BOOL) isEqual: (MKSynthPatch *) anObject; 

- (unsigned) hash;  

- patchTemplate;

- (int) noteTag; 

- orchestra; 

-(BOOL) isFreeable; 

- (void) dealloc; /*sb: was -free before OS conversion. Maybe I should have left it alone... */
 /* Same as dealloc */


- controllerValues: (id) controllers;

- next;

- freeSelf;

- (MKPhraseStatus) phraseStatus;

 /* -read: and -write: 
  * Note that archiving is not supported in the MKSynthPatch object, since,
  * by definition the MKSynthPatch instance only exists when it is resident on
  * a DSP.
  */

@end

@interface MKSynthPatch(PatchLoad)

+ (Class) findPatchClass: (NSString *) name;

@end

#endif

---