MKOrchestra Class Reference

This is the allocator and manager of DSP resources. More...

#import <MKOrchestra.h>

Inheritance diagram for MKOrchestra:

SndStreamClient ArielQP ArielQPSat

List of all members.

Public Member Functions

(MKDeviceStatus) - deviceStatus
 Returns the MKDeviceStatus of the receiver, one of.
(void) - setHeadroom:
 Sets the receiver's computation headroom, adjusting the tradeoff between processing power and reliability.
(double) - headroom
 Returns the receiver's headroom, as set through the setHeadroom: method.
(id) - beginAtomicSection
 Marks the beginning of a section of DSP commands that are sent as a unit.
(id) - endAtomicSection
 Marks the end of a section of DSP commands that are sent as a unit.
(id) - init
 Initialises the MKOrchestra instance on the first (default) DSP resource.
(id) - initOnDSP:
 Initialises an MKOrchestra instance on the given DSP processing resource.
(int) - tickSize
 Returns the tick size used by synthesis unit-generators.
(double) - samplingRate
 Returns the receiver's sampling rate.
(id) - setSamplingRate:
 Sets the receiver's sampling rate to newSRate, taken as samples per second.
(id) - setTimed:
 If isOrchTimed is YES, the receiver's DSP executes the commands it receives according to their timestamps.
(MKOrchestraTiming) - isTimed
 Returns YES if the receiver is timed NO if it's untimed.
(id) - setSynchToConductor:
 Specify that the MKOrchestra is to synchronize the DSP's notion of time to that of the MKConductor's time.
(id) - setFastResponse:
 <<NeXT hardware only.>> Sets the size of the sound output buffer; two sizes are possible.
(char) - fastResponse
 Returns YES if the receiver is using small sound-out buffers to minimize response latency.
(id) - setLocalDeltaT:
 Sets the offset, in seconds, that's added to the timestamps of commands sent to the receiver's DSP.
(double) - localDeltaT
 Returns the value set through setLocalDeltaT:.
(id) - setHostSoundOut:
 Sets whether the receiver, which must be closed, sends its sound signal to the host DAC, as yesOrNo is YES or NO.
(id) - setSoundIn:
 Sets whether the receiver, which must be closed, receives sound, as yesOrNo is YES or NO.
(BOOL) - soundIn
 Sets whether soundIn is enabled.
(void) - setDebug:
 Sets extra debugging information during orchestra synthesis to printed.
(id) - setOutputSoundfile:
 Sets the soundfile to which sound samples are written.
(NSString *) - outputSoundfile
 Returns a pointer to the name of the receiver's output soundfile, or nil if none.
(id) - setOutputCommandsFile:
 Sets a file name to which DSP commands are to be written as a DSP Commands format soundfile.
(NSString *) - outputCommandsFile
 Returns the output soundfile or nil if none.
(id) - flushTimedMessages
 Sends buffered DSP commands to the DSP.
(id) - installSharedObject:for:
 Places aSynthObj on the shared object table and sets its reference count to 1.
(id) - installSharedObject:for:type:
 Places aSynthObj on the shared object table and sets its reference count to 1.
(id) - installSharedSynthDataWithSegment:for:
 Places aSynthDataObj on the shared object table in the.
(id) - installSharedSynthDataWithSegment:for:type:
 Places aSynthDataObj on the shared object table in the segment specified by aSynthDataObj and sets its reference count to 1.
(id) - installSharedSynthDataWithSegmentAndLength:for:type:
 Places aSynthDataObj on the shared object table in the segment of aSynthDataObj with the specified length and sets its reference count to 1.
(id) - sharedObjectFor:
 Returns, from the receiver's shared object table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj If the object is found, aKeyObj's reference count is incremented.
(id) - sharedObjectFor:type:
 Returns, from the receiver's shared object table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj. The object must be allocated with the specified type.
(id) - sharedSynthDataFor:segment:
 Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.
(id) - sharedSynthDataFor:segment:type:
 Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.
(id) - sharedSynthDataFor:segment:length:
 Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.
(id) - sharedSynthDataFor:segment:length:type:
 Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.
(id) - sineROM
 Returns a MKSynthData object representing the SineROM.
(id) - muLawROM
 Returns a MKSynthData object representing the MuLawROM.
(id) - segmentZero:
 Returns a special pre-allocated patchpoint (a MKSynthData) in the specified segment that always holds 0 and to which, by convention, nothing is ever written.
(id) - segmentSink:
 Returns a special pre-allocated patchpoint (a MKSynthData) in the specified segment which may be used to write garbage.
(id) - segmentSinkModulus:
 Returns a special pre-allocated patchpoint (a MKSynthData) in the specified segment, aligned for modulus addressing, which may be used to write garbage.
(id) - open
 Opens the receiver's DSP and sets the receiver's status to MK_devOpen.
(id) - run
 Starts the clock on the receiver's DSP, thus allowing the processor to begin executing commands, and sets the receiver's status to MK_devRunning.
(id) - stop
 Stops the clock on the receiver's DSP, thus halting execution of commands, and sets the receiver's status to MK_devStopped.
(id) - close
 Waits for all enqueued DSP commands to be executed.
(id) - abort
 This is the same as close, except that it doesn't wait for enqueued DSP commands to be executed.
(id) - trace:msg:
 Used to print debugging information.
(NSString *) - segmentName:
 Returns a pointer to the name of the specified MKOrchMemSegment.
(unsigned short) - orchestraIndex
 Returns the index of the DSP associated with the receiver.
(double) - computeTime
 Returns the compute time estimate currently used by the receiver in seconds per sample.
(id) - allocSynthPatch:
 Same as allocSynthPatch:patchTemplate: but uses the default template, obtained by sending the message defaultPatchTemplate to aSynthPatchClass.
(id) - allocSynthPatch:patchTemplate:
 Allocates and returns a MKSynthPatch for MKPatchTemplate p.
(id) - allocUnitGenerator:
 Allocates and returns a MKUnitGenerator of the specified class, creating a new one, if necessary.
(id) - allocUnitGenerator:before:
 Allocates and returns a MKUnitGenerator of the specified class.
(id) - allocUnitGenerator:after:
 Allocates and returns a MKUnitGenerator of the specified class.
(id) - allocUnitGenerator:between::
 Allocates and returns an MKUnitGenerator of the specified class.
(id) - allocSynthData:length:
 Allocates and returns a new MKSynthData object with the specified length, or nil if the receiver doesn't have sufficient resources, if size is 0, or if an illegal segment is requested.
(id) - allocPatchpoint:
 Allocates and returns a MKSynthData to be used as a patchpoint in the specified segment (MK_xPatch or MK_yPatch).
(id) - dealloc:
 Deallocates aSynthResource by sending it the dealloc message.
(BOOL) - isRealTime
 Returns YES if the receiver runs in real time.
(BOOL) - supportsSamplingRate:
 Returns YES if the DSP or driver supports the specified sampling rate (or half that rate).
(double) - defaultSamplingRate
 Returns the default sampling rate for the driver or hardware corresponding to this MKOrchestra instance's DSP.
(BOOL) - prefersAlternativeSamplingRate
 Returns YES if the MKOrchestra will do better with a lower sampling rate than is ordinarily needed.
(id) - setDefaultSoundOut
 Resets serialSoundOut, hostSoundOut, serialPortDevice, etc. to produce the "default sound output" for the given hardware.
(id) - getMonitorVersion:release:
 Returns the version and release characters of the DSP monitor.
(unsigned) - capabilities
 returns an unsigned int, the bits of which report what capabilities are provided by the DSP device corresponding to the MKOrchestra.
