windows-server-2003/multimedia/directx/dplay/dvoice/dxvutils/inqueue2.h

/*==========================================================================
 *
 *  Copyright (C) 1999 Microsoft Corporation.  All Rights Reserved.
 *
 *  File:		inqueue2.h
 *  Content:	Definition of the CInputQueue2 class
 *		
 *  History:
 *   Date		By		Reason
 *   ====		==		======
 * 07/16/99		pnewson	Created
 * 07/27/99		pnewson Overhauled to support new message numbering method 
 * 08/03/99		pnewson General clean up
 * 08/24/99		rodtoll	Fixed for release builds -- removed m_wQueueId from debug block
 * 01/31/2000	pnewson replace SAssert with DNASSERT
 * 03/26/2000   rodtoll Modified queue to be more FPM friendly
 * 03/29/2000	rodtoll Bug #30753 - Added volatile to the class definition
 *  07/09/2000	rodtoll	Added signature bytes 
 *
 ***************************************************************************/

#ifndef _INPUTQUEUE2_H_
#define _INPUTQUEUE2_H_

class CFrame;
class CFramePool;
class CInnerQueue;
class CInnerQueuePool;

typedef struct _QUEUE_PARAMS
{
    WORD wFrameSize;
	BYTE bInnerQueueSize;
	BYTE bMaxHighWaterMark;
	int iQuality;
	int iHops;
	int iAggr;
	BYTE bInitHighWaterMark;
	WORD wQueueId;
	WORD wMSPerFrame;
	CFramePool* pFramePool;
} QUEUE_PARAMS, *PQUEUE_PARAMS;

typedef struct _QUEUE_STATISTICS
{
    DWORD dwTotalFrames;
    DWORD dwTotalMessages;
    DWORD dwTotalBadMessages;
    DWORD dwDiscardedFrames;
    DWORD dwDuplicateFrames;
    DWORD dwLostFrames;
    DWORD dwLateFrames;
    DWORD dwOverflowFrames;
} QUEUE_STATISTICS, *PQUEUE_STATISTICS;

