AUBase

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


HasInput

public nonvirtual method


 bool HasInput(AudioUnitElement inElement);

Predicate. Returns whether an input is connected or has a callback.



SetConnection

public virtual method


 virtual ComponentResult SetConnection(const AudioUnitConnection& inConnection);

Makes a connection from another AudioUnit to an input of this unit.



SetInputCallback

public virtual method


 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

public 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


~AUBase

public virtual destructor


 virtual ~AUBase();

The destructor.



Elements


CreateElement

protected virtual method


 virtual AUElement* CreateElement(
          AudioUnitScope                  scope,
          AudioUnitElement                element
    );

Internal. The proper type of element will be created for the scope provided.



CreateElements

public nonvirtual method


 void CreateElements();

Internal. This creates the elements for a scope.



GetElement

public nonvirtual method


 AUElement* GetElement(
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement
    );

Accessor. Get the specified element. Will return null if there is no such element.



GetGroup

public nonvirtual method


 AUGroupElement* GetGroup(AudioUnitElement inElement);

Accessor. Get the specified group element. Will throw an exception if there is no such element.



GetInput

public nonvirtual method


 AUInputElement* GetInput(AudioUnitElement inElement);

Accessor. Get the specified input element. Will throw an exception if there is no such element.



GetOutput

public nonvirtual method


 AUOutputElement* GetOutput(AudioUnitElement inElement);

Accessor. Get the specified output element. Will throw an exception if there is no such element.



GetScope

public nonvirtual method


 AUScope& GetScope(AudioUnitScope inScope);

Accessor. Get the specified AUScope object.



GlobalScope

public nonvirtual method


 AUScope& GlobalScope();

Accessor. Get the global scope AUScope object.



Globals

public nonvirtual method


 AUElement* Globals();

Accessor. Get the global scope AUElement object.



Groups

public nonvirtual method


 AUScope& Parts();

Accessor. Get the group scope AUScope object.



Inputs

public nonvirtual method


 AUScope& Inputs();

Accessor. Get the input scope AUScope object.



Outputs

public nonvirtual method


 AUScope& Outputs();

Accessor. Get the output scope AUScope object.



SafeGetElement

public nonvirtual method


 AUElement* SafeGetElement(
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement
    );

Accessor. Get the specified element. Will throw an exception if there is no such element.



SetNumberOfElements

public nonvirtual method


 void SetNumberOfElements(
          AudioUnitScope                  inScope,
          UInt32                          numElements
    );

Sets the number of elements for a scope.



Format


ChangeStreamFormat

public virtual method


 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.



FormatIsCanonical

public nonvirtual method


 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.



GetStreamFormat

public virtual method


 virtual const CAStreamBasicDescription& GetStreamFormat(
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement
    );

Returns the stream format for the specified element.



IsStreamFormatWritable

public nonvirtual method


 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



MakeCanonicalFormat

public nonvirtual method


 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.



StreamFormatWritable

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.



ValidFormat

public virtual method


 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


Cleanup

public virtual method


 virtual void Cleanup();

Override this to do any necessary clean up.



DoCleanup

public nonvirtual method


 void DoCleanup();

DoCleanup calls Cleanup, making sure that clean up is only attempted once. Your clean up code should be in Cleanup.



DoInitialize

public nonvirtual method


 ComponentResult DoInitialize();

DoInitialize calls Initialize, making sure that initialization is only attempted once. Your initialization code should be in Initialize.



Initialize

public virtual method


 virtual ComponentResult Initialize();

Override this to do your initialization.



IsInitialized

public nonvirtual method


 bool IsInitialized() const;

Predicate. Returns whether the unit is initialized.



PostConstructor

public virtual method


 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.



ReallocateBuffers

protected virtual method


 virtual void ReallocateBuffers();

Internal. This gets called by DoInitialize and SetMaxFramesPerSlice.



Other


AudioUnitAPIVersion

public nonvirtual method


 UInt8 AudioUnitAPIVersion() const;

