SndAudioFader Class Reference

An object providing basic amplitude and balance controls on incoming audio buffers. "Fader" movements can be scheduled for arbitrary times in the future. More...

#import <SndAudioFader.h>

Inheritance diagram for SndAudioFader:

List of all members.

Public Member Functions
(void)	- setEnvelopeClass:
	Sets the class object used for the internal amplitude and balance envelopes.
(id)	- envelopeClass
	Returns the class of the internal envelope objects.
(id)	- setBalance:clearingEnvelope:
	Sets the instantaneous balance value between stereo (2) channels, optionally clearing future scheduled events.
(float)	- getBalance
	Returns the balance value as of the start of the currently running, or next buffer.
(id)	- setAmp:clearingEnvelope:
	Sets the instantaneous amplitude value, optionally clearing future scheduled events.
(float)	- getAmp
	Returns the amplitude value of all channels as of the start of the currently running, or next buffer.
(id)	- setBalance:atTime:
	Sets the balance value at the given future time.
(float)	- getBalanceAtTime:
	Returns the scheduled balance value for the given time.
(id)	- setAmp:atTime:
	Sets the amp value at the given future time.
(float)	- getAmpAtTime:
	Returns the scheduled amp value for the given time.
(BOOL)	- rampAmpFrom:to:startTime:endTime:
	Creates an amplitude ramp for a given time in the future.
(BOOL)	- rampBalanceFrom:to:startTime:endTime:
	Creates a balance ramp for a given time in the future.
(float)	- paramValue:
	Retrieve the value of the indexed parameter.
(NSString *)	- paramName:
	Retrieve the name of the indexed parameter.
(void)	- setParam:toValue:
	Assigns the indexed parameter a value.
(BOOL)	- processReplacingInputBuffer:outputBuffer:
	Processes the input buffer according to the amplitude and balance settings.
Static Public Member Functions
(void)	+ setEnvelopeClass:
	Sets the class object used for the internal amplitude and balance envelopes.
(id)	+ envelopeClass
	Returns the class of the internal envelope objects.
Public Attributes
BpBeforeOrEqualIMP	bpBeforeOrEqual
BpAfterIMP	bpAfter
FlagsForBpIMP	flagsForBp
YForBpIMP	yForBp
YForXIMP	yForX
XForBpIMP	xForBp
Protected Attributes
id	envClass
id< SndEnveloping, NSObject >	ampEnv
float	staticAmp
id< SndEnveloping, NSObject >	balanceEnv
float	staticBalance
SndUnifiedEnvelopeEntry *	uee
NSLock *	envelopesLock
NSLock *	balanceEnvLock
NSLock *	ampEnvLock

---

Detailed Description

An object providing basic amplitude and balance controls on incoming audio buffers. "Fader" movements can be scheduled for arbitrary times in the future.

SndAudioFader objects can be inserted into SndAudioProcessorChains at arbitrary points. In addition, all SndAudioProcessorChains have a SndAudioFader which is run after any other user defined processors.

Because both SndStreamMixer and SndStreamClient have processor chains, both the overall output and the individual clients (respectively) can have faders.

SndAudioFader is built to be as efficient as possible. If it does not have to do any processing on the incoming stream, it does not.

SndAudioFader keeps track of amplitude and/or balance settings in two ways: via a static setting, and via an envelope system for scheduling future movements. This process is largely transparent to the user.

For computational ease, interpolation between breakpoints in the scheduled amplitude fader movements is linear. For stereo balance, the situation is similar, as the balance calculations are not adjusted for equal power. This is because balance is a different art to pan, where a mono sound is panned into a stereo sound field. The balance calculations mimic the traditional analog balance implementation with a twin gang potentiometer. That is, at every balance position left of centre, the left channel is on full power, and the right channel loses power linearly, proportional to the distance left of centre. The same applies to positions right of centre (the right channel is on full power, and the left channel drops off). One advantage of doing it this way is that at the centre position, both channels are at full power. Most panning implementations scale to root 2 (0.707) at the centre position.

One limitation of the faders is that the "postfader" copies (in SndStreamMixer and SndStreamClient) are only created once the audio streams have started to play. Thus the user cannot pre-load the faders with future movements. To pre-load faders before a stream starts to play, create a SndAudioFader programmatically, send it the fader movements, then insert it into the SndAudioProcessorChain later.

