|
ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference
|
IOAudioEngine |
| Inherits from: | |
| Declared In: |
Abstract base class for a single audio audio / I/O engine.
An IOAudioEngine is defined by a single I/O engine to transfer data to or from one or more sample buffers. Each sample buffer is represented by a single IOAudioStream instance. A single IOAudioEngine must contain at least one IOAudioStream, but has no upper limit on the number of IOAudioStreams it may contain. An IOAudioEngine instance may contain both input and output IOAudioStreams.
An audio driver must subclass IOAudioEngine in order to provide certain services. An IOAudioEngine subclass must start and stop the I/O engine when requested. The I/O engine should be continuously running and loop around from end to beginning. While the audio engine is running, it must take a timestamp as the sample buffer(s) wrap around and start at the beginning. The CoreAudio.framework uses the timestamp to calculate the exact position of the audio engine. An IOAudioEngine subclass must implement getCurrentSampleFrame() to provide a sample position on demand. Finally, an IOAudioEngine subclass must provide clipping and format conversion routines to go to/from the CoreAudio.framework's native float format.
If multiple stream formats or sample rates are allowed, the IOAudioEngine subclass must provide support for changing the hardware when a format or sample rate is changed.
There are several attributes associated with a single IOAudioEngine:
The IOAudioEngine superclass provides a shared status buffer that contains all of the dynamic pieces of information about the audio engine (type IOAudioEngineStatus). It runs an erase process on all of the output streams. The erase head is used to zero out the mix and sample buffers after the samples have been played. Additionally, the IOAudioEngine superclass handles the communication with the CoreAudio.framework and makes the decision to start and stop the audio engine when it detects it is in use.
In order for an audio device to play back or record sound, an IOAudioEngine subclass must be created. The subclass must initialize all of the necessary hardware resources to prepare for starting the audio I/O engine. It typically will perform these tasks in the initHardware() method. A subclass may also implement a stop() method which is called as the driver is being torn down. This is typically called in preparation of removing the device from the system for removable devices.
In addition to initializing the necessary hardware, there are a number of other tasks an IOAudioEngine must do during initHardware(). It must create the necessary IOAudioStream objects to match the device capabilities. Each IOAudioStream must be added using addAudioStream(). It also should create the IOAudioControls needed to control the various attributes of the audio engine: output volume, mute, input gain, input selection, analog passthru. To do that, addDefaultAudioControl() should be called with each IOAudioControl to be attached to the IOAudioEngine. In order to provide for proper synchronization, the latency of the audio engine should be specified with setSampleLatency(). This value represents the latency between the timestamp taken at the beginning of the buffer and when the audio is actually played (or recorded) by the device. If a device is block based or if there is a need to keep the CoreAudio.framework a certain number of samples ahead of (or behind for input) the I/O head, that value should be specified using setSampleOffset(). If this is not specified the CoreAudio.framework may attempt to get as close to the I/O head as possible.
The following fields in the shared IOAudioEngineStatus struct must be maintained by the subclass implementation:
fCurrentLoopCount - the number of times the sample buffer has wrapped around to the beginning fLastLoopTime - timestamp of the most recent time that the I/O engine looped back to the beginning of the sample buffer
It is critically important that the fLastLoopTime field be as accurate as possible. It is the basis for the entire timer and synchronization mechanism used by the audio system.
At init time, the IOAudioEngine subclass must call setNumSampleFramesPerBuffer() to indicate how large each of the sample buffers are (measured in sample frames). Within a single IOAudioEngine, all sample buffers must be the same size and be running at the same sample rate. If different buffers/streams can be run at different rates, separate IOAudioEngines should be used. The IOAudioEngine subclass must also call setSampleRate() at init time to indicate the starting sample rate of the device.
Adds an IOAudioStream to the audio engine.
Enables the timer event for the audio engine.
Zeros out all of the sample and mix buffers associated with the IOAudioEngine
Called automatically when a user client closes its connection to the audio engine.
Clip output samples and convert to hardware format.
Convert input samples from hardware format to 32-bit float.
Override this method if you want to return a different number of sample frames than was requested.
Override this method if you want to return a different number of sample frames than was requested.
Generates a dictionary matching the given sample rate.
Generates a sample rate from an OSDictionary.
This function allows for the actual erasing of the mix and sample buffer to be overridden by a child class.
Frees all of the resources allocated by the IOAudioEngine.
Returns the IOCommandGate for this IOAudioEngine.
Gets the current sample frame from the IOAudioEngine subclass.
Returns true if the audio engine will run the erase head when the audio engine is running.
Returns the sample rate of the IOAudioEngine in samples per second.
Returns the current state of the IOAudioEngine.
Returns a pointer to the shared status buffer.
Gets the timer interval for use by the timer event.
Returns the IOWorkLoop for the driver.
Performs initialization of a newly allocated IOAudioEngine.
This function is called by start() to provide a convenient place for the subclass to perform its hardware initialization.
Generates the OSSymbols with the keys.
Requests a new user client object for this service.
Called to start the audio I/O engine
Called to stop the audio I/O engine
Performs erase head processing.
Performs the flush operation.
Called when this audio engine is ready to begin vending services.
Disables the timer event for the audio engine.
Resets the status buffer to its default values.
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.
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.
Sets the offset CoreAudio will read from off the current read pointer
set the offset CoreAudio will read from off the current read pointer
Used to tell IOAudioFamily when the watchdog timer must fire by.
Sets the offset CoreAudio will write at off the current write pointer
set the offset CoreAudio will write at off the current write pointer
Tells the audio engine whether or not to run the erase head.
Sets the sample latency for the audio engine.
Records the sample rate of the audio engine.
Indicates that the audio engine is in the specified state.
A simple cover function for start(IOService *, IOAudioDevice *) that assumes the provider is the IOAudioDevice.
Standard IOKit start() routine called to start an IOService
Starts the audio I/O engine.
Stops the service and prepares for the driver to be terminated.
Stops the audio I/O engine.
A static method used as a callback for the IOAudioDevice timer services.
Indicates the timer has fired.
addAudioStream |
Adds an IOAudioStream to the audio engine.
public
virtual IOReturn addAudioStream( IOAudioStream *stream);
streamThe IOAudioStream to be added.
Returns kIOReturnSuccess if the stream was successfully added.
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.
addTimer |
Enables the timer event for the audio engine.
protected
virtual void addTimer();
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.
clearAllSampleBuffers |
Zeros out all of the sample and mix buffers associated with the IOAudioEngine
public
virtual void clearAllSampleBuffers();
This is called during resumeAudioEngine() since the audio engine gets started back at the beginning of the sample buffer.
clientClosed |
Called automatically when a user client closes its connection to the audio engine.
protected
virtual void clientClosed( IOAudioEngineUserClient *client);
clientThe user client that has disconnected.
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.
clipOutputSamples |
Clip output samples and convert to hardware format.
public
virtual IOReturn clipOutputSamples( const void *mixBuf, void *sampleBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);
This method clips output samples to +/- 1.0 (float) and converts them to the correct format for the hardware sample buffer. You must override this method in a device-specific audio engine subclass.
convertInputSamples |
Convert input samples from hardware format to 32-bit float.
public
virtual IOReturn convertInputSamples( const void *sampleBuf, void *destBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);
The convertInputSamples function converts input samples from a hardware-specific format to 32-bit floating point. Your device-specific subclass must override this method.
convertInputSamplesVBR(const void *, void *, UInt32, UInt32 &, const IOAudioStreamFormat *, IOAudioStream *) |
Override this method if you want to return a different number of sample frames than was requested.
public
virtual IOReturn convertInputSamplesVBR( const void *sampleBuf, void *destBuf, UInt32 firstSampleFrame, UInt32 &numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);
convertInputSamplesVBR(const void *, void *, UInt32, UInt32 &, const IOAudioStreamFormat *, IOAudioStream *) |
Override this method if you want to return a different number of sample frames than was requested.
public
virtual IOReturn convertInputSamplesVBR( const void *sampleBuf, void *destBuf, UInt32 firstSampleFrame, UInt32 &numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);
createDictionaryFromSampleRate |
Generates a dictionary matching the given sample rate.
public
static OSDictionary *createDictionaryFromSampleRate( const IOAudioSampleRate *sampleRate, OSDictionary *rateDict = 0);
Returns the newly created OSDictionary.
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.
createSampleRateFromDictionary |
Generates a sample rate from an OSDictionary.
public
static IOAudioSampleRate *createSampleRateFromDictionary( const OSDictionary *rateDict, IOAudioSampleRate *sampleRate = 0);
Returns the sample rate.
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.
eraseOutputSamples |
This function allows for the actual erasing of the mix and sample buffer to be overridden by a child class.
public
virtual IOReturn eraseOutputSamples( const void *mixBuf, void *sampleBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream);
mixBufPointer to the IOAudioFamily allocated mix buffer.
sampleBufPointer to the child class' sample buffer.
firstSampleFrameIndex to the first sample frame to erase.
numSampleFramesNumber of sample frames to erase.
streamFormatFormat of the data to be erased.
audioStreamPointer to stream object that corresponds to the sample buffer being erased.
Must return kIOReturnSuccess if the samples have been erased.
free |
Frees all of the resources allocated by the IOAudioEngine.
public
virtual void free();
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.
getCommandGate |
Returns the IOCommandGate for this IOAudioEngine.
public
virtual IOCommandGate *getCommandGate() const;
getCurrentSampleFrame |
Gets the current sample frame from the IOAudioEngine subclass.
public
virtual UInt32 getCurrentSampleFrame() = 0;
getLoopCountAndTimeStamp |
public
virtual IOReturn getLoopCountAndTimeStamp( UInt32 *loopCount, AbsoluteTime *timestamp);
This method returns the current loop count and time stamp values.
getNumSampleFramesPerBuffer |
protected
virtual UInt32 getNumSampleFramesPerBuffer();
This method returns the size of the sample buffer (in terms of the number of frames).
getRunEraseHead |
Returns true if the audio engine will run the erase head when the audio engine is running.
public
virtual bool getRunEraseHead();
getSampleRate |
Returns the sample rate of the IOAudioEngine in samples per second.
public
virtual const IOAudioSampleRate *getSampleRate();
getState |
Returns the current state of the IOAudioEngine.
public
virtual IOAudioEngineState getState();
The current state of the IOAudioEngine: kIOAudioEngineRunning, kIOAudioEngineStopped.
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.
getStatus |
Returns a pointer to the shared status buffer.
public
virtual const IOAudioEngineStatus *getStatus();
getTimerInterval |
Gets the timer interval for use by the timer event.
public
virtual AbsoluteTime getTimerInterval();
Returns the interval for the timer event.
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.
getWorkLoop |
Returns the IOWorkLoop for the driver.
public
virtual IOWorkLoop *getWorkLoop() const;
init |
Performs initialization of a newly allocated IOAudioEngine.
public
virtual bool init( OSDictionary *properties);
propertiesThe default properties for the IOAudioEngine.
Returns true if initialization was successful.
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.
initHardware |
This function is called by start() to provide a convenient place for the subclass to perform its hardware initialization.
public
virtual bool initHardware( IOService *provider);
providerThe service provider nub for this audio engine - typically the IOAudioDevice.
Returns true if the hardware was successfully initialized.
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.
initKeys |
Generates the OSSymbols with the keys.
protected
static void initKeys();
Do not call this directly. This is an internal initialization routine.
newUserClient |
Requests a new user client object for this service.
public
virtual IOReturn newUserClient( task_t task, void *securityID, UInt32 type, IOUserClient **handler);
taskThe task requesting the new user client.
securityIDOptional security parameter passed in by the client - ignored.
typeOptional user client type passed in by the client - ignored.
handlerThe new IOUserClient * must be stored in this param on a successful completion.
Returns kIOReturnSuccess on success. May also return kIOReturnError or kIOReturnNoMemory.
This function is called automatically by the 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.
performAudioEngineStart |
Called to start the audio I/O engine
public
virtual IOReturn performAudioEngineStart();
Must return kIOReturnSuccess on a successful start of the engine.
This method is called by startAudioEngine() when the audio engine is placed into use. 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(kAudioEngineRunning). 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.
performAudioEngineStop |
Called to stop the audio I/O engine
public
virtual IOReturn performAudioEngineStop();
Must return kIOReturnSuccess on a successful stop of the engine.
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.
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.
performErase |
Performs erase head processing.
public
virtual void performErase();
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.
performFlush |
Performs the flush operation.
public
virtual void performFlush();
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.
performFormatChange(IOAudioStream *, const IOAudioStreamFormat *, const IOAudioSampleRate *) |
public
virtual IOReturn performFormatChange( IOAudioStream *audioStream, const IOAudioStreamFormat *newFormat, const IOAudioSampleRate *newSampleRate);
This method changes the sample format for the audio device.
performFormatChange(IOAudioStream *, const IOAudioStreamFormat *, const IOAudioStreamFormatExtension *, const IOAudioSampleRate *) |
public
virtual IOReturn performFormatChange( IOAudioStream *audioStream, const IOAudioStreamFormat *newFormat, const IOAudioStreamFormatExtension *formatExtension, const IOAudioSampleRate *newSampleRate);
This method changes the sample format for the audio device with a format extension (optional).
registerService |
Called when this audio engine is ready to begin vending services.
public
virtual void registerService( IOOptionBits options = 0);
optionsThis function is called by IOAudioDevice::activateAudioEngine() once the audio engine has been fully initialized and is ready to begin audio playback.
removeTimer |
Disables the timer event for the audio engine.
protected
virtual void removeTimer();
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.
resetStatusBuffer |
Resets the status buffer to its default values.
public
virtual void resetStatusBuffer();
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.
setClockDomain |
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.
public
virtual void setClockDomain( UInt32 clockDomain = kIOAudioNewClockDomain);
clockDomainis 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.
setClockIsStable |
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.
public
virtual void setClockIsStable( bool clockIsStable);
clockIsStableTRUE 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.
setDescription |
public
virtual void setDescription( const char *description);
This function should be called to make the name of the I/O engine available to Audio HAL clients.
setInputSampleLatency |
protected
virtual void setInputSampleLatency( UInt32 numSamples);
Sets the sample latency for an audio engine's input streams.
setInputSampleOffset(UInt32) |
Sets the offset CoreAudio will read from off the current read pointer
public
virtual void setInputSampleOffset( UInt32 numSamples);
numSamplessize of offset in sample
setInputSampleOffset(UInt32) |
set the offset CoreAudio will read from off the current read pointer
public
virtual void setInputSampleOffset( UInt32 numSamples);
numSamplessize of offset in sample
setMixClipOverhead |
Used to tell IOAudioFamily when the watchdog timer must fire by.
public
virtual void setMixClipOverhead( UInt32 newMixClipOverhead);
newMixClipOverheadHow much time per buffer should be made available for the mix and clip routines to run. Valid values are 1 through 99, inclusive.
return no error
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).
setNumSampleFramesPerBuffer |
protected
virtual void setNumSampleFramesPerBuffer( UInt32 numSampleFrames);
This method should be called on subclass initialization to indicate the size of the sample buffer (in terms of the number of frames).
setOutputSampleLatency |
protected
virtual void setOutputSampleLatency( UInt32 numSamples);
Sets the sample latency for an audio engine's output streams.
setOutputSampleOffset(UInt32) |
Sets the offset CoreAudio will write at off the current write pointer
public
virtual void setOutputSampleOffset( UInt32 numSamples);
numSamplessize of offset in sample
setOutputSampleOffset(UInt32) |
set the offset CoreAudio will write at off the current write pointer
public
virtual void setOutputSampleOffset( UInt32 numSamples);
numSamplessize of offset in sample
setRunEraseHead |
Tells the audio engine whether or not to run the erase head.
protected
virtual void setRunEraseHead( bool runEraseHead);
runEraseHeadThe audio engine will run the erase head if this value is true.
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.
setSampleLatency |
Sets the sample latency for the audio engine.
protected
virtual void setSampleLatency( UInt32 numSamples);
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.
setSampleOffset |
protected
virtual void setSampleOffset( UInt32 numSamples);
Sets the sample offet for an audio engine.
setSampleRate |
Records the sample rate of the audio engine.
protected
virtual void setSampleRate( const IOAudioSampleRate *newSampleRate);
newSampleRateThe sample rate of the audio engine in samples per second.
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.
setState |
Indicates that the audio engine is in the specified state.
protected
virtual IOAudioEngineState setState( IOAudioEngineState newState);
newStateThe state the audio engine is in.
Returns the old state.
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.
start(IOService *) |
A simple cover function for start(IOService *, IOAudioDevice *) that assumes the provider is the IOAudioDevice.
public
virtual bool start( IOService *provider);
providerThe service provider for the IOAudioEngine (the IOAudioDevice in this case).
Returns true if the IOAudioEngine was successfully started.
Subclasses will want to override start(IOService *, IOAudioDevice *) rather than this one.
start(IOService *, IOAudioDevice *) |
Standard IOKit start() routine called to start an IOService
public
virtual bool start( IOService *provider, IOAudioDevice *device);
providerThe service provider for the IOAudioEngine.
deviceThe IOAudioDevice to which this IOAudioEngine belongs.
Returns true if the service was successfully started.
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.
startAudioEngine |
Starts the audio I/O engine.
public
virtual IOReturn startAudioEngine();
Must return kIOReturnSuccess on a successful start of the engine.
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.
stop |
Stops the service and prepares for the driver to be terminated.
public
virtual void stop( IOService *provider);
providerThe service provider for the IOAudioEngine.
This function is called before the driver is terminated and usually means that the device has been removed from the system.
stopAudioEngine |
Stops the audio I/O engine.
public
virtual IOReturn stopAudioEngine();
Must return kIOReturnSuccess on a successful stop of the engine.
This method is called automatically when the last client disconnects from this audio engine.
This method calls performAudioEngineStop, which you must override in your
subclass.
takeTimeStamp |
public
virtual void takeTimeStamp( bool incrementLoopCount = true, AbsoluteTime *timestamp = NULL);
Takes a time stamp. This function should be called each time the ring buffer wraps around. The optional
timestamp argument can be used to specify a time other than the current time. This can be
used in cases where the ring buffer has wrapped around at some time in the past and the actual time stamp
must be calculated or determined through other means.
timerCallback |
A static method used as a callback for the IOAudioDevice timer services.
public
static void timerCallback( OSObject *arg1, IOAudioDevice *device);
arg1The IOAudioEngine that is the target of the event.
deviceThe IOAudioDevice that sent the timer event.
This method implements the IOAudioDevice::TimerEvent type.
timerFired |
Indicates the timer has fired.
public
virtual void timerFired();
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.
audioDevice |
public
IOAudioDevice * audioDevice;
The IOAudioDevice instance to which the IOAudioEngine belongs.
audioEngineStopPosition |
public
IOAudioEnginePosition audioEngineStopPosition;
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
commandGate |
public
IOCommandGate *commandGate;
The IOCommandGate for this audio engine - attached to the driver's IOWorkLoop.
configurationChangeInProgress |
public
bool configurationChangeInProgress;
Set to true after beginConfigurationChange() and false upon a subsequent call to completeConfigurationChange() or cancelConfigurationChange().
defaultAudioControls |
public
OSSet *defaultAudioControls;
All of the IOAudioControls that affect this audio engine.
deviceStartedAudioEngine |
protected
bool deviceStartedAudioEngine;
Used by the IOAudioDevice to determine responsibility for shutting the audio engine down when it is no longer needed.
gSampleRateFractionKey |
public
static const OSSymbol *gSampleRateFractionKey;
gSampleRateWholeNumberKey |
public
static const OSSymbol *gSampleRateWholeNumberKey;
inputStreams |
public
OSOrderedSet *inputStreams;
An OSSet of all of the input IOAudioStreams attached to this IOAudioEngine.
isRegistered |
public
bool isRegistered;
Internal state variable to keep track or whether registerService() has been called.
numActiveUserClients |
public
UInt32 numActiveUserClients;
A total of the active user clients - those that are currently playing or recording audio.
numErasesPerBuffer |
public
UInt32 numErasesPerBuffer;
The number of times the erase head get scheduled to run for each cycle of the audio engine.
numSampleFramesPerBuffer |
public
UInt32 numSampleFramesPerBuffer;
outputStreams |
public
OSOrderedSet *outputStreams;
An OSSet of all of the output IOAudioStreams attached to this IOAudioEngine.
runEraseHead |
public
bool runEraseHead;
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.
sampleRate |
public
IOAudioSampleRate sampleRate;
The current sample rate of the audio engine in samples per second.
state |
public
IOAudioEngineState state;
The current state of the IOAudioEngine - running, stopped, paused.
status |
public
IOAudioEngineStatus * status;
Status struct shared with the CoreAudio.framework.
userClients |
public
OSSet *userClients;
An OSSet of all of the currently connected user clients.
workLoop |
public
IOWorkLoop *workLoop;
The IOWorkLoop for the audio driver - shared with the IOAudioDevice.
|
Last Updated: 2008-12-19