MKSynthPatch Class Reference

A MKSynthPatch contains a configuration of MKUnitGenerators that work as a sound synthesis module. More...

#import <MKSynthPatch.h>

Inheritance diagram for MKSynthPatch:

List of all members.

Public Member Functions
(id)	- synthInstrument
	Returns synthInstrument owning the receiver, if any.
(id)	- init
	Sent by the MKOrchestra only when a new MKSynthPatch has just been created and before its MKUnitGenerator connections have been made, as defined by the MKPatchTemplate.
(id)	- synthElementAt:
	Returns the MKUnitGenerator or MKSynthData at the specified index or nil if anIndex is out of bounds.
(void)	- mkdealloc
	(sb): changed to mkdealloc to prevent conflict with OpenStep deallocation.
(id)	- preemptFor:
	Sent when the receiver is running or finishing and is preempted by its MKSynthInstrument.
(id)	- noteOnSelf:
	You never invoke this method directly.
(id)	- noteUpdateSelf:
	You never invoke this method, it's invoked automatically by noteUpdate:.
(double)	- noteOffSelf:
	You never invoke this method; it's invoked automatically by noteOff:.
(id)	- noteEndSelf
	This method is invoked automatically when the MKNote stream is complete.
(id)	- noteOn:
	This starts or rearticulates a MKNote stream by sending noteOnSelf:aNote to the receiver.
(id)	- noteUpdate:
	Sent ordinarily only by the MKSynthInstrument when a noteUpdate is received.
(double)	- noteOff:
	Concludes a MKNote stream by sending [self noteOffSelf: aNote].
(id)	- noteEnd
	Causes the receiver to become idle.
(id)	- moved:
	Sent when the MKOrchestra moves a MKSynthPatch's MKUnitGenerator during DSP memory compaction.
(int)	- status
	Returns the status of the receiver.
(BOOL)	- isEqual:
	Two MKSynthPatches are considered equal if they have the same noteTag.
(unsigned)	- hash
	Uses the noteTag to hash itself.
(id)	- patchTemplate
	Returns the MKPatchTemplate associated with the receiver.
(int)	- noteTag
	Returns the noteTag associated with the MKNote stream the receiver is currently playing.
(id)	- orchestra
	Returns the MKOrchestra instance to which the receiver belongs.
(BOOL)	- isFreeable
	Returns YES if the receiver may be freed; otherwise returns NO.
(id)	- controllerValues:
	Sent by the MKSynthInstrument to a MKSynthPatch when a new tag stream begins, before the noteOn: message is sent.
(id)	- next
	This method is used in conjunction with a MKSynthInstrument's preemptSynthPatchFor:patches: method.
(id)	- freeSelf
	Sent just before the receiver is free, a subclass can implement this method to provide specialized behavior.
(MKPhraseStatus)	- phraseStatus
	This is a convenience method for MKSynthPatch subclass implementors.
Static Public Member Functions
(id)	+ patchTemplateFor:
	Returns an appropriate MKPatchTemplate with which to create an MKSynthPatch instance that will adequately synthesize currentNote.
(id)	+ orchestraClass
	Always returns the MKOrchestra class.
(id)	+ defaultPatchTemplate
	Returns the default MKPatchTemplate for the class.
Protected Attributes
NSMutableArray *	synthElements
id	synthInstrument
int	noteTag
MKSynthStatus	status
id	patchTemplate
BOOL	isAllocated
MKOrchestra *	orchestra

---

Detailed Description

A MKSynthPatch contains a configuration of MKUnitGenerators that work as a sound synthesis module.

MKSynthPatches are not created by the application; rather, they're created by the MKOrchestra. The MKOrchestra is also responsible for filling the MKSynthPatch instance with MKUnitGenerator and MKSynthData instances. It does this on the basis of a template provided by the MKSynthPatch class method patchTemplate. You implement this method in a subclass of MKSynthPatch to provide a MKPatchTemplate that specifies the mix of MKUnitGenerators and MKSynthData objects, in what order they're allocated, and how to connect them.

