#import <MKTimbre.h>
Public Member Functions | |
| (id) | - init |
| Initialize timbre to be a new anonymous timbre. | |
| (id) | - copyWithZone: |
| (id) | - addWaveTable:forFreq: |
| Add the specified MKWaveTable/frequency pair. | |
| (id) | - removeWaveTable: |
| Removes the given MKWaveTable and its corresponding frequency. | |
| (MKWaveTable *) | - waveTableForFreq: |
| Returns the MKWaveTable object corresponding to the specified freq, if any. | |
| (double) | - freqForWaveTable: |
| Returns the freq corresponding to the specified freq, if any. | |
| (MKWaveTable *) | - waveTableAt: |
| Returns the MKWaveTable object corresponding to the specified index, if any. | |
| (double) | - freqAt: |
| Returns the freq corresponding to the specified index, if any. | |
| (id) | - setTimbreName: |
| if successful or nil if newName is already in use. | |
| (void) | - dealloc |
| Frees receiver and removes it from Data Base. Frees WaveTables. | |
| (void) | - removeAllObjects |
| Empties the MKWaveTable and freqs NSArrays. | |
| (NSString *) | - timbreName |
| Returns timbreName. | |
| (NSMutableArray *) | - waveTables |
| Returns waveTables object. | |
| (NSMutableArray *) | - freqs |
| Returns freqs. | |
| (MKWaveTable *) | - MKWaveTableForTimbreKey |
| Extracts the timbre name from timbreKey (by removing leading and trailing numbers) and looks up that name in the Data Base. | |
Static Public Member Functions | |
| (id) | + newTimbre: |
| Retrieve timbre if it exists, otherwise create it and install it in Data Base. | |
| (NSDictionary *) | + timbres |
| Returns the timbre data base, a NSDictionary mapping names to MKTimbres. | |
Protected Attributes | |
| NSString * | timbreName |
| NSMutableArray * | freqs |
| NSMutableArray * | waveTables |
Each MKTimbre maps a timbre name to a 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 List object of WaveTables sorted according to frequency. The table that corresponds to the lowest frequency is first in the List. freqs is a NSMutableArray object containing the frequencies corresponding to each MKWaveTable. The timbreName may be any string, but should not have a number in it and should not be longer than MK_MAXTIMBRENAMELEN, which is defined in MKTimbre.h.
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 MusicKit 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 the freq0 or freq1 parameter, respectively, to determine the appropriate MKWaveTable. For convenience in supporting this functionality in your own MKSynthPatch subclasses, we provide the function MKWaveTableForTimbreKey (MKTimbre).
The Data Base is stored in a HashTable object that maps names to MKTimbre objects. This HashTable can be retrieved by the +timbres method. See <objc/HashTable.h> for how to enumerate the objects in a HashTable.
An individual timbre can be written to an archive file. Alternatively, the entire database can be saved to an archive file using the +timbres method to retrieve the database and then archiving that object.
| + (id) newTimbre: | (NSString *) | name |
Retrieve timbre if it exists, otherwise create it and install it in Data Base.
| name | is an NSString. |
| - (id) init |
Initialize timbre to be a new anonymous timbre.
| - (id) copyWithZone: | (NSZone *) | zone |
Abrief Copy timbre from specified zone.
The new timbre is "anonymous", i.e. it's name is NULL.
| - (id) addWaveTable: | (MKWaveTable *) | obj | ||
| forFreq: | (double) | freq | ||
Add the specified MKWaveTable/frequency pair.
For speed, no check is made as to whether the given MKWaveTable is already present. If you're not sure, send removeWaveTable: first.
| obj | is a MKWaveTable *. | |
| freq | is a double. |
| - (id) removeWaveTable: | (MKWaveTable *) | obj |
Removes the given MKWaveTable and its corresponding frequency.
Returns nil if the obj is not found, otherwise self.
| obj | is a MKWaveTable *. |
| - (MKWaveTable *) waveTableForFreq: | (double) | freq |
Returns the MKWaveTable object corresponding to the specified freq, if any.
| freq | is a double. |
| - (double) freqForWaveTable: | (MKWaveTable *) | obj |
Returns the freq corresponding to the specified freq, if any.
Returns MK_NODVAL if none.
| obj | is a MKWaveTable *. |
| - (MKWaveTable *) waveTableAt: | (int) | index |
Returns the MKWaveTable object corresponding to the specified index, if any.
Index is zero-based.
| index | is an int. |
| - (double) freqAt: | (int) | index |
Returns the freq corresponding to the specified index, if any.
Otherwise, returns MK_NODVAL. Index is zero-based.
| index | is an int. |
| + (NSDictionary *) timbres |
| - (id) setTimbreName: | (NSString *) | newName |
if successful or nil if newName is already in use.
| newName | is a NSString instance. |
| - (NSString *) timbreName |
Returns timbreName.
The string is not copied and should not be altered or freed.
| - (NSMutableArray *) waveTables |
Returns waveTables object.
The NSMutableArray is not copied and should not be altered.
| - (NSMutableArray *) freqs |
Returns freqs.
freqs NSMutableArray is not copied.
| - (MKWaveTable*) MKWaveTableForTimbreKey | (NSString *) | timbreKey | ||
| (double) | freq0 | |||
| (double) | freq1 | |||
Extracts the timbre name from timbreKey (by removing leading and trailing numbers) and looks up that name in the Data Base.
If there is a no timbre with that name, returns nil. Otherwise, looks for a trailing number in the timbreKey. If there is one, uses this as a 1-based index into the List of WaveTables and returns that MKWaveTable. Otherwise, looks for a 0 or 1 prepended to the timbreKey. If there is one, uses this to determine whether freq0 or freq1 is to be used to chose the MKWaveTable. If no number is prepended, uses freq1. Returns the MKWaveTable with frequency greater than or equal to the specified frequency.
- (NSString*) timbreName [protected] |
Name of this timbre
- (NSMutableArray*) freqs [protected] |
Array object of frequencies
- (NSMutableArray*) waveTables [protected] |
Array object of MKWaveTables
1.5.6