MKWaveTable Class Reference
A MKWaveTable represents a single period of a sound waveform as a series of samples. More...
#import <MKWaveTable.h>
Public Member Functions | |
| (id) | - copyWithZone: |
| Creates and returns a new MKWaveTable as a copy of the receiver. | |
| (id) | - init |
| Initializes the receiver. | |
| (void) | - dealloc |
| dealloc frees dataDSP and dataDouble then sends [super free]. | |
| (unsigned int) | - length |
| Returns the length, in elements, of the data arrays (the two arrays should always contain the same number of elements). | |
| (double) | - scaling |
| Returns the factor by which the values (sample amplitues) in the data arrays are scaled. | |
| (DSPDatum *) | - dataDSPLength:scale: |
| Returns a pointer to the receiver's dataDSP array, recomputing the data if necessary (as defined in the class description). | |
| (double *) | - dataDoubleLength:scale: |
| Returns a pointer to the receiver's dataDouble array, recomputing the data if necessary (as defined in the class description). | |
| (DSPDatum *) | - dataDSP |
| Returns a pointer to the receiver's dataDSP array. | |
| (DSPDatum *) | - dataDSPLength: |
| Returns a pointer to the receiver's dataDSP array. | |
| (DSPDatum *) | - dataDSPScale: |
| Returns a pointer to the receiver's dataDSP array. | |
| (double *) | - dataDouble |
| Returns a pointer to the receiver's dataDouble array. | |
| (double *) | - dataDoubleLength: |
| Returns a pointer to the receiver's dataDouble array. | |
| (double *) | - dataDoubleScale: |
| Returns a pointer to the receiver's dataDouble array. | |
| (id) | - fillTableLength:scale: |
| Computes the receiver's data, sizing and scaling according to the arguments. | |
Detailed Description
A MKWaveTable represents a single period of a sound waveform as a series of samples.MKWaveTable is an abstract class that's succeeded by two inheriting classes: MKSamples and MKPartials. The MKSamples subclass lets you define a MKWaveTable through association with a Sound object or soundfile; MKPartials lets you build a waveform by adding sine wave components. If you're interested in using Wavetables to create a library of timbres you should refer to the descriptions of the MKSamples and MKPartials subclasses. Detailed familiarity with the MKWaveTable class, in this case, isn't necessary.
MKWaveTable objects are designed to be used as lookup tables for oscillator MKUnitGenerators such as OscgafiUG. When it's instructed to run, the oscillator downloads the WaveTable's data to a portion of memory on the DSP and then cycles over the data to generate a timbre that's defined by the shape of the waveform that the data represents. To assist this process, a MKWaveTable object maintains two separate arrays of data pointed to by the dataDSP and dataDouble
A MKWaveTable contain an array of data that's used by a MKUnitGenerator object as a lookup table. The Music Kit provides two subclasses of this absract class: MKPartials, and MKSamples.
Access to the data is through one of the data: methods. The method used depends on the data type needed (type DSPDatum (i.e., for the DSP) or type double), the scaling needed and the length of the array needed. If necessary, the subclass is called upon to recompute the data. These methods do not copy the data. Thus, the caller should not free or alter the array of data. The need to recompute is recognized on the basis of whether the length or scaling instance variables have changed. The subclass can signal that a recomputation is needed by setting length to 0.
The computation of the data is handled by the subclass method fillTableLength:scale:.
Subclasses provided by the MusicKit are:
-
MKPartials computes a MKWaveTable given an arrays of harmonic amplitudes, frequency ratios, and phases.
- MKSamples stores a MKWaveTable of existing samples read in from a Sound object or soundfile.
The MKWaveTable class caches multiple formats for the data. This is useful because it is expensive to recompute the data. Access to the data is through one of the "data" methods (-dataDSP, -dataDouble, etc.). The method used depends on the data type needed (type DSPDatum for the DSP or type double), the scaling needed, and the length of the array needed. The caller should not free nor alter the array of data.
If necessary, the subclass is called upon to recompute the data. The computation of the data is handled by the subclass method fillTableLength:scale:.
Member Function Documentation
| - (id) copyWithZone: | (NSZone *) | zone |
Creates and returns a new MKWaveTable as a copy of the receiver.
- Returns:
- Returns an id.
Reimplemented in MKPartials, and MKSamples.
| - (id) init |
Initializes the receiver.
This method should be invoked when a new MKWaveTable is created. You can also use it to reset, or empty, an existing object. If you override this method in a subclass, you should include [super init] in the implementation. Returns the receiver.
- Returns:
- Returns an id.
Reimplemented in MKPartials, and MKSamples.
| - (void) dealloc |
dealloc frees dataDSP and dataDouble then sends [super free].
It also removes the name, if any, from the MusicKit name table.
Reimplemented in MKPartials, and MKSamples.
| - (unsigned int) length |
Returns the length, in elements, of the data arrays (the two arrays should always contain the same number of elements).
- Returns:
- Returns an int. A return value of 0 indicates that the arrays haven't been filled, or that the data needs to be recomputed.
| - (double) scaling |
Returns the factor by which the values (sample amplitues) in the data arrays are scaled.
- Returns:
- Returns a double. A return value of 0.0, the default, indicates that the values are normalized, or scaled to fit perfectly within the range -1.0 to 1.0.
| - (DSPDatum *) dataDSPLength: | (unsigned int) | aLength | ||
| scale: | (double) | aScaling | ||
Returns a pointer to the receiver's dataDSP array, recomputing the data if necessary (as defined in the class description).
- Parameters:
-
aLength is an int. aScaling is a double.
- Returns:
- Returns a DSPDatum *. Returns the wavetable as an array of DSPDatums, recomputing the data if necessary at the requested scaling and length. If the subclass has no data, returns NULL. The data should neither be modified nor freed by the sender. The array is sized and scaled according to the arguments and the length and scaling instance variables are set to these values. If the receiver can't fill the array, NULL is returned. You should neither modify nor free the data returned by this method.
| - (double *) dataDoubleLength: | (unsigned int) | aLength | ||
| scale: | (double) | aScaling | ||
Returns a pointer to the receiver's dataDouble array, recomputing the data if necessary (as defined in the class description).
- Parameters:
-
aLength is an int. aScaling is a double.
- Returns:
- Returns a double *. Returns the MKWaveTable as an array of doubles, recomputing the data if necessary at the requested scaling and length. If the subclass has no data, returns NULL. The data should neither be modified nor freed by the sender. The array is sized and scaled according to the arguments and the length and scaling instance variables are set to these values. If the array cna't be filled, NULL is returned. You should neither modify nor free the data returned by this method.
| - (DSPDatum *) dataDSP |
Returns a pointer to the receiver's dataDSP array.
- Returns:
- Returns a DSPDatum *. Implemented as an invocation of dataDSPLength:scale:, with the length and scaling instance variables as arguments.
| - (DSPDatum *) dataDSPLength: | (int) | aLength |
Returns a pointer to the receiver's dataDSP array.
- Parameters:
-
aLength is an int.
- Returns:
- Returns a DSPDatum *. Implemented as an invocation of dataDSPLength:scale:, with aLength and the scaling instance variable as arguments.
| - (DSPDatum *) dataDSPScale: | (double) | aScaling |
Returns a pointer to the receiver's dataDSP array.
- Parameters:
-
aScaling is a double.
- Returns:
- Returns a DSPDatum *. Implemented as an invocation of dataDSPLength:scale:, with the length instance variable and aScaling as arguments.
| - (double *) dataDouble |
Returns a pointer to the receiver's dataDouble array.
- Returns:
- Returns a double *. Implemented as an invocation of dataDoubleLength:scale:, with the length and scaling instance variables as arguments.
| - (double *) dataDoubleLength: | (int) | aLength |
Returns a pointer to the receiver's dataDouble array.
- Parameters:
-
aLength is an int.
- Returns:
- Returns a double *. Implemented as an invocation of dataDoubleLength:scale:, with aLength and the scaling instance variable as arguments.
| - (double *) dataDoubleScale: | (double) | aScaling |
Returns a pointer to the receiver's dataDouble array.
- Parameters:
-
aScaling is a double.
- Returns:
- Returns a double *. Implemented as an invocation of dataDoubleLength:scale:, with the length instance variable and aScaling as arguments.
| - (id) fillTableLength: | (int) | aLength | ||
| scale: | (double) | aScaling | ||
Computes the receiver's data, sizing and scaling according to the arguments.
- Parameters:
-
aLength is an int. aScaling is a double.
- Returns:
- Returns an id. This is a subclass responsibility method; a subclass can implement the method to fill the dataDSP array, the dataDouble array, or both. If only one of the arrays is computed and filled, the other should be freed and its pointer set to NULL. If the data can't be computed, both arrays should be freed and nil returned. Otherwise, the receiver should be returned.
The documentation for this class was generated from the following file:
