SndPerformance Class Reference

Holds the state associated with each sounding (or soon to be) Snd. More...

#import <SndPerformance.h>

List of all members.

Public Member Functions
(id)	- initWithSnd:playingAtTime:
	Initialise a performance with a sound and a time to begin playing.
(id)	- initWithSnd:playingAtTime:beginAtIndex:endAtIndex:
	Initialise a performance with a sound and a time to begin playing, and the index of the first and last samples of the sound to play.
(id)	- initWithSnd:playingAtTime:startPosition:duration:deltaTime:
	Initialise a performance with a sound and a time to begin playing, and the index of the last sample of the sound to play.
(Snd *)	- snd
	Returns the Snd instance being played in this performance.
(double)	- playTime
	Returns the time the sound is to begin playing.
(id)	- setPlayTime:
	Sets the time interval in seconds from the current time the sound is to begin playing.
(long)	- playIndex
	Returns the sample to start playing from.
(void)	- setPlayIndex:
	Sets the sample to start playing from.
(long)	- rewindPlayIndexBySamples:
	Rewinds the sample to start playing from by the supplied number of samples.
(long)	- endAtIndex
	Returns the sample to stop playing at.
(long)	- startAtIndex
	Returns the sample to start playing at.
(void)	- setEndAtIndex:
	Sets the sample to stop playing at.
(void)	- setLooping:
	Sets looping during performance on or off.
(BOOL)	- looping
	Returns whether this performance loops.
(void)	- setLoopStartIndex:
	Sets the sample to start looping from.
(long)	- loopStartIndex
	Returns the sample to start looping from.
(void)	- setLoopEndIndex:
	Sets the sample at which the performance loops back to the start index (set using setLoopStartIndex:).
(long)	- loopEndIndex
	Returns the sample index at the end of the loop.
(void)	- stopInFuture:
	Stop the currently playing performance at some time in the future.
(void)	- stopNow
	Stops the performance immediately.
(BOOL)	- isEqual:
	Compares two performances.
(void)	- dealloc
	Destructor.
(NSString *)	- description
	Returns a string containing a brief description of the performance object.
(BOOL)	- isPaused
(id)	- setPaused:
(id)	- pause
	Pauses a performance.
(id)	- resume
	Resumes a paused performance.
(BOOL)	- isPlaying
	Indicates whether the current performance is actually sounding.
(SndAudioProcessorChain *)	- audioProcessorChain
(void)	- setAudioProcessorChain:
(long)	- retrievePerformBuffer:ofLength:
	Fills the given buffer with sound data, reading from the playIndex up until endAtIndex (which allows us to play a sub-section of a sound).
(BOOL)	- atEndOfPerformance
	Tests if the play index has reached the end index, indicating that the performance has completed.
Static Public Member Functions
(SndPerformance *)	+ performanceOfSnd:playingAtTime:
	Create and return an autoreleased instance of SndPerformance with a sound and a time to begin playing. Convenience method to performanceOfSnd:playingAtTime:endAtIndex.
(SndPerformance *)	+ performanceOfSnd:playingAtTime:beginAtIndex:endAtIndex:
	Create and return an autoreleased instance of SndPerformance with a sound and a time to begin playing.
Protected Attributes
Snd *	snd
double	playTime
long	startAtIndex
long	playIndex
long	endAtIndex
BOOL	paused
SndAudioProcessorChain *	audioProcessorChain
BOOL	looping
long	loopStartIndex
long	loopEndIndex

---

Detailed Description

Holds the state associated with each sounding (or soon to be) Snd.

This differs from a Snd instance itself, since we can have multiple overlapping simultaneous performances of the same (potentially huge) Snd, some looping, others not. We need some way of indicating to the delegate exactly which performance has completed, hence this class. A SndPerformance also has an SndAudioProcessorChain enabling each performance of a sound to be signal processed, including volume fading, panning etc using the audio processor chain "postFader" SndAudioFader.

---

Member Function Documentation

