Private container class for MpOutputDeviceDriver pointer and mixer buffer. More...

#include <MpAudioOutputConnection.h>

Inheritance diagram for MpAudioOutputConnection:

Collaboration diagram for MpAudioOutputConnection:

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

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

Private Attributes
OsMutex	mMutex
	Mutex to synchronize access to connection. More...

int	mUseCount
	Use counter, used to implement safe delete. More...

MpOutputDeviceDriver *	mpDeviceDriver
	connection. More...

MpFrameTime	mCurrentFrameTime
	Frame time of the mixer buffer begin. More...

unsigned	mMixerBufferLength
	Length of mixer buffer (in samples). More...

MpAudioSample *	mpMixerBuffer
	several media streams. More...

unsigned	mMixerBufferBegin
	Index of first available sample in mixer buffer. More...

OsCallback	readyForDataCallbackNotf

OsNotification *	mpFlowgraphTicker
	when it should process next frame. More...

Creators
	MpAudioOutputConnection (MpOutputDeviceHandle deviceId, MpOutputDeviceDriver *deviceDriver)
	Default constructor. More...

virtual	~MpAudioOutputConnection ()
	Destructor. More...

Manipulators
OsStatus	enableDevice (unsigned samplesPerFrame, unsigned samplesPerSec, MpFrameTime currentFrameTime, MpFrameTime mixerBufferLength)
	Initialize device driver and mixer buffer. More...

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

OsStatus	enableFlowgraphTicker (OsNotification *pFlowgraphTicker)
	Use this device to signal frame processing interval start. More...

OsStatus	disableFlowgraphTicker ()
	Stop using this device to signal frame processing interval start. More...

OsStatus	pushFrameBeginning (unsigned int numSamples, const MpAudioSample *samples, MpFrameTime &frameTime)
	Send data frame to the beginning of mixer buffer and return frame time. More...

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

unsigned	increaseUseCount ()
	Add one more reference to this connection. More...

unsigned	decreaseUseCount ()
	Remove one reference to this connection. More...

Accessors
MpOutputDeviceDriver *	getDeviceDriver () const
	Return device driver contained in this connection. More...

MpFrameTime	getMixerBufferLength () const
	Return length of mixer buffer in milliseconds. More...

unsigned	getUseCount () const
	Return number of external entities, referring to this connection. More...

unsigned	getSamplesPerFrame () const
	Return number of samples per frame, this driver expect from flowgraph. More...

MpFrameTime	getCurrentFrameTime () const

Mixer buffer methods
OsStatus	initMixerBuffer (unsigned mixerBufferLength)
	Allocate mixer buffer and initialize all related member variables. More...

OsStatus	freeMixerBuffer ()
	Free mixer buffer and set all related member variables to zero. More...

OsStatus	mixFrame (unsigned frameOffset, const MpAudioSample *samples, unsigned numSamples)
	Mix frame to mixer buffer. More...

OsStatus	isLateToMix (unsigned frameOffset, unsigned numSamples) const
	Check whether it's too late to mix this frame in or not (does not check for too early). More...

OsStatus	advanceMixerBuffer (unsigned numSamples)
	Pull frame from mixer buffer. More...

static void	readyForDataCallback (const intptr_t userData, const intptr_t eventData)
	Call this when driver become ready for the next frame. More...

Detailed Description

Private container class for MpOutputDeviceDriver pointer and mixer buffer.

All public methods of MpOutputDeviceDriver class are synchronized with internal mutex. This class also provide capability to implement safe delete. All external entities, accessing this class should call increaseUseCount() before accessing this class and call decreaseUseCount() after all access operations are finished. Entity, owning this object, should check use counter value before deleting with getUseCount() method and wait while it would not be equal to zero. Note, that calls to increaseUseCount(), decreaseUseCount() and getUseCount() should be synchronized by external entity, owning object of this class.

Constructor & Destructor Documentation

