Header file: AudioToolbox/AudioUnitUtilities.h
The AU Parameter Listener is designed to provide notifications of an Audio Unit's parameters. This API is designed to avoid the need for UI components to continually poll an Audio Unit to determine if a parameter value has been changed. In order for this notification to be used, the parameter value should be changed using the AUParameterSet call (discussed below), which allows the notification mechanism to be used. This also removes the need for an Audio Unit to provide and support a notification mechanism, particular as AudioUnitSetParameter may be received by an Audio Unit during the render process.
There are also some utilities for converting between non-linear and linear value ranges. These are very useful for displaying a non-linear parameter (such as Hz, or dB) using a linear control mechanism, such as a slider, to ensure that the user has a wider perceived range of control over the parameter value.
Contents |
Functions | ||
AUListenerCreate | Create an object for fielding notifications when AudioUnit parameter values change. | |
AUListenerDispose | Dispose a parameter listener object. | |
AUListenerAddParameter | Connect a parameter to a listener. | |
AUListenerRemoveParameter | Remove a parameter/listener connection. | |
AUParameterSet | Set an AudioUnit parameter value and notify listeners. | |
AUParameterListenerNotify | Notify listeners of a parameter change without actually changing the value. | |
AUParameterValueFromLinear | Converts a linear value to the parameter's natural value range, according to its units. | |
AUParameterValueToLinear | Converts a parameter value to a linear value according to the parameter's units. | |
AUParameterFormatValue | Format a parameter value into a string. | |
Callbacks | ||
AUParameterListenerProc | Called when a parameter's value has changed. | |
Defined Types | ||
AUParameterListenerRef | ||
Constants | ||
kAUParameterListener_AnyParameter |
OSStatus AUListenerCreate( AUParameterListenerProc inProc, void * inRefCon, CFRunLoopRef inRunLoop, CFStringRef inRunLoopMode, Float32 inNotificationInterval, AUParameterListenerRef * outListener );Note that only parameter changes issued through AUParameterSet will generate notifications to listeners; thus, in most cases, AudioUnit clients should use AUParameterSet in preference to AudioUnitSetParameterValue.
OSStatus AUListenerDispose( AUParameterListenerRef inListener );
OSStatus AUListenerAddParameter( AUParameterListenerRef inListener, void * inObject, const AudioUnitParameter * inParameter );Associate an arbitrary object (often a user interface widget) with an AudioUnitParameter, and deliver notifications to the specified listener, telling it that the object needs to be informed of the parameter's value change.
OSStatus AUListenerRemoveParameter( AUParameterListenerRef inListener, void * inObject, const AudioUnitParameter * inParameter );
OSStatus AUParameterSet( AUParameterListenerRef inListener, void * inObject, const AudioUnitParameter * inParameter, Float32 inValue, UInt32 inBufferOffsetInFrames );Calls AudioUnitSetParameter, and performs/schedules notification callbacks to all parameter listeners, for that parameter -- except that optionally, no callback will be generated to the inListener/inObject pair that invoked this call.
OSStatus AUParameterListenerNotify( AUParameterListenerRef inListener, void * inObject, const AudioUnitParameter * inParameter );Performs and schedules the listener notification functions of AUParameterSet, without actually setting an AudioUnit parameter value. Clients scheduling ramped parameter changes to AudioUnits must make this call dynamically during playback in order for AudioUnitViews to be updated. When the view's listener receives a notification, it will be passed the current value of the parameter.
A special meaning is applied if the mParameterID value of inParameter is equal to kAUParameterListener_AnyParameter. In this case, ANY listener for ANY parameter value changes on the specified AudioUnit will be notified of the current value of that parameter.
Float32 AUParameterValueFromLinear( Float32 inLinearValue, const AudioUnitParameter * inParameter );
Float32 AUParameterValueToLinear( Float32 inParameterValue, const AudioUnitParameter * inParameter );
char * AUParameterFormatValue( double inParameterValue, const AudioUnitParameter * inParameter, char * inTextBuffer, UInt32 inDigits );Formats a floating point value into a string. Computes a power of 10 to which the value will be rounded and displayed as follows: if the the parameter is logarithmic (Hertz), the number of significant digits is inDigits - pow10(inParameterValue) + 1. Otherwise, it is inDigits - pow10(maxValue - minValue) + 1.
Example for inDigits=3:
pow10 range digits after decimal place display -2 .0100-.0999 4 -1 .100-.999 3 0 1.00-9.99 2 1 10.0-99.9 1 2 100-999 0 3 1000-9990 -1 4 10000-99900 -2
typedef void (*AUParameterListenerProc)( void * inRefCon, void * inObject, const AudioUnitParameter * inParameter, Float32 inValue );
typedef struct AUParameterListener *AUParameterListenerRef;
enum { kAUParameterListener_AnyParameter = 0xFFFFFFFF };