---

Member Function Documentation

+ (void) setEnvelopeClass:

(id)

aClass

Sets the class object used for the internal amplitude and balance envelopes.

If you wish to develop your own high performance envelopes, perhaps with improved interpolation, ensure that they conform to the SndEnveloping protocol, then call this method with [MyNewEnvelopeClass class] before doing any audio output for the first time. All future envelope objects created by SndAudioFader will use the new class.

Parameters:

aClass

The alternative class to set.

+ (id) envelopeClass

Returns the class of the internal envelope objects.

Defaults to SndEnvelope. Note that this method does not check the class of its envelopes directly, but returns the stored class object used for creating future envelopes.

Returns:

<SndEnveloping> (a class conforming to the SndEnveloping protocol)

- (void) setEnvelopeClass:

(id)

aClass

Sets the class object used for the internal amplitude and balance envelopes.

If you wish to develop your own high performance envelopes, perhaps with improved interpolation, ensure that they conform to the SndEnveloping protocol, then call this method with [MyNewEnvelopeClass class] before doing any audio output for the first time. Note that sending this message to an instance of SndAudioFader will affect ONLY this instance.

See also:

+(void)+ setEnvelopeClass:aClass

Parameters:

aClass

The alternative class to set.

Returns:

void

- (id) envelopeClass

Returns the class of the internal envelope objects.

Defaults to SndEnvelope. Note that this method does not check the class of its envelopes directly, but returns the stored class object used for creating future envelopes.

Returns:

instance<SndEnveloping> (a class conforming to the SndEnveloping protocol)

- (id) setBalance:		(float)	newBalance
clearingEnvelope:		(BOOL)	clear

Sets the instantaneous balance value between stereo (2) channels, optionally clearing future scheduled events.

The balance value takes effect from the next buffer to pass through the processor chain. The parameter newBalance must be a floating-point number between -1.0 (left) 0.0 (centre) and 1.0 (right). If successful, returns self; otherwise returns nil. For greater than 2 channel sound, balance must be defined as between two lateral planes of outputs. So a 5.1 surround system should map balance between the combined left front and left surround speaker vs. the right front and right surround speaker. This needs further description as to how stereo panning should map onto other multichannel formats and in the most general sense, i.e even is left, odd is right.

Parameters:

	newBalance	is a float (-1.0 to +1.0)
	clear	If TRUE, discard any future scheduled balance events.

Returns:

Returns self.

- (float) getBalance

Returns the balance value as of the start of the currently running, or next buffer.

Returns the position between stereo channels as a floating-point number between -1.0 (left) and 1.0 (right).

Returns:

float (usually -1.0 to +1.0).

- (id) setAmp:		(float)	amp
clearingEnvelope:		(BOOL)	clear

Sets the instantaneous amplitude value, optionally clearing future scheduled events.

The amplitude value takes effect from the next buffer to pass through the processor chain.

Parameters:

	amp	A floating point value normally between 0.0 (minimum, silence) and +1.0 (maximum, full volume) inclusive. This parameter is the scaling factor for all channels. Negative values will invert the audio stream. There is no checking done for overload.
	clear	If TRUE, discard any future scheduled amp events.

Returns:

self

- (float) getAmp

Returns the amplitude value of all channels as of the start of the currently running, or next buffer.

Returns:

float (usually 0.0 to +1.0)

- (id) setBalance:		(float)	balance
atTime:		(double)	atTime

Sets the balance value at the given future time.

The balance value is scheduled for the given time. If the specified time bisects an already scheduled ramp, the first part of the old ramp is maintained at its existing trajectory until the time of the new point, then the new balance point is inserted. Subsequent ramps are unaffected.

Parameters:

	balance	(-1.0 to +1.0)
	atTime	(double) the time at which to insert the new balance value

Returns:

self

- (float) getBalanceAtTime:

(double)

atTime

Returns the scheduled balance value for the given time.

If the time given bisects a scheduled ramp, the value is linearly interpolated.

Parameters:

atTime

(double) the time for which to return the balance value

Returns:

float (usually -1.0 to +1.0)

- (id) setAmp:		(float)	amp
atTime:		(double)	atTime

Sets the amp value at the given future time.