Typically, a MKSynthPatch is owned and operated by a MKSynthInstrument object. The MKSynthInstrument manages the allocation of MKSynthPatches in response to incoming MKNotes. Alternatively, MKSynthPatches may be used in a stand-alone fashion. In this case, you must allocate the objects by sending the MKOrchestra an allocSynthPatch: or allocSynthPatch:patchTemplate: message.

While in performance, a MKSynthPatch is identified by the noteTag of the MKNote stream that it's synthesizing.

---

Member Function Documentation

+ (id) patchTemplateFor:

(MKNote *)

currentNote

Returns an appropriate MKPatchTemplate with which to create an MKSynthPatch instance that will adequately synthesize currentNote.

Determines an appropriate patchTemplate and returns it. In some cases, it is necessary to look at the current note to determine which patch to use. This method is invoked by MKSynthInstrument whenever it needs to allocate a new MKSynthPatch instance. It may also be sent by an application to obtain the template to be used as the second argument to MKSynthInstrument's setSynthPatchCount:patchTemplate: method. Implementation of this method is a subclass responsibility such that when currentNote is nil, a default template is returned.

Parameters:

currentNote

is an MKNote instance. If currentNote is nil, the default template should be returned.

Returns:

Returns an id.

Reimplemented in DBWave2vi, Fm1, Fm1v, Fm2cnvi, Fm2cvi, Fm2pnvi, Fm2pvi, Pluck, Shape, Shapev, Simp, Wave1, Wave1i, and Wave1v.

+ (id) orchestraClass

Always returns the MKOrchestra class.

Returns:

Returns an id. It's provided for applications that extend the Music Kit to use other hardware. Each MKSynthPatch subclass is associated with a particular kind of hardware. The default hardware is that represented by MKOrchestra, the DSP56001.

+ (id) defaultPatchTemplate

Returns the default MKPatchTemplate for the class.

Returns:

Returns an id.

You never implement this method. It is the same as return [self patchTemplateFor: nil].

- (id) synthInstrument

Returns synthInstrument owning the receiver, if any.

Returns:

Returns an id.

- (id) init

Sent by the MKOrchestra only when a new MKSynthPatch has just been created and before its MKUnitGenerator connections have been made, as defined by the MKPatchTemplate.

Returns:

Returns an id. A subclass may override the init method to provide additional initialization. A return of nil aborts the creation and frees the new MKSynthPatch. The default implementation does nothing and returns the receiver.

Reimplemented in Fm1i, Pluck, Shape, and Wave1i.

- (id) synthElementAt:

(unsigned)

anIndex

Returns the MKUnitGenerator or MKSynthData at the specified index or nil if anIndex is out of bounds.

Parameters:

anIndex

is an unsigned int and is zero-based.

Returns:

Returns an id.

- (void) mkdealloc

(sb): changed to mkdealloc to prevent conflict with OpenStep deallocation.

This is used to explicitly deallocate a MKSynthPatch you previously allocated manually from the MKOrchestra with allocSynthPatch: or allocSynthPatch:patchTemplate:. It sends noteEnd to the receiver, then causes the receiver to become deallocated and returns nil. This message is ignored (and self is returned) if the receiver is owned by a MKSynthInstrument.

- (id) preemptFor:

(MKNote *)

aNote

Sent when the receiver is running or finishing and is preempted by its MKSynthInstrument.

This happens, for example, when a MKSynthInstrument with 3 voices receives a fourth note. It preempts one of the voices by sending it preemptFor:newNote followed by noteOn:newNote. The default implementation does nothing and returns self. Normally, a time equal to the value returned by MKPreemptDuration() is allowed to elapse before the preempting MKNote begins. A subclass can specify that the new MKNote happen immediately by returning nil.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns an id.

Reimplemented in Fm1i, Pluck, Shape, and Wave1i.

- (id) noteOnSelf:

(MKNote *)

aNote

You never invoke this method directly.