MpAudioOutputConnection	(	MpOutputDeviceHandle	deviceId,
		MpOutputDeviceDriver *	deviceDriver
	)

Default constructor.

Parameters

[in]	deviceId	- Device ID assigned to this connection.
[in]	deviceDriver	- Device driver, assigned with this connection.

~MpAudioOutputConnection ( )

virtual

Destructor.

MpAudioOutputConnection ( const MpAudioOutputConnection & rMpAudioOutputConnection )

private

Copy constructor (not implemented for this class)

Member Function Documentation

OsStatus enableDevice	(	unsigned	samplesPerFrame,
		unsigned	samplesPerSec,
		MpFrameTime	currentFrameTime,
		MpFrameTime	mixerBufferLength
	)

Initialize device driver and mixer buffer.

This method enables the device driver associated with this connection and create mixer buffer if requested.

Parameters

[in]	samplesPerFrame	- the number of samples in a frame of media
[in]	samplesPerSec	- sample rate for media frame in samples per second
[in]	currentFrameTime	- time in milliseconds for beginning of frame relative to the MpOutputDeviceManager reference time
[in]	mixerBufferLength	- length of mixer buffer in milliseconds.

Returns: OS_INVALID_STATE if device already enabled.; OS_SUCCESSS if device is successfully enabled.

See also: MpOutputDeviceDriver::enableDevice() for more information.; MpOutputDeviceManager constructor description for more information on mixer buffer length parameter.

OsStatus disableDevice ( )

Uninitialize device driver.

This method disables the device driver associated with this connection and free mixer buffer.

See also: MpOutputDeviceDriver::disableDevice() for more information.

OsStatus enableFlowgraphTicker ( OsNotification * pFlowgraphTicker )

Use this device to signal frame processing interval start.

Parameters

[in] pFlowgraphTicker - Ticker to signal for next frame processing interval.

Returns: OS_SUCCESS if ticker registered successfully.; OS_FAILED if device failed to register ticker.

OsStatus disableFlowgraphTicker ( )

Stop using this device to signal frame processing interval start.

Returns: OS_SUCCESS if ticker registered successfully.; OS_FAILED if device failed to unregister ticker.

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

Send data frame to the beginning of mixer buffer and return frame time.

This method is usually used only once when first frame is pushed. It pushes frame to the very beginning of the mixer buffer and return frame time of that position. Client should use this time to initialize his own frame time counter to use usual pushFrame() method.

See also: pushFrame() for more information.

Parameters

[in]	numSamples	- Number of samples in `samples` array.
[in]	samples	- Array of samples to push to device.
[out]	frameTime	- Time in milliseconds for beginning of frame relative to the MpOutputDeviceManager reference time.

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

Send data frame to output device.

This method is used to push a frame to the MpOutputDeviceManager to be buffered for a short window of time and mixed with data from other contributors.

This method is usually called from MpOutputDeviceManager::pushFrame().

Returns: OS_LIMIT_REACHED if mixer buffer is full, i.e. frame come too early.; OS_INVALID_STATE if frame come too late and was rejected. Frame considered late if whole frame does not fit into buffer, i.e. it would be rejected even if part of frame fit into buffer.; OS_FAILED for other errors.; OS_SUCCESS if frame sent correctly.

unsigned increaseUseCount ( )

inline

Add one more reference to this connection.

Every external entity which refer to this connection should increment use counter to prevent sudden deletion of connection, while it is still in use. Do not forget to decrement use counter when no more needed or connection will never be deleted.

Returns: Value of internal use counter after increment.

This function is NOT thread-safe. All manipulations with use counter must be synchronized by external entities.

See also: decreaseUseCount(), getUseCount()

unsigned decreaseUseCount ( )

inline

Remove one reference to this connection.

Returns: Value of internal use counter after decrement.

This function is NOT thread-safe. All manipulations with use counter must be synchronized by external entities.

See also: increaseUseCount(), getUseCount()

MpOutputDeviceDriver * getDeviceDriver ( ) const

inline

Return device driver contained in this connection.

