MusicKit  0.0.0
MKSynthData.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     MKSynthData objects represent DSP memory that's used in music synthesis.
00007     For example, you can use a MKSynthData object to load predefined data
00008     for wavetable synthesis or to store DSP-computed data to create a
00009     digital delay.  Perhaps the most common use of MKSynthData is to create
00010     a location through which MKUnitGenerators can pass data.  This type of
00011     MKSynthData object is called a patchpoint.  For example, in frequency
00012     modulation an oscillator MKUnitGenerator writes its output to a
00013     patchpoint which can then be read by another oscillator as its
00014     frequency input.
00015    
00016     You never create MKSynthData objects directly in an application, they
00017     can only be created by the MKOrchestra through its
00018     allocSynthData:length: or allocPatchpoint: methods.  MKSynthData objects
00019     are typically owned by a MKSynthPatch, an object that configures a set
00020     of MKSynthData and MKUnitGenerator objects into a DSP software instrument.
00021    
00022     The methods setData: and setToConstant: are used to load a MKSynthData
00023     object with data from an array or as a constant, respectively.  These
00024     methods are simple versions of the more thorough methods
00025     setData:length:offset: and setToConstant:length:offset:, which allow you
00026     to load an arbitrary amount of data into any portion of the
00027     MKSynthData's memory.  The data in a MKSynthData object, like all DSP data
00028     used in music synthesis, is 24-bit fixed point words (data type
00029     DSPDatum).  You can declare a MKSynthData to be read-only by sending it
00030     the message setReadOnly:YES.  You can't change the data in a read-only
00031     MKSynthData object.
00032    
00033     An instance of MKSynthData consists of an MKOrchAddrStruct, a structure
00034     that describes the DSP location of the object's data, and a length
00035     instance variable, an integer value that measures the size of the data
00036     in DSPDatum words.  However, it doesn't contain a copy of the memory
00037     itself.  When you load data into a MKSynthData, it's instantly sent to
00038     the DSP device driver.
00039    
00040     DSP memory allocation and management is explained in the MKOrchestra
00041     class description; many of the return types used here, such as
00042     DSPAddress and DSPMemorySpace, are described in MKOrchestra.  In
00043     general, the design of the MKOrchestra makes intimate knowledge of the
00044     details of the DSP unnecessary.
00045    
00046     CF: MKSynthPatch, MKOrchestra, MKUnitGenerator
00047 
00048   Original Author: David A. Jaffe
00049 
00050   Copyright (c) 1988-1992, NeXT Computer, Inc.
00051   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00052   Portions Copyright (c) 1994 Stanford University  
00053   Portions Copyright (c) 1999-2001, The MusicKit Project.
00054 */
00097 #ifndef __MK_SynthData_H___
00098 #define __MK_SynthData_H___
00099 
00100 #import <Foundation/NSObject.h>
00101 
00102 @interface MKSynthData : NSObject
00103 {
00104     /* DO NOT CHANGE THE POSITION OF THE FOLLOWING BLOCK OF IVARS! */
00105     id synthPatch;      /* The MKSynthPatch that owns this object (if any). */
00106     id orchestra;       /* The orchestra on which the SynthElement object is allocated. */
00107 
00108 @private
00109     unsigned short _orchIndex;
00110     unsigned short _synthPatchLoc;
00111     id _sharedKey;
00112     BOOL _protected;
00113     int _instanceNumber;
00114     /* END OF INVARIANT IVARS */
00115 
00116     unsigned int length;       /* Length of allocated memory in words. */
00117     MKOrchAddrStruct orchAddr; /* Structure that directly represents DSP memory. Contains size, space, etc.*/
00118     BOOL readOnly;             /* YES if the object's data is read-only. */
00119 
00120     MKOrchMemStruct _reso;     /* Each instance has its own here */
00121     BOOL isModulus;
00122 }
00123 
00124 +new;
00125 + allocWithZone:(NSZone *)zone;
00126 +alloc;
00127 -copy;
00128 
00129 - copyWithZone:(NSZone *)zone;
00130  /* These methods are overridden to return [self doesNotRecognize]. 
00131     You never create, free or copy MKUnitGenerators directly. These operations
00132     are always done via an MKOrchestra object. */
00133 
00134 - (void) dealloc; /* was "free" before conversion */
00135  /* Same as [self dealloc]. */
00136 
00137 
00142 - clear; 
00143 
00148 - (unsigned int) length; 
00149 
00154 - (DSPAddress) address; 
00155 
00160 - (DSPMemorySpace) memorySpace; 
00161 
00166 - (MKOrchAddrStruct *) orchAddrPtr; 
00167 
00168 - (BOOL) isModulus;
00169 
00184 - setData: (DSPDatum *) dataArray length: (unsigned int) len offset: (int) off; 
00185 
00200 - setShortData: (short *) dataArray length: (unsigned int) len offset: (int) off;
00201 
00214 - setData: (DSPDatum *) dataArray; 
00215 
00228 - setShortData: (short *) dataArray;
00229 
00239 - setToConstant: (DSPDatum) value length: (unsigned int) len offset: (int) off; 
00240 
00252 - setToConstant: (DSPDatum) value;    
00253 
00262 - run;
00263 
00272 - idle;
00273 
00283 - (double) finish;
00284 
00295 + orchestraClass;
00296 
00301 - orchestra; 
00302 
00303 /* 
00304   Deallocates the receiver and frees its MKSynthPatch, if any. Returns nil.
00305   sb: was dealloc, but this may differ from OpenStep's
00306   ideas of dealloc. I have changed things here and
00307   in MKSynthPatch h/m, MKUnitGenerator.h (not m), and in
00308   synthElementMethods.m
00309  */
00310 - (void) mkdealloc;     
00311 
00312 
00319 - (BOOL) isAllocated;
00320 
00329 - (BOOL) isFreeable; 
00330 
00335 - synthPatch; 
00336 
00347 - setReadOnly: (BOOL) readOnlyFlag;
00348 
00353 - (BOOL) readOnly;
00354 
00362 - (int) referenceCount;
00363 
00364  /* -read: and -write: 
00365   * Note that archiving is not supported in the MKSynthData object, since,
00366   * by definition the MKSynthData instance only exists when it is resident on
00367   * a DSP.
00368   */
00369 
00370 
00386 - readDataUntimed: (DSPDatum *) dataArray length: (unsigned int) len offset: (int) off;
00387 
00397 - readShortDataUntimed: (short *) dataArray length: (unsigned int) len offset: (int) off;
00398 
00399 @end
00400 
00401 
00402 
00403 #endif