(int) - outputChannelCount
 Returns the number of output channels.
(BOOL) - upSamplingOutput
 When sending sound to the DSP serial port, the sound may need to be up-sampled if the current sampling rate is supported by the serial port device only as a "half sampling rate".
(id) - setUpDSP
 A subclass may implement this message.
(BOOL) - startSoundWhenOpening
 Returns YES.
(NSString *) - driverName
 Returns the name of the sound driver associated with this instance of MKOrchestra.
(int) - driverUnit
 <<Intel-based hardware only>> Returns the unit of the DSP driver associated with this instance of MKOrchestra.
(NSString *) - driverParameter:
 <<Intel-based hardware only>> Returns the parameter value of the specified driver parameter for the driver associated with this instance of MKOrchestra.

Static Public Member Functions

(void) + setHeadroom:
 Sets the headroom of all MKOrchestras instances that have been created.
(id) + orchestra
 Returns and initializes a new MKOrchestra for the default DSP, if one doesn't already exist, otherwise returns the existing one.
(id) + orchestraOnDSP:
 Creates and returns an MKOrchestra instance for the index'th DSP.
(NSArray *) + orchestrasOnAllDSPs
 Creates an MKOrchestra instance for every available DSP, if it has not already been created.
(id) + flushTimedMessages
 Flushes all currently buffered DSP commands by invoking the flushTimedMessages instance method for each MKOrchestra.
(unsigned short) + DSPCount
 Returns the maximum possible number of DSPs.
(MKOrchestra *) + nthOrchestra:
 Returns the MKOrchestra of the index'th DSP.
(id) + open
 Sends open to each of the MKOrchestra instances and sets each to MK_devOpen.
(id) + run
 Sends run to each of the MKOrchestra instances and sets each to MK_devRunning.
(id) + stop
 Sends stop to each of the MKOrchestra instances and sets each to MK_devStopped.
(id) + close
 Sends close to each of the MKOrchestra instances and sets each to MK_devClosed.
(id) + abort
 Sends abort to each of the MKOrchestra instances and sets each to MK_devClosed.
(void) + setSamplingRate:
 Sets the sampling rate of all the MKOrchestra instances by sending setSamplingRate:newSRate to all closed MKOrchestras.
(id) + setTimed:
 Sends setTimed:areOrchsTimed to each MKOrchestra instance.
(id) + setFastResponse:
 Sends setFastResponse:yesOrNo to all existing MKOrchestras objects and returns the receiver.
(id) + setLocalDeltaT:
 Sets the local delta time for all MKOrchestras and changes the default, which is otherwise 0.0.
(id) + allocUnitGenerator:
 Allocates a MKUnitGenerator of class classObj.
(id) + allocSynthData:length:
 Allocates a MKSynthData object.
(id) + allocPatchpoint:
 Allocates a patchpoint in segment segment Returns the patchpoint (a MKSynthData object), or nil if the object couldn't be allocated.
(id) + allocSynthPatch:
 This is the same as allocSynthPatch:patchTemplate: but uses the default template obtained by sending the message defaultPatchTemplate to aSynthPatchClass..
(id) + allocSynthPatch:patchTemplate:
 Allocates a MKSynthPatch with a MKPatchTemplate of p on the first DSP with sufficient resources.
(id) + dealloc:
 Deallocates the argument, which must be a previously allocated MKSynthPatch, MKUnitGenerator or MKSynthData, by sending it the dealloc message.
(id) + registerOrchestraSubclass:forOrchIndex:
 Used by subclasses to register themselves as the default class for the specified DSP index.
(NSArray *) + getDriverNames
 Drivers now refer to independently addressable sound ports which consist of 1 or more channels of sound.
(NSString *) + driverParameter:forOrchIndex:
 <<Intel-based hardware only>> Returns the parameter value of the specified driver parameter for the driver associated with the given index of MKOrchestra.

Protected Attributes

double computeTime
double samplingRate
NSMutableArray * unitGeneratorStack
NSString * outputSoundfile
NSString * inputSoundfile
NSString * outputCommandsFile
MKDeviceStatus deviceStatus
unsigned short orchIndex
BOOL soundIn
double localDeltaT

Detailed Description

This is the allocator and manager of DSP resources.

The MKOrchestra class manages signal processing resources used in music synthesis. Each instance of MKOrchestra represents a single "signal processor resource" that may refer to a DSP hardware processor, or to processing behaviour performed by the main processor, a networked processor (i.e Beowulf clustered), or perhaps one of the vector processor resources of a main processor. This is for historical reasons collectively termed a "DSP". The signal processing resource is identified by orchIndex, a zero-based integer index.

In the basic NeXT hardware configuration, there's only one MC56001 DSP so there's only one MKOrchestra instance (orchIndex 0). On Intel-based hardware, there may be any number of DSPs or none, depending on how many DSP cards the user has installed (See "INSTALLING INTEL-BASED DSP DRIVERS" below). On PowerPC class machines the signal processing is performed on the main processor, so there's only one MKOrchestra.

The methods defined by the MKOrchestra class let you manage a DSP by allocating (TODO should this be assign?, i.e. alloc as normal, then assign the initialised instance?) portions of its memory for specific synthesis modules and by setting its processing characteristics. There are two levels of allocation: MKSynthPatch allocation and unit generator allocation. MKSynthPatches are higher-level entities, collections of MKUnitGenerators.

You can allocate entire MKSynthPatches or individual MKUnitGenerator and MKSynthData objects through the methods defined here. Keep in mind, however, that similar methods defined in other class - specifically, the MKSynthPatch allocation methods defined in MKSynthInstrument, and the MKUnitGenerator and MKSynthData allocation methods defined in MKSynthPatch - are built upon and designed to usurp those defined by MKOrchestra. You only to need to allocate synthesis objects directly if you want to assemble sound-making modules at a low level.

Before you can do anything with an MKOrchestra - particularly, before you can allocate synthesis objects - you must create and open the MKOrchestra. The MKOrchestra is a shared resource (that is, various DSP modules all use the same single MKOrchestra instance.) Therefore, creation is done through the orchestra method - sending orchestra twice returns the same object. (This strange convention is for historical reasons and matches the ApplicationKit convention.) To open an MKOrchestra, you send it the open message. This provides a channel of communication with the DSP that the MKOrchestra represents. Once you've allocated the objects that you want, either through the methods described here or through those defined by MKSynthInstrument and MKSynthPatch, you can start the synthesis by sending the run message to the MKOrchestra. (If your application uses the MusicKit's performance scheduling mechanism, the run message should be sent immediately before or immediately after the startPerformance message is sent to the MKConductor.) The stop method halts synthesis and close breaks communication with the DSP. These methods change the MKOrchestra's status, which is always one of the following MKDeviceStatus values:

MKDeviceStatus Description
MK_devOpen The MKOrchestra is open but not running.
MK_devRunning The MKOrchestra is open and running.
MK_devStopped The MKOrchestra has been running, but is now stopped.
MK_devClosed The MKOrchestra is closed.

You can query an MKOrchestra's status through the deviceStatus method.

When the MKOrchestra is running, the allocated MKUnitGenerators produce a stream of samples that, by default, are sent to the "default sound output". On most modern hardware, that is the stereo digital to analog converter (the DAC), which converts the samples into an audio signal. This type of sound output is called "Host sound output" because the samples are sent from the DSP to the host computer.

