Microsoft DirectX 8.0

COutputQueue Class

COutputQueue class hierarchy

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 MethodCOutputQueue Method
IPin::BeginFlushBeginFlush
IPin::EndFlushEndFlush
IPin::EndOfStreamEOS
IPin::NewSegmentNewSegment
MemInputPin::ReceiveReceive
MemInputPin::ReceiveMultipleReceiveMultiple

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_pPinPointer to the input pin's IPin interface.
m_pInputPinPointer to the input pin's IMemInputPin interface.
m_bBatchExactFlag that specifies whether the object delivers samples in exact batches.
m_lBatchSizeBatch size.
m_ListMedia sample queue.
m_hSemHandle to a semaphore, used by the thread to wait for samples.
m_evFlushCompleteEvent that signals when a flush operation has finished.
m_hThreadHandle to the worker thread.
m_ppSamplesArray of samples of size m_lBatchSize.
m_nBatchedNumber of samples currently batched and awaiting processing.
m_lWaitingFlag that has a nonzero value when the thread is waiting for a sample.
m_bFlushingFlag that specifies whether the object is performing a flush operation.
m_bTerminateFlag that specifies whether the thread should terminate.
m_bSendAnywayFlag to override batch processing.
m_hrHRESULT value that indicates whether the object will accept samples.
m_hEventPopEvent that is signalled whenever the object removes a sample from the queue.
Protected Methods
InitialThreadProcCalls the ThreadProc method when the thread is created.
ThreadProcRetrieves samples from the queue and delivers them to the input pin.
IsQueuedDetermines whether the object is using a worker thread to deliver samples.
QueueSampleQueues a media sample or control message.
IsSpecialSampleDetermines whether queued data is a control message.
FreeSamplesFrees all pending samples.
NotifyThreadNotifies the thread that the queue contains data.
Public Methods
COutputQueueConstructor method.
~COutputQueueDestructor method.
BeginFlushBegins a flush operation.
EndFlushEnds a flush operation.
EOSDelivers an end-of-stream call to the input pin.
SendAnywayDelivers any pending samples.
NewSegmentDelivers a new segment to the input pin.
ReceiveDelivers a media sample to the input pin.
ReceiveMultipleDelivers a batch of media samples to the input pin.
ResetResets the object so that it can receive more data.
IsIdleDetermines whether the object is waiting for data.
SetPopEventSpecifies an event that is signalled whenever the object removes a sample from the queue.

COutputQueue.m_pPin

COutputQueue Class

Pointer to the input pin's IPin interface.

Syntax

IPin * const m_pPin;

COutputQueue.m_pInputPin

COutputQueue Class

Pointer to the input pin's IMemInputPin interface.

Syntax

IMemInputPin *m_pInputPin;

COutputQueue.m_bBatchExact

COutputQueue Class

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.

COutputQueue.m_lBatchSize

COutputQueue Class

Batch size.

Syntax

LONG const m_lBatchSize;

COutputQueue.m_List

COutputQueue Class

Media sample queue.

Syntax

typedef CGenericList<IMediaSample> CSampleList;
CSampleList *m_List;

Remarks

Pointer to a CGenericList class template, specialized to hold IMediaSample pointers.

COutputQueue.m_hSem

COutputQueue Class

Handle to a semaphore, used by the thread to wait for samples.

Syntax

HANDLE m_hSem;

COutputQueue.m_evFlushComplete

COutputQueue Class

Event that signals when a flush operation has finished.

Syntax

CAMEvent m_evFlushComplete;

COutputQueue.m_hThread

COutputQueue Class

Handle to the worker thread.

Syntax

HANDLE m_hThread;

COutputQueue.m_ppSamples

COutputQueue Class

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.

COutputQueue.m_nBatched

COutputQueue Class

Number of samples currently batched and awaiting processing.

Syntax

LONG m_nBatched;

COutputQueue.m_lWaiting

COutputQueue Class

Flag that has a nonzero value when the thread is waiting for a sample.

Syntax

LONG m_lWaiting;

COutputQueue.m_bFlushing

COutputQueue Class

Flag that specifies whether the object is performing a flush operation. If TRUE, the object has started flushing.

Syntax

BOOL m_bFlushing;

COutputQueue.m_bTerminate

COutputQueue Class

Flag that specifies whether the thread should terminate. If TRUE, the thread terminates.

Syntax

BOOL m_bTerminate;

COutputQueue.m_bSendAnyway

COutputQueue Class

Flag to override batch processing. Setting this flag to TRUE overrides the m_bBatchExact flag and delivers all pending samples.

Syntax

BOOL m_bSendAnyway;

COutputQueue.m_hr

COutputQueue Class

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.

COutputQueue.m_hEventPop

COutputQueue Class

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;

COutputQueue::BeginFlush

COutputQueue Class

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.

COutputQueue::COutputQueue

COutputQueue Class

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.

COutputQueue::~COutputQueue

COutputQueue Class

Destructor method.

Syntax

~COutputQueue(void);

COutputQueue::EndFlush

COutputQueue Class

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.

COutputQueue::EOS

COutputQueue Class

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.

COutputQueue::FreeSamples

COutputQueue Class

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).

COutputQueue::InitialThreadProc

COutputQueue Class

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.

COutputQueue::IsIdle

COutputQueue Class

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.

COutputQueue::IsQueued

COutputQueue Class

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.

COutputQueue::IsSpecialSample

COutputQueue Class

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.

COutputQueue::NewSegment

COutputQueue Class

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:

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.

COutputQueue::NotifyThread

COutputQueue Class

Notifies the thread that the queue contains data.

Syntax

void NotifyThread(void);

Remarks

Hold the critical section before calling this method.

COutputQueue::QueueSample

COutputQueue Class

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.

MessageAction
EOS_PACKETDeliver an end-of-stream notification.
NEW_SEGMENTDeliver a new segment.
RESET_PACKETReset the state of the queue.
SEND_PACKETSend a partial batch of samples.

This is a protected method, which the COutputQueue class uses internally.

COutputQueue::Receive

COutputQueue Class

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.

COutputQueue::ReceiveMultiple

COutputQueue Class

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.

COutputQueue::Reset

COutputQueue Class

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.

COutputQueue::SendAnyway

COutputQueue Class

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.

COutputQueue::SetPopEvent

COutputQueue Class

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.

COutputQueue::ThreadProc

COutputQueue Class

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:

  1. Retrieves a sample for the queue (m_List).
  2. If the sample is a control message, the thread executes the control action. Otherwise, it places the sample into the m_ppSamples array.
  3. When the array is full (or if m_bBatchExact is FALSE), the thread calls the IMemInputPin::ReceiveMultiple method to deliver the samples.
  4. If no samples are queued, the thread waits on the m_hSem semaphore.

The thread terminates when the m_bTerminate member variable becomes TRUE.