MKSamples Class Reference

A MKSamples object represents one complete cycle of a sound waveform as a series of samples. More...

#import <MKSamples.h>

Inheritance diagram for MKSamples:

List of all members.

Public Member Functions
(id)	- init
	Send this message when you create a new instance.
(void)	- dealloc
	dealloc frees dataDSP and dataDouble then sends [super free].
(id)	- copyWithZone:
	Creates and returns a new MKSamples object as a copy of the receiver.
(BOOL)	- setSound:
	Sets the receiver's Snd to a copy of aSound.
(BOOL)	- readSoundfile:
	Creates a new Snd object, reads the data from aSoundfile into the object, and then sends setSound: to the receiver with the new Snd as the argument.
(Snd *)	- sound
	Returns the receiver's Snd object.
(NSString *)	- soundfile
	Returns the name of the receiver's soundfile, or nil if the receiver's Snd wasn't set through readSoundfile:.
(id)	- writeScorefileStream:
	Writes the receiver in scorefile format.
(void)	- encodeWithCoder:
	Archives object by archiving filename and sound object.
(id)	- initWithCoder:
	Initialise from the NSCoder.
(int)	- tableType
	Returns the tableType of the currently-cached data, if any, either MK_oscTable or MK_excitationTable.
(void)	- setProcessingStartSample:
	Assigns the starting sample to begin some (arbitary) processing from.
(unsigned int)	- processingStartSample
	returns the sample used to begin some (arbitary) processing from.
(void)	- setProcessingEndSample:
	assigns the sample to end some (arbitary) processing at.
(unsigned int)	- processingEndSample
	returns the sample to end some (arbitary) processing at.
(unsigned int)	- currentSample
	returns the current sample being used to perform processing.
(void)	- setCurrentSample:
	Assigns the current sample to perform processing at.
(double)	- amplitude
	Returns the amplitude scaling.
(void)	- setAmplitude:
	Assigns an amplitude scaling.
(void)	- setPanBearing:
	Assigns the panning in a stereo field.
(double)	- panBearing
	Returns the panning in a stereo field.
(SndAudioProcessorChain *)	- audioProcessorChain
	Returns the SndAudioProcessorChain associated with this sample.
(id)	- setAudioProcessorChain:
	Sets an SndAudioProcessorChain to be associated with the Snd instance.
Protected Attributes
Snd *	sound
NSString *	soundfile
SndAudioProcessorChain *	audioProcessorChain
int	curLoc
double	amplitude
double	panBearing
unsigned int	startSampleLoc
unsigned int	lastSampleLoc

---

Detailed Description

A MKSamples object represents one complete cycle of a sound waveform as a series of samples.

The data for a MKSamples object is established through association with a Snd object, defined by the SndKit. Two methods are provided to create this association:

• setSound: takes a Snd object as an argument, copies it, and associates the reciever with the copied Snd.
• readSoundfile: takes the name of a soundfile, creates a Snd object for the data contained therein, and associates the receiver with the newly created Snd.

The Snd object or soundfile must be one channel of 16-bit linear data (SND_FORMAT_LINEAR_16). The sampling rate is ignored; MKSamples objects are designed to be used as lookup tables for oscillator MKUnitGenerators in which use the sampling rate of the original data is of no consequence.

You can create a MKSamples object from a scorefile by quoting the name of a soundfile within curly brackets which are themselves enclosed by square brackets. The object can be given a name in a waveTable statement:

waveTable mySamples = [ {"samplesFile.snd" }];

A MKSamples object that's written to a soundfile is referred to by the name of the soundfile from which it was created. If a Snd object is used, a soundfile is created and the object is written to it, as explained in the method writeScorefileStream:. You should always name your MKSamples objects by calling the MKNameObject() C function.

MKSamples' sister class, MKPartials, lets you define a waveform by its sine wave components.

MKSamples objects are automatically created by the Music Kit in a number of circumstances, such as when reading a Scorefile. The function MKSetSamplesClass() allows you to specify that your own subclass of MKSamples be used when MKSamples objects are automatically created. You retrieve the MKSamples class with MKGetSamplesClass().

Note that most of the MusicKit DSP oscillators require tables to be of a length that is a power of 2. Note also that the length of a Sample load to the DSP is limited by the amount of DSP memory.

MKSamples can be used in two contexts - to provide wavetables for oscillators and to provide tables for periodic excitation table (PET) 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 excitation table format. To do this, use one of the methods of the form accessMethodAsExcitationTablearguments. For example, to get the data for the DSP with the default table length and scaling, use -dataDSPAsExcitationTable. In this case the MKPartials tableType instance varaible is set to MK_excitationTable. For symmetry, a set of methods of the form dataDSPAsOscTable is provided. These methods are synonyms for the inherited methods.

