Container for Microsoft Windows device specific output driver. More...

#include <MpodWinMM.h>

Inheritance diagram for MpodWinMM:

Collaboration diagram for MpodWinMM:

Classes
class	MpWinOutputAudioDeviceNotifier

class	WinAudioData
	Structure used to pass WMM message data to processing thread. More...

Public Member Functions
Creators
	MpodWinMM (const UtlString &name, MpOutputDeviceManager *outputManger, unsigned nOutputBuffers=DEFAULT_N_OUTPUT_BUFS)
	Default constructor. More...

	~MpodWinMM ()
	Destructor. More...

Manipulators
OsStatus	enableDevice (unsigned samplesPerFrame, unsigned samplesPerSec, MpFrameTime currentFrameTime, OsCallback &frameTicker)

OsStatus	disableDevice ()
	Uninitialize device driver. More...

OsStatus	pushFrame (unsigned int numSamples, const MpAudioSample *samples, MpFrameTime frameTime)
	Send data to output device. More...

OsStatus	switchToMMTimer ()
	Switch to use MMTimer for Media subsystem ticks instead of output device. More...

virtual OsStatus	signal (const intptr_t eventData)
	callback used by MpMMTimer when output device is not providing ticks More...

Inquiry
UtlBoolean	isDeviceValid ()
	Inquire if the windows device is valid. More...

Public Member Functions inherited from MpOutputDeviceDriver
	MpOutputDeviceDriver (const UtlString &name)
	Default constructor. More...

virtual	~MpOutputDeviceDriver ()
	Destructor. More...

MpFrameTime	getFramePeriod () const
	Calculate the number of milliseconds that a frame occupies in time. More...

unsigned	getSamplesPerFrame () const
	Get number of samples in a frame. More...

unsigned	getSamplesPerSec () const
	Get number of samples per second. More...

const UtlString &	getDeviceName () const
	Get device name. More...

virtual OsStatus	canEnable ()
	Check if this device can connect. More...

virtual UtlBoolean	isEnabled () const
	Inquire if this driver is enabled. More...

Static Public Member Functions
Accessors
static UtlString	getDefaultDeviceName ()
	get the windows name of the default wave output device. More...

Static Public Member Functions inherited from MpOutputDeviceDriver
static MpFrameTime	getFramePeriod (unsigned samplesPerFrame, unsigned samplesPerSec)
	Calculate the number of milliseconds that a frame occupies in time. More...

Protected Member Functions
WAVEHDR *	initWaveHeader (int n)
	Zero out a wave header, so it is ready to be filled in by us. More...

void	finalizeProcessedHeader (WAVEHDR *pWaveHdr)
	Adds a header/buffer to the empty header list and notifies for a new frame. More...

OsStatus	internalPushFrame (unsigned int numSamples, const MpAudioSample *samples, MpFrameTime frameTime)
	internal method to handle final writing of audio to the output device More...

Static Protected Member Functions
static void CALLBACK	waveOutCallbackStatic (HWAVEOUT hwo, UINT uMsg, void dwInstance, void dwParam1, void *dwParam2)
	callback used by wave output multimedia interface More...

Protected Attributes
MpOutputDeviceManager *	mpOutputManger
	output manager this device will belong to. More...

OsMutex	mEmptyHdrVPtrListsMutex
	Mutex to serialize access to vptr and empty header lists. More...

int	mWinMMDeviceId

HWAVEOUT	mDevHandle
	The Microsoft handle for this audio input device. More...

MpFrameTime	mCurFrameTime
	The current frame time for this device. More...

unsigned	mNumOutBuffers

unsigned	mWaveBufSize

WAVEHDR *	mpWaveHeaders
	Array of nNumInBuffers wave headers. More...

LPSTR *	mpWaveBuffers
	Array of nNumInBuffers wave buffers. More...

UtlSList	mEmptyHeaderList

UtlSList	mUnusedVPtrList

int	mUnderrunLength
	Length of underrun, taking place now (in frames). More...

DWORD	mTotSampleCount
	A count of the samples coming in via pushFrame. More...

IMMNotificationClient *	mWinAudioDeviceChangeCallback
	device state changes. More...

IMMDeviceEnumerator *	mDeviceEnumeratorPtr

HANDLE	mCallbackThread
	Handle of thread which processes WMM messages. More...