TODO modify this: But there are a number of other alternatives. You can write the samples to the DSP serial port, to be played through any of a number of devices that have their own DACs or do digital transfer to DAT recorders. To do this, invoke the method setSerialSoundOut: with a YES argument before sending open to the MKOrchestra. This is also called "SSI" sound output. See the DSPSerialPortDevice class for more details.

Another option is to write the samples to a soundfile. You do this by invoking the method setOutputSoundfile: before sending open to the MKOrchestra. If you're writing a soundfile, the computer's DAC is automatically disabled. It is also possible to save the DSP commands as a "DSP commands format soundfile". Such files are much smaller than the equivalent soundfile. Use the method setOutputCommandsFile: to create such a file. However, support for playing DSP commands file may not continue in future releases. Therefore, we do not encourage their use.

The MKOrchestra can also process sound that it receives. To do this, send setSoundIn: with a YES argument. TODO update this: <<Note that currently serial input may not be combined with writing a soundfile.>>

Every command that's sent to the DSP is given a timestamp indicating when the command should be executed. The manner in which the DSP regards these timestamps depends on whether its MKOrchestra is timed or untimed, as set through the setTimed: method. In a timed MKOrchestra, commands are executed at the time indicated by its timestamp. If the MKOrchestra is untimed, the DSP ignores the timestamps, executing commands as soon as it receives them. By default, an MKOrchestra is timed.

Since the DSP is a separate processor, it has its own clock and its own notion of the current time. Since the DSP can be dedicated to a single task - in this case, generating sound - its clock is generally more reliable than the main processor, which may be controlling any number of other tasks. If your application is generating MKNotes without user-interaction, for example, if it's playing a MKScore or scorefile, then you should set the Music Kit performance to be unclocked, through the MKConductor's setClocked: method, and the MKOrchestra to be timed. This allows the Music Kit to process MKNotes and send timestamped commands to the DSP as quickly as possible, relying on the DSP's clock to synthesize the MKNotes at the correct time. However, if your application must respond to user-initiated actions with as little latency as possible, then the MKConductor must be clocked. In this case, you can set the MKOrchestra to be untimed. A clocked MKConductor and an untimed MKOrchestra yields the best possible response time.

If your application responds to user actions, but can sustain some latency between an action and its effect, then you may want to set the MKConductor to be clocked and the DSP to be timed, and then use the C function MKSetDeltaT() to set the delta time. Delta time is an imposed latency that allows the Music Kit to run slightly ahead of the DSP. Any rhythmic irregularities created by the Music Kit's dependence on the CPU's clock are evened out by the utter dependability of the DSP's clock (assuming that the such an irregularity isn't greater than the delta time).

Since parameter updates can occur asynchronously, the MKOrchestra doesn't know, at the beginning of a MKNote, if the DSP can execute a given set of MKUnitGenerators quickly enough to produce a steady supply of output samples for the entire duration of the MKNote. However, it makes an educated estimate and will deny allocation requests that it thinks will overload the DSP and cause it to fall out of real time. Such a denial may result in a smaller number of simultaneously synthesized voices. You can adjust the MKOrchestra's DSP processing estimate, or headroom, by invoking the setHeadroom: method. This takes an argument between -1.0 and 1.0; a negative headroom allows a more liberal estimate of the DSP resources - resulting in more simultaneous voices - but it runs the risk of causing the DSP to fall out of real time. Conversely, a positive headroom is more conservative: You have a greater assurance that the DSP won't fall out of real time but the number of simultaneous voices is decreased. The default is a somewhat conservative 0.1. If you're writing samples to a soundfile with the DAC disabled, headroom is ignored. On Intel-based hardware, the differences between the clock and memory speed of various DSP cards requires some hand-tuning of the headroom variable. Slower DSP cards should use a higher headroom and faster cards should use a negative headroom.

When sending sound to the DSP serial port, there is very little latency - for example, sound can be taken in the serial port, processed, and sent out again with less than 10 milliseconds of delay. However, in the case of sound output via the NeXT monitor, there's a sound output time delay that's equal to the size of the buffer that's used to collect computed samples before they're shovelled to the NeXT DAC. To accommodate applications that require the best possible response time (the time between the iniitation of a sound and its actual broadcast from the DAC), a smaller sample output buffer can be requested by sending the setFastResponse:YES message to an MKOrchestra. However, the more frequent attention demanded by the smaller buffer will detract from synthesis computation and, again, fewer simultaneous voices may result. You can also improve response time by using the high sampling rate (44100) although this, too, attenuates the synthesis power of the DSP. By default, the MKOrchestra's sampling rate is 22050 samples per second. setFastResponse: has no effect when sending samples to the DSP serial port.

To avoid creating duplicate synthesis modules on the DSP, each instance of MKOrchestra maintains a shared object table. Objects on the table are MKSynthPatches, SynthDatas, and MKUnitGenerators and are indexed by some other object that represents the shared object. For example, the OscgafUG MKUnitGenerator (a family of oscillators) lets you specify its waveform-generating wave table as a MKPartials object (you can also set it as a MKSamples object; for the purposes of this example we only consider the MKPartials case). When its wave table is set, through the setTable:length: method, the oscillator allocates a MKSynthData object from the MKOrchestra to represent the DSP memory that will hold the waveform data that's computed from the MKPartials. It also places the MKSynthData on the shared object table using the MKPartials as an index by sending the message

[MKOrchestra installSharedSynthData:theSynthData for:thePartials];

If another oscillator's wave table is set as the same MKPartials object, the already-allocated MKSynthData can be returned by sending the message

id aSynthData = [MKOrchestra sharedObjectFor:thePartials];

The method installSharedObject:for: is provided for installing MKSynthPatches and MKUnitGenerators.

If appropriate hardware is available, multiple DSPs may be used in concert. The MKOrchestra automatically performs allocation on the pool of DSPs. On Intel-based hardware, multiple DSP support is achieved by adding multiple DSP cards. On NeXT hardware, multiple DSP support is available via the Ariel QuintProcessor, a 5-DSP card.

The MKOrchestra class may be subclassed to support other 56001-based cards. See the ArielQP and ArielQPSat objects for an example.

The default sound output configuration may be customized by using the defaults data base. On NeXT hardware, you can specify the destination of the sound output, and on both NeXT hardware and Intel-based DSP cards with NeXT-compatible DSP serial ports, you can specify the type of the serial port device. The default sound out type is derived from the MusicKit "OrchestraSoundOut" variable in the defaults data base, which may currently have the value "SSI" or "Host". More values may be added in the future. Note that an "SSI" value for "OrchestraSoundOut" refers to the DSP's use of the SSI port and that usage does not imply NeXT-compatiblility. For example, for the Turtle Beach cards, the default is "serialSoundOut" via the on-card CODEC. (On Intel-based hardware, the determination as to whether the DSP serial port is NeXT-compatible is based on the driver's "SerialPortDevice" parameter - if its value is "NeXT", the serial port is NeXT-compatible. ) You can always return to the default sample output configuration by sending the message setDefaultSoundOut.

New MKOrchestras are auto-configured with their default configuration, with a DSPSerialPortDevice object automatically created. For devices with NeXT-compatible DSP serial ports, you may change the configuration using the MKOrchestra methods such as -setSerialPortDevice:.

INSTALLING INTEL-BASED DSP DRIVERS

To install an Intel-based DSP driver, follow these steps:

1. Double click on the driver you want to install. The drivers can be found on /LocalLibrary/Devices/. For example, to install the ArielPC56D driver, double click on /LocalLibrary/Devices/ArielPC56D.config. Type the root pass word. It will tell you driver was successfully installed. Click OK. You've now "installed" the driver.

