Superclasses :
ComponentBase, AUElementCreator
Subclasses :
AUEffectBase, MusicDeviceBase, AUOutputBase
Header : AUBase
class AUBase : public ComponentBase, public AUElementCreator
This is the base class for writing your own AudioUnit. It handles many of the bookkeeping chores to support an AudioUnit.
An AudioUnit is responsible for providing a lot of features and information about itself through the property mechanism.
AUBase provides support for many of these properties for you and makes it simpler for you to support those that you must provide yourself.
If you are writing an effect processor, you will probably want to use AUEffectBase or AUInlineEffectBase instead of AUBase.
If you are writing a MIDI controlled unit then you will want to use AUMIDIEffectBase.
Methods
Connections
bool HasInput(AudioUnitElement inElement);
Predicate. Returns whether an input is connected or has a callback.
virtual ComponentResult SetConnection(const AudioUnitConnection& inConnection);
Makes a connection from another AudioUnit to an input of this unit.
virtual ComponentResult SetInputCallback(
UInt32 inPropertyID,
AudioUnitElement inElement,
ProcPtr inProc,
void* inRefCon
);
Set a function to call to get data for an input to this AudioUnit.
Constructor
AUBase(
AudioUnit inInstance,
UInt32 numInputElements,
UInt32 numOutputElements,
UInt32 numGroupElements = 0,
UInt32 numPartElements = 0
);
Create an instance of AUBase. Arguments specify numbers of initial inputs, outputs and groups and the owning AudioUnit.
Destructor
|
public virtual destructor
|
virtual ~AUBase();
The destructor.
Elements
virtual AUElement* CreateElement(
AudioUnitScope scope,
AudioUnitElement element
);
Internal. The proper type of element will be created for the scope provided.
void CreateElements();
Internal. This creates the elements for a scope.
AUElement* GetElement(
AudioUnitScope inScope,
AudioUnitElement inElement
);
Accessor. Get the specified element. Will return null if there is no such element.
AUGroupElement* GetGroup(AudioUnitElement inElement);
Accessor. Get the specified group element. Will throw an exception if there is no such element.
AUInputElement* GetInput(AudioUnitElement inElement);
Accessor. Get the specified input element. Will throw an exception if there is no such element.
AUOutputElement* GetOutput(AudioUnitElement inElement);
Accessor. Get the specified output element. Will throw an exception if there is no such element.
AUScope& GetScope(AudioUnitScope inScope);
Accessor. Get the specified AUScope object.
AUScope& GlobalScope();
Accessor. Get the global scope AUScope object.
AUElement* Globals();
Accessor. Get the global scope AUElement object.
AUScope& Parts();
Accessor. Get the group scope AUScope object.
AUScope& Inputs();
Accessor. Get the input scope AUScope object.
AUScope& Outputs();
Accessor. Get the output scope AUScope object.
AUElement* SafeGetElement(
AudioUnitScope inScope,
AudioUnitElement inElement
);
Accessor. Get the specified element. Will throw an exception if there is no such element.
void SetNumberOfElements(
AudioUnitScope inScope,
UInt32 numElements
);
Sets the number of elements for a scope.
Format
virtual ComponentResult ChangeStreamFormat(
AudioUnitScope inScope,
AudioUnitElement inElement,
const CAStreamBasicDescription& inPrevFormat,
const CAStreamBasicDescription& inNewFormat
);
This method gets called in response to setting kAudioUnitProperty_StreamFormat or kAudioUnitProperty_SampleRate.
Classes intended to be base classes that need to do some additional bookkeeping when changing stream format
may want to override this method. Will only be called after IsStreamFormatWritable and ValidFormat have succeeded.
bool FormatIsCanonical(const CAStreamBasicDescription &format);
Predicate. Returns true if format is canonical. A canonical format is floating point samples in the host's endianness and the
interleave-edness matches that of the AudioUnit API version which is interleaved for version 1 and noninterleaved for version 2.
virtual const CAStreamBasicDescription& GetStreamFormat(
AudioUnitScope inScope,
AudioUnitElement inElement
);
Returns the stream format for the specified element.
bool IsStreamFormatWritable(
AudioUnitScope scope,
AudioUnitElement element
);
Predicate. Returns whether an input or output's stream format can be set.
The scope argument should be either kAudioUnitScope_Input or kAudioUnitScope_Output
void MakeCanonicalFormat(
CAStreamBasicDescription& outDesc,
int numChannels = 2
);
Convenience function to fill in a CAStreamBasicDescription with a canonical format description of the specified number of channels.
See FormatIsCanonical for a description of canonical format.
|
public pure virtual method
|
virtual bool StreamFormatWritable(
AudioUnitScope scope,
AudioUnitElement element
) = 0;
Override this to tell whether one of your input or output elements can have the stream format changed.
virtual bool ValidFormat(
AudioUnitScope inScope,
AudioUnitElement inElement,
const CAStreamBasicDescription& inNewFormat
);
Override to return whether a particular stream format is valid for one of your input or output elements.
The default implementation returns the result of FormatIsCanonical.
Initialization
virtual void Cleanup();
Override this to do any necessary clean up.
void DoCleanup();
DoCleanup calls Cleanup, making sure that clean up is only attempted once. Your clean up code should be in Cleanup.
ComponentResult DoInitialize();
DoInitialize calls Initialize, making sure that initialization is only attempted once. Your initialization code should be in Initialize.
virtual ComponentResult Initialize();
Override this to do your initialization.
bool IsInitialized() const;
Predicate. Returns whether the unit is initialized.
virtual void PostConstructor();
Allows base class to do additional initialization once the derived class is fully constructed. This gets called automatically.
Can be overridden to do any initialization that requires a fully constructed object with working virtual methods.
AUBase calls CreateElements here.
virtual void ReallocateBuffers();
Internal. This gets called by DoInitialize and SetMaxFramesPerSlice.
Other
UInt8 AudioUnitAPIVersion() const;
Return the version number of the AudioUnit API.
virtual bool BusCountWritable(AudioUnitScope inScope);
This method gets called in response to handling kAudioUnitProperty_BusCount.
Returns whether the number of buses can be changed. The default method returns false.
Override if your AudioUnit can have a variable number of buses for input or output.
kAudioUnitProperty_BusCount may only be set if this method returns true and the unit has not been initialized.
OSStatus CallHostBeatAndTempo (
Float64* outCurrentBeat,
Float64* outCurrentTempo
);
OSStatus CallHostMusicalTimeLocation (
UInt32* outDeltaSampleOffsetToNextBeat,
Float32* outTimeSig_Numerator,
UInt32* outTimeSig_Denominator,
Float64* outCurrentMeasureDownBeat
);
OSStatus CallHostTransportState (
Boolean* outIsPlaying,
Boolean* outTransportStateChanged,
Float64* outCurrentSampleInTimeLine,
Boolean* outIsCycling,
Float64* outCycleStartBeat,
Float64* outCycleEndBeat
);
virtual OSStatus CanSetMaxFrames() const;
virtual ComponentResult RemovePropertyValue (
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement
);
static ComponentResult ComponentEntryDispatch(
ComponentParameters* params,
AUBase* This
);
Internal. This does the dispatching of component selectors to AudioUnit methods.
virtual UInt32 GetAudioChannelLayout(
AudioUnitScope scope,
AudioUnitElement element,
AudioChannelLayout* outLayoutPtr,
Boolean& outWritable
);
virtual ComponentResult GetGroupParameter(
AudioUnitParameterID inID,
AudioUnitElement inElement,
Float32& outValue
);
AUIOElement* GetIOElement(
AudioUnitScope inScope,
AudioUnitElement inElement
);
virtual CFURLRef GetIconLocation ();
virtual int GetNumCustomUIComponents ();
virtual void GetUIComponentDescs (ComponentDescription* inDescArray);
static SInt32 GetVectorUnitType();
static bool HasAltivec();
virtual bool HasIcon ();
static bool HasSSE2();
static bool HasSSE3();
static bool HasVectorUnit();
bool InRenderThread () const;
virtual void PreDestructor();
virtual OSStatus RemoveAudioChannelLayout(
AudioUnitScope scope,
AudioUnitElement element
);
virtual OSStatus SetAudioChannelLayout(
AudioUnitScope scope,
AudioUnitElement element,
const AudioChannelLayout* inLayout
);
virtual ComponentResult SetGroupParameter(
AudioUnitParameterID inID,
AudioUnitElement inElement,
Float32 inValue,
UInt32 inBufferOffsetInFrames
);
|
protected nonvirtual method
|
void SetWantsRenderThreadID (bool inFlag);
virtual UInt32 SupportedNumChannels (const AUChannelInfo** outInfo);
Returns a list of the supported input and output channel configurations.
|
protected nonvirtual method
|
bool WantsRenderThreadID () const;
Parameters
static void FillInParameterName (
AudioUnitParameterInfo& ioInfo,
CFStringRef inName,
bool inShouldRelease
);
Service. A convenience function for putting the name of the parameter from a CFStringRef into an AudioUnitParameterInfo.
You will use this when you write your GetParameterInfo method.
This method's signature has been changed to highlight the fact that the AU should declare if the CFString parameter name should be
released by the client of not.
virtual ComponentResult GetParameter(
AudioUnitParameterID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
Float32& outValue
);
Returns the value of a parameter.
virtual ComponentResult GetParameterInfo(
AudioUnitScope inScope,
AudioUnitParameterID inParameterID,
AudioUnitParameterInfo& outParameterInfo
);
Override this to return info on the parameters for your AudioUnit.
virtual ComponentResult GetParameterList(
AudioUnitScope inScope,
AudioUnitParameterID* outParameterList,
UInt32& outNumParameters
);
Internal. This provides support for a call to GetProperty on the kAudioUnitProperty_ParameterList property.
virtual ComponentResult GetParameterValueStrings(
AudioUnitScope inScope,
AudioUnitParameterID inParameterID,
CFArrayRef* outStrings
);
Internal. This provides support for a call to GetProperty on the kAudioUnitProperty_ParameterValueStrings property.
virtual ComponentResult RestoreState(CFPropertyListRef inData);
Restores all parameter values from the CFPropertyListRef.
virtual ComponentResult SaveState(CFPropertyListRef* outData);
Stores the values of all parameters into a CFPropertyListRef.
virtual ComponentResult ScheduleParameter (
const AudioUnitParameterEvent* inParameterEvent,
UInt32 inNumEvents
);
Enters parameter changes into a queue for the audio unit.
virtual ComponentResult SetParameter(
AudioUnitParameterID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
Float32 inValue,
UInt32 inBufferOffsetInFrames
);
Set a parameter value.
Presets
virtual ComponentResult GetPresets (CFArrayRef* outData) const;
virtual OSStatus NewFactoryPresetSet (const AUPreset& inNewFactoryPreset);
bool SetAFactoryPresetAsCurrent (const AUPreset& inPreset);
Properties
virtual ComponentResult AddPropertyListener(
AudioUnitPropertyID inID,
AudioUnitPropertyListenerProc inProc,
void* inProcRefCon
);
Registers a function to call whenever there is a change to a property.
ComponentResult DispatchGetProperty(
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
void* outData
);
Certain properties are dispatched to be handled with different virtual methods.
Your own properties should be handled by overriding GetProperty, not DispatchGetProperty.
ComponentResult DispatchGetPropertyInfo(
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
UInt32& outDataSize,
Boolean& outWritable
);
Certain properties are dispatched to be handled with different virtual methods.
Your own properties should be handled by overriding GetPropertyInfo, not DispatchGetPropertyInfo.
ComponentResult DispatchSetProperty(
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
const void* inData,
UInt32 inDataSize
);
Certain properties are dispatched to be handled with different virtual methods.
Your own properties should be handled by overriding SetProperty, not DispatchSetProperty.
virtual Float64 GetLatency();
Returns the throughput latency of the unit in seconds. Override this if your AudioUnit has a throughput latency.
The default method returns zero.
virtual ComponentResult GetProperty(
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
void* outData
);
Override to return values for your own properties.
virtual ComponentResult GetPropertyInfo(
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
UInt32& outDataSize,
Boolean& outWritable
);
Override to return info for your own properties.
virtual Float64 GetTailTime();
Override this method if your AudioUnit takes some time to decay after the source has ended.
If you override this then you should also override SupportsRampAndTail
void PropertyChanged(
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement
);
Internal. Notifies property listeners that a property value has changed.
virtual ComponentResult RemovePropertyListener(
AudioUnitPropertyID inID,
AudioUnitPropertyListenerProc inProc
);
Removes a property listener proc for the property.
virtual ComponentResult SetProperty(
AudioUnitPropertyID inID,
AudioUnitScope inScope,
AudioUnitElement inElement,
const void* inData,
UInt32 inDataSize
);
Override to set values for your own properties.
virtual bool SupportsTail ();
Override to return true if your audio unit has a ramp time and tail time. The default method returns false.
If you override this then you should also override either or both GetRampUpTime and
GetTailTime
Rendering
ComponentResult DoRender(
AudioUnitRenderActionFlags& ioActionFlags,
const AudioTimeStamp& inTimeStamp,
UInt32 inBusNumber,
UInt32 inNumberFrames,
AudioBufferList& ioData
);
Internal. Handles rendering of audio. This will call RenderBus.
|
private nonvirtual method
|
ComponentResult DoRenderBus(
AudioUnitRenderActionFlags& ioActionFlags,
const AudioTimeStamp& inTimeStamp,
UInt32 inBusNumber,
AUOutputElement* theOutput,
UInt32 inNumberFrames,
AudioBufferList& ioData
);
Internal. Handles common code for rendering audio.
ComponentResult DoRenderSlice(
AudioUnitRenderActionFlags inActionFlags,
const AudioTimeStamp& inTimeStamp,
UInt32 inBusNumber,
AudioBufferList& ioData
);
Internal. Handles rendering of audio. This will call RenderBus.
UInt32 GetMaxFramesPerSlice() const;
Accessor. Get the maximum number of frames that can be requested in a render call.
|
protected nonvirtual method
|
bool NeedsToRender(Float64 inSampleTime);
Returns whether the audio unit needs to call render for this sample time. If it has already rendered for this time, then it returns false.
ComponentResult PullInput(
UInt32 inBusNumber,
AudioUnitRenderActionFlags& ioActionFlags,
const AudioTimeStamp& inTimeStamp,
UInt32 inNumberFrames
);
Convenience function to pull an input. You would use this in your Render method.
virtual ComponentResult RemoveRenderNotification(
ProcPtr inProc,
void* inRefCon
);
Removes the notification function from the list of functions called before and after rendering. See also SetRenderNotification.
virtual ComponentResult Render(
AudioUnitRenderActionFlags& ioActionFlags,
const AudioTimeStamp& inTimeStamp,
UInt32 inNumberFrames
);
This method is called in response to another AudioUnit or function requesting a buffer of output from your unit.
Your signal processing needs to be done in here or in a function called from here.
If your AudioUnit processes multiple output busses together, not independantly override this method.
Otherwise override RenderBus.
N.B. For a unit with only one output bus, it can assume in its implementation of this
method that the output's buffer list has already been prepared and access it with
GetOutput(0)->GetBufferList() instead of GetOutput(0)->PrepareBuffer(nFrames)
-- if PrepareBuffer is called, a copy may occur after rendering.
virtual ComponentResult RenderBus(
AudioUnitRenderActionFlags& ioActionFlags,
const AudioTimeStamp& inTimeStamp,
UInt32 inBusNumber,
UInt32 inNumberFrames
);
Override this method if your AudioUnit processes multiple output busses completely independently
(you'll want to just call Render without the NeedsToRender check). Otherwise, override Render.
N.B. Implementations of this method can assume that the output's buffer list has already been
prepared and access it with GetOutput(inBusNumber)->GetBufferList() instead of
GetOutput(inBusNumber)->PrepareBuffer(nFrames) -- if PrepareBuffer is called, a
copy may occur after rendering.
virtual ComponentResult Reset(
AudioUnitScope inScope,
AudioUnitElement inElement
);
Resets the unit to restart audio processing. AUEffectBase overrides this to reset the DSP kernels.
virtual void SetMaxFramesPerSlice(UInt32 nFrames);
An accessor to set the maximum number of frames that can be requested in a render call. Buffers will be reallocated if necessary.
virtual ComponentResult SetRenderNotification(
ProcPtr inProc,
void* inRefCon
);
Adds the notification function to a list of functions called before and after rendering. See also RemoveRenderNotification.
Data
Elements
|
private instance variable
|
AUScope mScopes[kNumScopes];
List of the AUScope objects which in turn contain AUElements.
Initialization
|
protected instance variable
|
bool mBuffersAllocated;
Whether buffers have yet been allocated.
|
private instance variable
|
bool mElementsCreated;
Whether CreateElements has yet been called.
|
protected instance variable
|
bool mInitialized;
Whether Initialize has been called successfully. See also IsInitialized.
Other
|
private instance variable
|
UInt8 mAudioUnitAPIVersion;
The AudioUnit API version number. Currently either 1 or 2.
|
protected instance variable
|
CFStringRef mContextName;
|
protected instance variable
|
HostCallbackInfo mHostCallbackInfo;
A place to store the information for the beat and tempo callback.
|
private instance variable
|
UInt32 mInitNumGroupEls;
|
private instance variable
|
UInt32 mInitNumInputEls;
|
private instance variable
|
UInt32 mInitNumOutputEls;
|
private instance variable
|
UInt32 mInitNumPartEls;
|
private instance variable
|
#if TARGET_OS_MAC pthread_t mRenderThreadID;
|
private instance variable
|
bool mWantsRenderThreadID;
static SInt32 sVectorUnitType;
enum value indicating which type of vector unit this machine has, if any. See GetVectorUnitType.
Parameters
|
protected instance variable
|
ParameterEventList mParamList;
List of scheduled ParameterEvents.
Presets
|
private instance variable
|
AUPreset mCurrentPreset;
The current preset number and name.
Properties
|
protected instance variable
|
PropertyListeners mPropertyListeners;
List of functions to call when a property changes.
Rendering
|
private instance variable
|
OSStatus mLastRenderError;
The first render error that occurred after the last time kAudioUnitProperty_LastRenderError was checked.
|
private instance variable
|
Float64 mLastRenderedSampleTime;
Set by NeedsToRender.
|
private instance variable
|
UInt32 mMaxFramesPerSlice;
The maximum number of frames that can be requested in a render call.
|
private instance variable
|
RenderCallbackList mRenderCallbacks;
List of functions to call before and after rendering.