Return the version number of the AudioUnit API.



BusCountWritable

public virtual method


 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.



CallHostBeatAndTempo

public nonvirtual method


 OSStatus CallHostBeatAndTempo (
          Float64*                        outCurrentBeat,
          Float64*                        outCurrentTempo
    );



CallHostMusicalTimeLocation

public nonvirtual method


 OSStatus CallHostMusicalTimeLocation (
          UInt32*                         outDeltaSampleOffsetToNextBeat,
          Float32*                        outTimeSig_Numerator,
          UInt32*                         outTimeSig_Denominator,
          Float64*                        outCurrentMeasureDownBeat
    );



CallHostTransportState

public nonvirtual method


 OSStatus CallHostTransportState (
          Boolean*                        outIsPlaying,
          Boolean*                        outTransportStateChanged,
          Float64*                        outCurrentSampleInTimeLine,
          Boolean*                        outIsCycling,
          Float64*                        outCycleStartBeat,
          Float64*                        outCycleEndBeat
    );



CanSetMaxFrames

protected virtual method


 virtual OSStatus CanSetMaxFrames() const;



ClearPropertyUsage

public virtual method


 virtual ComponentResult RemovePropertyValue (
          AudioUnitPropertyID             inID,
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement
    );



ComponentEntryDispatch

public static method


 static ComponentResult ComponentEntryDispatch(
          ComponentParameters*            params,
          AUBase*                         This
    );

Internal. This does the dispatching of component selectors to AudioUnit methods.



GetAudioChannelLayout

protected virtual method


 virtual UInt32 GetAudioChannelLayout(
          AudioUnitScope                  scope,
          AudioUnitElement                element,
          AudioChannelLayout*             outLayoutPtr,
          Boolean&                        outWritable
    );



GetGroupParameter

public virtual method


 virtual ComponentResult GetGroupParameter(
          AudioUnitParameterID            inID,
          AudioUnitElement                inElement,
          Float32&                        outValue
    );



GetIOElement

public nonvirtual method


 AUIOElement* GetIOElement(
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement
    );



GetIconLocation

public virtual method


 virtual CFURLRef GetIconLocation ();



GetNumCustomUIComponents

public virtual method


 virtual int GetNumCustomUIComponents ();



GetUIComponentDescs

public virtual method


 virtual void GetUIComponentDescs (ComponentDescription* inDescArray);



GetVectorUnitType

public static method


 static SInt32 GetVectorUnitType();



HasAltivec

public static method


 static bool HasAltivec();



HasIcon

public virtual method


 virtual bool HasIcon ();



HasSSE2

public static method


 static bool HasSSE2();



HasSSE3

public static method


 static bool HasSSE3();



HasVectorUnit

public static method


 static bool HasVectorUnit();



IsRenderThread

public nonvirtual method


 bool InRenderThread () const;



PreDestructor

public virtual method


 virtual void PreDestructor();



RemoveAudioChannelLayout

protected virtual method


 virtual OSStatus RemoveAudioChannelLayout(
          AudioUnitScope                  scope,
          AudioUnitElement                element
    );



SetAudioChannelLayout

protected virtual method


 virtual OSStatus SetAudioChannelLayout(
          AudioUnitScope                  scope,
          AudioUnitElement                element,
          const AudioChannelLayout*       inLayout
    );



SetGroupParameter

public virtual method


 virtual ComponentResult SetGroupParameter(
          AudioUnitParameterID            inID,
          AudioUnitElement                inElement,
          Float32                         inValue,
          UInt32                          inBufferOffsetInFrames
    );



SetWantsRenderThreadID

protected nonvirtual method


 void SetWantsRenderThreadID (bool inFlag);



SupportedNumChannels

public virtual method


 virtual UInt32 SupportedNumChannels (const AUChannelInfo** outInfo);

Returns a list of the supported input and output channel configurations.



WantsRenderThreadID

protected nonvirtual method


 bool WantsRenderThreadID () const;



Parameters


FillInParameterName

protected static method


 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.



