Contains higher-level utility functions for the use of AudioUnit clients.
The AU Parameter Listener is designed to provide notifications when an Audio Unit's parameters
or other state changes. It makes it unnecessary for UI components to continually poll an Audio
Unit to determine if a parameter value has been changed. In order for this notification
mechanism to work properly, parameter values should be changed using the AUParameterSet call
(discussed below). This also makes it unnecessary for an Audio Unit to provide and support a
notification mechanism, particularly as AudioUnitSetParameter may be received by an Audio Unit
during the render process.
The AUEventListener API's extend the AUParameterListener API's by supporting event types
other than parameter changes. Events, including parameter changes are delivered serially to the
listener, preserving the time order of the events and parameter changes.
There are also some utilities for converting between non-linear and linear value ranges. These
are useful for displaying a non-linear parameter (such as one whose units are in Hertz or
decibels) 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.
AUListenerCreate |
Create an object for fielding notifications when AudioUnit parameter values change.
extern OSStatus AUListenerCreate( AUParameterListenerProc inProc, void *inRefCon, CFRunLoopRef inRunLoop, CFStringRef inRunLoopMode, Float32 inNotificationInterval, AUParameterListenerRef *outListener);
inProc
- Function called when the parameter's value changes.
inRefCon
- A reference value for the use of the callback function.
inRunLoop
- The run loop on which the callback is called. If NULL, CFRunLoopGetCurrent() is used.
inRunLoopMode
- The run loop mode in which the callback's underlying run loop source will be attached. If NULL, kCFRunLoopDefaultMode is used.
inNotificationInterval
- The minimum time interval, in seconds, at which the callback will be called. If multiple parameter value changes occur within this time interval, the listener will only receive a notification for the last value change that occurred before the callback. If inNotificationInterval is 0, the inRunLoop and inRunLoopMode arguments are ignored, and the callback will be issued immediately, on the thread on which the parameter was changed.
outListener
- On succcessful return, an AUParameterListenerRef.
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.
AUListenerDispose |
Dispose a parameter listener object.
extern OSStatus AUListenerDispose( AUParameterListenerRef inListener);
inListener
- The parameter listener to dispose.
AUListenerAddParameter |
Connect a parameter to a listener.
extern OSStatus AUListenerAddParameter( AUParameterListenerRef inListener, void *inObject, const AudioUnitParameter *inParameter);
inListener
- The parameter listener which will receive the callback.
inObject
- The object which is interested in the value of the parameter. This will be passed as the inObject parameter to the listener callback function when the parameter changes.
inParameter
- The parameter whose value changes are to generate callbacks.
Associates an arbitrary object (often a user interface widget) with an AudioUnitParameter, and delivers notifications to the specified listener, telling it that the object needs to be informed of the parameter's value change.
AUListenerRemoveParameter |
Remove a parameter/listener connection.
extern OSStatus AUListenerRemoveParameter( AUParameterListenerRef inListener, void *inObject, const AudioUnitParameter *inParameter);
inListener
- The parameter listener to stop receiving callbacks.
inObject
- The object which is no longer interested in the value of the parameter.
inParameter
- The parameter whose value changes are to stop generating callbacks.
AUParameterSet |
Set an AudioUnit parameter value and notify listeners.
extern OSStatus AUParameterSet( AUParameterListenerRef inSendingListener, void *inSendingObject, const AudioUnitParameter *inParameter, Float32 inValue, UInt32 inBufferOffsetInFrames) ;
inListener
- A parameter listener generating the change and which does not want to receive a callback as a result of it. May be NULL.
inObject
- The object generating the change and which does not want to receive a callback as a result of it. NULL is treated specially when inListener is non-null; it signifies that none of the specified listener's objects will receive notifications.
inParameter
- The parameter being changed.
inValue
- The new value of the parameter.
Calls AudioUnitSetParameter, and performs/schedules notification callbacks to all parameter listeners, for that parameter -- except that no callback will be generated to the inListener/inObject pair.
AUParameterListenerNotify |
Notify listeners of a past parameter change.
extern OSStatus AUParameterListenerNotify( AUParameterListenerRef inSendingListener, void *inSendingObject, const AudioUnitParameter *inParameter);
inListener
- A parameter listener generating the change and which does not want to receive a callback as a result of it. May be NULL.
inObject
- The object generating the change and which does not want to receive a callback as a result of it. NULL is treated specially when inListener is non-null; it signifies that none of the specified listener's objects will receive notifications.
inParameter
- The parameter which was changed changed.
Performs and schedules the notification callbacks 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.
AUEventListenerCreate |
Creates an Audio Unit event listener.
extern OSStatus AUEventListenerCreate( AUEventListenerProc inProc, void *inCallbackRefCon, CFRunLoopRef inRunLoop, CFStringRef inRunLoopMode, Float32 inNotificationInterval, // seconds Float32 inValueChangeGranularity, // seconds AUEventListenerRef *outListener);
inProc
- Function called when an event occurs.
inCallbackRefCon
- A reference value for the use of the callback function.
inRunLoop
- The run loop on which the callback is called. If NULL, CFRunLoopGetCurrent() is used.
inRunLoopMode
- The run loop mode in which the callback's underlying run loop source will be attached. If NULL, kCFRunLoopDefaultMode is used.
inNotificationInterval
- The minimum time interval, in seconds, at which the callback will be called.
inValueChangeGranularity
- Determines how parameter value changes occuring within this interval are queued; when an event follows a previous one by a smaller time interval than the granularity, then the listener will only be notified for the second parameter change.
outListener
- On succcessful return, an AUEventListenerRef.
AUEventListener is a specialization of AUParameterListener; use AUListenerDispose to
dispose of an AUEventListener. You may use AUListenerAddParameter and
AUListenerRemoveParameter with AUEventListerRef's, in addition to
AUEventListenerAddEventType / AUEventListenerRemoveEventType.
Some examples illustrating inNotificationInterval and inValueChangeGranularity:
[1] a UI receiver: inNotificationInterval = 100 ms, inValueChangeGranularity = 100 ms.
User interfaces almost never care about previous values, only the current one,
and don't wish to perform redraws too often.
[2] An automation recorder: inNotificationInterval = 200 ms, inValueChangeGranularity = 10 ms.
Automation systems typically wish to record events with a high degree of timing precision,
but do not need to be woken up for each event.
In case [1], the listener will be called within 100 ms (the notification interval) of an
event. It will only receive one notification for any number of value changes to the
parameter concerned, occurring within a 100 ms window (the granularity).
In case [2], the listener will be received within 200 ms (the notification interval) of
an event It can receive more than one notification per parameter, for the last of each
group of value changes occurring within a 10 ms window (the granularity).
In both cases, thread scheduling latencies may result in more events being delivered to
the listener callback than the theoretical maximum (notification interval /
granularity).
AUEventListenerAddEventType |
Begin delivering a particular type of events to a listener.
extern OSStatus AUEventListenerAddEventType( AUEventListenerRef inListener, void *inObject, const AudioUnitEvent *inEvent);
inListener
- The parameter listener which will receive the events.
inObject
- The object which is interested in the value of the parameter. This will be passed as the inObject parameter to the listener callback function when the parameter changes.
inEvent
- The type of event to listen for.
AUEventListenerRemoveEventType |
Stop delivering a particular type of events to a listener.
extern OSStatus AUEventListenerRemoveEventType( AUEventListenerRef inListener, void *inObject, const AudioUnitEvent *inEvent);
inListener
- The parameter listener to stop receiving events.
inObject
- The object which is no longer interested in the value of the parameter.
inEvent
- The type of event to stop listening for.
AUEventListenerNotify |
Deliver an AudioUnitEvent to all listeners registered to receive it.
extern OSStatus AUEventListenerNotify( AUEventListenerRef inSendingListener, void *inSendingObject, const AudioUnitEvent *inEvent);
inSendingListener
- A parameter listener generating the change and which does not want to receive a callback as a result of it. May be NULL.
inSendingObject
- The object generating the change and which does not want to receive a callback as a result of it. NULL is treated specially when inListener is non-null; it signifies that none of the specified listener's objects will receive notifications.
inEvent
- The event to be delivered.
AUParameterValueFromLinear |
Converts a linear value to a parameter value according to the parameter's units.
extern Float32 AUParameterValueFromLinear( Float32 inLinearValue, // 0-1 const AudioUnitParameter *inParameter);
inLinearValue
- The linear value (0.0-1.0) to convert.
inParameter
- The parameter, including its Audio Unit, that will define the conversion of the supplied linear value to a value that is natural to that parameter.
AUParameterValueToLinear |
Converts a parameter value to a linear value according to the parameter's units.
extern Float32 AUParameterValueToLinear( Float32 inParameterValue, const AudioUnitParameter *inParameter);
inParameterValue
- The value in the natural units of the specified parameter.
inParameter
- The parameter, including its Audio Unit, that will define the conversion of the supplied parameter value to a corresponding linear value.
AUParameterFormatValue |
Format a parameter value into a string.
extern char * AUParameterFormatValue( double inParameterValue, const AudioUnitParameter *inParameter, char *inTextBuffer, UInt32 inDigits);
inParameterValue
- The parameter value to be formatted.
inParameter
- The Audio Unit, scope, element, and parameter whose value this is.
inTextBuffer
- The character array to receive the formatted text. Should be at least 32 characters.
inDigits
- The resolution of the string (see example above).
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
- .0100-.0999 4
- .100-.999 3
- 1.00-9.99 2
- 10.0-99.9 1
- 100-999 0
- 1000-9990 -1
- 10000-99900 -2
AUParameterListenerRef |
An object which receives notifications of Audio Unit parameter value changes.
typedef struct AUListenerBase *AUParameterListenerRef;
AUEventListenerRef |
An object which receives Audio Unit events.
typedef AUParameterListenerRef AUEventListenerRef;
An AUEventListenerRef may be passed to API's taking an AUEventListenerRef as an argument.
AudioUnitEvent |
Describes a change to an Audio Unit's state.
See Also:
- AudioUnitEvent
typedef struct AudioUnitEvent { AudioUnitEventType mEventType; union { AudioUnitParameter mParameter; // for parameter value change, begin and end gesture AudioUnitProperty mProperty; // for kAudioUnitEvent_PropertyChange } mArgument; } AudioUnitEvent;
mEventType
- The type of event.
mArgument
- Specifies the parameter or property which has changed.
AUParameterListenerProc |
A function called when a parameter value changes.
typedef void (*AUParameterListenerProc)( void *inRefCon, void *inObject, const AudioUnitParameter *inParameter, Float32 inValue);
inRefCon
- The value passed to AUListenerCreate when the callback function was installed.
inObject
- The object which generated the parameter change.
inParameter
- Signifies the parameter whose value changed.
inValue
- The parameter's new value.
AUParameterListenerProc |
A function called when an Audio Unit event occurs.
See Also:
- AUEventListenerProc
typedef void (*AUEventListenerProc)( void *inCallbackRefCon, void *inObject, const AudioUnitEvent *inEvent, UInt64 inEventHostTime, Float32 inParameterValue);
inCallbackRefCon
- The value passed to AUListenerCreate when the callback function was installed.
inObject
- The object which generated the parameter change.
inEvent
- The event which occurred.
inEventHostTime
- The host time at which the event occurred.
inParameterValue
- If the event is parameter change, the parameter's new value (otherwise, undefined).
AUEventListenerProc |
A function called when an Audio Unit event occurs.
See Also:
- AUParameterListenerProc
typedef void (*AUEventListenerProc)( void *inCallbackRefCon, void *inObject, const AudioUnitEvent *inEvent, UInt64 inEventHostTime, Float32 inParameterValue);
inCallbackRefCon
- The value passed to AUListenerCreate when the callback function was installed.
inObject
- The object which generated the parameter change.
inEvent
- The event which occurred.
inEventHostTime
- The host time at which the event occurred.
inParameterValue
- If the event is parameter change, the parameter's new value (otherwise, undefined).
kAUParameterListener_AnyParameter |
enum { kAUParameterListener_AnyParameter = 0xFFFFFFFF };
kAUParameterListener_AnyParameter
- A wildcard value for an AudioUnitParameterID.
AudioUnitEventType |
Types of Audio Unit Events.
enum { // typedef UInt32 AudioUnitEventType kAudioUnitEvent_ParameterValueChange = 0, kAudioUnitEvent_BeginParameterChangeGesture = 1, kAudioUnitEvent_EndParameterChangeGesture = 2, kAudioUnitEvent_PropertyChange = 3 };
kAudioUnitEvent_ParameterValueChange
- The event is a change to a parameter value
kAudioUnitEvent_BeginParameterChangeGesture
- The event signifies a gesture (e.g. mouse-down) beginning a potential series of related parameter value change events.
kAudioUnitEvent_EndParameterChangeGesture
- The event signifies a gesture (e.g. mouse-up) ending a series of related parameter value change events.
kAudioUnitEvent_PropertyChange
- The event is a change to a property value.
(Last Updated July 18, 2005)