+ nthOrchestra:(unsigned short)index
Returns the Orchestra of the index'th DSP. If index is out of bounds, or if an Orchestra hasn't been created for the specified DSP, nil is returned.
open
+ openSends open to each of the Orchestra instances and sets each to MK_devOpen. If any of the Orchestras responds to the open message by returning nil, so, too, does this method return nil. Otherwise returns self.
run
+ runSends run to each of the Orchestra instances and sets each to MK_devRunning. If any of the Orchestras responds to the run message by returning nil, so, too, does this method return nil. Otherwise returns self.
setFastResponse:
+ setFastResponse:(BOOL)yesOrNo
Sends setFastResponse:yesOrNo to all existing Orchestra objects and returns self.
This also sets the default used by subsequently created Orchestras.
setHeadroom:
+ setHeadroom:( double )headroom
Sets the headroom of all Orchestra instances to headroom. Returns self.
setLocalDeltaT:
+ setLocalDeltaT: (double )val
Sets the local delta time for all Orchestras and changes the default, which is otherwise 0.0.
setSamplingRate:
+ setSamplingRate:( double )newSRate
Sets the sampling rate of all Orchestra instances by sending
setSamplingRate:newSRate to all closed 01',:;hestras. This method also changes the default sampling rate; when a new Orchestra is subsequently created, it also gets set to newSRate. Returns self.
setTimed:
+ setTimed:(BOOL)areOrchsTimed
Sends setTimed:areOrchsTimed to each Orchestra instance. 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 Orchestra is timed; this method sets the default to areOrchsTimed.
stop
+ stopSends stop to each of the Orchestra instances and sets each to MK_devStopped. If any of the Orchestras responds to the run message by returning nil, so, too, does this method return nil. Otherwise returns self.
INSTANCE METHODS
abort
- abort
This is the same as close, except it doesn't wait for enqueued DSP commands to be executed. Returns nil if an error occurs, otherwise returns self.
allocPatchpoint:
- allocPatchpoint:(MKOrchMemSegment)segment
Allocates and returns a SynthData to be used as a patchpoint in the specified segment (MK_xPatch or MK_yPatch). Returns nil if an illegal segment is requested.
allocSynthData:length:
- allocSynthData:(MKOrchMemSegment)segment length:(unsigned)size
Allocates and returns a new SynthData object with the specified length, or nil if the Orchestra doesn't have sufficient resources, if size is 0, or if an illegal segment is requested. segment should be MK_xData or MK_yData.
allocSynthPatch:
- allocSynthPatch:aSynthPatchC lass
Same as allocSynthPatch:patchTemplate: but uses the default template.
allocSynthPatch:patchTemplate:
- allocSynthPatch:aSynthPatchClass patchTemplate:p
Allocates and returns a SynthPatch for PatchTemplate p. The Orchestra first tries to find an idle SynthPatch; failing that, it creates and returns a new one. If a new one can't be built, this method returns nil.
allocU nitGenerator:
- allocUnitGenerator:class
Allocates and returns a UnitGenerator of the specified class, creating a new one if necessary.
alloc U nitGenerator :after:
- allocUnitGenerator:class after:aUnitGeneratorlnstance
Allocates and returns a UnitGenerator of the specified class. The newly allocated object will execute after aUnitGeneratorlnstance.
allocUnitGenerator:before:
- allocUnitGenerator:class before:aUnitGeneratorlnstance
Allocates and returns a UnitGenerator of the specified class. The newly allocated object will execute before aUnitGeneratorlnstance.
alloc U nitGenerator: between::
- allocUnitGenerator:class
between:aUnitGeneratorlnstance :anotherU nitGeneratorI nstance
Allocates and returns a UnitGenerator of the specified class. The newly allocated object will execute after aUnitGeneratorlnstance and before anotherUnitGenerator.
beginAtomicSection - beginAtomicSection
Marks the beginning of a section of DSP commands that are sent as a unit; this method should be balanced by endAtomicSection. Returns self. You should use this method when you are sending a block of DSP commands that, if broken up, would leave the DSP in an inconsistent state. Atomic sections are recursive: If you send
beginAtomicSection twice, you must send end Atomic Section twice.
close - close
Severs communication with the DSP, allowing other processes to claim it. Before closing, all enqueued DSP commands are executed. The SynthPatch-allocated UnitGenerators and Synthlnstrument-allocated SynthPatches are freed. All SynthPatches must be idle and non-SynthPatch-allocated UnitGenerators must be deallocated before sending this message. Returns nil if an error occurs, otherwise returns self.
computeTime
- (double )computeTime
Returns the compute time estimate currently used by the Orchestra, in seconds-per-sample.
dealloc:
- dealloc:aSynthResource
Deallocates aSynthResource by sending it the dealloc message. aSynthResource may be a UnitGenerator, a SynthData, or a SynthPatch.
deviceStatus
- (MKDeviceStatus )deviceStatus Returns the Orchestra status, one of
MK_devClosed MK_devOpen MK_devRunning
• MK_devStopped
The Orchestra states are explained in the class description, above.
endAtomicSection - endAtomicSection
Marks the end of a section of DSP commands that are sent as a unit, as begun by beginAtomicSection. Returns self.
fastResponse
- (BOOL)fastResponse
Returns YES if the Orchestra is using small sound-out buffers to minimize response latency. Otherwise returns NO.
flushTimedMessages - flushTimedMessages
Sends buffered DSP commands to the DSP. This is usually done for you by the Conductor; however, if your application sends messages directly to a SynthPatch or UnitGenerator without the assistance of a Conductor, you must invoke this method yourself (after sending the synthesis messages). Returns self.
free - free
Frees the Orchestra and its UnitGenerators, clears all SynthPatch allocation lists, and releases the DSP. All SynthPatches must be idle and non-SynthPatch-allocated UnitGenerators must be deallocated before sending this message. Returns nil if an error occurs, otherwise returns self.
headroom
- (double )headroom
Returns the Orchestra's headroom, as set through the setHeadroom: method.
Headroom should be a value between -.0 and 1.0. The default is 0.1.
index
- (unsigned short)index
Returns the (zero-based) index of the DSP associated with the Orchestra.
installSharedObject:for:
- installSharedObject:aSynthObj for:aKeyObj
Places aSynthObj on the shared object table and sets its reference count to 1. aKeyObj 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 self.
This method differs from installSharedObjectWithSegmentAndLength:for: in that the length and segment are wild cards.
installSharedSynthData WithSegment:for:
- installSharedSynthData WithSegment:aSynthDataObj for: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 isn't open.
Otherwise, returns self.
This method differs from installSharedObjectWithSegmentAndLength:for: in that the length is a wild card.
installSharedSynthData WithSegmentAndLength:for:
- installSharedSynthDataWithSegmentAndLength:aSynthDataObj for:aKeyObj 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 isn't open. Otherwise, returns self.
isTimed
- (BOOL)isTimed
Returns YES if the Orchestra is timed, NO if it's untimed.
localDeltaT
- (double)localDeltaT
Returns the value set through setLocalDeltaT:.
muLawROM
-muLawROM
Returns a SynthData object representing the MuLawROM. You should never deallocate this object.
open
-open
Opens the Orchestra's DSP and sets the Orchestra's status to MK_devOpen. Returns nil if the DSP can't be opened, otherwise returns self.
outputCommandsFile
- (char *)outputCommandsFile
Returns a pointer to the name of the Orchestra's DSP commands format soundfile, or NULL if none.
outputSoundfile
- (char *)outputSoundfile
Returns a pointer to the name of the Orchestra's output soundfile, or NULL if none.
peekMemoryResources:
- (MKOrchMemStruct *)peekMemoryResources:(MKOrchMemStruct *)peek Returns the available resources in peek, which must be a pointer to a valid
MKOrchMemStuct. The returned value is the available memory for each segment;
however, xData, yData and pSubr compete for the same memory. You should interpret the returned value with appropriate caution.
run
-run
Starts the clock on the Orchestra's DSP, thus allowing the processor to begin executing commands, and sets the Orchestra's status to MK_devRunning. This opens the DSP if it isn't already open. Returns nil if the DSP couldn't be opened or run, otherwise returns self.
samplingRate
- (double )samplingRate
Returns the Orchestra's sampling rate. The default is 22050.0.
segmentName:
- (char *)segmentName:(int)whichSegment
Returns a pointer to the name of the specified MKOrchMemSegment.
segmentSink:
- segmentSink:(MKOrchMemSegment)segment
Returns a special pre-allocated patchpoint (a SynthData) in the specified segment from which, by convention, data is never read. It's commonly used as a place to send the output of idle UnitGenerators. The patchpoint shouldn't be deallocated. The argument must be either MK_xPatch or MK_yPatch.
segmentZero:
- segmentZero:(MKOrchMemSegment)segment
Returns a special pre-allocated patchpoint (a SynthData) in the specified segment that always holds 0 and to which, by convention, nothing is ever written. The patchpoint shouldn't be deallocated. The argument must be either MK_xPatch or MK_yPatch.
setFastResponse:
- setFastResponse:(BOOL)yesOrNo
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 Orchestra uses the larger buffer. Returns self.
setHeadroom:
- setHeadroom:(double)headroom
Sets the Orchestra's computation headroom, adjusting the tradeoff between processing power and reliability. The argument should be in the range -.0 to 1.0. As you increase an Orchestra'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 Orchestra thinks the DSP has to produce a sample-is based on the formula
(1.0/samplingRate)
*
(1.0 - headroom).Returns self.
setLocalDeltaT:
- setLocalDeltaT:(double)val
Sets the offset, in seconds, that's added to the timestamps of commands sent to the Orchestra's DSP. The offset is added to the delta time that's set with MKSetDeltaTO.
This has no effect if the receiver isn't timed. Returns self.