MusicKit  0.0.0
MKTimbre.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     The MusicKit supports a Timbre Data Base.  Each element in the data base
00007     is an MKTimbre.  MKTimbres map a timbre name to an NSArray of MKWaveTable objects
00008     and a parallel list of frequencies for those MKWaveTables.  The Data Base
00009     is initialized with an extensive set of timbres.  These timbres may be
00010     removed or modified, additional timbres may be added, etc.
00011 
00012     The waveTables list is a NSArray of MKWaveTables sorted according to
00013     freq, with the table corresponding to the lowest frequency first.
00014     freqs is a NSArray containing the frequencies corresponding to
00015     each MKWaveTable.  The name may be any string, but should not have a number
00016     in it and should not be longer than MK_MAXTIMBRENAMELEN.
00017 
00018     You normally create or retrieve an MKTimbre with +newTimbre:, passing the
00019     name of the timbre you want.  If that timbre exists, it is retrieved,
00020     otherwise it is created and installed in the Data Base.  Alternatively,
00021     you can create a new anonymous timbre with +alloc and init.  In this case,
00022     the timbre is not put in the Data Base until its name is set with
00023     -setTimbreName:.  -setTimbreName: can also be used to change the name of a
00024     timbre that is already in the Data Base.  -timbreName may be used to
00025     retrieve the name of an MKTimbre.  An anonymous timbre has a name field of
00026     NULL.
00027 
00028     The Music Kit MKSynthPatches use the Data Base by passing it a "timbre key".
00029     A timbre key is a timbre name with an optional integer appended to it and
00030     an optional 0 or 1 prepended to it. The trailing number in a timbre key
00031     specifies a particular table (1-based).  A leading 0 or 1 specifies use of
00032     freq0 or freq1 respectively to determine the appropriate MKWaveTable.
00033     For convenience in supporting this functionality in your own MKSynthPatch
00034     subclasses, we provide the function MKWaveTableForTimbreKey().
00035 
00036     The Data Base is stored in a NSDictionary object that maps names to
00037     MKTimbre objects.  This NSDictionary can be retrieved by the +timbres method.
00038     See <Foundation/NSDictionary.h> for how to enumerate the objects in a NSDictionary.
00039 
00040     An individual timbre can be written to an archive file.  Alternatively, the
00041     entire Data Base can be saved to an archive file using the +timbres method
00042     to retrieve the Data Base and then archiving that object.
00043 
00044   Original Author: David A. Jaffe
00045 
00046   Copyright (c) 1988-1992, NeXT Computer, Inc.
00047   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00048   Portions Copyright (c) 1994 Stanford University  
00049   Portions Copyright (c) 1999-2001, The MusicKit Project.
00050 */
00096 #ifndef __MK_Timbre_H___
00097 #define __MK_Timbre_H___
00098 
00099 #import <Foundation/Foundation.h>
00100 
00101 @interface MKTimbre : NSObject
00102 {
00104     NSString *timbreName;
00106     NSMutableArray *freqs;
00108     NSMutableArray *waveTables;
00109 }
00110 
00112 #define MK_MAXTIMBRENAMELEN 64
00113 
00119 + newTimbre: (NSString *) name;
00120 
00125 -init;
00126 
00132 - copyWithZone: (NSZone *) zone;
00133 
00143 - addWaveTable: (MKWaveTable *) obj forFreq: (double) freq;
00144 
00152 -removeWaveTable:(MKWaveTable *)obj;
00153 
00160 - (MKWaveTable *) waveTableForFreq: (double) freq;
00161 
00169 - (double) freqForWaveTable: (MKWaveTable *) obj;
00170 
00178 - (MKWaveTable *) waveTableAt: (int) index;
00179 
00187 - (double) freqAt: (int) index;
00188 
00197 + (NSDictionary *) timbres;
00198 
00204 - setTimbreName: (NSString *) newName;
00205 
00209 - (void) dealloc;
00210 
00214 - (void) removeAllObjects;
00215 
00222 - (NSString *) timbreName;
00223 
00230 - (NSMutableArray *) waveTables;
00231 
00238 - (NSMutableArray *) freqs;
00239 
00240 /* Reads object from archive file. */
00241 - (id) initWithCoder: (NSCoder *) aDecoder;
00242 
00243 /* Writes object to archive file. */
00244 - (void) encodeWithCoder: (NSCoder *) aCoder;
00245 
00246 /* If name is already in use, frees newly unarchived object and returns
00247      existing MKTimbre for that name.   */
00248 - awakeAfterUsingCoder: (NSCoder *) aDecoder;
00249 
00263 MKWaveTable *MKWaveTableForTimbreKey(NSString *timbreKey, 
00264                                    double freq0, 
00265                                    double freq1);
00266    
00267 @end
00268 
00269 #endif