MpFrameTime getMixerBufferLength ( ) const

inline

Return length of mixer buffer in milliseconds.

unsigned getUseCount ( ) const

inline

Return number of external entities, referring to this connection.

Returns: Value of internal use counter.

This function is NOT thread-safe. All manipulations with use counter must be synchronized by external entities.

See also: increaseUseCount(), decreaseUseCount()

unsigned getSamplesPerFrame ( ) const

inline

Return number of samples per frame, this driver expect from flowgraph.

MpFrameTime getCurrentFrameTime ( ) const

OsStatus initMixerBuffer ( unsigned mixerBufferLength )

protected

Allocate mixer buffer and initialize all related member variables.

Parameters

[in] mixerBufferLength - Number of samples in mixer buffer. This parameter must be greater then 0.

Not thread-safe. This function is supposed to be used from other (synchronized) functions.

OsStatus freeMixerBuffer ( )

protected

Free mixer buffer and set all related member variables to zero.

Not thread-safe. This function is supposed to be used from other (synchronized) functions.

Returns: OS_FAILED if mixer buffer is not allocated.

OsStatus mixFrame	(	unsigned	frameOffset,
		const MpAudioSample *	samples,
		unsigned	numSamples
	)

protected

Mix frame to mixer buffer.

Parameters

[in]	frameOffset	- Number of samples between the beginning of mixer buffer and the start of pushed frame.
[in]	samples	- Pointer to frame data.
[in]	numSamples	- Number of samples in frame.

Returns: OS_LIMIT_REACHED if mixer buffer is full.

Not thread-safe. This function is supposed to be used from other (synchronized) functions.

OsStatus isLateToMix	(	unsigned	frameOffset,
		unsigned	numSamples
	)		const

inlineprotected

Check whether it's too late to mix this frame in or not (does not check for too early).

Parameters

[in]	frameOffset	- Number of samples between the beginning of mixer buffer and the start of pushed frame.
[in]	numSamples	- Number of samples in frame.

Return values

OS_LIMIT_REACHED	if mixer buffer is full and it's too late mix this frame in.
OS_SUCCESS	if it's not yet too late.

Not thread-safe. This function is supposed to be used from other (synchronized) functions.

OsStatus advanceMixerBuffer ( unsigned numSamples )

protected

Pull frame from mixer buffer.

Remove samples from mixer buffer begin, equal number of samples become available at the end of mixer buffer. This method is usually called after device driver read samples from the beginning of buffer. After this current frame time should be advanced by appropriate number of milliseconds to move time window forward.

Parameters

[in] numSamples - How many samples to advance.

void readyForDataCallback	(	const intptr_t	userData,
		const intptr_t	eventData
	)

staticprotected

Call this when driver become ready for the next frame.

Parameters

[in]	userData	- Contain pointer connection it is associated with.
[in]	eventData	- contains 0 for now.

MpAudioOutputConnection& operator= ( const MpAudioOutputConnection & rhs )

private

Assignment operator (not implemented for this class)

Member Data Documentation

OsMutex mMutex

mutableprivate

Mutex to synchronize access to connection.

int mUseCount

private

Use counter, used to implement safe delete.

MpOutputDeviceDriver* mpDeviceDriver

private

connection.

Device driver associated with this

MpFrameTime mCurrentFrameTime

private

Frame time of the mixer buffer begin.

unsigned mMixerBufferLength

private

Length of mixer buffer (in samples).

MpAudioSample* mpMixerBuffer

private

several media streams.

Mixer circular buffer. Used to mix

unsigned mMixerBufferBegin

private

Index of first available sample in mixer buffer.

OsCallback readyForDataCallbackNotf

private

This callback is used in mixer mode to notify connection that device is ready for the next frame.

OsNotification* mpFlowgraphTicker

private

when it should process next frame.

Notification to call to notify graph

Private Member Functions

Private Attributes

Creators

Manipulators

Accessors

Mixer buffer methods

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation