Share via


COutputQueue Class (Compact 2013)

3/26/2014

CCritSec Class

     COutputQueue Class

Output pins use the COutputQueue to send samples to another filter by using the local memory-based transport (that is, to input pins that support the IMemInputPin interface).

COutputQueue uses IMemInputPin::ReceiveCanBlock to determine if the connected input pin has a blocking implementation of IMemInputPin::Receive. If so, all samples are queued in COutputQueue and a thread is created to pass samples from the queue to the connected input pin.

If the input pin's IMemInputPin::Receive method does not block, samples are passed directly to IMemInputPin::Receive. COutputQueue can also batch samples to reduce the number of calls to the downstream pin.

COutputQueue is useful when the filter has other work to do while samples that it has already completed are being processed downstream.

For example, this occurs in a filter that can read more data off disk while data is being processed, or when it has more than one output pin and does not want to starve an output pin because IMemInputPin::Receive has no optional batching of samples.

To use this class, create one COutputQueue object for every output pin for which it will be used. This can either be created when the pin is created and deleted when the pin is disconnected, or it can be created when the pin goes active and deleted when the pin goes inactive.

The samples sent to this object by calling its COutputQueue::Receive or COutputQueue::ReceiveMultiple member function should have references added by means of IUnknown::AddRef (as they usually are if they were obtained directly from an allocator).

This object then calls IUnknown::Release on all samples it receives, whether they were processed successfully or not.

Release is not called for special (control) samples.

Some control information, such as end of stream, must be queued with the data and processed after all data has been delivered. This information is queued in the form of special control packets.

COutputQueue implements a sticky HRESULT so it will not send any more data after it gets a return code that is not S_OK from the downstream ReceiveMultiple call. (A sticky state setting is one that persists even after execution of operations that would usually reset the setting.)

This sticky state is reset by the EndFlush and EOS calls. However, if the sticky HRESULT is not S_OK, EOS itself is not sent downstream; the HRESULT is just reset. Because of this, if this object is not deleted when the pin goes inactive, BeginFlush and EndFlush should be called at that time to free the state.

In many ways this object acts as a proxy for the connected input pin, supporting a similar set of methods for stream control.

Protected Data Members

Member

Description

m_bBatchExact

TRUE if commands are batched; FALSE if commands are sent singly.

m_bFlushed

Flag to signify if samples have been flushed.

m_bFlushing

Flag for flushing state.

m_bSendAnyway

Flag to override batch processing.

m_bTerminate

Termination flag.

m_evFlushComplete

Event signaling that flushing has finished.

m_hSem

Handle used for signaling.

m_hr

HRESULT structure for return values; used to implement a sticky return value (one that persists even after operations that would usually change the value).

m_hThread

Worker thread handle.

m_lBatchSize

Work in batches of this batch size. Ignored if m_bBatchExact is not TRUE.

m_List

Pointer to a CSampleList object. The class CSampleList is a generic list (CGenericList) of objects of IMediaSample type. It is defined as follows:

typedef CGenericList<IMediaSample> CSampleList;

m_lWaiting

Variable set to nonzero value when waiting for a free element.

m_nBatched

Number of samples currently batched awaiting processing.

m_pInputPin

Pointer to the connected input pin.

m_pPin

Pointer to the output pin.

m_ppSamples

Pointer to an array of batched samples.

Member Functions

Member function

Description

BeginFlush

Causes all unsent samples to be discarded and sets flushing state.

COutputQueue

Constructs a COutputQueue object.

EndFlush

Finalizes flush of batched or queued samples and resets flushing state.

EOS

Queues an end-of-stream call to the connected input pin after all batched and queued samples have been passed to the input pin.

FreeSamples

Removes and releases batched and queued samples.

InitialThreadProc

Executed by the thread on thread creation.

IsIdle

Determines if the output queue is idle.

IsQueued

Determines if samples are being queued or being sent directly.

IsSpecialSample

Determines if the sample is a control sample.

NotifyThread

Notifies the thread that there is something to do.

NewSegment

Queues an IPin::NewSegment call to the connected input pin after all queued samples have been passed to the input pin.

QueueSample

Queues the prepared sample.

Receive

Passes in a single sample to send to the input pin.

ReceiveMultiple

Passes a set of samples to send to the input pin.

Reset

Resets the deferred return code m_hr to allow the output queue to be ready for more data.

SendAnyway

Frees any batches samples to be sent to the input pin.

ThreadProc

Implements the thread that sends samples downstream.

Requirements

Header

dshow.h,
Streams.h

Library

ole32.lib,
Ole32auth.lib,
Strmbase.lib,
Strmiids.lib,
uuid.lib

See Also

Reference

DirectShow Classes