HANDLE	mCallbackEvent
	Event to signal that WMM message is available for processing. More...

OsAtomicLightBool	mExitFlag
	Should processing thread finish its execution? More...

MpMMTimer *	mpTickerTimer

UtlSList	mListSignaled
	Queue of WMM messages signaled for processing. More...

UtlSList	mListFree
	Pool of WMM messages. More...

Protected Attributes inherited from MpOutputDeviceDriver
OsAtomicLightBool	mIsEnabled
	Whether this device driver is enabled or not. More...

OsAtomicLightUInt	mSamplesPerFrame
	number of samples. More...

OsAtomicLightUInt	mSamplesPerSec
	of samples per second. More...

OsCallback *	mpTickerNotification
	is ready to accept more data. See enableDevice() for details. More...

Private Member Functions
	MpodWinMM (const MpodWinMM &rMpodWinMM)
	Copy constructor (not implemented for this class) More...

MpodWinMM &	operator= (const MpodWinMM &rhs)
	Assignment operator (not implemented for this class) More...

OsStatus	resetDevice ()

Static Private Member Functions
static DWORD WINAPI	ThreadMMProc (LPVOID lpMessage)
	WMM messages processing thread. More...

Detailed Description

Container for Microsoft Windows device specific output driver.

The MpOutputDeviceDriver is the class for the Microsoft Windows output media driver wrapper implementation. An instance of MpodWinMM is created for every physical or logical output device (e.g. speaker).

Note: If stuttering occurs from this device driver, one can tweak the LOW_WAVEBUF_LVL value in MpodWinMM.cpp, but keep in mind increasing this directly increases latency in this device driver.

Todo:: With the current model of operation we should use events as callback mechanism in waveOutOpen, because now we use callback function from whic we set event by hands. This looks like a bit of overhead, while we can use events directly.

See also: MpOutputDeviceDriver

Constructor & Destructor Documentation

MpodWinMM	(	const UtlString &	name,
		MpOutputDeviceManager *	outputManger,
		unsigned	nOutputBuffers = `DEFAULT_N_OUTPUT_BUFS`
	)

explicit

Default constructor.

Parameters

[in]	name	- unique windows device driver name (e.g. "YAMAHA AC-XG WDM Audio", etc.)
[in]	outputmanager	- pounter to the output manager this device will belong to.
[in]	nOutputBuffers	- The number of frame-sized buffers to have around for filling with data and passing to windows.

Note: nOutputBuffers does not directly determine the latency – this doesn't wait until all nOutputBuffers are full before passing on to windows, it just makes them available if we're passing frames faster than they're being output.

~MpodWinMM ( )

Destructor.

MpodWinMM ( const MpodWinMM & rMpodWinMM )

private

Copy constructor (not implemented for this class)

Member Function Documentation

OsStatus enableDevice	(	unsigned	samplesPerFrame,
		unsigned	samplesPerSec,
		MpFrameTime	currentFrameTime,
		OsCallback &	frameTicker
	)

virtual

Implements MpOutputDeviceDriver.

OsStatus disableDevice ( )

virtual

Uninitialize device driver.

This method disables the device driver and should release any platform device resources so that the device might be used else where.

this SHOULD NOT be used to mute/unmute a device. Disabling and enabling a device results in state and buffer queues being cleared.

This method is supposed to be used from MpAudioOutputConnection only. If you want disable device, use MpOutputDeviceManager or MpAudioOutputConnection methods.

Implements MpOutputDeviceDriver.

OsStatus pushFrame	(	unsigned int	numSamples,
		const MpAudioSample *	samples,
		MpFrameTime	frameTime
	)

virtual

Send data to output device.

This method is called from a callback which is called when we fire ticker notification. See enableDevice() for details.

Parameters

[in]	numSamples	- Number of samples in `samples` array.
[in]	samples	- Array of samples to push to device.
[in]	frameTime	- Time of pushed frame. Device may consider does it want it or not internally. If frame come too late driver should return OS_SUCCESS and throw out it silently. Common problem is when MediaTask queue is jammed - no frames are processed for some time and then they are processed bursty. Using given frameTime driver may keep its internal queue short. It is guaranteed that frame time would increase monotonically.

