MKSynthInstrument Class Reference

An MKSynthInstrument realizes MKNotes by synthesizing them on the DSP. More...

#import <MKSynthInstrument.h>

Inheritance diagram for MKSynthInstrument:

List of all members.

Public Member Functions
(id)	- init
	Initializes the receiver.
(int)	- setSynthPatchCount:patchTemplate:
	Immediately allocates voices MKSynthPatch objects using the patch template aTemplate (the MKOrchestra must be open) and puts the receiver in manual mode.
(int)	- setSynthPatchCount:
	Immediately allocates voices MKSynthPatch objects.
(int)	- synthPatchCountForPatchTemplate:
	Returns the number of allocated MKSynthPatch objects created with the MKPatchTemplate aTemplate.
(int)	- synthPatchCount
	Returns the number of allocated MKSynthPatch objects created with the default MKPatchTemplate.
(id)	- realizeNote:fromNoteReceiver:
	Synthesizes aNote.
(id)	- synthPatchClass
	Returns the receiver's MKSynthPatch class.
(id)	- setSynthPatchClass:
	Sets the receiver's MKSynthPatch class to aSynthPatchClass.
(id)	- setSynthPatchClass:orchestra:
	Like setSynthPatchClass: but also specifies that MKSynthPatch instances are to be allocated using the object anOrch.
(Class)	- orchestra
	Returns the value set with setSynthPatchClass:orchestra:, if any.
(id)	- preemptSynthPatchFor:patches:
	You never invoke this method.
(id)	- activeSynthPatches:
	Returns the first in the sequence of MKSynthPatches with MKPatchTemplate aTemplate that are currently sounding.
(id)	- mute:
	You never invoke this method; it's invoked automatically when the receiver receives a mute MKNote.
(id)	- autoAlloc
	Sets the receiver's allocation mode to MK_AUTOALLOC and releases any manually allocated MKSynthPatch objects.
(unsigned short)	- allocMode
	Returns the receiver's allocation mode, one of MK_AUTOALLOC or MK_MANUALALLOC.
(id)	- abort
	Sends the noteEnd message to all running (or finishing) MKSynthPatches managed by the receivers MKSynthInstrument.
(id)	- copyWithZone:
	Creates and returns a new MKSynthInstrument as a copy of the receiver.
(id)	- clearUpdates
	Causes the MKSynthInstrument to clear any noteUpdate state it has accumulated as a result of receiving noteUpdates without noteTags.
(id)	- setRetainUpdates:
	Controls whether the noteUpdate and controller state is retained from performance to performance.
(BOOL)	- doesRetainUpdates
	Returns whether the noteUpdate and controller state is retained from performance to performance.
(id)	- getUpdates:controllerValues:
	Returns by reference the MKNote used to store the accumulated noteUpdate state.
(id)	- allNotesOff
	Sends a noteOff: message to all running MKSynthPatches managed by this MKSynthInstrument.
Protected Attributes
id	synthPatchClass
unsigned short	allocMode
NSMutableDictionary *	taggedPatches
NSMutableDictionary *	controllerTable
MKNote *	updates
BOOL	retainUpdates
Class	orchestra

---

Detailed Description

An MKSynthInstrument realizes MKNotes by synthesizing them on the DSP.

It does this by forwarding each MKNote it receives to a MKSynthPatch object, which translates the parameter information in the MKNote into DSP instructions. A MKSynthInstrument can manage any number of MKSynthPatch objects (limited by the speed and size of the DSP). However, all of its MKSynthPatches are instances of the same MKSynthPatch subclass. You assign a particular MKSynthPatch subclass to a MKSynthInstrument through the latter's setSynthPatchClass: method. A MKSynthInstrument can change its MKSynthPatch at any time, even during a performance.

Each MKSynthPatch managed by the MKSynthInstrument corresponds to a particular noteTag. As the MKSynthInstrument receives MKNotes, it compares the MKNote's noteTag to the noteTags of the MKSynthPatches that it's managing. If a MKSynthPatch already exists for the noteTag, the MKNote is forwarded to that object; otherwise, the MKSynthInstrument either asks the MKOrchestra to allocate another MKSynthPatch, or it preempts an allocated MKSynthPatch to accommodate the MKNote. Which action it takes depends on the SynthInstrument's allocation mode and the available DSP resources.

A MKSynthInstrument can either be in automatic allocation mode (MK_AUTOALLOC) or manual mode (MK_MANUALALLOC). In automatic mode, MKSynthPatches are allocated directly from the MKOrchestra as MKNotes are received by the MKSynthInstrument and released when it's no longer needed. Automatic allocation is the default.

In manual mode, the MKSynthInstrument pre-allocates a fixed number of MKSynthPatch objects through the setSynthPatchCount: method. If it receives more simultaneously sounding MKNotes than it has MKSynthPatches, the MKSynthInstrument preempt its oldest running MKSynthPatch (by sending it the preemptFor: message).

The MKSynthInstrument has a "noteUpdate state", a MKNote object containing the most recent parameter values that the MKSynthInstrument has received from noteUpdates without noteTags. For example, the current value of MIDI pitch bend would be stored there. Additionally, the MKSynthInstrument has a "controllerTable." This is used to map MIDI controller numbers to the most recent controller values that the MKSynthInstrument has received from noteUpdates without noteTags. This information cannot be stored in the noteUpdate state because the noteUpdate state has room for only one controller/value pair.

By default, the update state is cleared after each performance. However, you can request that it be retained with the setRetainUpdates: method. You can examine the updates and controllerTable with the method getUpdates:controllerValues:.

---

Member Function Documentation

- (id) init

Initializes the receiver.

You invoke this method when you create a new instance of MKSynthInstrument. An overriding subclass method should send [super init] before setting its own defaults.

Returns:

Returns an id.

- (int) setSynthPatchCount:		(int)	voices
patchTemplate:		(id)	aTemplate

Immediately allocates voices MKSynthPatch objects using the patch template aTemplate (the MKOrchestra must be open) and puts the receiver in manual mode.

If aTemplate is nil, the value returned by the message:

[synthPatchClass defaultPatchTemplate]

is used. Returns the number of objects that were allocated (it may be less than the number requested). If you decrease the number of manually allocated MKSynthPatches during a performance, the extra MKSynthPatches aren't deallocated until they become inactive. In other words, reallocating downward won't interrupt notes that are already sounding.

Parameters:

	voices	is an int.
	aTemplate	is an id.

Returns:

Returns an int.

- (int) setSynthPatchCount:

(int)

voices

Immediately allocates voices MKSynthPatch objects.

Implemented as:

[self setSynthPatchCount: voices template: nil];

Returns the number of objects that were allocated.

Parameters:

voices

is an int.

Returns:

Returns an int.

- (int) synthPatchCountForPatchTemplate:

(id)

aTemplate

Returns the number of allocated MKSynthPatch objects created with the MKPatchTemplate aTemplate.

Parameters:

aTemplate

is an id.

Returns:

Returns an int.

- (int) synthPatchCount

Returns the number of allocated MKSynthPatch objects created with the default MKPatchTemplate.

Returns:

Returns an int.

- (id) realizeNote:		(MKNote *)	aNote
fromNoteReceiver:		(MKNoteReceiver *)	aNoteReceiver

Synthesizes aNote.

Parameters:

	aNote	is an MKNote instance.
	aNoteReceiver	is an MKNoteReceiver instance.

Returns:

Returns an id.

Reimplemented from MKInstrument.

- (id) synthPatchClass

Returns the receiver's MKSynthPatch class.

Returns:

Returns an id.

- (id) setSynthPatchClass:

(Class)

aSynthPatchClass

Sets the receiver's MKSynthPatch class to aSynthPatchClass.

Returns nil if the argument isn't a subclass of MKSynthPatch or the receiver is in a performance (the class isn't set in this case). Otherwise returns the receiver.

Parameters:

aSynthPatchClass

is an id.

Returns:

Returns an id.

- (id) setSynthPatchClass:		(Class)	aSynthPatchClass
orchestra:		(Class)	anOrch

Like setSynthPatchClass: but also specifies that MKSynthPatch instances are to be allocated using the object anOrch.

This is only used when you want a particular orchestra instance to be used rather than allocating from the MKOrchestra class. If anOrch is nil, the orchestra used is the value returned by [aSynthPatchClass orchestraClass].

Parameters:

	aSynthPatchClass	is an id.
	anOrch	is an MKOrchestra.

Returns:

Returns an id.

- (Class) orchestra

Returns the value set with setSynthPatchClass:orchestra:, if any.

Otherwise returns [MKOrchestra class].

Returns:

Returns a Class.

- (id) preemptSynthPatchFor:		(MKNote *)	aNote
patches:		(MKSynthPatch *)	firstPatch

You never invoke this method.

It's invoked automatically when the receiver is in manual mode and all MKSynthPatches are in use, or when it's in auto mode and the DSP resources needed to build another MKSynthPatch aren't available. The return value is taken as the MKSynthPatch to preempt in order to accommodate the latest request. firstPatch is the first in a sequence of ordered active MKSynthPatches, as returned by the activeSynthPatches: method. The default implementation simply returns firstPatch, the MKSynthPatch with the oldest phrase. A subclass can reimplement this method to provide a different scheme for determining which MKSynthPatch to preempt.