2. In Configure.app, Click Other. Click Add... Click Add. Select the driver (from the "other" category) and make sure that the I/O port corresponds to your hardware configuration. From Menu/Configuration, select Save. You've now "added the driver".

3. Repeat the process for any other drivers, such as the TurtleBeach Multisound driver, /LocalLibrary/Devices/TurtleBeachMS.config.

4. If you have multiple cards of a certain type, repeat step 2, making sure to assign a different I/O address to each instance of the driver. The first will be given the name <driverName>0, where <driverName> is the name of the driver (e.g. "ArielPC56D") The second will be given the name <driverName>1, etc. The trailing number is called the "unit." For example, if you add 2 Ariel cards to your system, they will be assigned the names "ArielPC56D0" and "ArielPC56D1". If you have one Multisound card, it will be assigned the name "TurtleBeachMS0". This assignment is done by the Configure.app application.

5. Reboot. Drivers are now installed and usable.

All DSP drivers are in the same "family", called "DSP." All DSP units are numbered with a set of "DSP indecies", beginning with 0. (Note that this is distinct from the "unit" numbers.) If there is only one DSP card, there is no ambiguity. However, if there is more than one card, the user's defaults data base determines which DSP or DSPs should be used. For example, in the example given above, a user's defaults data base may have:

MusicKit DSP0 ArielPC56D1 MusicKit DSP2 ArielPC56D0 MusicKit DSP4 TurtleBeachMS0

This means that the default DSP is the one on the 2nd Ariel card that you installed. Also, notice that there may be "holes" - in this example, there is no DSP1 or DSP3. DSP identifiers up to 15 may be used. The DSP indecies refer to the MKOrchestra index passed to methods like +newOnDSP:. If there is no driver for that DSP, +newOnDSP: returns nil.

Some DSP cards support multiple DSPs on a single card. For such cards, we have the notion of a "sub-unit", which follows the unit in the assigned name with the following format: <driver><unit>-<subunit>. For example if a card named "Frankenstein" supports 4 DSPs, and there are two Frankenstein units installed in the system, the user's defaults data base might look like this:

MusicKit DSP0 Frankenstein0-0 MusicKit DSP1 Frankenstein0-1 MusicKit DSP2 Frankenstein0-2 MusicKit DSP3 Frankenstein0-3 MusicKit DSP4 Frankenstein1-0 MusicKit DSP5 Frankenstein1-1 MusicKit DSP6 Frankenstein1-2 MusicKit DSP7 Frankenstein1-3

Currently, the Music Kit provides drivers for the following cards: Ariel PC56D, Turtle Beach Multisound, I*Link i56, Frankenstein. See the release notes for the latest information on supported drivers.

Member Function Documentation

- (MKDeviceStatus) deviceStatus  

Returns the MKDeviceStatus of the receiver, one of.

Returns:
Returns a MKDeviceStatus.
  • MK_devClosed
  • MK_devOpen
  • MK_devRunning
  • MK_devStopped
The MKOrchestra states are explained in the class description, above.

- (void) setHeadroom: (double)  headroom  

Sets the receiver's computation headroom, adjusting the tradeoff between processing power and reliability.

Parameters:
headroom is a double.
Returns:
Returns an id. The argument should be in the range -1.0 to 1.0. As you increase an MKOrchestra's headroom, the risk of falling out of real time decreases, but synthesis power is also weakened. The default, 0.1, is a conservative estimate and can be decreased in many cases without heightening the risk of falling out of real time.
The effective sampling period - the amount of time the MKOrchestra thinks the DSP has to produce a sample - is based on the formula

(1.0/samplingRate) * (1.0 - headroom).

Returns the receiver.

+ (void) setHeadroom: (double)  headroom  

Sets the headroom of all MKOrchestras instances that have been created.

Parameters:
headroom is a double.
Returns:
Returns the receiver.
See also:
-- setHeadroom:

- (double) headroom  

Returns the receiver's headroom, as set through the setHeadroom: method.

Headroom should be a value between -.0 and 1.0. The default is 0.1.

Returns:
Returns a double.

- (id) beginAtomicSection  

Marks the beginning of a section of DSP commands that are sent as a unit.

Returns:
Returns an id. Returns the receiver.

- (id) endAtomicSection  

Marks the end of a section of DSP commands that are sent as a unit.

Returns:
Returns an id. Returns the receiver.

+ (id) orchestra  

Returns and initializes a new MKOrchestra for the default DSP, if one doesn't already exist, otherwise returns the existing one.

The DSP isn't actually claimed until the MKOrchestra instance is sent the openmessage.

Returns:
Returns an autoreleased MKOrchestra instance.

+ (id) orchestraOnDSP: (unsigned short)  index  

Creates and returns an MKOrchestra instance for the index'th DSP.

If an MKOrchestra object already exists for the specified DSP, the existing object is returned. Returns nil if index is out of bounds or if the index'th DSP isn't available. For example, on Intel hardware, if there is no driver for the index'th DSP, this method returns nil. Note that for some types of DSP devices, the object returned will be a subclass of MKOrchestra, rather than an instance of MKOrchestra.

Parameters:
index is an unsigned short indicating which DSP resource to initialise on.
Returns:
Returns an id.
See also:
+ registerOrchestraSubclass:forOrchIndex:.

+ (NSArray *) orchestrasOnAllDSPs  

Creates an MKOrchestra instance for every available DSP, if it has not already been created.

This is accomplished by consulting the user's defaults data base (setable with the Preferences application). Returns all the MKOrchestra's created.

Returns:
Returns an NSArray of MKOrchestra instances.

+ (id) flushTimedMessages  

Flushes all currently buffered DSP commands by invoking the flushTimedMessages instance method for each MKOrchestra.

The usual way to invoke this method is via the MKConductor +unlockPerformance method (which must be preceeded by +lockPerformance.)

Returns:
Returns an id.

+ (unsigned short) DSPCount  

Returns the maximum possible number of DSPs.

This may be more than the number of DSPs you actually have.

Returns:
Returns an unsigned short.

+ (MKOrchestra *) nthOrchestra: (unsigned short)  index  

Returns the MKOrchestra of the index'th DSP.

If index is out of bounds, or if an MKOrchestra hasn't been created for the specified DSP, nil is returned.

Parameters:
index is an unsigned short.
Returns:
Returns an id.

- (id) initOnDSP: (unsigned short)  dspIndex  

Initialises an MKOrchestra instance on the given DSP processing resource.

A DSP processing resource is nowdays an abstract concept of processing resource which may refer to a hardware DSP processor, vector unit or networked processor.

Parameters:
dspIndex The index of the DSP processing resource as returned by +driverNames.

+ (id) open  

Sends open to each of the MKOrchestra instances and sets each to MK_devOpen.

If any of the MKOrchestras responds to the open message by returning nil, so too does this method return nil. Otherwise returns the receiver. Note that if you first send open and then create a new MKOrchestra, the new MKOrchestra will not automatically be opened.

Returns:
Returns an id.

+ (id) run  

Sends run to each of the MKOrchestra instances and sets each to MK_devRunning.

If any of the MKOrchestras responds to the run message by returning nil, so too does this method return nil. Otherwise returns the receiver.

Returns:
Returns an id.

+ (id) stop  

Sends stop to each of the MKOrchestra instances and sets each to MK_devStopped.

If any of the MKOrchestras responds to the run message by returning nil, so too does this method return nil. Otherwise returns the receiver.

Returns:
Returns an id.

+ (id) close  

