MKPartials Class Reference

The MKPartials class lets you define a sound waveform by adding together a number of sine wave components. More...

#import <MKPartials.h>

Inheritance diagram for MKPartials:

List of all members.

Public Member Functions
(id)	- init
	Initializes the receiver.
(id)	- copyWithZone:
	Creates and returns a new MKWaveTable as a copy of the receiver.
(void)	- dealloc
	dealloc frees dataDSP and dataDouble then sends [super free].
(double)	- highestFreqRatio
	Returns the highest (i.e., largest absolute value) frequency ratio in the receiver.
(id)	- setPartialCount:freqRatios:ampRatios:phases:orDefaultPhase:
	Defines the receiver's sine wave components.
(id)	- setFromSamples:
	Sets freqRatios, ampRatios, and phases based on the data in the samplesObject.
(id)	- prunePartials:
	Change contents to remove any partials with amplitudes below specified threshold.
(int)	- partialCount
	Returns the number of sine wave components.
(double *)	- freqRatios
	Returns a pointer to the receiver's frequency ratios array.
(double *)	- ampRatios
	Returns a pointer to the receiver's amplitude ratios array.
(double)	- defaultPhase
	Returns the receiver's default phase.
(double *)	- phases
	Returns a pointer to the receiver's phase array or NULL if none.
(int)	- getPartial:freqRatio:ampRatio:phase:
	Returns, by reference, the frequency ratio, amplitude ratio, and initial phase of the nth sine wave component (counting from 0).
(id)	- writeScorefileStream:
	Writes the receiver in scorefile format on the specified stream.
(int)	- tableType
	Returns the tableType of the currently-cached data, if any.
Protected Attributes
double *	freqRatios
double *	phases
int	partialCount
double	defaultPhase
double	minFreq
double	maxFreq

---

Detailed Description

The MKPartials class lets you define a sound waveform by adding together a number of sine wave components.

MKPartials are used to provide musical timbres in DSP synthesis, primarily by the MKSynthPatch classes that provide wave table synthesis - classes such as Wave1vi and DBWave1vi, as well as classes that provide waveshaping synthesis - class such as Shape. MKPartials' sister class, MKSamples, lets you define a waveform (or waveshaping table) as a series of sound samples, through association with a Snd object or soundfile.

Each of the sine waves in a MKPartials object is characterized by a frequency ratio, an amplitude ratio, and an initial phase. The frequency ratios are taken as integer multiples of a fundamental frequency - in other words, a ratio of 1.0 is the fundamental frequency, 2.0 is twice the fundamental, 3.0 is three times the fundamental, and so on. The fundamental frequency itself is defined in the frequency parameters of the MKNote objects that use the MKPartials. The amplitude ratios are relative to each other: A sine wave component with an amplitude ratio of 0.5 has half the amplitude of a component with an amplitude ratio of 1.0. The initial phase determines the point in the sine curve at which a particular component starts. Phase is specified in degrees; a phase of 360.0 is the same as a phase of 0.0. While phase information has been found to have little significance in the perception of timbre, it can be important in other uses. For example, if you're creating a waveform that's used as a sub-audio control signal - most notably for vibrato - you will probably want to randomize or stagger the phases of the sine waves.

All the component information for a MKPartials object is set through the setPartialCount:freqRatios:ampRatios:phases:orDefaultPhase: method. The first argument, an int, is the number of sine waves in the object. The next three arguments are pointers to arrays of doubles that provide corresponding lists of frequency, amplitude, and phase information. The additional orDefaultPhase: keyword is provided in recognition of phase's slim contribution to the scheme: Rather than create and set an array of initial phases, you can pass NULL to phases: and set all the sine wave components to a common initial phase as the argument to orDefaultPhase:. The following example demonstrates how to create a simple, three component MKPartials object.

double freqs = {1.0, 2.0, 3.0 }; double amps = {1.0, 0.5, 0.25 }; MKPartials *aPartials = [MKPartials new];

[aPartials setPartialCount: 3 freqRatios: freqs ampRatios: amps phases: NULL orDefaultPhase: 0.0];

The elements in the arrays are matched by index order: The first sine wave is defined by the first element of freqs and the first element of amps; the second elements of the arrays define the second sine wave; the third elements define the third sine wave. Since the phase array is specified as NULL, all three sine waves are given an initial phase of 0.0.

In a scorefile, MKPartials are defined as curly-bracketed value pairs - or triplets if you want to specify phase - and the entire MKPartials definition is enclosed in square brackets. If a phase value is missing, the phase of the previous component is used; the default phase is 0.0. You can define a MKPartials object in-line as the value of a parameter or, more typically, in a global waveTable statement. The previous example could be defined in a scorefile as

waveTable simpleSound = [{1.0, 1.0}{2.0, 0.5}{3.0, 0.25}];

where simpleSound is used to identify the object in subsequent MKNote statements:

partName (1.0) ... waveform:simpleSound ...;

When this scorefile is read into an application, the MKPartials object will be given the string name “simpleSound”. The object itself can be retrieved by passing this string to the MKGetNamedObject() C function.

If you're creating a MKPartials object in an application and writing it to a scorefile, you should always name the object through MKNameObject(). This allows the object to be defined once (albeit in-line, not in the header) in a waveTable statement and then referred to by name in subsequent MKNotes. Without a name, a MKPartials object is defined in-line in every MKNote statement that refers to it.