Returns: OS_LIMIT_REACHED if mixer buffer is full, i.e. frame come too early.; OS_FAILED for other errors.; OS_SUCCESS if frame sent correctly.

See also: enableDevice() for documentation when this is being called.

Implements MpOutputDeviceDriver.

OsStatus switchToMMTimer ( )

Switch to use MMTimer for Media subsystem ticks instead of output device.

OsStatus signal ( const intptr_t eventData )

virtual

callback used by MpMMTimer when output device is not providing ticks

UtlString getDefaultDeviceName ( )

static

get the windows name of the default wave output device.

UtlBoolean isDeviceValid ( )

inline

Inquire if the windows device is valid.

WAVEHDR * initWaveHeader ( int n )

protected

Zero out a wave header, so it is ready to be filled in by us.

Initialize all the values in the wave header indicated by n.

Parameters

[in] n - The index into mpWaveHeaders indicating which wave header to initialize.

Returns: a pointer to the wave header that was initialized.

void finalizeProcessedHeader ( WAVEHDR * pWaveHdr )

protected

Adds a header/buffer to the empty header list and notifies for a new frame.

This method, called from ThreadMMProc thread, adds a header/buffer to a list of empty headers so pushFrame() knows there are free buffers to fill and send to WMM, pumps silence if we are critically low, and sends a ticker notification to keep processing data.

Parameters

[in] pWaveHdr - Pointer to a wave header that windows is done with.

void CALLBACK waveOutCallbackStatic	(	HWAVEOUT	hwo,
		UINT	uMsg,
		void *	dwInstance,
		void *	dwParam1,
		void *	dwParam2
	)

staticprotected

callback used by wave output multimedia interface

This should only be called by the windows wave output multimedia.

OsStatus internalPushFrame	(	unsigned int	numSamples,
		const MpAudioSample *	samples,
		MpFrameTime	frameTime
	)

protected

internal method to handle final writing of audio to the output device

MpodWinMM& operator= ( const MpodWinMM & rhs )

private

Assignment operator (not implemented for this class)

DWORD WINAPI ThreadMMProc ( LPVOID lpMessage )

staticprivate

WMM messages processing thread.

All WMM messages are forwarded from static callback function to this thread and are actually processed here. This is done to avoid deadlocks, when other WMM functions are called from static callback functions.

OsStatus resetDevice ( )

private

Member Data Documentation

MpOutputDeviceManager* mpOutputManger

protected

output manager this device will belong to.

OsMutex mEmptyHdrVPtrListsMutex

protected

Mutex to serialize access to vptr and empty header lists.

int mWinMMDeviceId

protected

The underlying windows Device ID (not the logical Mp device ID)

HWAVEOUT mDevHandle

protected

The Microsoft handle for this audio input device.

MpFrameTime mCurFrameTime

protected

The current frame time for this device.

unsigned mNumOutBuffers

protected

The number of buffers to supply to windows for audio processing.

unsigned mWaveBufSize

protected

The size, in bytes, of mpWaveBuffer after allocation.

WAVEHDR* mpWaveHeaders

protected

Array of nNumInBuffers wave headers.

LPSTR* mpWaveBuffers

protected

Array of nNumInBuffers wave buffers.

UtlSList mEmptyHeaderList

protected

List of pointers to the mpWaveHeaders that are empty, waiting to be filled.

UtlSList mUnusedVPtrList

protected

List of unused UtlVoidPtrs. Used ones are in mEmptyHeaderList.

int mUnderrunLength

protected

Length of underrun, taking place now (in frames).

DWORD mTotSampleCount

protected

A count of the samples coming in via pushFrame.

IMMNotificationClient* mWinAudioDeviceChangeCallback

protected

device state changes.

Callback interface for audio

IMMDeviceEnumerator* mDeviceEnumeratorPtr

protected

HANDLE mCallbackThread

protected

Handle of thread which processes WMM messages.

HANDLE mCallbackEvent

protected

Event to signal that WMM message is available for processing.

OsAtomicLightBool mExitFlag

protected

Should processing thread finish its execution?

MpMMTimer* mpTickerTimer

protected

Optional timer to provide media subsystem ticks when output device is not working properly.

UtlSList mListSignaled

protected

Queue of WMM messages signaled for processing.

UtlSList mListFree

protected

Pool of WMM messages.

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation