MusicKit  0.0.0
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Attributes
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:
SndAudioProcessor SndAudioProcessor

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.
(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.
(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

+ (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)
+ (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)
- (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) 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)
- (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)
- (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)
- (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)
- (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)
- (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).
- (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).
- (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)
- (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)
- (NSString *) paramName: (const int)  index

Retrieve the name of the indexed parameter.

Parameters:
indexenumerated index for parameters.
Returns:
Returns an NSString instance.

Reimplemented from SndAudioProcessor.

- (NSString *) paramName: (const int)  index

Retrieve the name of the indexed parameter.

Parameters:
indexenumerated index for parameters.
Returns:
Returns an NSString instance.

Reimplemented from SndAudioProcessor.

- (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:
indexenumerated index for parameters.
Returns:
Returns a floating point value.

Reimplemented from SndAudioProcessor.

- (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:
indexenumerated index for parameters.
Returns:
Returns a floating point value.

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:
inBthe audio buffer with input to the processor
outBunused
Returns:
Always returns NO since SndAudioFader processes audio in place, in inB.

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:
inBthe audio buffer with input to the processor
outBunused
Returns:
Always returns NO since SndAudioFader processes audio in place, in inB.

Reimplemented from SndAudioProcessor.

- (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:
startRampLevelthe level at the start of the ramp
endRampLevelthe 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) 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:
startRampLevelthe level at the start of the ramp
endRampLevelthe 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:
startRampLevelthe balance at the start of the ramp
endRampLevelthe 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
- (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:
startRampLevelthe balance at the start of the ramp
endRampLevelthe 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
- (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:
ampany valid amplitude multiplier (usually 0.0 to 1.0)
atTime(double) the time at which to insert the new amp value
Returns:
self
- (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:
ampany valid amplitude multiplier (usually 0.0 to 1.0)
atTime(double) the time at which to insert the new amp value
Returns:
self
- (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:
ampA 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.
clearIf TRUE, discard any future scheduled amp events.
Returns:
self
- (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:
ampA 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.
clearIf TRUE, discard any future scheduled amp events.
Returns:
self
- (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
- (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
- (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:
newBalanceis a float (-1.0 to +1.0)
clearIf TRUE, discard any future scheduled balance events.
Returns:
Returns self.
- (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:
newBalanceis a float (-1.0 to +1.0)
clearIf TRUE, discard any future scheduled balance events.
Returns:
Returns self.
+ (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:
aClassThe alternative class to set.
+ (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:
aClassThe alternative class to set.
- (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:
aClassThe alternative class to set.
Returns:
void
- (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:
aClassThe alternative class to set.
Returns:
void
- (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:
indexenumerated index for parameters.
vThe floating point value to assign.

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:
indexenumerated index for parameters.
vThe floating point value to assign.

Reimplemented from SndAudioProcessor.


Member Data Documentation

- (id< SndEnveloping, NSObject >) ampEnv [protected]
- (NSLock *) ampEnvLock [protected]
- (id< SndEnveloping, NSObject >) balanceEnv [protected]
- (NSLock *) balanceEnvLock [protected]
- (BpAfterIMP) bpAfter
- (BpBeforeOrEqualIMP) bpBeforeOrEqual
- (id) envClass [protected]

Class object used in initialising new envelopes

- (NSLock *) envelopesLock [protected]

Locks changes to both the envelope objects (?)

- (FlagsForBpIMP) flagsForBp
- (float) staticAmp [protected]
- (float) staticBalance [protected]
- (SndUnifiedEnvelopeEntry *) uee [protected]

Unified Envelope Entry

- (XForBpIMP) xForBp
- (YForBpIMP) yForBp
- (YForXIMP) yForX

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