Sends close to each of the MKOrchestra instances and sets each to MK_devClosed.

If any of the MKOrchestras responds to the close message by returning nil, so too does this method return nil. Otherwise returns the receiver.

Returns:
Returns an id.

+ (id) abort  

Sends abort to each of the MKOrchestra instances and sets each to MK_devClosed.

If any of the MKOrchestras responds to the abort message by returning nil, so too does this method return nil. Otherwise returns the receiver.

Returns:
Returns an id.

- (int) tickSize  

Returns the tick size used by synthesis unit-generators.

Each unit generator runs for this many frames, and patchpoints are this length. Since 1989, the tick-size used on the DSP has been 16.

Returns:
Returns an int.

- (double) samplingRate  

Returns the receiver's sampling rate.

The default is determined by the method defaultSamplingRate.

Returns:
Returns a double.

+ (void) setSamplingRate: (double)  newSRate  

Sets the sampling rate of all the MKOrchestra instances by sending setSamplingRate:newSRate to all closed MKOrchestras.

Parameters:
newSRate is a double.
Returns:
Returns an id. This method also changes the default sampling rate; when a new MKOrchestra is subsequently created, it also gets set to newSRate. Returns the receiver.

- (id) setSamplingRate: (double)  newSRate  

Sets the receiver's sampling rate to newSRate, taken as samples per second.

Parameters:
newSRate is a double.
Returns:
Returns an id. The receiver must be closed - nil is returned if the receiver's status isn't MK_devClosed. Returns the receiver.

+ (id) setTimed: (MKOrchestraTiming)  areOrchsTimed  

Sends setTimed:areOrchsTimed to each MKOrchestra instance.

Parameters:
areOrchsTimed is a MKOrchestraTiming.
Returns:
Returns an id. If areOrchsTimed is YES, the DSP processes the commands that it receives at the times specified by the commands' timestamps. If it's NO, DSP commands are processed as quickly as possible. By default, an MKOrchestra is timed. Note, however, that this method changes the default to areOrchsTimed.

- (id) setTimed: (MKOrchestraTiming)  isOrchTimed  

If isOrchTimed is YES, the receiver's DSP executes the commands it receives according to their timestamps.

Parameters:
isOrchTimed is a MKOrchestraTiming.
Returns:
Returns an id. If it's NO, it ignores the timestamps processes the commands immediately. By default, an MKOrchestra is timed. * Note that untimed mode was originally intended primarily as a means of inserting "out of band" messages into a timed stream and is not as efficient for high-bandwidth transfers normally associated with a Music Kit performance. Note also that untimed mode is not deterministic with respect to precise timing. However, it has the advantage of providing the minimum possible latency. It is permissable to change time timing mode during a Music Kit performance.

- (MKOrchestraTiming) isTimed  

Returns YES if the receiver is timed NO if it's untimed.

Returns:
Returns a MKOrchestraTiming.

- (id) setSynchToConductor: (BOOL)  yesOrNo  

Specify that the MKOrchestra is to synchronize the DSP's notion of time to that of the MKConductor's time.

The DSP sample counter and the System clock (i.e. the MKConductor clock) are intended to keep the same time (except for fluctuations due to the internal buffering of the DSP and sound drivers). Over a long-term performance, however, the two clocks may begin to drift apart slightly, on the order of a few milliseconds per minutes. If you are running with an extremely small "delta time" (cf. MKSetDeltaT()), you may want to synchronize the two clocks periodically. By sending setSynchToConductor:YES, you specify that the MKOrchestra is to synchronizes the DSP's notion of time to that of the MKConductor's time every 10 seconds to account for slight differences between the rate of the two clocks. This method assumes an Application object exists and is running and that the MKConductor is in clocked mode.

Note: This method may cause time to go backwards in the DSP temporarily, and thus may cause distortion of envelopes, lost notes, etc. Therefore, its use is recommended only when absolutely necessary. An alternative method of synchronization (though no safer) can be found in the Ensemble programming example.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns an id.

- (id) setFastResponse: (char)  yesOrNo  

<<NeXT hardware only.>> Sets the size of the sound output buffer; two sizes are possible.

If yesOrNo is YES, the smaller size is used, thereby improving response time but somewhat decreasing the DSP's synthesis power. If it's NO, the larger buffer is used. By default, an MKOrchestra uses the larger buffer. Returns the receiver. This method has no effect if sound output is done via the DSP serial port.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns an id.

+ (id) setFastResponse: (char)  yesOrNo  

Sends setFastResponse:yesOrNo to all existing MKOrchestras objects and returns the receiver.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns an id. This also sets the default used by subsequently created MKOrchestras.

- (char) fastResponse  

Returns YES if the receiver is using small sound-out buffers to minimize response latency.

Otherwise returns NO.

Returns:
Returns a BOOL.

- (id) setLocalDeltaT: (double)  val  

Sets the offset, in seconds, that's added to the timestamps of commands sent to the receiver's DSP.

The offset is added to the delta time that's set with MKSetDeltaT(). This has no effect if the receiver isn't timed.

Parameters:
val is a double.
Returns:
Returns the receiver.

- (double) localDeltaT  

Returns the value set through setLocalDeltaT:.

Returns:
Returns a double.

+ (id) setLocalDeltaT: (double)  val  

Sets the local delta time for all MKOrchestras and changes the default, which is otherwise 0.0.

Parameters:
val is a double.
Returns:
Returns an id.

- (id) setHostSoundOut: (BOOL)  yesOrNo  

Sets whether the receiver, which must be closed, sends its sound signal to the host DAC, as yesOrNo is YES or NO.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns an id. Returns the receiver, or nil if it isn't closed. On NeXT hardware, the default is to send sound to the host DAC.
Sending setHostSoundOut:YES also sends setOutputSoundfile: nil; you can't write samples to a soundfile and to the DAC at the same time. Sending setHostSoundOut:YES also sends setSerialSoundOut: NO; you can't write samples to the DSP serial port and to the DAC at the same time.

- (id) setSoundIn: (BOOL)  yesOrNo  

Sets whether the receiver, which must be closed, receives sound, as yesOrNo is YES or NO.

Parameters:
yesOrNo is a BOOL.
Returns:
Returns the receiver, or nil if it isn't closed.

- (BOOL) soundIn  

Sets whether soundIn is enabled.

Returns:
Returns a BOOL.

- (void) setDebug: (BOOL)  yesOrNo  

Sets extra debugging information during orchestra synthesis to printed.

Used to be setOnChipMemoryDebug:patchPoints:.

- (id) setOutputSoundfile: (NSString *)  fileName  

Sets the soundfile to which sound samples are written.

The receiver must be closed; nil is returned if it's open, otherwise returns the receiver. A copy of fileName is stored in the instance variable outputSoundfile. If you re-run the MKOrchestra, the file is rewritten. To specify that you no longer want to write a file when the MKOrchestra is re-run, close the MKOrchestra, then send setOutputSoundfile:NULL. When switching from soundfile writing to other forms of sound output, note that you must explicitly send setHostSoundOut:YESor setSerialSoundOut:YES after setting the output soundfile to NULL.

It is not permissable to have an output soundfile open and do host or serial port sound output at the same time.

Parameters:
fileName is an NSString instance.
Returns:
Returns an id.

- (NSString *) outputSoundfile  

Returns a pointer to the name of the receiver's output soundfile, or nil if none.

Returns:
Returns an NSString instance.

- (id) setOutputCommandsFile: (NSString *)  fileName  

Sets a file name to which DSP commands are to be written as a DSP Commands format soundfile.

