#import <MKSynthData.h>
Public Member Functions | |
| (id) | - clear |
| Clears the receiver's memory but doesn't deallocate it. | |
| (unsigned int) | - length |
| Returns the size (in words) of the receiver's memory block. | |
| (DSPAddress) | - address |
| Returns the DSP address of the receiver's memory block. | |
| (DSPMemorySpace) | - memorySpace |
| Returns the DSP space in which the receiver's memory block is allocated. | |
| (MKOrchAddrStruct *) | - orchAddrPtr |
| Returns a pointer to the receiver's address structure. | |
| (id) | - setData:length:offset: |
| Loads (at most) len words of data from dataArray into the receiver's memory, starting at location off words from the beginning of the receiver's memory block. | |
| (id) | - setShortData:length:offset: |
| Loads (at most) len words of data from dataArray into the receiver's memory, right justified, starting at location off words from the beginning of the receiver's memory block. | |
| (id) | - setData: |
| Loads dataArray into the receiver's memory. | |
| (id) | - setShortData: |
| Loads dataArray into the receiver's memory, right justified. | |
| (id) | - setToConstant:length:offset: |
| Similar to setData:length:offset:, but loads the constant value rather than an array; see setData:length:offset: for details. | |
| (id) | - setToConstant: |
| Fills the receiver's memory with the constant value. | |
| (id) | - run |
| This does nothing and returns the receiver. | |
| (id) | - idle |
| This does nothing and returns the receiver. | |
| (double) | - finish |
| This does nothing and returns 0.0. | |
| (id) | - orchestra |
| Returns the receiver's MKOrchestra object. | |
| (BOOL) | - isAllocated |
| Provided for compatability with MKUnitGenerator. | |
| (BOOL) | - isFreeable |
| Invoked by the MKOrchestra to determine whether the receiver may be freed. | |
| (id) | - synthPatch |
| Returns the MKSynthPatch that the receiver is part of, if any. | |
| (id) | - setReadOnly: |
| Sets the receiver to read-only if readOnlyFlag is YES and read-write if it's NO. | |
| (BOOL) | - readOnly |
| Returns YES if the receiver is read-only. | |
| (int) | - referenceCount |
| If the receiver is installed in its MKOrchestra's shared object table, this returns the number of objects that have allocated it. | |
| (id) | - readDataUntimed:length:offset: |
| Queries the DSP for the value of the given DSP memory. | |
| (id) | - readShortDataUntimed:length:offset: |
| Queries the DSP for the value of the given DSP memory. | |
Static Public Member Functions | |
| (id) | + orchestraClass |
| This method always returns the id of the MKOrchestra class. | |
For example, you can use a MKSynthData object to load predefined data for wavetable synthesis or to store DSP-computed data to create a digital delay. Perhaps the most common use of MKSynthData is to create a location through which MKUnitGenerators can pass data. This type of MKSynthData object is called a patchpoint. For example, in frequency modulation an oscillator MKUnitGenerator writes its output to a patchpoint which can then be read by another oscillator as its frequency input.
You never create MKSynthData objects directly in an application, they can only be created by the MKOrchestra through its allocSynthData:length: or allocPatchpoint: methods. MKSynthData objects are typically owned by a MKSynthPatch, an object that configures a set of MKSynthData and MKUnitGenerator objects into a DSP software instrument.
The methods setData: and setConstant: are used to load a MKSynthData object with data from an array or as a constant, respectively. These methods are simple versions of the more thorough methods setData:length:offset: and setConstant:length:offset:, which allow you to load an arbitrary amount of data into any portion of the SynthData's memory. The data in a MKSynthData object, like all DSP data used in music synthesis, is 24-bit fixed point words (data type DSPDatum). You can declare a MKSynthData to be read-only by sending it the message setReadOnly:YES. You can't change the data in a read-only MKSynthData object.
An instance of MKSynthData consists of an MKOrchAddrStruct, a structure that describes the DSP location of the object's data, and a length instance variable, an integer value that measures the size of the data in DSPDatum words. However, it doesn't contain a copy of the memory itself. When you load data into a MKSynthData, it's instantly sent to the DSP device driver.
DSP memory allocation and management is explained in the MKOrchestra class description; many of the return types used here, such as DSPAddress and DSPMemorySpace, are described in MKOrchestra. In general, the design of the MKOrchestra makes intimate knowledge of the details of the DSP unnecessary.
| - (id) clear |
Clears the receiver's memory but doesn't deallocate it.
| - (unsigned int) length |
Returns the size (in words) of the receiver's memory block.
| - (DSPAddress) address |
Returns the DSP address of the receiver's memory block.
| - (DSPMemorySpace) memorySpace |
Returns the DSP space in which the receiver's memory block is allocated.
| - (MKOrchAddrStruct *) orchAddrPtr |
Returns a pointer to the receiver's address structure.
| - (id) setData: | (DSPDatum *) | dataArray | ||
| length: | (unsigned int) | len | ||
| offset: | (int) | off | ||
Loads (at most) len words of data from dataArray into the receiver's memory, starting at location off words from the beginning of the receiver's memory block.
If off + len is greater than the receiver's length (as returned by the length method), or if the data couldn't otherwise be loaded, the error MK_synthDataLoadErr is generated and nil is returned. Otherwise returns the receiver.
| dataArray | is a DSPDatum *. | |
| len | is an int. | |
| off | is an int. |
| - (id) setShortData: | (short *) | dataArray | ||
| length: | (unsigned int) | len | ||
| offset: | (int) | off | ||
Loads (at most) len words of data from dataArray into the receiver's memory, right justified, starting at location off words from the beginning of the receiver's memory block.
If off + len is greater than the receiver's length (as returned by the length method), or if the data couldn't otherwise be loaded, the error MK_synthDataLoadErr is generated and nil is returned. Otherwise returns the receiver.
| dataArray | is a short *. | |
| len | is an int. | |
| off | is an int. |
| - (id) setData: | (DSPDatum *) | dataArray |
Loads dataArray into the receiver's memory.
Implemented as (and returns the value of):
[self setData: dataArray length: length offset: 0];
where the second argument is the instance variable length. This assumes that dataArray is the same length as the receiver.
| dataArray | is a DSPDatum *. |
| - (id) setShortData: | (short *) | dataArray |
Loads dataArray into the receiver's memory, right justified.
Implemented as (and returns the value of):
[self setShortData: dataArray length: length offset: 0];
where the second argument is the instance variable length. This assumes that dataArray is the same length as the receiver.
| dataArray | is a short *. |
| - (id) setToConstant: | (DSPDatum) | value | ||
| length: | (unsigned int) | len | ||
| offset: | (int) | off | ||
Similar to setData:length:offset:, but loads the constant value rather than an array; see setData:length:offset: for details.
| value | is a DSPDatum. | |
| len | is an unsigned int. | |
| off | is an int. |
| - (id) setToConstant: | (DSPDatum) | value |
Fills the receiver's memory with the constant value.
Implemented as (and returns the value of):
[self setToConstant: value length: length offset: 0];
where the second argument is the instance variable length.
| value | is a DSPDatum. |
| - (id) run |
This does nothing and returns the receiver.
It's provided for compatibility with MKUnitGenerator; specifically, it allows a MKSynthPatch to send run to all its MKSynthElement objects without regard for their class.
| - (id) idle |
This does nothing and returns the receiver.
It's provided for compatibility with MKUnitGenerator; specifically, it allows a MKSynthPatch to send idle to all its MKSynthElement objects without regard for their class.
| - (double) finish |
This does nothing and returns 0.0.
It's provided for compatibility with MKUnitGenerator; specifically, it allows a MKSynthPatch to send finish to all its MKSynthElement objects without regard for their class.
| + (id) orchestraClass |
This method always returns the id of the MKOrchestra class.
It's provided for applications that extend the MusicKit to use other synthesis hardware. If you're using more than one type of hardware, you should create a subclass of MKSynthData and/or MKUnitGenerator for each. The default hardware is that represented by MKOrchestra, the DSP56001.
| - (id) orchestra |
| - (BOOL) isAllocated |
Provided for compatability with MKUnitGenerator.
Always returns YES, since deallocated MKSynthDatas are freed immediately.
| - (BOOL) isFreeable |
Invoked by the MKOrchestra to determine whether the receiver may be freed.
Returns YES if it can, NO if it can't. (A MKSynthData can be freed if its a member of a MKSynthPatch that can be freed.)
| - (id) synthPatch |
| - (id) setReadOnly: | (BOOL) | readOnlyFlag |
Sets the receiver to read-only if readOnlyFlag is YES and read-write if it's NO.
The default access for a MKSynthData object is read-write. Returns the receiver. The MKOrchestra automatically creates some read-only MKSynthData objects (SineROM, MuLawROM, and the zero and sink patchpoints) that ignore this method.
| readOnlyFlag | is a BOOL. |
| - (BOOL) readOnly |
Returns YES if the receiver is read-only.
| - (int) referenceCount |
If the receiver is installed in its MKOrchestra's shared object table, this returns the number of objects that have allocated it.
Otherwise returns 1.
| - (id) readDataUntimed: | (DSPDatum *) | dataArray | ||
| length: | (unsigned int) | len | ||
| offset: | (int) | off | ||
Queries the DSP for the value of the given DSP memory.
This returns a valid value by reference only when one of the following is true:
| dataArray | is a DSPDatum *. | |
| len | is an unsigned int. | |
| off | is an int. |
| - (id) readShortDataUntimed: | (short *) | dataArray | ||
| length: | (unsigned int) | len | ||
| offset: | (int) | off | ||
Queries the DSP for the value of the given DSP memory.
Same as readDataUntimed:length:offset: for 16-bit arrays of data.
| dataArray | is a short *. | |
| len | is an int. | |
| off | is an int. |
1.5.6