The amp value is scheduled for the given time. If the specified time bisects an already scheduled ramp, the first part of the old ramp is maintained at its existing trajectory until the time of the new point, then the new amp point is inserted. Subsequent ramps are unaffected.

Parameters:

	amp	any valid amplitude multiplier (usually 0.0 to 1.0)
	atTime	(double) the time at which to insert the new amp value

Returns:

self

- (float) getAmpAtTime:

(double)

atTime

Returns the scheduled amp value for the given time.

If the given time bisects a scheduled ramp, the value is linearly interpolated.

Parameters:

atTime

(double) the time for which to return the amp value

Returns:

float any valid amplitude multiplier (usually 0.0 to 1.0)

- (BOOL) rampAmpFrom:		(float)	startRampLevel
to:		(float)	endRampLevel
startTime:		(double)	startRampTime
endTime:		(double)	endRampTime

Creates an amplitude ramp for a given time in the future.

The amp value is scheduled for the given time. If the start time of the new ramp bisects an already scheduled ramp, the first part of the old ramp is maintained at its existing trajectory until the time of the onset of the new ramp, then the new ramp is inserted. Subsequent ramps are unaffected.

Parameters:

	startRampLevel	the level at the start of the ramp
	endRampLevel	the level at the end of the ramp
	startRampTime	(double) the time at which to start the new ramp
	endRampTime	(double) the time at which to end the new ramp

Returns:

self

- (BOOL) rampBalanceFrom:		(float)	startRampLevel
to:		(float)	endRampLevel
startTime:		(double)	startRampTime
endTime:		(double)	endRampTime

Creates a balance ramp for a given time in the future.

The balance value is scheduled for the given time.

If the start time of the new ramp bisects an already scheduled ramp, the first part of the old ramp is maintained at its existing trajectory until the time of the onset of the new ramp, then the new ramp is inserted. Subsequent ramps are unaffected.

Parameters:

	startRampLevel	the balance at the start of the ramp
	endRampLevel	the balance at the end of the ramp
	startRampTime	(double) the time at which to start the new ramp
	endRampTime	(double) the time at which to end the new ramp

Returns:

self

- (float) paramValue:

(const int)

index

Retrieve the value of the indexed parameter.

This is just the standardised SndAudioProcessor protocol for retrieving the amplitude and balance.

Parameters:

index

enumerated index for parameters.

Returns:

Returns a floating point value.

Reimplemented from SndAudioProcessor.

- (NSString *) paramName:

(const int)

index

Retrieve the name of the indexed parameter.

Parameters:

index

enumerated index for parameters.

Returns:

Returns an NSString instance.

Reimplemented from SndAudioProcessor.

- (void) setParam:		(const int)	index
toValue:		(const float)	v

Assigns the indexed parameter a value.

This is just the standardised SndAudioProcessor protocol for assigning the amplitude and balance.

Parameters:

	index	enumerated index for parameters.
	v	The floating point value to assign.

Reimplemented from SndAudioProcessor.

- (BOOL) processReplacingInputBuffer:		(SndAudioBuffer *)	inB
outputBuffer:		(SndAudioBuffer *)	outB

Processes the input buffer according to the amplitude and balance settings.

This method currently only works with stereo float buffers. Not to be called directly. This method is called by SndAudioProcessorChain with buffers destined for audio output.

Parameters:

	inB	the audio buffer with input to the processor
	outB	unused

Returns:

Always returns NO since SndAudioFader processes audio in place, in inB.

Reimplemented from SndAudioProcessor.

---

Member Data Documentation

- (id) envClass [protected]

Class object used in initialising new envelopes

- (id<SndEnveloping, NSObject>) ampEnv [protected]

- (float) staticAmp [protected]

- (id<SndEnveloping,NSObject>) balanceEnv [protected]

- (float) staticBalance [protected]

- (SndUnifiedEnvelopeEntry*) uee [protected]

Unified Envelope Entry

- (NSLock*) envelopesLock [protected]

Locks changes to both the envelope objects (?)

- (NSLock*) balanceEnvLock [protected]

- (NSLock*) ampEnvLock [protected]

- (BpBeforeOrEqualIMP) bpBeforeOrEqual

- (BpAfterIMP) bpAfter

- (FlagsForBpIMP) flagsForBp

- (YForBpIMP) yForBp

- (YForXIMP) yForX

- (XForBpIMP) xForBp

---

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

• SndAudioFader.h