+ (SndPerformance *) performanceOfSnd:		(Snd *)	s
playingAtTime:		(double)	seconds

Create and return an autoreleased instance of SndPerformance with a sound and a time to begin playing. Convenience method to performanceOfSnd:playingAtTime:endAtIndex.

Parameters:

	s	The sound to be played
	seconds	Time in seconds to start playing the sound

Returns:

Returns the newly created instance if able to initialise, nil if unable.

+ (SndPerformance *) performanceOfSnd:		(Snd *)	s
playingAtTime:		(double)	seconds
beginAtIndex:		(long)	beginIndex
endAtIndex:		(long)	endIndex

Create and return an autoreleased instance of SndPerformance with a sound and a time to begin playing.

Parameters:

	s	The sound to be played
	seconds	Time in seconds to start playing the sound
	beginIndex	The sample index at which to start playback. This sample will be played.
	endIndex	The sample index at which to stop playback. This sample will not be played.

Returns:

Returns the newly created instance if able to initialise, nil if unable.

- (id) initWithSnd:		(Snd *)	s
playingAtTime:		(double)	seconds

Initialise a performance with a sound and a time to begin playing.

Convenience method to initWithSnd:playingAtTime:endAtIndex:

Parameters:

	s	The sound to be played
	seconds	Time in seconds to start playing the sound

Returns:

Returns self if able to initialise, nil if unable.

- (id) initWithSnd:		(Snd *)	s
playingAtTime:		(double)	seconds
beginAtIndex:		(long)	beginIndex
endAtIndex:		(long)	endIndex

Initialise a performance with a sound and a time to begin playing, and the index of the first and last samples of the sound to play.

Parameters:

	s	The sound to be played
	seconds	Time in seconds to start playing the sound
	beginIndex	The sample index at which to start playback
	endIndex	The sample index at which to stop playback

Returns:

Returns self if able to initialise, nil if unable.

- (id) initWithSnd:		(Snd *)	s
playingAtTime:		(double)	playTime
startPosition:		(double)	startPosition
duration:		(double)	duration
deltaTime:		(double)	deltaTime

Initialise a performance with a sound and a time to begin playing, and the index of the last sample of the sound to play.

Parameters:

	s	The Snd instance to begin playing.
	playTime	The time to begin playback.
	startPosition	The sample index at which to begin playback.
	duration	The duration in seconds of the Snd instance to play.
	deltaTime	TBD.

Returns:

Returns self if able to initialise, nil if unable.

- (Snd *) snd

Returns the Snd instance being played in this performance.

Returns:

Returns the Snd instance being played in this performance.

- (double) playTime

Returns the time the sound is to begin playing.

Returns:

Returns the time interval in seconds from the current time the sound is to begin playing.

- (long) playIndex

Returns the sample to start playing from.

Returns:

Returns the sample index to start playing from.

- (void) setPlayIndex:

(long)

newPlayIndex

Sets the sample to start playing from.

Parameters:

newPlayIndex

The sample index that playing should begin from.

- (long) rewindPlayIndexBySamples:

(long)

numberOfSamplesToRewind

Rewinds the sample to start playing from by the supplied number of samples.

The loop points are respected, such that rewinding a sound that is set to loop before it's loop start index will wrap to the end of the loop. If this isn't wanted, either temporarily disable looping or use setPlayIndex:.

Parameters:

numberOfSamplesToRewind

The number of samples to rewind to where playing should begin from.

Returns:

Returns the new play index as a convience to save calling playIndex.

- (long) endAtIndex

Returns the sample to stop playing at.

This sample is not played, that is it is typically initialised with the sound length.

Returns:

Returns the sample index to stop playing at.

- (long) startAtIndex

Returns the sample to start playing at.

Returns:

Returns the sample index to start playing at.

- (void) setEndAtIndex:

(long)

newEndAtIndex

Sets the sample to stop playing at.

The end at index indicates the first sample at which the playback stops, that is, this sample is not played.

Parameters:

newEndAtIndex

