MKTimbre.h

/*
  $Id: MKTimbre.h 3449 2009-04-04 16:52:47Z leighsmith $
  Defined In: The MusicKit

  Description:
    The MusicKit supports a Timbre Data Base.  Each element in the data base
    is an MKTimbre.  MKTimbres map a timbre name to an NSArray of MKWaveTable objects
    and a parallel list of frequencies for those MKWaveTables.  The Data Base
    is initialized with an extensive set of timbres.  These timbres may be
    removed or modified, additional timbres may be added, etc.

    The waveTables list is a NSArray of MKWaveTables sorted according to
    freq, with the table corresponding to the lowest frequency first.
    freqs is a NSArray containing the frequencies corresponding to
    each MKWaveTable.  The name may be any string, but should not have a number
    in it and should not be longer than MK_MAXTIMBRENAMELEN.

    You normally create or retrieve an MKTimbre with +newTimbre:, passing the
    name of the timbre you want.  If that timbre exists, it is retrieved,
    otherwise it is created and installed in the Data Base.  Alternatively,
    you can create a new anonymous timbre with +alloc and init.  In this case,
    the timbre is not put in the Data Base until its name is set with
    -setTimbreName:.  -setTimbreName: can also be used to change the name of a
    timbre that is already in the Data Base.  -timbreName may be used to
    retrieve the name of an MKTimbre.  An anonymous timbre has a name field of
    NULL.

    The Music Kit MKSynthPatches use the Data Base by passing it a "timbre key".
    A timbre key is a timbre name with an optional integer appended to it and
    an optional 0 or 1 prepended to it. The trailing number in a timbre key
    specifies a particular table (1-based).  A leading 0 or 1 specifies use of
    freq0 or freq1 respectively to determine the appropriate MKWaveTable.
    For convenience in supporting this functionality in your own MKSynthPatch
    subclasses, we provide the function MKWaveTableForTimbreKey().

    The Data Base is stored in a NSDictionary object that maps names to
    MKTimbre objects.  This NSDictionary can be retrieved by the +timbres method.
    See <Foundation/NSDictionary.h> for how to enumerate the objects in a NSDictionary.

    An individual timbre can be written to an archive file.  Alternatively, the
    entire Data Base can be saved to an archive file using the +timbres method
    to retrieve the Data Base and then archiving that object.

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

#import <Foundation/Foundation.h>

@interface MKTimbre : NSObject
{
    NSString *timbreName;
    NSMutableArray *freqs;
    NSMutableArray *waveTables;
}

#define MK_MAXTIMBRENAMELEN 64

+ newTimbre: (NSString *) name;

-init;

- copyWithZone: (NSZone *) zone;

- addWaveTable: (MKWaveTable *) obj forFreq: (double) freq;

-removeWaveTable:(MKWaveTable *)obj;

- (MKWaveTable *) waveTableForFreq: (double) freq;

- (double) freqForWaveTable: (MKWaveTable *) obj;

- (MKWaveTable *) waveTableAt: (int) index;

- (double) freqAt: (int) index;

+ (NSDictionary *) timbres;

- setTimbreName: (NSString *) newName;

- (void) dealloc;

- (void) removeAllObjects;

- (NSString *) timbreName;

- (NSMutableArray *) waveTables;

- (NSMutableArray *) freqs;

/* Reads object from archive file. */
- (id) initWithCoder: (NSCoder *) aDecoder;

/* Writes object to archive file. */
- (void) encodeWithCoder: (NSCoder *) aCoder;

/* If name is already in use, frees newly unarchived object and returns
     existing MKTimbre for that name.   */
- awakeAfterUsingCoder: (NSCoder *) aDecoder;

MKWaveTable *MKWaveTableForTimbreKey(NSString *timbreKey, 
                                   double freq0, 
                                   double freq1);
   
@end

#endif

---