Parameters:
fileName is an NSString instance.
Returns:
Returns an id. A copy of the fileName is stored in the instance variable outputCommandsFile. This message is ignored if the receiver is not closed. Playing of DSP Commands format soundfiles is currently (1995) implemented only for NeXT hardware.

- (NSString *) outputCommandsFile  

Returns the output soundfile or nil if none.

Returns:
Returns a NSString.

+ (id) allocUnitGenerator: (id)  classObj  

Allocates a MKUnitGenerator of class classObj.

Parameters:
classObj is an id.
Returns:
Returns an id. The object is allocated on the first MKOrchestra that can accomodate it. Returns the MKUnitGenerator, or nil if the object couldn't be allocated.

+ (id) allocSynthData: (MKOrchMemSegment)  segment
length: (unsigned)  size 

Allocates a MKSynthData object.

Parameters:
segment is a MKOrchMemSegment.
size is an unsigned.
Returns:
Returns an id. The allocation is on the first MKOrchestra that will accommodate size words in segment segment. Returns the MKSynthData, or nil if the object couldn't be allocated.

+ (id) allocPatchpoint: (MKOrchMemSegment)  segment  

Allocates a patchpoint in segment segment Returns the patchpoint (a MKSynthData object), or nil if the object couldn't be allocated.

Parameters:
segment is a MKOrchMemSegment.
Returns:
Returns an id.

+ (id) allocSynthPatch: (id)  aSynthPatchClass  

This is the same as allocSynthPatch:patchTemplate: but uses the default template obtained by sending the message defaultPatchTemplate to aSynthPatchClass..

Parameters:
aSynthPatchClass is an id.
Returns:
Returns an id.

+ (id) allocSynthPatch: (id)  aSynthPatchClass
patchTemplate: (id)  p 

Allocates a MKSynthPatch with a MKPatchTemplate of p on the first DSP with sufficient resources.

Returns the MKSynthPatch or nil if it couldn't be allocated.

Parameters:
aSynthPatchClass is an id.
p is an id.
Returns:
Returns an id.

+ (id) dealloc: (id)  aSynthResource  

Deallocates the argument, which must be a previously allocated MKSynthPatch, MKUnitGenerator or MKSynthData, by sending it the dealloc message.

This method is provided for symmetry with the allocfamily of methods.

Parameters:
aSynthResource is an id.
Returns:
Returns an id.

- (id) flushTimedMessages  

Sends buffered DSP commands to the DSP.

This is done for you by the MKConductor. However, if your application sends messages directly to a MKSynthPatch or MKUnitGenerator without the assistance of a MKConductor, you must invoke this method yourself (after sending the synthesis messages). The usual way to invoke this method is via the MKConductor +unlockPerformance method (which must be preceeded by +lockPerformance). Note that you must send flushTimedMessages even if the MKOrchestra is set to MK_UNTIMED mode ("flushTimedMessages" is somewhat of a misnomer; a better name would have been "sendBufferedDSPCommands").

Returns:
Returns the receiver.

- (id) installSharedObject: (id)  aSynthObj
for: (id)  aKeyObj 

Places aSynthObj on the shared object table and sets its reference count to 1.

aKeyObj is any object associated with the abstract notion of the data and is used to index the shared object. Does nothing and returns nil if the aSynthObj is already present in the table. Also returns nil if the orchestra isn't open. Otherwise, returns the receiver.

This method differs from installSharedObjectWithSegmentAndLength:for: in that the length and segment are wild cards.

Parameters:
aSynthObj is an id.
aKeyObj is an id.
Returns:
Returns an id.

- (id) installSharedObject: (id)  aSynthObj
for: (id)  aKeyObj
type: (MKOrchSharedType)  aType 

Places aSynthObj on the shared object table and sets its reference count to 1.

aKeyObj is used to index the shared object. type is used to specify additional details about the data that is being installed. For example, oscillator tables are intsalled as type MK_oscTable, while waveshaping tables are installed as MK_waveshapingTable. Waveguide physical model excitation tables are installed as MK_excitationTable. type makes it possible to use aKeyObj to lookup various different types of Synth objects. Does nothing and returns nil if the aSynthObj is already present in the table. Also returns nil if the orchestra isn't open. Otherwise, returns the receiver.

This method differs from installSharedObjectWithSegmentAndLength:for: in that the length and segment are wild cards.

Parameters:
aSynthObj is an id.
aKeyObj is an id.
aType is a MKOrchSharedType.
Returns:
Returns an id.

- (id) installSharedSynthDataWithSegment: (id)  aSynthDataObj
for: (id)  aKeyObj 

Places aSynthDataObj on the shared object table in the.

segment specified by aSynthDataObj and sets its reference count to 1.

Does nothing and returns nil if the aSynthObj is already present in the table. Also returns nil if the orchestra is not open. Otherwise, returns the receiver.

This method differs from installSharedObjectWithSegmentAndLength:for: in that the length is a wild card.

Parameters:
aSynthDataObj is an id.
aKeyObj is an id.
Returns:
Returns an id.

- (id) installSharedSynthDataWithSegment: (id)  aSynthDataObj
for: (id)  aKeyObj
type: (MKOrchSharedType)  aType 

Places aSynthDataObj on the shared object table in the segment specified by aSynthDataObj and sets its reference count to 1.

Does nothing and returns nil if the aSynthObj is already present in the table. Also returns nil if the orchestra is not open. Otherwise, returns the receiver.

This method differs from installSharedObjectWithSegmentAndLength:for: in that the length is a wild card.

Parameters:
aSynthDataObj is an id.
aKeyObj is an id.
aType is an MKOrchSharedType.
Returns:
Returns an id.

- (id) installSharedSynthDataWithSegmentAndLength: (MKSynthData *)  aSynthDataObj
for: (id)  aKeyObj
type: (MKOrchSharedType)  aType 

Places aSynthDataObj on the shared object table in the segment of aSynthDataObj with the specified length and sets its reference count to 1.

aKeyObj is used to index the shared object. Does nothing and returns nil if the aSynthDataObj is already present in the table. Also returns nil if the orchestra is not open. Otherwise, returns the receiver.

Parameters:
aSynthDataObj is an id.
aKeyObj is an id.
aType is an MKOrchSharedType.
Returns:
Returns an id.

- (id) sharedObjectFor: (id)  aKeyObj  

Returns, from the receiver's shared object table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj If the object is found, aKeyObj's reference count is incremented.

If it isn't found, or if the receiver isn't open, returns nil.

Parameters:
aKeyObj is an id.
Returns:
Returns an id.

- (id) sharedObjectFor: (id)  aKeyObj
type: (MKOrchSharedType)  aType 

Returns, from the receiver's shared object table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj. The object must be allocated with the specified type.

If the object is found, aKeyObj's reference count is incremented. If it isn't found, or if the receiver isn't open, returns nil.

Parameters:
aKeyObj is an id.
aType is a MKOrchSharedType.
Returns:
Returns an id.

- (id) sharedSynthDataFor: (id)  aKeyObj
segment: (MKOrchMemSegment)  whichSegment 

Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.

The object must be allocated in the specifed segment. aKeyObj on the receiver in the specified segment. If the object is found, aKeyObj's reference count is incremented. If it isn't found, or if the receiver isn't open, returns nil.

Parameters:
aKeyObj is an id.
whichSegment is a MKOrchMemSegment.
Returns:
Returns an id.

- (id) sharedSynthDataFor: (id)  aKeyObj
segment: (MKOrchMemSegment)  whichSegment
type: (MKOrchSharedType)  aType 

Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.

