MKUnitGenerator.h

/*
  $Id: MKUnitGenerator.h 3447 2009-04-01 21:27:50Z leighsmith $
  Defined In: The MusicKit

  Description:
    MKUnitGenerator is an abstract class; each subclass provides a
    particular music synthesis operation or function.  A MKUnitGenerator
    object represents a DSP unit generator, a program that runs on the
    DSP.
    
    You never create MKUnitGenerator objects directly in an application,
    they can only be created by the MKOrchestra through its
    allocUnitGenerator: method.  MKUnitGenerators are typically owned by a
    MKSynthPatch, an object that configures a set of MKSynthData and
    MKUnitGenerator objects into a DSP software instrument.  The MusicKit
    provides a number of MKUnitGenerator subclasses that can be configured
    to create new MKSynthPatch classes.
    
    Most of the methods defined in the MKUnitGenerator class are subclass
    responsiblities or are provided to help define the functionality of a
    subclass.  The most important of these are runSelf, idleSelf, and
    finishSelf.  These methods implement the behavior of the object in
    response to the run, finish, and idle messages, respectively.
    
    In addition to implementing the subclass responsibility methods, you
    should also provide methods for poking values into the memory
    arguments of the DSP unit generator that the MKUnitGenerator represents.
    For example, an oscillator MKUnitGenerator would provide a setFreq:
    method to set the frequency of the unit generator that's running on
    the DSP.
    
    MKUnitGenerator subclasses are created from DSP macro code.  The utility
    dspwrap turns a DSP macro into a MKUnitGenerator master class,
    implementing some of the subclass responsibility methods.
    
    It also creates a number of classes that inherit from your
    MKUnitGenerator subclass; these are called leaf classes.  A leaf class
    represents a specific memory space configuration on the DSP.  For
    example, OnePoleUG is a one-pole filter MKUnitGenerator master class
    provided by the Music Kit.  It has an input and an output argument
    that refer to either the x or the y memory spaces on the DSP.  To
    provide for all memory space configurations, dspwrap creates the leaf
    classes OnePoleUGxx, OnePoleUGxy, OnePoleUGyx, and OnePoleUGyy.
    
    You can modify a master class (the setFreq: method mentioned above
    would be implemented in a master class), but you never create an
    instance of one.  MKUnitGenerator objects are always instances of leaf
    classes.
    

  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-2005, The MusicKit Project.
*/
#ifndef __MK_UnitGenerator_H___
#define __MK_UnitGenerator_H___

#ifndef _MK_UNITGENERATOR_H
#define _MK_UNITGENERATOR_H

#import <Foundation/NSData.h> /*sb for NSData */
#import <Foundation/NSObject.h>
#import "orch.h"

/* It's actually either MKUnitGenerator or MKSynthData, but this makes compiler happy */
#define SynthElement MKUnitGenerator 

typedef struct _MKUGArgStruct {
    MKOrchAddrStruct addrStruct;
    DSPMemorySpace addressMemSpace;
    DSPLongDatum curVal;
    BOOL initialized;
    int type;
} MKUGArgStruct;

#import "dspwrap.h"

@interface MKUnitGenerator : NSObject
{
    id synthPatch;      /* The MKSynthPatch that owns this object, if any. */
    id orchestra;       /* The MKOrchestra on which the object is allocated. */

@protected
    unsigned short _orchIndex;
    unsigned short _synthPatchLoc;
    id _sharedKey;
    BOOL _protected;
    int _instanceNumber;

    BOOL isAllocated;   /* YES if allocated */
    MKUGArgStruct *args;   /* Pointer to the first of a block of 
                             MKUGArgStructs. Each of these corresponds to 
                             a unit generator memory argment. */
    MKSynthStatus status;
    MKOrchMemStruct relocation;

    MKLeafUGStruct *_classInfo; /* Same as [[self class] classInfo]. 
                                   Stored in instance as an optimization. */ 
    id _next;                   /* For available linked lists. */
}

+new;
+ allocWithZone:(NSZone *)zone;
+alloc;
-copy;
- copyWithZone:(NSZone *)zone;

 /* These methods are overridden to return [self doesNotRecognize]. 
    You never create, free or copy MKUnitGenerators directly. These operations
    are always done via an MKOrchestra object. */

+orchestraWillCreate:anOrch;
 /* Sent by MKOrchestra before creating a new instance.  This method may be
  * overridden to do any last-minute adjustments before the MKOrchestra creates 
  * a new instance.  Default implementation does nothing.
  */

- (void)dealloc; /*sb: used to be -free before OS conversion */
 /* Same as [self dealloc]. */


+(MKMasterUGStruct *) masterUGPtr; 

+ (MKLeafUGStruct *) classInfo; 

+ (unsigned int) argCount; 

- moved; 

+ (BOOL) shouldOptimize: (unsigned) arg;

- init;

- run;

- runSelf; 

- (double) finish; 

- (double) finishSelf; 

- idle;

- idleSelf; 

- (int) status; 

- (MKOrchMemStruct *) relocation; 

- (BOOL) runsAfter: (MKUnitGenerator *) aUnitGenerator; 

- (unsigned int) argCount; 

- (MKLeafUGStruct *) classInfo; 

- (MKOrchMemStruct *) resources; 

+ (NSString *) argName: (unsigned) argNum; 

+ orchestraClass;

- orchestra; 

 /* 
 * Deallocates the receiver and frees its MKSynthPatch, if any.
 * Returns nil.
 * sb: changed from dealloc to avoid conflict with foundation kit.
 */
- (void) mkdealloc; 

- (BOOL) isFreeable; 

- synthPatch; 

- (BOOL) isAllocated; 

- setDatumArg: (unsigned) argNum to: (DSPDatum) val; 

- setDatumArg: (unsigned) argNum toLong: (DSPLongDatum *) val;

- setAddressArg: (unsigned) argNum to: (id) memoryObj; 

- setAddressArg: (unsigned) argNum toInt: (DSPAddress) address;

- setAddressArgToSink: (unsigned) argNum; 

- setAddressArgToZero: (unsigned) argNum; 

+ (DSPMemorySpace) argSpace: (unsigned) argNum; 

- freeSelf;

+ enableErrorChecking: (BOOL) yesOrNo;

- (int) referenceCount;

/* Functions that are equivalent to above methods, for speed. The first
   argument is assumed to be an instance of class MKUnitGenerator. */

id MKSetUGDatumArg(MKUnitGenerator *ug, unsigned argNum, DSPDatum value);

id MKSetUGDatumArgLong(MKUnitGenerator *ug, unsigned argNum, DSPLongDatum *value);

id MKSetUGAddressArg(MKUnitGenerator *ug, unsigned argNum, id memoryObj);

id MKSetUGAddressArgToInt(MKUnitGenerator *ug, unsigned argNum, DSPAddress address);


- writeSymbolsToStream: (NSMutableData *) s;

- (int) instanceNumber;

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

@end

#endif /* _MK_UNITGENERATOR_H  */

#endif

---