The sample index that playing should stop before.

- (void) setLooping:

(BOOL)

yesOrNo

Sets looping during performance on or off.

Parameters:

yesOrNo

Sets looping during performance on or off.

- (BOOL) looping

Returns whether this performance loops.

Returns:

Returns whether this performance loops.

- (void) setLoopStartIndex:

(long)

loopStartIndex

Sets the sample to start looping from.

Parameters:

loopStartIndex

The sample index to start looping from.

The loop start index may be changed while the sound is being performed and regardless of whether the performance is looping. This sample index is the first sample of the loop, i.e it is the first sample heard when the performance loops.

- (long) loopStartIndex

Returns the sample to start looping from.

Returns:

Returns the sample index to start looping from.

- (void) setLoopEndIndex:

(long)

newLoopEndIndex

Sets the sample at which the performance loops back to the start index (set using setLoopStartIndex:).

Parameters:

newLoopEndIndex

The sample index at the end of the loop.

This sample index is the last sample of the loop, i.e. it is the last sample heard before the performance loops, the next sample heard will be that returned by -loopStartIndex. The loop end index may be changed while the sound is being performed and regardless of whether the performance is looping.

- (long) loopEndIndex

Returns the sample index at the end of the loop.

Returns:

Returns the sample index ending the loop.

- (void) stopInFuture:

(double)

inSeconds

Stop the currently playing performance at some time in the future.

Parameters:

inSeconds

The time interval when to stop the performance.

- (BOOL) isEqual:

(id)

anotherPerformance

Compares two performances.

Parameters:

anotherPerformance

- (NSString *) description

Returns a string containing a brief description of the performance object.

Returns:

A string containing a brief description of the performance object.

- (BOOL) isPaused

Returns:

Boolean - YES/TRUE if the performance is paused

- (id) setPaused:

(BOOL)

b

Parameters:

b

a flag to signal whether or not the performance is paused.

Returns:

self

- (BOOL) isPlaying

Indicates whether the current performance is actually sounding.

Returns:

Returns YES if the performance is currently sounding, NO if it is paused, has yet to be begin playing or has finished.

- (SndAudioProcessorChain *) audioProcessorChain

Returns:

The audioProcessorChain associated with this performance

- (void) setAudioProcessorChain:

(SndAudioProcessorChain *)

anAudioProcessorChain

Parameters:

anAudioProcessorChain

- (long) retrievePerformBuffer:		(SndAudioBuffer *)	bufferToFill
ofLength:		(long)	buffLength

Fills the given buffer with sound data, reading from the playIndex up until endAtIndex (which allows us to play a sub-section of a sound).

Parameters:

	bufferToFill	A SndAudioBuffer that will be filled with samples.
	buffLength	The intended number of samples TODO or bytes? to retrieve.

Returns:

Returns the final buffer length, which may be less than the requested amount in the case of a premature stop, or simply reaching the end of the data. playIndex is updated, and looping is respected. In the case of the end of the sound being encountered, a smaller buffer will be filled, and the smaller size is returned.

---

Member Data Documentation

- (Snd*) snd [protected]

The sound being performed.

- (double) playTime [protected]

The time when to initiate playing.

- (long) startAtIndex [protected]

The index where the sound will begin playing from at the start of a sound performance.

- (long) playIndex [protected]

The index where the sound will next play from (using retrievePerformBuffer:).

- (long) endAtIndex [protected]

The index where the sound will stop before. This marks the sample after the last one to be played, the sample at endAtIndex is not played.

- (BOOL) paused [protected]

Controls whether performance of the Snd is occuring.

- (SndAudioProcessorChain*) audioProcessorChain [protected]

Effects applied to this particular performance.

- (BOOL) looping [protected]

Indicates whether to loop during performance.

- (long) loopStartIndex [protected]

The sample the loop begins at. This sample is included in the loop.

- (long) loopEndIndex [protected]

The sample the loop ends at. This sample is included in the loop.

---

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

• SndPerformance.h