The object must be allocated in the specifed segment. aKeyObj on the receiver in the specified segment. If the object is found, aKeyObj's reference count is incremented. If it isn't found, or if the receiver isn't open, returns nil.

Parameters:
aKeyObj is an id.
whichSegment is a MKOrchMemSegment.
aType is a MKOrchSharedType.
Returns:
Returns an id.

- (id) sharedSynthDataFor: (id)  aKeyObj
segment: (MKOrchMemSegment)  whichSegment
length: (int)  length 

Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.

The object must be allocated in the specifed segment. aKeyObj on the receiver in the specified segment. If the object is found, aKeyObj's reference count is incremented. If it isn't found, or if the receiver isn't open, returns nil.

Parameters:
aKeyObj is an id.
whichSegment is a MKOrchMemSegment.
length is an integer.
Returns:
Returns an id.

- (id) sharedSynthDataFor: (id)  aKeyObj
segment: (MKOrchMemSegment)  whichSegment
length: (int)  length
type: (MKOrchSharedType)  aType 

Returns, from the receiver's shared data table, the MKSynthData, MKUnitGenerator, or MKSynthPatch object that's indexed by aKeyObj.

The object must be allocated in the specifed segment, have a length of lengthand have a type type . aKeyObj on the receiver in the specified segment. If the object is found, aKeyObj's reference count is incremented. If it isn't found, or if the receiver isn't open, returns nil.

Parameters:
aKeyObj is an id.
whichSegment is a MKOrchMemSegment.
length is an int.
aType is a MKOrchSharedType.
Returns:
Returns an id.

- (id) sineROM  

Returns a MKSynthData object representing the SineROM.

Returns:
Returns an id. You should never deallocate this object.

- (id) muLawROM  

Returns a MKSynthData object representing the MuLawROM.

Returns:
Returns an id. You should never deallocate this object.

- (id) segmentZero: (MKOrchMemSegment)  segment  

Returns a special pre-allocated patchpoint (a MKSynthData) in the specified segment that always holds 0 and to which, by convention, nothing is ever written.

Parameters:
segment is a MKOrchMemSegment.
Returns:
Returns an id. The patchpoint shouldn't be deallocated. segment can be MK_xPatch or MK_yPatch.

- (id) segmentSink: (MKOrchMemSegment)  segment  

Returns a special pre-allocated patchpoint (a MKSynthData) in the specified segment which may be used to write garbage.

Parameters:
segment is a MKOrchMemSegment.
Returns:
Returns an id. It's commonly used as a place to send the output of idle MKUnitGenerators. The patchpoint shouldn't be deallocated. segment can be MK_xPatch or MK_yPatch.

- (id) segmentSinkModulus: (MKOrchMemSegment)  segment  

Returns a special pre-allocated patchpoint (a MKSynthData) in the specified segment, aligned for modulus addressing, which may be used to write garbage.

Parameters:
segment is a MKOrchMemSegment.
Returns:
Returns an id. It's commonly used as a place to send the output of idle MKUnitGenerators. The patchpoint shouldn't be deallocated. segment can be MK_xPatch or MK_yPatch.

- (id) open  

Opens the receiver's DSP and sets the receiver's status to MK_devOpen.

Returns:
Returns an id. Resets orchestra loop (if not already reset), freeing all Unit Generators and MKSynthPatches. Returns nil if the DSP can't be opened for some reason, otherwise returns the receiver. To find out why the DSP can't be opened, enable Music Kit or DSP error tracing. Possible problems opening the DSP include another application using the DSP, a missing DSP monitor file, a version mismatch and missing or broken hardware.

- (id) run  

Starts the clock on the receiver's DSP, thus allowing the processor to begin executing commands, and sets the receiver's status to MK_devRunning.

Returns:
Returns an id. This opens the DSP if it isn't already open. Returns nil if the DSP couldn't be opened or run, otherwise returns the receiver.

- (id) stop  

Stops the clock on the receiver's DSP, thus halting execution of commands, and sets the receiver's status to MK_devStopped.

Returns:
Returns an id. This opens the DSP if it isn't already open. Returns nil if an error occurs, otherwise returns the receiver.

- (id) close  

Waits for all enqueued DSP commands to be executed.

Returns:
Returns an id. Then severs communication with the DSP, allowing other processes to claim it. The MKSynthPatch-allocated MKUnitGenerators and MKSynthInstrument-allocated MKSynthPatches are freed. All MKSynthPatches must be idle and non-MKSynthPatch-allocated MKUnitGenerators must be deallocated before sending this message. Returns nil if an error occurs, otherwise returns the receiver.

- (id) abort  

This is the same as close, except that it doesn't wait for enqueued DSP commands to be executed.

Returns:
Returns an id. Returns nil if an error occurs, otherwise returns the receiver.

- (id) trace: (int)  typeOfInfo
msg: (NSString *)  fmt
,   ... 

Used to print debugging information.

Parameters:
typeOfInfo is an int.
fmt,... is a char *.
Returns:
Returns an id. The arguments to the msg: keyword are like those to printf(). If the typeOfInfo trace is set, prints to stderr.

- (NSString *) segmentName: (int)  whichSegment  

Returns a pointer to the name of the specified MKOrchMemSegment.

The name is not copied and should not be freed.

Parameters:
whichSegment is an int.
Returns:
Returns an NSString instance.

- (unsigned short) orchestraIndex  

Returns the index of the DSP associated with the receiver.

Returns:
Returns an unsigned short. Used to be named index.

- (double) computeTime  

Returns the compute time estimate currently used by the receiver in seconds per sample.

Returns:
Returns a double.

- (id) allocSynthPatch: (id)  aSynthPatchClass  

Same as allocSynthPatch:patchTemplate: but uses the default template, obtained by sending the message defaultPatchTemplate to aSynthPatchClass.

Parameters:
aSynthPatchClass is an id.
Returns:
Returns an id.

- (id) allocSynthPatch: (id)  aSynthPatchClass
patchTemplate: (id)  p 

Allocates and returns a MKSynthPatch for MKPatchTemplate p.

The receiver first tries to find an idle MKSynthPatch; failing that, it creates and returns a new one. The MKUnitGenerators are added to the SynthPatch's unitGenerators list in the same order they are specified in the MKPatchTemplate. If a new MKSynthPatch can't be built, this method returns nil.

Parameters:
aSynthPatchClass is an id.
p is an id.
Returns:
Returns an id.

- (id) allocUnitGenerator: (id)  aClass  

Allocates and returns a MKUnitGenerator of the specified class, creating a new one, if necessary.

Parameters:
aClass is an id.
Returns:
Returns an id.

- (id) allocUnitGenerator: (id)  aClass
before: (id)  aUnitGeneratorInstance 

Allocates and returns a MKUnitGenerator of the specified class.

The newly allocated object will execute before aUnitGeneratorInstance.

Parameters:
aClass is an id.
aUnitGeneratorInstance is an id.
Returns:
Returns an id.

- (id) allocUnitGenerator: (id)  aClass
after: (id)  aUnitGeneratorInstance 

Allocates and returns a MKUnitGenerator of the specified class.

The newly allocated object will execute after aUnitGeneratorInstance.

Parameters:
aClass is an id.
aUnitGeneratorInstance is an id.
Returns:
Returns an id.

- (id) allocUnitGenerator: (id)  aClass
between: (id)  aUnitGeneratorInstance
: (id)  anotherUnitGeneratorInstance 

Allocates and returns an MKUnitGenerator of the specified class.