Actually, excitationTable and oscTable formats are the same when the length requested is the same as the length of the Snd. However, the two behave differently when asked for a length that differs from the length of the Snd. For a excitationTable, samples are omitted from the end of the Snd (if the Snd is longer) or zeros are appended to the end of the Snd (if the Snd is shorter.) For an oscTable, if the requested length evenly divides the actualy length, the Snd is downsampled by simply omitting samples. Note that non-integer resampling is not currently supported.

See also:

MKWaveTable, MKPartials

---

Member Function Documentation

- (id) init

Send this message when you create a new instance.

Returns:

Returns the receiver. You can also invoke this method to reset a MKSamples object. It sets the receiver's sound variable to nil and soundfile to nil. The receiver's previous Snd object, if any, is freed. A subclass implementation should send [super init].

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.

- (id) copyWithZone:

(NSZone *)

zone

Creates and returns a new MKSamples object as a copy of the receiver.

The receiver's Snd is copied into the new MKSamples object.

Returns:

Returns an id.

Reimplemented from MKWaveTable.

- (BOOL) setSound:

(Snd *)

aSound

Sets the receiver's Snd to a copy of aSound.

Parameters:

aSound

is an Snd, and will be converted to one-channel, 16-bit linear data.

Returns:

Returns NO if aSound is in the wrong format, otherwise returns YES.

- (BOOL) readSoundfile:

(NSString *)

aSoundfile

Creates a new Snd object, reads the data from aSoundfile into the object, and then sends setSound: to the receiver with the new Snd as the argument.

You shouldn't free the Snd yourself; it's automatically freed when the receiver is freed, initialized, or when a subsequent Snd is set.

Parameters:

aSoundfile

is an NSString.

Returns:

Returns NO if the setSound: message returns nil; otherwise returns YES for success.

- (Snd *) sound

Returns the receiver's Snd object.

Returns:

Returns an Snd.

- (NSString *) soundfile

Returns the name of the receiver's soundfile, or nil if the receiver's Snd wasn't set through readSoundfile:.

The name isn't copied; you shouldn't alter the returned string.

Returns:

Returns an NSString.

- (id) writeScorefileStream:

(NSMutableData *)

aStream

Writes the receiver in scorefile format.

Writes the receiver in scorefile format to the stream aStream. If the Snd wasn't set from a soundfile, a soundfile with the unique name “samplesNumber.snd” (where Number is added only if needed), is created and the Snd is written to it. The object remembers if its Snd has been written to a soundfile.

Parameters:

aStream

is a NSMutableData instance.

Returns:

If the receiver couldn't be written to the stream, returns nil, otherwise returns the receiver.

- (void) encodeWithCoder:

(NSCoder *)

aCoder

Archives object by archiving filename and sound object.

Note that the sound object is archived whether it was created from readSoundfile: or from setSound:. We assume that the sound, even if it comes from an external source, is an intrinsic part of the object. You never send this message directly.

Reimplemented from MKWaveTable.

- (id) initWithCoder:

(NSCoder *)

aDecoder

Initialise from the NSCoder.

Note that -init is not sent to newly unarchived objects. You never send this message directly.

Reimplemented from MKWaveTable.

- (int) tableType

Returns the tableType of the currently-cached data, if any, either MK_oscTable or MK_excitationTable.

If none, returns the default, MK_oscTable.

Returns:

Returns an int.

- (SndAudioProcessorChain *) audioProcessorChain

Returns the SndAudioProcessorChain associated with this sample.

Returns:

The audioProcessorChain associated with this sample

- (id) setAudioProcessorChain:

(SndAudioProcessorChain *)

anAudioProcessorChain

Sets an SndAudioProcessorChain to be associated with the Snd instance.

This can be used for any signal processing or amplitude enveloping.

Parameters:

anAudioProcessorChain

An initialized SndAudioProcessorChain.

Returns:

Returns self.

---

Member Data Documentation

- (Snd*) sound [protected]

The object's Snd object.

- (NSString*) soundfile [protected]

The name of the soundfile, if the Snd was set through readSoundfile:.

- (SndAudioProcessorChain*) audioProcessorChain [protected]

Used for signal processing including amplitude modifying the sound.

- (int) curLoc [protected]

Index into current sample in soundfile

- (double) amplitude [protected]

Amplitude scaling of soundfile in floating point

- (double) panBearing [protected]

Panning between stereo sounds, expressed as a bearing in degrees from centre.

- (unsigned int) startSampleLoc [protected]

Starting sample to be processed

- (unsigned int) lastSampleLoc [protected]

Ending sample to be processed, defining the portion of sound to be used.

---

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

• MKSamples.h