GetParameter

public virtual method


 virtual ComponentResult GetParameter(
          AudioUnitParameterID            inID,
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement,
          Float32&                        outValue
    );

Returns the value of a parameter.



GetParameterInfo

public virtual method


 virtual ComponentResult GetParameterInfo(
          AudioUnitScope                  inScope,
          AudioUnitParameterID            inParameterID,
          AudioUnitParameterInfo&         outParameterInfo
    );

Override this to return info on the parameters for your AudioUnit.



GetParameterList

public virtual method


 virtual ComponentResult GetParameterList(
          AudioUnitScope                  inScope,
          AudioUnitParameterID*           outParameterList,
          UInt32&                         outNumParameters
    );

Internal. This provides support for a call to GetProperty on the kAudioUnitProperty_ParameterList property.



GetParameterValueStrings

public virtual method


 virtual ComponentResult GetParameterValueStrings(
          AudioUnitScope                  inScope,
          AudioUnitParameterID            inParameterID,
          CFArrayRef*                     outStrings
    );

Internal. This provides support for a call to GetProperty on the kAudioUnitProperty_ParameterValueStrings property.



RestoreState

public virtual method


 virtual ComponentResult RestoreState(CFPropertyListRef inData);

Restores all parameter values from the CFPropertyListRef.



SaveState

public virtual method


 virtual ComponentResult SaveState(CFPropertyListRef* outData);

Stores the values of all parameters into a CFPropertyListRef.



ScheduleParameter

public virtual method


 virtual ComponentResult ScheduleParameter (
          const AudioUnitParameterEvent*  inParameterEvent,
          UInt32                          inNumEvents
    );

Enters parameter changes into a queue for the audio unit.



SetParameter

public virtual method


 virtual ComponentResult SetParameter(
          AudioUnitParameterID            inID,
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement,
          Float32                         inValue,
          UInt32                          inBufferOffsetInFrames
    );

Set a parameter value.



Presets


GetPresets

public virtual method


 virtual ComponentResult GetPresets (CFArrayRef* outData) const;



NewFactoryPresetSet

public virtual method


 virtual OSStatus NewFactoryPresetSet (const AUPreset& inNewFactoryPreset);



SetAFactoryPresetAsCurrent

public nonvirtual method


 bool SetAFactoryPresetAsCurrent (const AUPreset& inPreset);



Properties


AddPropertyListener

public virtual method


 virtual ComponentResult AddPropertyListener(
          AudioUnitPropertyID             inID,
          AudioUnitPropertyListenerProc   inProc,
          void*                           inProcRefCon
    );

Registers a function to call whenever there is a change to a property.



DispatchGetProperty

public nonvirtual method


 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.



DispatchGetPropertyInfo

public nonvirtual method


 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.



DispatchSetProperty

public nonvirtual method


 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.



GetLatency

public virtual method


 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.



GetProperty

public virtual method


 virtual ComponentResult GetProperty(
          AudioUnitPropertyID             inID,
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement,
          void*                           outData
    );

Override to return values for your own properties.



GetPropertyInfo

public virtual method


 virtual ComponentResult GetPropertyInfo(
          AudioUnitPropertyID             inID,
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement,
          UInt32&                         outDataSize,
          Boolean&                        outWritable
    );

Override to return info for your own properties.



GetTailTime

public virtual method


 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



PropertyChanged

public nonvirtual method


 void PropertyChanged(
          AudioUnitPropertyID             inID,
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement
    );

Internal. Notifies property listeners that a property value has changed.



RemovePropertyListener

public virtual method


 virtual ComponentResult RemovePropertyListener(
          AudioUnitPropertyID             inID,
          AudioUnitPropertyListenerProc   inProc
    );

Removes a property listener proc for the property.



SetProperty

public virtual method


 virtual ComponentResult SetProperty(
          AudioUnitPropertyID             inID,
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement,
          const void*                     inData,
          UInt32                          inDataSize
    );

Override to set values for your own properties.