The default implementation returns the receiver. Subclass may override this method to do any initialization needed for each noteOn. noteOnSelf: is sent whenever a new MKNote stream commences, even if the MKSynthPatch is already running. The subclass can determine whether or not the MKSynthPatch is already running by examing the status instance variable. It should also check for preemption with -phraseStatus.

The message noteEnd is sent to the receiver if this method returns nil.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns the receiver or nil if the receiver should immediately become idle.

Reimplemented in DBWave2vi, Fm1i, Fm2cnvi, Fm2cvi, Fm2pnvi, Fm2pvi, Pluck, Shape, Simp, and Wave1i.

- (id) noteUpdateSelf:

(MKNote *)

aNote

You never invoke this method, it's invoked automatically by noteUpdate:.

A subclass can implement this method to provide behavior appropriate to reception of a noteUpdate. noteUpdateSelf: should send whatever messages are necessary to update the state of the DSP as reflected by the parameters in aNote.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns an id.

Reimplemented in DBWave2vi, Fm1i, Fm2cnvi, Fm2cvi, Fm2pnvi, Fm2pvi, Pluck, Shape, Simp, and Wave1i.

- (double) noteOffSelf:

(MKNote *)

aNote

You never invoke this method; it's invoked automatically by noteOff:.

It is sent when a noteOff or end-of-noteDur is received. However, a subclass may provide an implementation that describes its response to a noteOff, the beginning of the final segment of the note or phrase. The return value is the amount of time to wait, in seconds, before the MKSynthPatch can be released. For example, a MKSynthPatch that has 2 envelope handlers should implement this method to send finish to each envelope handler and return the maximum of the two. The default implementation returns 0.0.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns a double.

Reimplemented in DBWave2vi, Fm1i, Fm2cnvi, Fm2cvi, Fm2pnvi, Fm2pvi, Pluck, Shape, Simp, and Wave1i.

- (id) noteEndSelf

This method is invoked automatically when the MKNote stream is complete.

Returns:

Returns an id. You never invoke this method directly; it's invoked by the MKSynthInstrument. A subclass may override this to do what it needs to do to ensure that the MKSynthPatch produces no output. Usually, the subclass implementation sends the idle message to the Out2sumUGx or Out2sumUGy MKUnitGenerator. The default implementation does nothing and returns the receiver.

Reimplemented in DBWave2vi, Fm1i, Fm2cnvi, Fm2cvi, Fm2pnvi, Fm2pvi, Pluck, Shape, Simp, and Wave1i.

- (id) noteOn:

(MKNote *)

aNote

This starts or rearticulates a MKNote stream by sending noteOnSelf:aNote to the receiver.

If noteOnSelf: returns self, the receiver's status is set to MK_running and the receiver is returned. If noteOnSelf: returns nil, noteEnd is sent to the receiver and nil is returned. Ordinarily sent only by MKSynthInstrument.

Parameters:

aNote

is an MKNote instance.

Returns:

Returns an id.

- (id) noteUpdate:

(MKNote *)

aNote

Sent ordinarily only by the MKSynthInstrument when a noteUpdate is received.

Implemented as [self noteUpdateSelf:aNote].

Parameters:

aNote

is an MKNote instance.

Returns:

Returns an id.

- (double) noteOff:

(MKNote *)

aNote

Concludes a MKNote stream by sending [self noteOffSelf: aNote].

Sets the receiver's status to MK_finishing. This method is ordinarily invoked only by an MKSynthInstrument.

Parameters:

aNote

is an MKNote.

Returns:

Returns the release duration as returned by noteOffSelf:

- (id) noteEnd

Causes the receiver to become idle.

Returns:

Returns self.

The message noteEndSelf is sent to the receiver and its status is set to MK_idle. Ordinarily this is invoked automatically by the MKSynthInstrument, but may be sent by anyone to immediately stop a patch.

- (id) moved:

(MKUnitGenerator *)

aUG

Sent when the MKOrchestra moves a MKSynthPatch's MKUnitGenerator during DSP memory compaction.

aUG is the unit generator that was moved. A subclass can override this method to provide specialized behavior. The default implementation does nothing.