MKPartials objects are automatically created by the MusicKit in a number of circumstances, such as when reading a Scorefile. The function MKSetPartialsClass() allows you to specify that your own subclass of MKPartials be used when Partialss are automatically created. You retrieve the MKPartials class with MKGetPartialsClass().

MKPartials can be used in two contexts - to provide wavetables for oscillators and to provide lookup tables for waveshaping synthesis. The access methods inherited from the MKWaveTable class (such as -dataDSP) provide the data in oscillator table format. In this case the MKPartials tableTypeinternal instance varaible is set to MK_oscTable. Alternatively, you can retrieve the data in waveshaping format. To do this, use one of the methods of the form accessMethodAsWaveshapingTablearguments. For example, to get the data for the DSP with the default table length and scaling, use -dataDSPAsWaveshapingTable. In this case the MKPartials tableType instance varaible is set to MK_waveshapingTable. For symmetry, a set of methods of the form dataDSPAsOscTable is provided. These methods are synonyms for the inherited methods.

For more information on waveshaping synthesis, see the Shape and Shapev MKSynthPatches and their documentation.

---

Member Function Documentation

- (id) init

Initializes the receiver.

Returns:

Returns an id. A subclass implementation should send [super init] before performing its own initialization.

Reimplemented from MKWaveTable.

- (id) copyWithZone:

(NSZone *)

zone

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

Returns:

Returns an id.

Reimplemented from MKWaveTable.

- (void) dealloc

dealloc frees dataDSP and dataDouble then sends [super free].

It also removes the name, if any, from the MusicKit name table.

Reimplemented from MKWaveTable.

- (double) highestFreqRatio

Returns the highest (i.e., largest absolute value) frequency ratio in the receiver.

Returns:

Returns a double. This can be useful for optimizing lookup table sizes in determining if the receiver will generate a waveform that will fold over.

- (id) setPartialCount:		(int)	count
freqRatios:		(double *)	freqRatios
ampRatios:		(double *)	ampRatios
phases:		(double *)	phases
orDefaultPhase:		(double)	defaultPhase

Defines the receiver's sine wave components.

freqRatios, ampRatios, and phases are pointers to arrays that define the frequency ratios, amplitude ratios, and initial phases, respectively, of the sine wave components (the arrays are copied into the receiver). The elements of the arrays are matched by index order: The nth sine wave is configured from the nth element in each array.

If phases is NULL, the value of defaultPhase is used as the initial phase for all the components. If freqRatios or ampRatios is NULL, the corresponding extant array, if any, is unchanged.

Note that this method sets the length instance variable to 0, forcing a recompute in a subsequent data array retrieval (through the dataDSP:... and dataDouble:... methods) as explained in the MKWaveTable class.

Parameters:

	count	is the number of sine wave components.
	freqRatios	is a double *.
	ampRatios	is a double *.
	phases	is a double *.
	defaultPhase	is a double.

Returns:

Returns the receiver.

- (id) setFromSamples:

(MKSamples *)

samplesObject

Sets freqRatios, ampRatios, and phases based on the data in the samplesObject.

Parameters:

samplesObject

is an id.

Returns:

Returns an id. This is done by taking an FFT of the data.

- (id) prunePartials:

(double)

amplitudeThreshold

Change contents to remove any partials with amplitudes below specified threshold.

Parameters:

amplitudeThreshold

is a double.

- (int) partialCount

Returns the number of sine wave components.

Returns:

Returns an int.

- (double *) freqRatios

Returns a pointer to the receiver's frequency ratios array.

Returns:

Returns a double *. You should neither free nor alter the array.

- (double *) ampRatios

Returns a pointer to the receiver's amplitude ratios array.

Returns:

Returns a double *. You should neither free nor alter the array.

- (double) defaultPhase

Returns the receiver's default phase.

Returns:

Returns a double.

- (double *) phases

Returns a pointer to the receiver's phase array or NULL if none.

Returns:

Returns a double *. You should neither free nor alter the array.

- (int) getPartial:		(int)	n
freqRatio:		(double *)	fRatio
ampRatio:		(double *)	aRatio
phase:		(double *)	phase

Returns, by reference, the frequency ratio, amplitude ratio, and initial phase of the nth sine wave component (counting from 0).

Parameters:

	n	is an int.
	fRatio	is a double *.
	aRatio	is a double *.
	phase	is a double *.

Returns:

Returns an int. The amplitude ratio value is scaled by the current value of the scaling instance variable inherited from MKWaveTable.

If the nth sine wave is the last in the receiver, the method returns MK_lastValue. If n is out of bounds, - is returned. Otherwise 0 is returned.

- (id) writeScorefileStream:

(NSMutableData *)

aStream

Writes the receiver in scorefile format on the specified stream.

Parameters:

aStream

is a NSMutableData.

Returns:

Returns an id. Returns nil if ampRatios or freqRatios is NULL, otherwise returns the receiver.

- (int) tableType

Returns the tableType of the currently-cached data, if any.

Returns:

Returns an int. Either MK_oscTable or MK_waveshapingTable. If none, returns the default, MK_oscTable.

---

Member Data Documentation

- (double*) freqRatios [protected]

Array of amplitudes.

- (double*) phases [protected]

Array of frequencies.

- (int) partialCount [protected]

Arrays of initial phases.

- (double) defaultPhase [protected]

Number of points in each array

- (double) minFreq [protected]

Default phase. If no phase-array, this is phase

- (double) maxFreq [protected]

Obsolete. See MKTimbre.

---

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

• MKPartials.h