Mac Developer Library

Developer

IOAudioEngine Class Reference

Options
Deployment Target:

On This Page
Language:

IOAudioEngine

Abstract base class for a single audio audio / I/O engine. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.1 and later.
  • Adds an IOAudioStream to the audio engine.

    Declaration

    C++

    virtual IOReturn addAudioStream( IOAudioStream *stream);

    Parameters

    stream

    The IOAudioStream to be added.

    Return Value

    Returns kIOReturnSuccess if the stream was successfully added.

    Discussion

    This function is called by the driver to add an IOAudioStream to the audio engine. This must be called at least once to make sure the audio engine has at least one IOAudioStream.

    Import Statement

  • Enables the timer event for the audio engine.

    Declaration

    C++

    virtual void addTimer();

    Discussion

    There is a timer event needed by the IOAudioEngine for processing the erase head and performing flushing operations. When the timer fires, the method timerFired() is ultimately called which in turn calls performErase() and performFlush(). This is called automatically to enable the timer event for this audio engine. It is called by setState() when the audio engine state is set to kIOAudioEngineRunning. When the timer is no longer needed, removeTimer() is called. There is no need to call this directly.

    Import Statement

  • Zeros out all of the sample and mix buffers associated with the IOAudioEngine

    Declaration

    C++

    virtual void clearAllSampleBuffers();

    Discussion

    This is called during resumeAudioEngine() since the audio engine gets started back at the beginning of the sample buffer.

    Import Statement

  • Called automatically when a user client closes its connection to the audio engine.

    Declaration

    C++

    virtual void clientClosed( IOAudioEngineUserClient *client);

    Parameters

    client

    The user client that has disconnected.

    Discussion

    This method decrements the number of connections to the audio engine and if they reach zero, the audio engine is called with a call to stopAudioEngine(). This method should not be called directly.

    Import Statement

  • Override this method if you want to return a different number of sample frames than was requested.

    Declaration

    C++

    virtual IOReturn convertInputSamplesVBR( const void *sampleBuf, void *destBuf, UInt32 firstSampleFrame, UInt32 &numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);

    Import Statement

  • Generates a dictionary matching the given sample rate.

    Declaration

    C++

    static OSDictionary *createDictionaryFromSampleRate( const IOAudioSampleRate *sampleRate, OSDictionary *rateDict = 0);

    Return Value

    Returns the newly create OSDictionary.

    Discussion

    This is an internal routine used to generate a dictionary matching the given sample rate. It is used to generate a sample rate dictionary for the I/O Registry - used by the CoreAudio.framework.

    Import Statement

  • Generates a sample rate from an OSDictionary.

    Declaration

    C++

    static IOAudioSampleRate *createSampleRateFromDictionary( const OSDictionary *rateDict, IOAudioSampleRate *sampleRate = 0);

    Return Value

    Returns the sample rate.

    Discussion

    This is an internal routine used to generate a sample rate from an OSDictionary. It is used to generate a sample rate give a new OSDictionary from the IORegistry - coming from the CoreAudio.framework.

    Import Statement

  • This function allows for the actual erasing of the mix and sample buffer to be overridden by a child class.

    Declaration

    C++

    virtual IOReturn eraseOutputSamples( const void *mixBuf, void *sampleBuf, UInt32firstSampleFrame, UInt32numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);

    Parameters

    mixBuf

    Pointer to the IOAudioFamily allocated mix buffer.

    sampleBuf

    Pointer to the child class' sample buffer.

    firstSampleFrame

    Index to the first sample frame to erase.

    numSampleFrames

    Number of sample frames to erase.

    streamFormat

    Format of the data to be erased.

    audioStream

    Pointer to stream object that corresponds to the sample buffer being erased.

    Return Value

    Must return kIOReturnSuccess if the samples have been erased.

    Import Statement

  • Frees all of the resources allocated by the IOAudioEngine.

    Declaration

    C++

    virtual void free();

    Discussion

    Do not call this directly. This is called automatically by the system when the instance's refcount goes to 0. To decrement the refcount, call release() on the object.

    Import Statement

  • Generic method to retrieve some attribute of the audio engine, specific to one connection.

    Declaration

    C++

    virtual IOReturn getAttributeForConnection( SInt32 connectIndex, UInt32 attribute, uintptr_t *value );

    Parameters

    attribute

    Defines the attribute to be returned. Some defined attributes are:

    value

    Returns the value for the attribute.

    Return Value

    an IOReturn code.

    Discussion

    IOAudioEngine subclasses may implement this method to allow arbitrary attribute/value pairs to be returned, specific to one connection.

    Import Statement

  • Returns the IOCommandGate for this IOAudioEngine.

    Declaration

    C++

    virtual IOCommandGate *getCommandGate() const;

    Import Statement

  • Gets the current sample frame from the IOAudioEngine subclass.

    Declaration

    C++

    virtual UInt32 getCurrentSampleFrame() = 0;

    Import Statement

  • Returns true if the audio engine will run the erase head when the audio engine is running.

    Declaration

    C++

    virtual bool getRunEraseHead();

    Import Statement

  • Returns the sample rate of the IOAudioEngine in samples per second.

    Declaration

    C++

    virtual const IOAudioSampleRate *getSampleRate();

    Import Statement

  • Returns the current state of the IOAudioEngine.

    Declaration

    C++

    virtual IOAudioEngineState getState();

    Return Value

    The current state of the IOAudioEngine: kIOAudioEngineRunning, kIOAudioEngineStopped.

    Discussion

    If this method is called in preparation for calling setState(), the stateLock must be acquired before the first call to getState() and held until after the last call to setState(). Be careful not to return from the code acquiring the lock while the lock is being held. That will cause a deadlock situation.

    Import Statement

  • Returns a pointer to the shared status buffer.

    Declaration

    C++

    virtual const IOAudioEngineStatus *getStatus();

    Import Statement

  • Gets the timer interval for use by the timer event.

    Declaration

    C++

    virtual AbsoluteTime getTimerInterval();

    Return Value

    Returns the interval for the timer event.

    Discussion

    This method is called each time the timer event is enabled through addTimer(). The default implementation is set to return a value such that the timer event runs n times each cycle of the audio engine through the sample buffer. The value n is stored as the instance variable: numErasesPerBuffer. The default value of numErasesPerBuffer is set to IOAUDIOENGINE_DEFAULT_NUM_ERASES_PER_BUFFER which is 4. A subclass may change the value of numErasesPerBuffer or override getTimerInterval. If it is overridden, the subclass should call the superclass's implementation, compare its interval with the superclass's and return the smaller of the two.

    Import Statement

  • Returns the IOWorkLoop for the driver.

    Declaration

    C++

    virtual IOWorkLoop *getWorkLoop() const;

    Import Statement

  • Performs initialization of a newly allocated IOAudioEngine.

    Declaration

    C++

    virtual bool init( OSDictionary *properties);

    Parameters

    properties

    The default properties for the IOAudioEngine.

    Return Value

    Returns true if initialization was successful.

    Discussion

    This function is responsible for initialization of all of the general attributes of a new IOAudioEngine. It initializes instance variables to their default values and allocates the shared status buffer. Subclasses will likely want to override this method and do all of their common initialization in their implementation. They do need to be sure to call IOAudioEngine's implementation of init and pay attention to the return value.

    Import Statement

  • This function is called by start() to provide a convenient place for the subclass to perform its hardware initialization.

    Declaration

    C++

    virtual bool initHardware( IOService *provider);

    Parameters

    provider

    The service provider numb for this audio engine - typically the IOAudioDevice.

    Return Value

    Returns true if the hardware was successfully initialized.

    Discussion

    Upon return from this function, all IOAudioStreams and IOAudioControls should be created and the audio engine should be ready to be started when a client requests that playback begin.

    Import Statement

  • Generates the OSSymbols with the keys.

    Declaration

    C++

    static void initKeys();

    Discussion

    Do not call this directly. This is an internal initialization routine.

    Import Statement

  • Requests a new user client object for this service.

    Declaration

    C++

    virtual IOReturn newUserClient( task_t task, void *securityID, UInt32 type, IOUserClient **handler);

    Parameters

    task

    The task requesting the new user client.

    securityID

    Optional security paramater passed in by the client - ignored.

    type

    Optional user client type passed in by the client - ignored.

    handler

    The new IOUserClient * must be stored in this param on a successful completion.

    properties

    A dictionary of additional properties for the connection.

    Return Value

    Returns kIOReturnSuccess on success. May also result kIOReturnError or kIOReturnNoMemory.

    Discussion

    This function is called automatically by I/O Kit when a user process attempts to connect to this service. It allocates a new IOAudioEngineUserClient object and increments the number of connections for this audio engine. If this is the first user client for this IOAudioEngine, it calls startAudioEngine(). There is no need to call this function directly. A derived class that requires overriding of newUserClient should override the version with the properties parameter for Intel targets, and without the properties parameter for PPC targets. The #if __i386__ directive can be used to select between the two behaviors.

    Import Statement

  • Called to start the audio I/O engine

    Declaration

    C++

    virtual IOReturn performAudioEngineStart();

    Return Value

    Must return kIOReturnSuccess on a successful start of the engine.

    Discussion

    This method is called by startAudioEngine(). This must be overridden by the subclass. No call to the superclass' implementation is necessary. The subclass' implementation must start up the audio I/O engine. This includes any audio engine that needs to be started as well as any interrupts that need to be enabled.

    Import Statement

  • Called to stop the audio I/O engine

    Declaration

    C++

    virtual IOReturn performAudioEngineStop();

    Return Value

    Must return kIOReturnSuccess on a successful stop of the engine.

    Discussion

    This method is called by stopAudioEngine() and pauseAudioEngine. This must be overridden by the subclass. No call to the superclass' implementation is necessary. The subclass' implementation must stop the audio I/O engine. This includes any audio engine that needs to be stopped as well as any interrupts that need to be disabled.

    Import Statement

  • Performs erase head processing.

    Declaration

    C++

    virtual void performErase();

    Discussion

    This method is called automatically each time the timer event fires and erases the sample buffer and mix buffer from the previous location up to the current location of the audio engine.

    Import Statement

  • Performs the flush operation.

    Declaration

    C++

    virtual void performFlush();

    Discussion

    This method is called automatically each time the timer event fires. It stops the audio engine if there are no more clients and the audio engine is passed the latest flush ending position.

    Import Statement

  • Called when this audio engine is ready to begin vending services.

    Declaration

    C++

    virtual void registerService( IOOptionBits options = 0);

    Parameters

    options

    Discussion

    This function is called by IOAudioDevice::activateAudioEngine() once the audio engine has been fully initialized and is ready to begin audio playback.

    Import Statement

  • Disables the timer event for the audio engine.

    Declaration

    C++

    virtual void removeTimer();

    Discussion

    This method is called automatically to disable the timer event for this audio engine. There is need to call it directly. This method is called by setState() when the audio engine state is changed from kIOAudioEngineRunning to one of the stopped states.

    Import Statement

  • Resets the status buffer to its default values.

    Declaration

    C++

    virtual void resetStatusBuffer();

    Discussion

    This is called during startAudioEngine() and resumeAudioEngine() to clear out the status buffer in preparation of starting up the I/O engine. There is no need to call this directly.

    Import Statement

  • Generic method to set some attribute of the audio engine, specific to one connection.

    Declaration

    C++

    virtual IOReturn setAttributeForConnection( SInt32 connectIndex, UInt32 attribute, uintptr_t value );

    Parameters

    attribute

    Defines the attribute to be set.

    value

    The new value for the attribute.

    Return Value

    an IOReturn code.

    Discussion

    IOAudioEngine subclasses may implement this method to allow arbitrary attribute/value pairs to be set, specific to one connection.

    Import Statement

  • Sets a property that CoreAudio uses to determine how devices are synchronized. If an audio device can tell that it is synchronized to another engine, it should set this value to that engine's clock domain. If an audio device can be a clock master, it may publish its own clock domain for other devices to use.

    Declaration

    C++

    virtual void setClockDomain( UInt32 clockDomain = clockDomain);

    Parameters

    clockDomain

    is the unique ID of another engine that this engine realizes it is synchronized to, use the default value kIOAudioNewClockDomain to have IOAudioEngine create a unique clock domain.

    Import Statement

  • This function sets a flag that CoreAudio uses to select its sample rate tracking algorithm. Set this to TRUE unless that results in dropped audio. If the driver is experiencing unexplained dropouts setting this FALSE might help.

    Declaration

    C++

    virtual void setClockIsStable( boolclockIsStable);

    Parameters

    clockIsStable

    TRUE tells CoreAudio to use an agressive PLL to quickly lock to the engine's sample rate while FALSE tells CoreAudio to adjust more slowly to perceived sample rate changes that might just be the result of an unstable clock.

    Import Statement

  • set the offset CoreAudio will read from off the current read pointer

    Declaration

    C++

    virtual void setInputSampleOffset( UInt32numSamples);

    Parameters

    numSamples

    size of offset in sample

    Import Statement

  • Used to tell IOAudioFamily when the watchdog timer must fire by.

    Declaration

    C++

    virtual void setMixClipOverhead( UInt32newMixClipOverhead);

    Parameters

    newMixClipOverhead

    How much time per buffer should be made available for the mix and clip routines to run. Valid values are 1 through 99, inclusive.

    Return Value

    return no error

    Discussion

    setMixClipOverhead allows an audio engine to tell IOAudioFamily how much time an engine will take to mix and clip its samples, in percent. The default value is 10, meaning 10%. This will cause IOAudioFamily to make the watchdog timer fire when there is just over 10% of the time to complete a buffer set left (e.g. 51 samples when the HAL is using a buffer size of 512 samples).

    Import Statement

  • set the offset CoreAudio will write at off the current write pointer

    Declaration

    C++

    virtual void setOutputSampleOffset( UInt32numSamples);

    Parameters

    numSamples

    size of offset in sample

    Import Statement

  • Tells the audio engine whether or not to run the erase head.

    Declaration

    C++

    virtual void setRunEraseHead( boolrunEraseHead);

    Parameters

    runEraseHead

    The audio engine will run the erase head if this value is true.

    Discussion

    By default, output audio engines run the erase head and input audio engines do not. This method can be called after setDirection() is called in order to change the default behavior.

    Import Statement

  • Sets the sample latency for the audio engine.

    Declaration

    C++

    virtual void setSampleLatency( UInt32 numSamples);

    Discussion

    The sample latency represents the number of samples ahead of the playback head that it is safe to write into the sample buffer. The audio device API will never write closer to the playback head than the number of samples specified. For input audio engines the number of samples is behind the record head.

    Import Statement

  • Records the sample rate of the audio engine.

    Declaration

    C++

    virtual void setSampleRate( const IOAudioSampleRate *newSampleRate);

    Parameters

    newSampleRate

    The sample rate of the audio engine in samples per second.

    Discussion

    This method must be called during initialization of a new audio engine to record the audio engine's initial sample rate. It also is intended to be used to record changes to the sample rate during use. Currently changing sample rates after the audio engine has been started is not supported. It may require that the sample buffers be re-sized. This will be available in an upcoming release.

    Import Statement

  • Indicates that the audio engine is in the specified state.

    Declaration

    C++

    virtual IOAudioEngineState setState( IOAudioEngineStatenewState);

    Parameters

    newState

    The state the audio engine is in.

    Return Value

    Returns the old state.

    Discussion

    This method simply sets the internal state of the audio engine to the specified state. It does not affect a change to the state. It does however keep other internal state-related attributes consistent. For example, it enables or disables the timer as needed when the state changes to running or stopped.

    Import Statement

  • A simple cover function for start(IOService *, IOAudioDevice *) that assumes the provider is the IOAudioDevice.

    Declaration

    C++

    virtual bool start( IOService *provider);

    Parameters

    provider

    The service provider for the IOAudioEngine (the IOAudioDevice in this case).

    Return Value

    Returns true if the IOAudioEngine was successfully started.

    Discussion

    Subclasses will want to override start(IOService *, IOAudioDevice *) rather than this one.

    Import Statement

  • Standard IOKit start() routine called to start an IOService.

    Declaration

    C++

    virtual bool start( IOService *provider, IOAudioDevice *device);

    Parameters

    provider

    The service provider for the IOAudioEngine.

    device

    The IOAudioDevice to which this IOAudioEngine belongs.

    Return Value

    Returns true if the service was successfully started.

    Discussion

    This function is called in order to prepare the IOAudioEngine for use. It does NOT mean that the audio I/O engine itself should be started. This implementation gets the IOWorkLoop from the IOAudioDevice and allocates an IOCommandGate. Finally it calls initHardware() in which all of the subclass-specific device initialization should be done. Upon return from initHardware() all IOAudioStreams should be created and added to the audio engine. Also, all IOAudioControls for this IOAudioEngine should be created and attached.

    Import Statement

  • Starts the audio I/O engine.

    Declaration

    C++

    virtual IOReturn startAudioEngine();

    Return Value

    Must return kIOReturnSuccess on a successful start of the engine.

    Discussion

    This method is called automatically when the audio engine is placed into use the first time. This must be overridden by the subclass. No call to the superclass's implementation is necessary. The subclass's implementation must start up the audio I/O engine. This includes any audio engine that needs to be started as well as any interrupts that need to be enabled. Upon successfully starting the engine, the subclass's implementation must call setState(kIOAudioEngineRunning). If it has also checked the state using getState() earlier in the implementation, the stateLock must be acquired for the entire initialization process (using IORecursiveLockLock(stateLock) and IORecursiveLockUnlock(stateLock)) to ensure that the state remains consistent. See the general class comments for an example.

    Import Statement

  • Stops the service and prepares for the driver to be terminated.

    Declaration

    C++

    virtual void stop( IOService *provider);

    Parameters

    provider

    The service provider for the IOAudioEngine.

    Discussion

    This function is called before the driver is terminated and usually means that the device has been removed from the system.

    Import Statement

  • Stops the audio I/O engine.

    Declaration

    C++

    virtual IOReturn stopAudioEngine();

    Return Value

    Must return kIOReturnSuccess on a successful stop of the engine.

    Discussion

    This method is called automatically when the last client disconnects from this audio engine. It must be overridden by the subclass. No call to the superclass's implementation is necessary. The subclass's implementation must stop the audio I/O engine. The audio engine (if it exists) should be stopped and any interrupts disabled. Upon successfully stopping the engine, the subclass must call setState(kAudioEngineStopped). If it has also checked the state using getState() earlier in the implementation, the stateLock must be acquired for the entire initialization process (using IORecursiveLockLock(stateLock) and IORecursiveLockUnlock(stateLock)) to ensure that the state remains consistent.

    Import Statement

  • A static method used as a callback for the IOAudioDevice timer services.

    Declaration

    C++

    static void timerCallback( OSObject *arg1, IOAudioDevice *device);

    Parameters

    arg1

    The IOAudioEngine that is the target of the event.

    device

    The IOAudioDevice that sent the timer event.

    Discussion

    This method implements the IOAudioDevice::TimerEvent type.

    Import Statement

  • Indicates the timer has fired.

    Declaration

    C++

    virtual void timerFired();

    Discussion

    This method is called by timerCallback to indicate the timer has fired. This method calls performErase() and performFlush() to do erase head processing and audio engine flushing each time the timer event fires.

    Import Statement