Parameters:

	aNote	is an MKNote instance.
	firstPatch	is an id.

Returns:

Returns an id.

- (id) activeSynthPatches:

(id)

aTemplate

Returns the first in the sequence of MKSynthPatches with MKPatchTemplate aTemplate that are currently sounding.

The sequence is ordered by the begin times of the MKSynthPatches' current phrases, from the earliest to the latest. In addition, all finishing MKSynthPatches are returned before all running MKSynthPatches. You step down the sequence by sending next to the objects returned by this method. If aTemplate is nil, the default MKPatchTemplate is used. If there aren't any active MKSynthPatches with the specified template, nil is returned.

Parameters:

aTemplate

is an id.

Returns:

Returns an id.

- (id) mute:

(id)

aMute

You never invoke this method; it's invoked automatically when the receiver receives a mute MKNote.

Mutes aren't normally forwarded to MKSynthPatches since they usually don't produce sound. The default implementation does nothing. A subclass can implement this method to examine aMute and act accordingly.

Parameters:

aMute

is an id.

Returns:

Returns an id.

- (id) autoAlloc

Sets the receiver's allocation mode to MK_AUTOALLOC and releases any manually allocated MKSynthPatch objects.

If the receiver is in performance and isn't already in MK_AUTOALLOC mode, this does nothing and returns nil. Otherwise returns the receiver.

Returns:

Returns an id.

- (unsigned short) allocMode

Returns the receiver's allocation mode, one of MK_AUTOALLOC or MK_MANUALALLOC.

Returns:

Returns an unsigned short.

- (id) abort

Sends the noteEnd message to all running (or finishing) MKSynthPatches managed by the receivers MKSynthInstrument.

Returns:

Returns an id. You should only invoke this method when all other attempts to halt synthesis fails.

- (id) copyWithZone:

(NSZone *)

zone

Creates and returns a new MKSynthInstrument as a copy of the receiver.

The copy has the same (MKNoteReceiver) connections but has no MKSynthPatches allocated.

Parameters:

zone

is a NSZone.

Returns:

Returns an id.

Reimplemented from MKInstrument.

- (id) clearUpdates

Causes the MKSynthInstrument to clear any noteUpdate state it has accumulated as a result of receiving noteUpdates without noteTags.

The effect is not felt by the MKSynthPatches until the next phrase. Also clears controller info.

Returns:

Returns an id.

- (id) setRetainUpdates:

(BOOL)

yesOrNo

Controls whether the noteUpdate and controller state is retained from performance to performance.

Default is NO.

Parameters:

yesOrNo

is a BOOL.

Returns:

Returns an id.

- (BOOL) doesRetainUpdates

Returns whether the noteUpdate and controller state is retained from performance to performance.

Returns:

Returns a BOOL.

- (id) getUpdates:		(MKNote **)	aNoteUpdate
controllerValues:		(NSMutableDictionary **)	controllers

Returns by reference the MKNote used to store the accumulated noteUpdate state.

Parameters:

	aNoteUpdate	is a MKNote **.
	controllers	is a NSMutableDictionary **.

Returns:

Returns an id. Also returns by reference the NSMutableDictionary used to store the state of the controllers. Any alterations to the returned objects will effect future phrases. The returned objects should be used only immediately after they are returned, as they may later be freed by the MKSynthInstrument. If clearUpdates is sent or the performance ends, the objects may be emptied or freed by the MKSynthInstrument.

- (id) allNotesOff

Sends a noteOff: message to all running MKSynthPatches managed by this MKSynthInstrument.

Returns:

Returns an id.

Reimplemented from MKInstrument.

---

Member Data Documentation

- (id) synthPatchClass [protected]

class used to create patches.

- (unsigned short) allocMode [protected]

One of MK_MANUALALLOC, MK_AUTOALLOC, or MK_MIXEDALLOC.

- (NSMutableDictionary*) taggedPatches [protected]

Dictionary mapping noteTags to MKSynthPatches

- (NSMutableDictionary*) controllerTable [protected]

Dictionary mapping MIDI controllers to values

- (MKNote*) updates [protected]

MKNote for storing common (no noteTag) updates.

- (BOOL) retainUpdates [protected]

NO if updates and controllerTable are cleared after each performance.

- (Class) orchestra [protected]

MKOrchestra class to allocate MKSynthPatches from

---

The documentation for this class was generated from the following file:

• MKSynthInstrument.h