MusicKit  0.0.0
MKPatchTemplate.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     A MKPatchTemplate is a recipe for building a MKSynthPatch object.  It
00007     contains specifications for the MKUnitGenerator and MKSynthData objects
00008     that are needed and instructions for connecting these objects
00009     together.
00010 
00011     MKPatchTemplate's addUnitGenerator:ordered: and addSynthData:length:
00012     methods describe the objects that make up the MKSynthPatch.  It's
00013     important to keep in mind that these methods don't add actual objects
00014     to the MKPatchTemplate.  Instead, they specify the types of objects that
00015     will be created when the MKSynthPatch is constructed by the MKOrchestra.
00016 
00017     A MKPatchTemplate's MKUnitGenerators are specified by their class, given
00018     as the first argument to the addUnitGenerator:ordered: method.  The
00019     argument should be a MKUnitGenerator leaf class, not a master class
00020     (leaf and master classes are explained in the MKUnitGenerator class
00021     description).
00022 
00023     The MKUnitGenerator is further described as being ordered or unordered,
00024     as the argument to the ordered: keyword is YES or NO.  Ordered
00025     MKUnitGenerators are executed (on the DSP) in the order that they're
00026     added to the MKPatchTemplate; unordered MKUnitGenerators are executed in
00027     an undetermined order.  Usually, the order in which MKUnitGenerators are
00028     executed is significant; for example, if the output of MKUnitGenerator A
00029     is read by MKUnitGenerator B, then A must be executed before B if no
00030     delay is to be incurred.  As a convenience, the addUnitGenerator:
00031     method is provided to add MKUnitGenerators that are automatically
00032     declared as ordered.  The advantage of unordered MKUnitGenerators is
00033     that their allocation is less constrained.
00034   
00035     MKSynthDatas are specified by a DSP memory segment and a length.  The
00036     memory segment is given as the first argument to addSynthData:length:.
00037     This can be either MK_xData, for x data memory, or MK_yData, for y
00038     data memory.  Which memory segment to specify depends on where the
00039     MKUnitGenerators that access it expects it to be.  The argument to the
00040     length: keyword specifies the size of the MKSynthData, or how much DSP
00041     memory it represents, and is given as DSPDatum (24-bit) words.
00042   
00043     A typical use of a MKSynthData is to create a location called a
00044     patchpoint that's written to by one MKUnitGenerator and then read by
00045     another.  A patchpoint, which is always 8 words long, is ordinarily
00046     the only way that two MKUnitGenerators can communicate.  The
00047     addPatchPoint: method is provided as a convenient way to add
00048     MKSynthDatas that are used as patchpoints.  The argument to this method
00049     is either MK_xPatch or MK_yPatch, for x and y patchpoint memory,
00050     respectively.
00051   
00052     The four object-adding methods return a unique integer that identifies
00053     the added MKUnitGenerator or MKSynthData.
00054   
00055     Once you have added the requisite synthesis elements to a
00056     MKPatchTemplate, you can specify how they are connected.  This is done
00057     through invocations of the to:sel:arg: method.  The first argument is
00058     an integer that identifies a MKUnitGenerator (such as returned by
00059     addUnitGenerator:), the last argument is an integer that identifies a
00060     MKSynthData (or patchpoint).  The argument to the sel: keyword is a
00061     selector that's implemented by the MKUnitGenerator and that takes a
00062     MKSynthData object as its only argument.  Typical selectors are
00063     setInput: (the MKUnitGenerator reads from the MKSynthData) and setOuput:
00064     (it writes to the MKSynthData).  Notice that you can't connect a
00065     MKUnitGenerator directly to another MKUnitGenerator.
00066   
00067     CF: MKUnitGenerator, MKSynthData, MKSynthPatch
00068 
00069   Original Author: David A. Jaffe
00070 
00071   Copyright (c) 1988-1992, NeXT Computer, Inc.
00072   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00073   Portions Copyright (c) 1994 Stanford University.
00074   Portions Copyright (c) 1999-2001, The MusicKit Project.
00075 */
00136 #ifndef __MK_PatchTemplate_H___
00137 #define __MK_PatchTemplate_H___
00138 
00139 #import <Foundation/NSObject.h>
00140 
00141 @interface MKPatchTemplate : NSObject
00142 {    
00143     /* All MKPatchTemplate instance variables are for internal use only */
00144 @private
00145     NSMutableArray *_elementStorage;         /* Array of template entries */
00146     NSMutableArray *_connectionStorage;      /* Array of MKPatchConnection objects of connection info */
00147     /* If MKOrchestra is loaded, this is an array of NSMutableArrays of deallocated patches, one per DSP. */
00148     NSMutableArray **_deallocatedPatches;
00149     unsigned int _eMemSegments; /* External memory segment bit vector */
00150 }
00151 
00156 - init;
00157 
00162 - copyWithZone: (NSZone *) zone;
00163 
00179 - to: (unsigned) anObjInt sel: (SEL) aSelector arg: (unsigned) anArgInt; 
00180 
00193 - (unsigned) addUnitGenerator: (id) aUGClass ordered: (BOOL) isOrdered; 
00194 
00202 - (unsigned) addUnitGenerator: (id) aUGClass; 
00203 
00213 - (unsigned) addSynthData: (MKOrchMemSegment) segment length: (unsigned) len; 
00214 
00224 - (unsigned) addPatchpoint: (MKOrchMemSegment) segment;
00225 
00231 - (unsigned) synthElementCount;
00232 
00233 /* 
00234  You never send this message directly.  
00235 */
00236 - (void) encodeWithCoder: (NSCoder *) aCoder;
00237 
00238 /* 
00239  You never send this message directly.  
00240  Should be invoked via NXReadObject(). 
00241  See write:. 
00242 */
00243 - (id) initWithCoder: (NSCoder *) aDecoder;
00244 
00245 @end
00246 
00247 #endif