Constants

  • gSampleRateWholeNumberKey

    gSampleRateWholeNumberKey

    Available in OS X v10.1 through OS X v10.5.

  • gSampleRateFractionKey

    gSampleRateFractionKey

    Available in OS X v10.1 through OS X v10.5.

  • Instance Variables

    • The IOWorkLoop for the audio driver - shared with the IOAudioDevice.

      Declaration

      C++

      IOWorkLoop *workLoop;

    • An OSSet of all of the currently connected user clients.

      Declaration

      C++

      OSSet *userClients;

    • Status struct shared with the CoreAudio.framework.

      Declaration

      C++

      IOAudioEngineStatus * status;

    • The current state of the IOAudioEngine - running, stopped, paused.

      Declaration

      C++

      IOAudioEngineState state;

    • The current sample rate of the audio engine in samples per second.

      Declaration

      C++

      IOAudioSampleRate sampleRate;

    • Set to true if the erase head is to run when the audio engine is running. This is the case if there are any output streams.

      Declaration

      C++

      bool runEraseHead;

    • An OSSet of all of the output IOAudioStreams attached to this IOAudioEngine.

      Declaration

      C++

      OSOrderedSet *outputStreams;

    • Declaration

      C++

      UInt32 numSampleFramesPerBuffer;

    • The number of times the erase head get scheduled to run for each cycle of the audio engine.

      Declaration

      C++

      UInt32 numErasesPerBuffer;

    • A total of the active user clients - those that are currently playing or recording audio.

      Declaration

      C++

      UInt32 numActiveUserClients;

    • Internal state variable to keep track or whether registerService() has been called.

      Declaration

      C++

      bool isRegistered;

    • An OSSet of all of the input IOAudioStreams attached to this IOAudioEngine.

      Declaration

      C++

      OSOrderedSet *inputStreams;

    • Used by the IOAudioDevice to determine responsibility for shutting the audio engine down when it is no longer needed.

      Declaration

      C++

      bool deviceStartedAudioEngine;

    • All of the IOAudioControls that affect this audio engine.

      Declaration

      C++

      OSSet *defaultAudioControls;

    • Set to true after beginConfigurationChange() and false upon a subsequent call to completeConfigurationChange() or cancelConfigurationChange().

      Declaration

      C++

      bool configurationChangeInProgress;

    • The IOCommandGate for this audio engine - attached to the driver's IOWorkLoop.

      Declaration

      C++

      IOCommandGate *commandGate;

    • When all clients have disconnected, this is set to one buffer length past the current audio engine position at the time. Then when the stop position is reached, the audio engine is stopped

      Declaration

      C++

      IOAudioEnginePosition audioEngineStopPosition;

    • The IOAudioDevice instance to which the IOAudioEngine belongs.

      Declaration

      C++

      IOAudioDevice * audioDevice;