SupportsRampAndTail

public virtual method


 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


DoRender

public nonvirtual method


 ComponentResult DoRender(
          AudioUnitRenderActionFlags&     ioActionFlags,
          const AudioTimeStamp&           inTimeStamp,
          UInt32                          inBusNumber,
          UInt32                          inNumberFrames,
          AudioBufferList&                ioData
    );

Internal. Handles rendering of audio. This will call RenderBus.



DoRenderBus

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.



DoRenderSlice

public nonvirtual method


 ComponentResult DoRenderSlice(
          AudioUnitRenderActionFlags      inActionFlags,
          const AudioTimeStamp&           inTimeStamp,
          UInt32                          inBusNumber,
          AudioBufferList&                ioData
    );

Internal. Handles rendering of audio. This will call RenderBus.



GetMaxFramesPerSlice

public nonvirtual method


 UInt32 GetMaxFramesPerSlice() const;

Accessor. Get the maximum number of frames that can be requested in a render call.



NeedsToRender

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.



PullInput

public nonvirtual method


 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.



RemoveRenderNotification

public virtual 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.



Render

public virtual method


 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.



RenderBus

public virtual method


 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.



Reset

public virtual method


 virtual ComponentResult Reset(
          AudioUnitScope                  inScope,
          AudioUnitElement                inElement
    );

Resets the unit to restart audio processing. AUEffectBase overrides this to reset the DSP kernels.



SetMaxFramesPerSlice

protected virtual method


 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.



SetRenderNotification

public virtual method


 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


mScopes

private instance variable


 AUScope mScopes[kNumScopes];

List of the AUScope objects which in turn contain AUElements.



Initialization


mBuffersAllocated

protected instance variable


 bool mBuffersAllocated;

Whether buffers have yet been allocated.



mElementsCreated

private instance variable


 bool mElementsCreated;

Whether CreateElements has yet been called.



mInitialized

protected instance variable


 bool mInitialized;

Whether Initialize has been called successfully. See also IsInitialized.



Other


mAudioUnitAPIVersion

private instance variable


 UInt8 mAudioUnitAPIVersion;

The AudioUnit API version number. Currently either 1 or 2.



mContextInfo

protected instance variable


 CFStringRef mContextName;



mHostCallbackInfo

protected instance variable


 HostCallbackInfo mHostCallbackInfo;

A place to store the information for the beat and tempo callback.



mInitNumGroupEls

private instance variable


 UInt32 mInitNumGroupEls;



mInitNumInputEls

private instance variable


 UInt32 mInitNumInputEls;



mInitNumOutputEls

private instance variable


 UInt32 mInitNumOutputEls;



mInitNumPartEls

private instance variable


 UInt32 mInitNumPartEls;



mRenderThreadID

private instance variable


#if TARGET_OS_MAC pthread_t mRenderThreadID;



mWantsRenderThreadID

private instance variable


 bool mWantsRenderThreadID;



sVectorUnitType

private static variable


 static SInt32 sVectorUnitType;

enum value indicating which type of vector unit this machine has, if any. See GetVectorUnitType.



Parameters


mParamList

protected instance variable


 ParameterEventList mParamList;

List of scheduled ParameterEvents.



Presets


mCurrentPreset

private instance variable


 AUPreset mCurrentPreset;

The current preset number and name.



Properties


mPropertyListeners

protected instance variable


 PropertyListeners mPropertyListeners;

List of functions to call when a property changes.



Rendering


mLastRenderError

private instance variable


 OSStatus mLastRenderError;

The first render error that occurred after the last time kAudioUnitProperty_LastRenderError was checked.



mLastRenderedSampleTime

private instance variable


 Float64 mLastRenderedSampleTime;

Set by NeedsToRender.



mMaxFramesPerSlice

private instance variable


 UInt32 mMaxFramesPerSlice;

The maximum number of frames that can be requested in a render call.



mRenderCallbacks

private instance variable


 RenderCallbackList mRenderCallbacks;

List of functions to call before and after rendering.