See also:

- phraseStatus.

Parameters:

aUG

is an MKUnitGenerator instance.

Returns:

Returns an id.

- (int) status

Returns the status of the receiver.

Returns:

Returns an int.

This is not necessarily the status of all contained MKUnitGenerators. For example, it is not unusual for a MKSynthPatch to be idle but most of its MKUnitGenerators, with the exception of the Out2sum, to be running.

- (BOOL) isEqual:

(MKSynthPatch *)

anObject

Two MKSynthPatches are considered equal if they have the same noteTag.

This is used by the MKSynthInstrument to search for a MKSynthPatch matching a certain noteTag.

Parameters:

anObject

is an MKSynthPatch instance.

Returns:

Returns a BOOL.

- (unsigned) hash

Uses the noteTag to hash itself.

Returns:

Returns an unsigned.

- (id) patchTemplate

Returns the MKPatchTemplate associated with the receiver.

Returns:

Returns an id.

- (int) noteTag

Returns the noteTag associated with the MKNote stream the receiver is currently playing.

Returns:

Returns an int.

- (id) orchestra

Returns the MKOrchestra instance to which the receiver belongs.

Returns:

Returns an id.

All MKUnitGenerators and MKSynthData in an instance of MKSynthPatch are on the same MKOrchestra instance. In the standard NeXT configuration, there is one DSP and, thus, one MKOrchestra instance.

- (BOOL) isFreeable

Returns YES if the receiver may be freed; otherwise returns NO.

Returns:

Returns a BOOL. An MKSynthPatch may only be freed if it is idle and not owned by a manually allocated MKSynthInstrument.

- (id) controllerValues:

(id)

controllers

Sent by the MKSynthInstrument to a MKSynthPatch when a new tag stream begins, before the noteOn: message is sent.

The default implementation does nothing. You may override it in a subclass as desired.

Note that the sustain pedal controller is handled automatically by the MKSynthPatch class. Note that pitchbend is not a controller in MIDI. Thus the current pitchbend is included in the MKNote passed to noteOn:, not in the HashTable. See the HashTable spec sheet for details on how to access the values in controllers. The table should not be altered by the receiver.

Parameters:

controllers

is a HashTable that describes the state of the MIDI controllers by mapping integer controller numbers to integer controller values.

Returns:

Returns an id.

Reimplemented in Fm1i, and Wave1i.

- (id) next

This method is used in conjunction with a MKSynthInstrument's preemptSynthPatchFor:patches: method.

Returns:

Returns an id. It returns the next MKSynthPatch in a List of active MKSynthPatches owned by the MKSynthInstrument. The objects in the List are in the order in which they began synthesizing their current phrases (oldest first), i.e in the order of the onset times of the phrases played by the MKSynthPatches.

- (id) freeSelf

Sent just before the receiver is free, a subclass can implement this method to provide specialized behavior.

Returns:

Returns an id.

- (MKPhraseStatus) phraseStatus

This is a convenience method for MKSynthPatch subclass implementors.

The value returned takes into account whether the phrase is preempted, the noteType of the current MKNote and the status of the receiver. If not called by a MKSynthPatch subclass, returns MK_noPhraseActivity.

Returns:

Returns a MKPhraseStatus.

---

Member Data Documentation

- (NSMutableArray*) synthElements [protected]

Array of MKUnitGenerator and MKSynthData objects.

- (id) synthInstrument [protected]

The MKSynthInstrument object currently in possession of the MKSynthPatch or nil if none.

- (int) noteTag [protected]

Tag of notes currently implemented by this MKSynthPatch.

- (MKSynthStatus) status [protected]

Status of patch. One of MK_running, MK_finishing or MK_idle. You should never set it explicitly in your subclass.

- (id) patchTemplate [protected]

MKPatchTemplate of this patch.

- (BOOL) isAllocated [protected]

YES if the object is allocated.

- (MKOrchestra*) orchestra [protected]

MKOrchestra instance on which the object is allocated and on which this MKSynthPatch is running.

---

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

• MKSynthPatch.h