The newly allocated object will execute immediately after aUnitGeneratorInstance and before anotherUnitGenerator.

Parameters:
aClass is an id.
aUnitGeneratorInstance is an id.
anotherUnitGeneratorInstance is an id.
Returns:
Returns an id.

- (id) allocSynthData: (MKOrchMemSegment)  segment
length: (unsigned)  size 

Allocates and returns a new MKSynthData object with the specified length, or nil if the receiver doesn't have sufficient resources, if size is 0, or if an illegal segment is requested.

segment should be MK_xData or MK_yData.

Parameters:
segment is a MKOrchMemSegment.
size is an unsigned.
Returns:
Returns an id.

- (id) allocPatchpoint: (MKOrchMemSegment)  segment  

Allocates and returns a MKSynthData to be used as a patchpoint in the specified segment (MK_xPatch or MK_yPatch).

Returns nil if an illegal segment is requested.

Parameters:
segment is a MKOrchMemSegment.
Returns:
Returns an id.

- (id) dealloc: (id)  aSynthResource  

Deallocates aSynthResource by sending it the dealloc message.

aSynthResource may be a MKUnitGenerator, a MKSynthData or a MKSynthPatch. This method is provided for symmetry with the alloc family of methods.

Parameters:
aSynthResource is an id.
Returns:
Returns an id.

- (BOOL) isRealTime  

Returns YES if the receiver runs in real time.

This will be YES if any of soundOut, serialSoundOut or soundIn is YES. Subclasses may want to override this method.

Returns:
Returns a BOOL.

Reimplemented in ArielQPSat.

- (BOOL) supportsSamplingRate: (double)  rate  

Returns YES if the DSP or driver supports the specified sampling rate (or half that rate).

The implementation forwards the message supportsSamplingRate: to the serial port device, if serialSoundOut or soundIn is enabled. Otherwise, for NeXT hardware, it returns YES if aRate is 22050 or 44100. A subclass may override this method.

Parameters:
rate is a double.
Returns:
Returns a BOOL.

- (double) defaultSamplingRate  

Returns the default sampling rate for the driver or hardware corresponding to this MKOrchestra instance's DSP.

Returns:
Returns a double. If serialSoundOut or soundIn is enabled, this method simply forwards the defaultSamplingRate message to the DSPSerialPortDevice object. Otherwise, returns 22050.0. Note that you may change the sampling rate using setSamplingRate:, but the default will still remain the same. A subclass may override this method to provide a different default.

- (BOOL) prefersAlternativeSamplingRate  

Returns YES if the MKOrchestra will do better with a lower sampling rate than is ordinarily needed.

Returns:
Returns a BOOL. The default implementation returns YES if the driver parameter "WaitStates" is "3". This is to accomodate the Multisound card.

- (id) setDefaultSoundOut  

Resets serialSoundOut, hostSoundOut, serialPortDevice, etc. to produce the "default sound output" for the given hardware.

On NeXT hardware, the default sound output is the NeXT monitor's DAC. On Intel-based hardware, this method sets up the card with the default serial port device, if any.

Returns:
Returns an id.

- (id) getMonitorVersion: (char *)  versionP
release: (int *)  releaseP 

Returns the version and release characters of the DSP monitor.

version is a pointer to a single character. No NULL is appended. release is a pointer to a single character. No NULL is appended.

Returns:
Returns nil if not open.

- (unsigned) capabilities  

returns an unsigned int, the bits of which report what capabilities are provided by the DSP device corresponding to the MKOrchestra.

Returns:
Returns an unsigned. Possible values (defined in MKOrchestra.h) are as follows: 
#define MK_nextCompatibleDSPPort 1
#define MK_hostSoundOut (1<<1)
#define MK_serialSoundOut (1<<2)
#define MK_soundIn (1<<3)
#define MK_soundfileOut (1<<4)

- (int) outputChannelCount  

Returns the number of output channels.

This information is normally derived from the serial port device, if any, or it defaults to 2. However, subclasses may override this method. For example, the ArielQPSat class, when sending its sound to the hub DSP, forwards this message to the ArielQP obect that represents the hub DSP.

Returns:
Returns an int.

Reimplemented in ArielQPSat.

- (BOOL) upSamplingOutput  

When sending sound to the DSP serial port, the sound may need to be up-sampled if the current sampling rate is supported by the serial port device only as a "half sampling rate".

See also:
DSPSerialPortDevice for more info).
Subclasses may override this method. For example, the ArielQPSat class, when sending its sound to the hub DSP, forwards this message to the ArielQP obect that represents the hub DSP.
Returns:
Returns YES if we are upsampling the sound before sending it to its output location.

Reimplemented in ArielQPSat.

- (id) setUpDSP  

A subclass may implement this message.

It is sent after boot and before sound out is started. The default implementation does nothing.

Returns:
Returns an id.

- (BOOL) startSoundWhenOpening  

Returns YES.

Subclass can override, if desired. For example, the ArielQP class overrides this method to return NO.

Returns:
Returns a BOOL.

+ (id) registerOrchestraSubclass: (id)  classObject
forOrchIndex: (int)  index 

Used by subclasses to register themselves as the default class for the specified DSP index.

This allows the user to say [MKOrchestra orchestraOnDSP:3] and get an instance of ArielQPSat, for example.

Parameters:
classObject is an id.
index is an int.
Returns:
Returns an id.

+ (NSArray *) getDriverNames  

Drivers now refer to independently addressable sound ports which consist of 1 or more channels of sound.

Returns those drivers returned by the SndKit.

Returns:
Returns an NSArray of driver names.

- (NSString *) driverName  

Returns the name of the sound driver associated with this instance of MKOrchestra.

The string is copied.

Returns:
Returns a NSString instance.

- (int) driverUnit  

<<Intel-based hardware only>> Returns the unit of the DSP driver associated with this instance of MKOrchestra.

Returns:
Returns an int.

+ (NSString *) driverParameter: (NSString *)  parameterName
forOrchIndex: (unsigned short)  index 

<<Intel-based hardware only>> Returns the parameter value of the specified driver parameter for the driver associated with the given index of MKOrchestra.

The string is not copied and should not be freed.

Parameters:
parameterName is a NSString.
index is an unsigned short.
Returns:
Returns an NSString.

- (NSString *) driverParameter: (NSString *)  parameterName  

<<Intel-based hardware only>> Returns the parameter value of the specified driver parameter for the driver associated with this instance of MKOrchestra.

The string is not copied and should not be freed.

Parameters:
parameterName is an NSString.
Returns:
Returns an NSString.

Member Data Documentation

- (double) computeTime [protected]

Runtime of orchestra loop in seconds.

- (double) samplingRate [protected]

Sampling rate.

- (NSMutableArray*) unitGeneratorStack [protected]

Stack of MKUnitGenerator instances in the order they appear in DSP memory. MKSynthData instances are not on this unitGeneratorStack.

- (NSString*) outputSoundfile [protected]

For output sound samples.

- (NSString*) inputSoundfile [protected]

For input sound samples. READ DATA

- (NSString*) outputCommandsFile [protected]

For output DSP commands.

- (MKDeviceStatus) deviceStatus [protected]

Status of MKOrchestra.

- (unsigned short) orchIndex [protected]

Index of the DSP resource managed by this instance.

- (BOOL) soundIn [protected]

Indicates if this orchestra will process incoming sound.

- (double) localDeltaT [protected]

positive offset in seconds added to out-going time-stamps

The documentation for this class was generated from the following file:
Generated on Sat Dec 5 17:01:15 2009 for MusicKit by  doxygen 1.5.6