Microsoft DirectX 8.0 |
Implements a queue to deliver media samples.
Declaration: Outputq.h
This class enables an output pin to deliver samples asynchronously. Samples are placed on a queue, and a worker thread delivers them to the input pin. The queue can also hold control messages that indicate a new segment, an end-of-stream notification, or a flush operation.
To use this class, create a COutputQueue object for every output pin on the filter. In the constructor method, specify the input pin connected to that output pin. Using this class, the output pin does not call methods directly on the input pin. Instead, it calls corresponding methods in COutputQueue, as shown in the following table.
Pin Method | COutputQueue Method |
---|---|
IPin::BeginFlush | BeginFlush |
IPin::EndFlush | EndFlush |
IPin::EndOfStream | EOS |
IPin::NewSegment | NewSegment |
MemInputPin::Receive | Receive |
MemInputPin::ReceiveMultiple | ReceiveMultiple |
Optionally, you can configure the COutputQueue object to deliver samples synchronously, without a worker thread. The object can also decide at run time whether to use a worker thread, based on the characteristics of the input pin. For more information, see COutputQueue::COutputQueue.
Protected Member Variables | |
---|---|
m_pPin | Pointer to the input pin's IPin interface. |
m_pInputPin | Pointer to the input pin's IMemInputPin interface. |
m_bBatchExact | Flag that specifies whether the object delivers samples in exact batches. |
m_lBatchSize | Batch size. |
m_List | Media sample queue. |
m_hSem | Handle to a semaphore, used by the thread to wait for samples. |
m_evFlushComplete | Event that signals when a flush operation has finished. |
m_hThread | Handle to the worker thread. |
m_ppSamples | Array of samples of size m_lBatchSize. |
m_nBatched | Number of samples currently batched and awaiting processing. |
m_lWaiting | Flag that has a nonzero value when the thread is waiting for a sample. |
m_bFlushing | Flag that specifies whether the object is performing a flush operation. |
m_bTerminate | Flag that specifies whether the thread should terminate. |
m_bSendAnyway | Flag to override batch processing. |
m_hr | HRESULT value that indicates whether the object will accept samples. |
m_hEventPop | Event that is signalled whenever the object removes a sample from the queue. |
Protected Methods | |
InitialThreadProc | Calls the ThreadProc method when the thread is created. |
ThreadProc | Retrieves samples from the queue and delivers them to the input pin. |
IsQueued | Determines whether the object is using a worker thread to deliver samples. |
QueueSample | Queues a media sample or control message. |
IsSpecialSample | Determines whether queued data is a control message. |
FreeSamples | Frees all pending samples. |
NotifyThread | Notifies the thread that the queue contains data. |
Public Methods | |
COutputQueue | Constructor method. |
~COutputQueue | Destructor method. |
BeginFlush | Begins a flush operation. |
EndFlush | Ends a flush operation. |
EOS | Delivers an end-of-stream call to the input pin. |
SendAnyway | Delivers any pending samples. |
NewSegment | Delivers a new segment to the input pin. |
Receive | Delivers a media sample to the input pin. |
ReceiveMultiple | Delivers a batch of media samples to the input pin. |
Reset | Resets the object so that it can receive more data. |
IsIdle | Determines whether the object is waiting for data. |
SetPopEvent | Specifies an event that is signalled whenever the object removes a sample from the queue. |
Pointer to the input pin's IPin interface.
Syntax
IPin * const m_pPin;
Pointer to the input pin's IMemInputPin interface.
Syntax
IMemInputPin *m_pInputPin;
Flag that specifies whether the object delivers samples in exact batches.
Syntax
BOOL const m_bBatchExact;
Remarks
If the value is TRUE, the object waits until it has a complete batch of media samples before delivering any. Otherwise, it delivers samples as they arrive. The m_lBatchSize member variable defines the batch size.
Batch size.
Syntax
LONG const m_lBatchSize;
Media sample queue.
Syntax
typedef CGenericList<IMediaSample> CSampleList; CSampleList *m_List;
Remarks
Pointer to a CGenericList class template, specialized to hold IMediaSample pointers.
Handle to a semaphore, used by the thread to wait for samples.
Syntax
HANDLE m_hSem;
Event that signals when a flush operation has finished.
Syntax
CAMEvent m_evFlushComplete;
Handle to the worker thread.
Syntax
HANDLE m_hThread;
Array of samples of size m_lBatchSize.
Syntax
IMediaSample **m_ppSamples;
Remarks
The worker thread pulls samples from the queue (m_List) and places them in this array. It passes the array to the IMemInputPin::ReceiveMultiple method. If the object is not using a worker thread, the object places samples directly into this array.
Number of samples currently batched and awaiting processing.
Syntax
LONG m_nBatched;
Flag that has a nonzero value when the thread is waiting for a sample.
Syntax
LONG m_lWaiting;
Flag that specifies whether the object is performing a flush operation. If TRUE, the object has started flushing.
Syntax
BOOL m_bFlushing;
Flag that specifies whether the thread should terminate. If TRUE, the thread terminates.
Syntax
BOOL m_bTerminate;
Flag to override batch processing. Setting this flag to TRUE overrides the m_bBatchExact flag and delivers all pending samples.
Syntax
BOOL m_bSendAnyway;
HRESULT value that indicates whether the object will accept samples. If the value is S_OK, the object will accept samples. Otherwise, it rejects samples.
Syntax
BOOL volatile m_hr;
Remarks
This member variable is used to coordinate activities across threads. If the downstream input pin rejects a sample, or if the object begins flushing, the value is set to S_FALSE or an error code. The object will not deliver any more samples until flushing is complete, or until the Reset method is called.
Optional event that is signaled whenever the object removes a sample from the queue. The value is initially NULL. Call the SetPopEvent method to specify an event handle.
Syntax
HANDLE m_hEventPop;
Begins a flush operation.
Syntax
void BeginFlush(void);
Remarks
This method sets the m_bFlushing member variable to TRUE. If the object is using a thread, the thread calls the FreeSamples method to free any pending samples. Otherwise, the object calls FreeSamples during the COutputQueue::EndFlush method. This method also sets the m_hr member variable to S_FALSE, which causes the object to discard all new samples.
The object passes the flush notification downstream by calling the IPin::BeginFlush method on the input pin.
Constructor method.
Syntax
COutputQueue( IPin *pInputPin, HRESULT *phr, BOOL bAuto = TRUE, BOOL bQueue = TRUE, LONG lBatchSize = 1, BOOL bBatchExact = FALSE, LONG lListSize = DEFAULTCACHE, DWORD dwPriority = THREAD_PRIORITY_NORMAL );
Parameters
- pInputPin
- Pointer to the IPin interface of the input pin. The object will deliver samples to this pin.
- phr
- Pointer to an HRESULT return code. Set the value to S_OK before calling this method. On return, phr receives a value that indicates the success or failure of the method.
- bAuto
- Flag that specifies whether the object decides when to create a queue. If TRUE, the object creates a queue only if the input pin might block. If FALSE, the bQueue parameter specifies whether to create a queue.
- bQueue
- If bAuto is TRUE, this parameter is ignored. If bAuto is FALSE, this flag specifies whether to create a queue.
- lBatchSize
- Maximum number of samples to deliver in one batch.
- bBatchExact
- Flag that specifies whether to use exact batch sizes. If TRUE, the object waits for lBatchSize samples before delivering them to the input pin. If FALSE, the object delivers samples as it receives them.
- lListSize
- Cache size for the queue. The default value, DEFAULTCACHE, is a constant defined for the CBaseList class.
- dwPriority
- Priority of the thread that delivers samples.
Remarks
If bAuto is TRUE, the object calls the IMemInputPin::ReceiveCanBlock method on the downstream pin. If ReceiveCanBlock returns S_OK (meaning the pin might block on Receive calls), the object creates a thread for delivering samples. Otherwise, it does not create a thread.
If bAuto is FALSE, the value of bQueue determines whether to create a thread.
If the object creates a thread, it assigns the thread handle to the m_hThread member variable. The thread procedure is InitialThreadProc, and the thread parameter is a pointer to this. The object also creates a queue for holding samples, which is given by the m_List member variable.
Destructor method.
Syntax
~COutputQueue(void);
Ends a flush operation.
Syntax
void EndFlush(void);
Remarks
If the object is using a thread, this method waits for the m_evFlushComplete event. The thread signals this event after it frees any pending samples. If the object is not using a thread, this method calls the FreeSamples method. Then the EndFlush method calls the IPin::EndFlush method on the input pin.
Delivers an end-of-stream call to the input pin.
Syntax
void EOS(void);
Remarks
If the object is using a thread, it queues an EOS_PACKET control message. The thread delivers any pending samples and calls the IPin::EndOfStream method on the input pin.
If the object is not using a thread, it calls the SendAnyway method to deliver any pending samples. Then it calls IPin::EndOfStream on the input pin.
Frees all pending samples.
Syntax
void FreeSamples(void);
Remarks
This method removes any pending samples from the queue and from the sample array (m_ppSamples).
Calls the ThreadProc method when the thread is created.
Syntax
static DWORD WINAPI InitialThreadProc( LPVOID pv );
Parameters
- pv
- this pointer.
Return Value
Returns the value returned by the ThreadProc method.
Remarks
This method is the thread procedure for the object's worker thread. The object's this pointer is the thread parameter. The method dereferences this to call ThreadProc.
Determines whether the object is waiting for data.
Syntax
BOOL IsIdle(void);
Return Value
Returns TRUE if the thread is waiting and the sample array is empty. Otherwise, returns FALSE.
Determines whether the object is using a worker thread to deliver samples.
Syntax
BOOL IsQueued(void);
Return Value
Returns TRUE if the object is using a worker thread, or FALSE otherwise.
Determines whether queued data is a control message.
Syntax
BOOL IsSpecialSample( IMediaSample *pSample );
Parameters
- pSample
- Pointer to an item in the queue.
Return Value
Returns TRUE if pSample is a control message, or FALSE otherwise.
Remarks
The QueueSample method can receive control messages in addition to media samples. A control message is a defined constant (cast to a LONG_PTR type) that instructs the thread to perform an action. Control messages do not contain media data. For more information, see QueueSample.
Delivers a new segment to the input pin.
Syntax
HRESULT NewSegment( REFERENCE_TIME tStart, REFERENCE_TIME tStop, double dRate );
Parameters
- tStart
- [in] Starting media position of the segment, in 100-nanosecond units.
- tStop
- [in] End media position of the segment, in 100-nanosecond units.
- dRate
- [in] Rate at which this segment should be processed, as a percentage of the original rate.
Return Value
Returns an HRESULT value.
Remarks
If the object is using a thread, it queues the following items, in order:
- A NEW_SEGMENT control message.
- The segment data.
The NEW_SEGMENT message notifies the thread that the next item on the queue will contain segment data. The segment data is bundled in a structure, declared as follows:
struct NewSegmentPacket { REFERENCE_TIME tStart; REFERENCE_TIME tStop; double dRate; };The thread calls the IPin::NewSegment method on the input pin, using the data given in the structure.
If the object is not using a thread, it calls the SendAnyway method to deliver any pending samples. Then it calls IPin::NewSegment on the input pin.
Notifies the thread that the queue contains data.
Syntax
void NotifyThread(void);
Remarks
Hold the critical section before calling this method.
Queues a sample.
Syntax
void QueueSample( IMediaSample *pSample );
Parameters
- pSample
- Pointer to the sample's IMediaSample interface.
Remarks
This method adds a sample to the tail of the queue (m_List). Hold the critical section before calling this method, and call it only when the object is using a thread to deliver samples. To determine if the object is using a thread, call the IsQueued method.
This method can also be used to put control messages onto the queue. A control message is a defined constant (cast to a LONG_PTR type) that instructs the thread to perform some action. The COutputQueue class defines the control messages shown in the following table.
Message Action EOS_PACKET Deliver an end-of-stream notification. NEW_SEGMENT Deliver a new segment. RESET_PACKET Reset the state of the queue. SEND_PACKET Send a partial batch of samples. This is a protected method, which the COutputQueue class uses internally.
Delivers a media sample to the input pin.
Syntax
HRESULT Receive( IMediaSample *pSample );
Parameters
- pSample
- Pointer to the sample's IMediaSample interface.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_FALSE End-of-stream notification received before processing this sample. S_OK Success.
Remarks
This method calls the COutputQueue::ReceiveMultiple method.
Delivers a batch of media samples to the input pin.
Syntax
HRESULT ReceiveMultiple ( IMediaSample **ppSamples, long nSamples, long *nSamplesProcessed );
Parameters
- ppSamples
- Address of a pointer to an array of samples.
- nSamples
- Number of samples in the array.
- nSamplesProcessed
- Pointer to a variable that receives the number of samples delivered successfully.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_FALSE End-of-stream notification received before processing this sample. S_OK Success.
Remarks
If the object is using a thread, this method queues all of the samples passed in the array. Otherwise, the method calls the IMemInputPin::ReceiveMultiple method on the input pin.
Resets the object so that it can receive more data.
Syntax
void Reset(void);
Return Value
No return value.
Remarks
This method resets the m_hr member variable to S_OK. The object can receive media samples again; for example, after a flush operation.
Delivers any pending samples.
Syntax
void SendAnyway(void);
Remarks
If the m_bBatchExact member variable is TRUE, the object fills the m_ppSamples array before it delivers a batch of samples. Call this method to deliver a partial batch. For example, the EOS method calls SendAnyway to serialize end-of-stream messages.
Specifies an event that is signalled whenever the object removes a sample from the queue.
Syntax
void COutputQueue::SetPopEvent( HANDLE hEvent );
Syntax
- hEvent
- Handle to an event created by the caller.
Retrieves samples from the queue and delivers them to the input pin.
Syntax
DWORD ThreadProc(void);
Return Value
Returns zero.
Remarks
The InitialThreadProc method calls this method, which implements the main thread loop. Within the loop, the method performs the following steps:
- Retrieves a sample for the queue (m_List).
- If the sample is a control message, the thread executes the control action. Otherwise, it places the sample into the m_ppSamples array.
- When the array is full (or if m_bBatchExact is FALSE), the thread calls the IMemInputPin::ReceiveMultiple method to deliver the samples.
- If no samples are queued, the thread waits on the m_hSem semaphore.
The thread terminates when the m_bTerminate member variable becomes TRUE.