MusicKit  0.0.0
MKUnitGenerator.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     MKUnitGenerator is an abstract class; each subclass provides a
00007     particular music synthesis operation or function.  A MKUnitGenerator
00008     object represents a DSP unit generator, a program that runs on the
00009     DSP.
00010     
00011     You never create MKUnitGenerator objects directly in an application,
00012     they can only be created by the MKOrchestra through its
00013     allocUnitGenerator: method.  MKUnitGenerators are typically owned by a
00014     MKSynthPatch, an object that configures a set of MKSynthData and
00015     MKUnitGenerator objects into a DSP software instrument.  The MusicKit
00016     provides a number of MKUnitGenerator subclasses that can be configured
00017     to create new MKSynthPatch classes.
00018     
00019     Most of the methods defined in the MKUnitGenerator class are subclass
00020     responsiblities or are provided to help define the functionality of a
00021     subclass.  The most important of these are runSelf, idleSelf, and
00022     finishSelf.  These methods implement the behavior of the object in
00023     response to the run, finish, and idle messages, respectively.
00024     
00025     In addition to implementing the subclass responsibility methods, you
00026     should also provide methods for poking values into the memory
00027     arguments of the DSP unit generator that the MKUnitGenerator represents.
00028     For example, an oscillator MKUnitGenerator would provide a setFreq:
00029     method to set the frequency of the unit generator that's running on
00030     the DSP.
00031     
00032     MKUnitGenerator subclasses are created from DSP macro code.  The utility
00033     dspwrap turns a DSP macro into a MKUnitGenerator master class,
00034     implementing some of the subclass responsibility methods.
00035     
00036     It also creates a number of classes that inherit from your
00037     MKUnitGenerator subclass; these are called leaf classes.  A leaf class
00038     represents a specific memory space configuration on the DSP.  For
00039     example, OnePoleUG is a one-pole filter MKUnitGenerator master class
00040     provided by the Music Kit.  It has an input and an output argument
00041     that refer to either the x or the y memory spaces on the DSP.  To
00042     provide for all memory space configurations, dspwrap creates the leaf
00043     classes OnePoleUGxx, OnePoleUGxy, OnePoleUGyx, and OnePoleUGyy.
00044     
00045     You can modify a master class (the setFreq: method mentioned above
00046     would be implemented in a master class), but you never create an
00047     instance of one.  MKUnitGenerator objects are always instances of leaf
00048     classes.
00049     
00050 
00051   Original Author: David A. Jaffe
00052 
00053   Copyright (c) 1988-1992, NeXT Computer, Inc.
00054   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00055   Portions Copyright (c) 1994 Stanford University
00056   Portions Copyright (c) 1999-2005, The MusicKit Project.
00057 */
00142 #ifndef __MK_UnitGenerator_H___
00143 #define __MK_UnitGenerator_H___
00144 
00145 #ifndef _MK_UNITGENERATOR_H
00146 #define _MK_UNITGENERATOR_H
00147 
00148 #import <Foundation/NSData.h> /*sb for NSData */
00149 #import <Foundation/NSObject.h>
00150 #import "orch.h"
00151 
00152 /* It's actually either MKUnitGenerator or MKSynthData, but this makes compiler happy */
00153 #define SynthElement MKUnitGenerator 
00154 
00160 typedef struct _MKUGArgStruct {
00162     MKOrchAddrStruct addrStruct;
00166     DSPMemorySpace addressMemSpace;
00169     DSPLongDatum curVal;
00171     BOOL initialized;
00173     int type;
00174 } MKUGArgStruct;
00175 
00176 #import "dspwrap.h"
00177 
00178 @interface MKUnitGenerator : NSObject
00179 {
00180     id synthPatch;      /* The MKSynthPatch that owns this object, if any. */
00181     id orchestra;       /* The MKOrchestra on which the object is allocated. */
00182 
00183 @protected
00184     unsigned short _orchIndex;
00185     unsigned short _synthPatchLoc;
00186     id _sharedKey;
00187     BOOL _protected;
00188     int _instanceNumber;
00189 
00190     BOOL isAllocated;   /* YES if allocated */
00191     MKUGArgStruct *args;   /* Pointer to the first of a block of 
00192                              MKUGArgStructs. Each of these corresponds to 
00193                              a unit generator memory argment. */
00194     MKSynthStatus status;
00195     MKOrchMemStruct relocation;
00196 
00197     MKLeafUGStruct *_classInfo; /* Same as [[self class] classInfo]. 
00198                                    Stored in instance as an optimization. */ 
00199     id _next;                   /* For available linked lists. */
00200 }
00201 
00202 +new;
00203 + allocWithZone:(NSZone *)zone;
00204 +alloc;
00205 -copy;
00206 - copyWithZone:(NSZone *)zone;
00207 
00208  /* These methods are overridden to return [self doesNotRecognize]. 
00209     You never create, free or copy MKUnitGenerators directly. These operations
00210     are always done via an MKOrchestra object. */
00211 
00212 +orchestraWillCreate:anOrch;
00213  /* Sent by MKOrchestra before creating a new instance.  This method may be
00214   * overridden to do any last-minute adjustments before the MKOrchestra creates 
00215   * a new instance.  Default implementation does nothing.
00216   */
00217 
00218 - (void)dealloc; /*sb: used to be -free before OS conversion */
00219  /* Same as [self dealloc]. */
00220 
00221 
00229 +(MKMasterUGStruct *) masterUGPtr; 
00230 
00237 + (MKLeafUGStruct *) classInfo; 
00238 
00243 + (unsigned int) argCount; 
00244 
00254 - moved; 
00255 
00273 + (BOOL) shouldOptimize: (unsigned) arg;
00274 
00285 - init;
00286 
00296 - run;
00297 
00307 - runSelf; 
00308 
00318 - (double) finish; 
00319 
00327 - (double) finishSelf; 
00328 
00337 - idle;
00338 
00350 - idleSelf; 
00351 
00356 - (int) status; 
00357 
00369 - (MKOrchMemStruct *) relocation; 
00370 
00378 - (BOOL) runsAfter: (MKUnitGenerator *) aUnitGenerator; 
00379 
00386 - (unsigned int) argCount; 
00387 
00394 - (MKLeafUGStruct *) classInfo; 
00395 
00405 - (MKOrchMemStruct *) resources; 
00406 
00415 + (NSString *) argName: (unsigned) argNum; 
00416 
00426 + orchestraClass;
00427 
00432 - orchestra; 
00433 
00434  /* 
00435  * Deallocates the receiver and frees its MKSynthPatch, if any.
00436  * Returns nil.
00437  * sb: changed from dealloc to avoid conflict with foundation kit.
00438  */
00439 - (void) mkdealloc; 
00440 
00449 - (BOOL) isFreeable; 
00450 
00455 - synthPatch; 
00456 
00461 - (BOOL) isAllocated; 
00462 
00475 - setDatumArg: (unsigned) argNum to: (DSPDatum) val; 
00476 
00489 - setDatumArg: (unsigned) argNum toLong: (DSPLongDatum *) val;
00490 
00501 - setAddressArg: (unsigned) argNum to: (id) memoryObj; 
00502 
00513 - setAddressArg: (unsigned) argNum toInt: (DSPAddress) address;
00514 
00526 - setAddressArgToSink: (unsigned) argNum; 
00527 
00539 - setAddressArgToZero: (unsigned) argNum; 
00540 
00549 + (DSPMemorySpace) argSpace: (unsigned) argNum; 
00550 
00559 - freeSelf;
00560 
00571 + enableErrorChecking: (BOOL) yesOrNo;
00572 
00580 - (int) referenceCount;
00581 
00582 /* Functions that are equivalent to above methods, for speed. The first
00583    argument is assumed to be an instance of class MKUnitGenerator. */
00584 
00628 id MKSetUGDatumArg(MKUnitGenerator *ug, unsigned argNum, DSPDatum value);
00629 
00673 id MKSetUGDatumArgLong(MKUnitGenerator *ug, unsigned argNum, DSPLongDatum *value);
00674 
00711 id MKSetUGAddressArg(MKUnitGenerator *ug, unsigned argNum, id memoryObj);
00712 
00748 id MKSetUGAddressArgToInt(MKUnitGenerator *ug, unsigned argNum, DSPAddress address);
00749 
00750 
00759 - writeSymbolsToStream: (NSMutableData *) s;
00760 
00769 - (int) instanceNumber;
00770 
00771  /* -read: and -write: 
00772   * Note that archiving is not supported in the MKUnitGenerator object, since,
00773   * by definition the MKUnitGenerator instance only exists when it is resident on
00774   * a DSP.
00775   */
00776 
00777 @end
00778 
00779 #endif /* _MK_UNITGENERATOR_H  */
00780 
00781 #endif