// This class manages a queue of frames. It is designed
// to allow a client class to remove frames from the queue
// at regular intervals, and to hide any out of order
// frame reception, or dropped frames from the caller.
// If for whatever reason there is no frame available
// to give a client, this class will still provide a
// frame marked as silent.  This allows the client to
// simply call the dequeue function once per period, and
// consume the data at the agreed rate.  So for example,
// the client to this class could be a thread which
// is consuming input data and passing it to DirectSound
// for playback. It can simply get a frame every 1/10 of
// a second (or however long a frame is), and play it.
//
// This is the second generation of input queue. It 
// manages a set of inner queues, each of which is used
// for a "message". The stream of speech is divided into
// a series of messages, using silence as the divider.
// This class will not function well if the audio stream
// is not divided into separate messages.
//
#define VSIG_INPUTQUEUE2		'QNIV'
#define VSIG_INPUTQUEUE2_FREE	'QNI_'
//
volatile class CInputQueue2
{
private:
	DWORD m_dwSignature; // Debug signature

	// A list of pointers to InnerQueue objects. This is where
	// the frames get stored. InnerQueues are retrieved from
	// a pool of InnerQueues and added to this list as new 
	// messages arrive. When a message is finished, the InnerQueue
	// is removed from this list and returned to the pool.
	std::list<CInnerQueue*> m_lpiqInnerQueues;

	// The queue will not enqueue any input frames until at least
	// one dequeue has been requested. This will function as an interlock
	// to ensure that the queue does not fill with data until the
	// consumer thread is ready to take it.
	BOOL m_fFirstDequeue;

	// This flag remembers if it's the first time a frame
	// has been accepted for enqueue. We need this so we
	// know what the first message number is.
	BOOL m_fFirstEnqueue;

	// The message number currently at the head of the queue
	BYTE m_bCurMsgNum;

	// A critical section used to exclude the enqueue, dequeue and reset
	// functions from one another. Also passed to the frame class so 
	// Return calls can be synchronized. These two classes need to share
	// a critical section because the CFramePool class updates the
	// CFrame pointers in the inner queues when a frame is returned to 
	// the frame pool.
	DNCRITICAL_SECTION m_csQueue;

	// a vector of the quality ratings of each high water mark
	std::vector<double> m_vdQualityRatings;

	// A vector that contains the factored optimum quality for
	// each high water mark. As the high water mark gets larger
	// we become more tolerant of lost packets. While you may 
	// want to have a 0.5% late packet rate at 0.1 or 0.2 second
	// long queues, you probably don't want to strive for that
	// when the queue size reaches 2 seconds!
	std::vector<double> m_vdFactoredOptQuals;

	// the quality parameters

	// Quality is measured by a floating point number.
	// This number represents the ratio of "bad stuff" that occurs
	// relative to the amount of "stuff" going on.
	//
	// In intuitive terms, if one of the last 100 frames was bad
	// (bad meaning late) the quality rating would be 0.01. (Note
	// that we don't count lost frames against the queue, since
	// increasing the queue size won't do anything to help lost
	// frames.)
	//
	// However, the measurement isn't quite that simple, because we 
	// bias it towards the more recent frames. That's what the frame
	// strength parameter is for. It represents the "weight" given to
	// the most recent frames. A frame strength of 0.01 would mean that 
	// the most recent frame counts for 1% of the quality of the queue,
	// either good or bad.
	//
	// Note that when we want to compare the "distance" between two
	// quality ratings, we'll use the inverse of the value, not the value
	// itself. That should match our perception of quality a bit
	// more (kind of like our hearing).
	// 
	// For example, the perceived difference in quality between 0.01 
	// and 0.02 is about 2 - twice as many errors occur on 0.02 than
	// 0.01 so the "distance" between 0.01 and 0.02 should be calculated
	// like 0.02/0.01 = 2. And the distance between 0.02 and 0.04 should
	// be calculated like 0.04/0.02 = 2. So the 'point' 0.04 is the same
	// 'distance' from 0.02 as the 'point' 0.01.
	//
	// Note the wording is weird - bad (low) quality has a higher numerical 
	// value, oh well
	//
	// The threshold value is the distance the quality value must wander
	// from the optimum in order to warrant considering a change of
	// high water mark. For example, a value of 2 would mean that 
	// for an optimum value of 0.02, the value would have to wander to
	// 0.01 or 0.04 before we'd consider a change. This is currently set
	// very low so the algorithm will quickly hunt out the best watermarks.
	double m_dOptimumQuality;
	double m_dQualityThreshold;
	double m_dFrameStrength;

	// the number of milliseconds in a frame. This is used to normalize
	// the frame strength to time, so a particular input aggressiveness
	// will provide the same results regardless of the current frame size.
	WORD m_wMSPerFrame;

	// We are interfacing to the outside world via 
	// two parameters, Quality and Aggressiveness.
	// these members are integers in the range
	// defined by the constants above, and are used
	// to set the double values above appropriately.
	// We need to provide the hop count for reasons 
	// discussed in the SetQuality() function.
	int m_iQuality;
	int m_iHops;
	int m_iAggr;

	// the current high water mark
	BYTE m_bCurHighWaterMark;

	// the cap on the high water mark
	BYTE m_bMaxHighWaterMark;

	// the initial high water mark on a new or reset queue
	BYTE m_bInitHighWaterMark;

	// Some statistics to track.
	DWORD m_dwTotalFrames;
	DWORD m_dwTotalMessages;
	DWORD m_dwTotalBadMessages;
	DWORD m_dwDiscardedFrames;
	DWORD m_dwDuplicateFrames;
	DWORD m_dwLostFrames;
	DWORD m_dwLateFrames;
	DWORD m_dwOverflowFrames;
	DWORD m_dwQueueErrors;

	// An abritrary queue ID, provided to the constructor, 
	// used to identify which queue an instrumentation message
	// is coming from. It serves no other purpose, and can be
	// ignored except for debug purposes.
	WORD m_wQueueId;

	// the frame pool to manage the frames so we don't have to
	// allocate a huge number of them when only a few are 
	// actually in use.
	CFramePool* m_pFramePool;

	// the inner queue pool to manage innner queues. Same idea
	// as the frame pool
	CInnerQueuePool* m_pInnerQueuePool;

public:

	// The constructor. 
	CInputQueue2();
    
    HRESULT Initialize( PQUEUE_PARAMS pQueueParams );
    void DeInitialize();

    void GetStatistics( PQUEUE_STATISTICS pStats ) const;

	// The destructor. Release all the resources we acquired in the
	// constructor
	~CInputQueue2();

	// This function clears all buffers and resets the other class 
	// information to an initial state. DO NOT CALL THIS FUNCTION
	// IF THE QUEUE IS IN USE! i.e. do not call it if you have
	// not called Return() on every frame that you have
	// taken from this queue.
	void Reset();

	// Call this function to add a frame to the queue.  I 
	// considered returning a reference to a frame which 
	// the caller could then stuff, but because the frames
	// will not always arrive in order, that would mean I would have
	// to copy the frame sometimes anyway.  So, for simplicity, the
	// caller has allocated a frame, which it passes a reference
	// to, and this function will copy that frame into the
	// appropriate place in the queue, according to its
	// message number and sequence number.
	void Enqueue(const CFrame& fr);

	// This function retrieves the next frame from the head of
	// the queue. For speed, it does not copy the data out of the
	// buffer, but instead returns a pointer to the actual
	// frame from the queue. Of course, there is the danger
	// that the CInputQueue2 object which returns a reference to the
	// frame may try to reuse that frame before the caller is 
	// finished with it. The CFrame's lock and unlock member functions
	// are used to ensure this does not happen.  When the caller
	// is finished with the CFrame object, it should call vUnlock()
	// on it. If the caller doesn't unlock the frame, bad things
	// will happen when the input queue tries lock it again when 
	// it wants to reuse that frame. In any case, the caller
	// should always unlock the returned frame before it attempts
	// to dequeue another frame.
	CFrame* Dequeue();

	// get and set the quality parameters
	int GetQuality() const { return m_iQuality; }
	void SetQuality(int iQuality, int iHops = 1);
	int GetAggr() const { return m_iAggr; }
	void SetAggr(int iAggr);

	// get and set the default high watermark
	BYTE GetInitHighWaterMark() const { return m_bInitHighWaterMark; }
	void SetInitHighWaterMark(BYTE bInitHighWaterMark) { m_bInitHighWaterMark = bInitHighWaterMark; }

	// get stats
	DWORD GetDiscardedFrames() const { return m_dwDiscardedFrames; }
	DWORD GetDuplicateFrames() const { return m_dwDuplicateFrames; }
	DWORD GetLateFrames() const { return m_dwLateFrames; }
	DWORD GetLostFrames() const { return m_dwLostFrames; }
	DWORD GetOverflowFrames() const { return m_dwOverflowFrames; }
	DWORD GetQueueErrors() const { return m_dwQueueErrors; }
	DWORD GetTotalBadMessages() const { return m_dwTotalBadMessages; }
	DWORD GetTotalFrames() const { return m_dwTotalFrames; }
	DWORD GetTotalMessages() const { return m_dwTotalMessages; }
	BYTE GetHighWaterMark() const { return m_bCurHighWaterMark; }

private:
	// a function to collect the stats from an input queue after a 
	// message is complete, and perform the queue adaptation
	void HarvestStats(CInnerQueue* piq);

	// a function which looks at a finished inner queue and decides
	// if the message was 'good' or 'bad'.
	double AdjustQuality(const CInnerQueue* piq, double dCurQuality) const;

	// set a new high water mark
	void SetNewHighWaterMark(BYTE bNewHighWaterMark);
};

#endif