CBaseOutputPin Class

CBaseOutputPin class hierarchy

CBaseOutputPin is an abstract base class derived from the CBasePin class that provides support for the common memory transport. CBaseOutputPin connects only to an input pin that supplies an IMemInputPin interface (such as a pin class derived from the CBaseInputPin class), and provides methods for the filter to access that interface. Derive your output pins from this class for the easiest implementation.

An output pin must provide one or more media types when connected to an input pin. If the media type that returns an index size, for example, is not currently available, the output pin should return S_FALSE in the CBasePin::GetMediaType member function, and the base class will skip it.

Your output pin class methods (represented here with the class name CYourPin) should call CBaseOutputPin. For example, CYourPin::Active should call CBaseOutputPin::Active first, to see if it should proceed. CYourPin::Inactive should call CBaseOutputPin::Inactive first, to decommit the sample allocator and avoid deadlock problems with CBaseOutputPin::GetDeliveryBuffer.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

All IQualityControl method implementations are inherited from the CBasePin class and are not overridden by this class.

Protected Data Members

m_pAllocator Pointer to the IMemAllocator interface for this pin.

m_pInputPin Pointer to the input pin to which this pin is connected.

Member Functions

CBaseOutputPin Constructs a CBaseOutputPin object.

Overridable Member Functions

Active Switches the pin to the active (running) mode.
BreakConnect Releases the allocator and the IMemInputPin interface.
CheckConnect Calls QueryInterface to retrieve an IMemInputPin interface.
CompleteConnect Completes the connection.
DecideAllocator Negotiates the allocator.
DecideBufferSize Retrieves the number and size of buffers required for the transfer.
Deliver Delivers an IMediaSample buffer to the connecting pin.
DeliverBeginFlush Calls the IPin::BeginFlush method on the connected pin.
DeliverEndFlush Calls IPin::EndFlush on the connected input pin to pass an end-flushing notification.
DeliverEndOfStream Calls IPin::EndOfStream on the connected input pin to pass an end-of-stream notification.
DeliverNewSegment Calls IPin::NewSegment on the connected input pin to pass a segment.
GetDeliveryBuffer Returns an IMediaSample buffer suitable for passing across the connection.
Inactive Switches the pin to the inactive (stopped) mode.
InitAllocator Creates a default memory allocator. Override this to provide your own allocator or to provide no allocator.

Implemented IPin Methods

BeginFlush Informs the pin to begin a flush operation. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.
EndFlush Informs the pin to end a flush operation. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.
EndOfStream Informs the pin that no additional data is expected until a new run command is issued. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.

CBaseOutputPin::Active

CBaseOutputPin Class

Called by the CBaseFilter implementation when the state changes from stopped to either paused or running.

Syntax

HRESULT Active(void);

Return Value

Returns VFW_E_NO_ALLOCATOR if there is no allocator.

Remarks

This member function calls CMemAllocator::Commit to commit memory required before becoming active.

CBaseOutputPin::BeginFlush

CBaseOutputPin Class

Informs the pin to begin a flush operation.

Syntax

HRESULT BeginFlush(void);

Return Value

Returns E_UNEXPECTED.

Remarks

This member function implements the IPin::BeginFlush method. It returns E_UNEXPECTED because this should be called only on input pins.

CBaseOutputPin::BreakConnect

CBaseOutputPin Class

Releases IMemAllocator and IMemInputPin objects acquired by the pin.

Syntax

HRESULT BreakConnect(void);

Return Value

Returns NOERROR by the default base class implementation.

Remarks

This member function releases the IMemAllocator and IPin interfaces used during the connection.
If you override this method, always call the base class BreakConnect or unexpected behavior will result, including reference count leaks.

CBaseOutputPin::CBaseOutputPin

CBaseOutputPin Class

Constructs a CBaseOutputPin object.

Syntax

CBaseOutputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName
);

Parameters

pObjectName
Pointer to the name of the object used in the CBaseOutputPin constructor for debugging purposes.
pFilter
Pointer to the filter to which the pin will be attached.
pLock
Pointer to a CBaseOutputPin object for locking.
phr
Pointer to the general COM return value. This value is changed only if this function fails.
pName
Pointer to the pin name.

Return Value

No return value.

CBaseOutputPin::CheckConnect

CBaseOutputPin Class

Calls QueryInterface on the connected pin to retrieve an IMemInputPin interface.

Syntax

HRESULT CheckConnect(
    IPin *pPin
);

Parameters

pPin
Pointer to the IPin interface on the connecting pin.

Return Value

Returns NOERROR if successful; otherwise, returns an HRESULT error value.

CBaseOutputPin::CompleteConnect

CBaseOutputPin Class

Completes a connection to another filter.

Syntax

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

Parameters

pReceivePin
Pointer to the connected (receiving) pin.

Return Value

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

This member function overrides the CBasePin::CompleteConnect member function and calls the CBaseOutputPin::DecideAllocator member function to finish completing the connection.

CBaseOutputPin::DecideAllocator

CBaseOutputPin Class

Negotiates the allocator to use.

Syntax

virtual HRESULT DecideAllocator(
    IMemInputPin *pPin,
    IMemAllocator **pAlloc
);

Parameters

pPin
Pointer to the IPin interface of the connecting pin.
pAlloc
Address of a pointer to the negotiated IMemAllocator interface.

Return Value

Returns NOERROR if successful; otherwise, returns an HRESULT value.

Remarks

This member function calls the CBaseOutputPin::DecideBufferSize member function, which is not implemented by this base class. Override DecideBufferSize to call IMemAllocator::SetProperties.
If the connected input pin fails a call to IMemInputPin::GetAllocator, this member function constructs a CMemAllocator object and calls CBaseOutputPin::DecideBufferSize on that object. If the call to DecideBufferSize is successful, this member function notifies the input pin of the selected allocator. This function is called by the base class implementation of the IPin::Connect method, which is responsible for locking the object's critical section.
Override this member function if you want to use your own allocator. The input pin gets the first choice for the allocator, and the output pin agrees or forces it to use another allocator.

CBaseOutputPin::DecideBufferSize

CBaseOutputPin Class

Retrieves the number and size of buffers required for the transfer.

Syntax

virtual HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
    ) PURE;

Parameters

pAlloc
Pointer to the allocator assigned to the transfer.
ppropInputRequest
Pointer to the requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.

Return Value

Returns an HRESULT value.

Remarks

The CBaseOutputPin::DecideAllocator member function calls this member function. You must override this member function in your derived class and call IMemAllocator::SetProperties.

CBaseOutputPin::Deliver

CBaseOutputPin Class

Delivers the IMediaSample buffer to the connected pin.

Syntax

virtual HRESULT Deliver(
    IMediaSample *pSample
);

Parameters

pSample
Pointer to the buffer to deliver.

Return Value

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns an HRESULT value.

Remarks

This member function delivers this buffer to the connected input pin by calling its IMemInputPin::Receive method.

CBaseOutputPin::DeliverBeginFlush

CBaseOutputPin Class

Calls the IPin::BeginFlush method on the connected input pin.

Syntax

virtual HRESULT DeliverBeginFlush(void);

Return Value

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value that is returned by the IPin::BeginFlush method.

Remarks

This member function delivers the BeginFlush notification downstream.

CBaseOutputPin::DeliverEndFlush

CBaseOutputPin Class

Calls the IPin::EndFlush method on the connected input pin.

Syntax

virtual HRESULT DeliverEndFlush(void);

Return Value

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value that is returned by IPin::EndFlush.

Remarks

This member function delivers the EndFlush notification downstream.

CBaseOutputPin::DeliverEndOfStream

CBaseOutputPin Class

Calls the IPin::EndOfStream method on the connected input pin.

Syntax

virtual HRESULT DeliverEndOfStream(void);

Return Value

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value returned by the IPin::EndOfStream call to the connected pin.

Remarks

This member function delivers the end-of-stream notification downstream by calling the IPin::EndOfStream method on the connected pin.

CBaseOutputPin::DeliverNewSegment

CBaseOutputPin Class

Calls the IPin::NewSegment method on the connected input pin.

Syntax

virtual HRESULT DeliverNewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

Parameters

tStart
Start time of the segment.
tStop
Stop time of the segment.
dRate
Rate of the segment.

Return Value

Returns an HRESULT value.

Remarks

You will need to override this member function in your derived output pin class if your filter queues any data in the output pin.

CBaseOutputPin::EndFlush

IPin Interface

Informs the pin to end a flush operation.

Syntax

HRESULT EndFlush(void);

Return Value

Returns E_UNEXPECTED.

Remarks

This member function implements the IPin::EndFlush method. It returns E_UNEXPECTED because this should be called only on input pins.

CBaseOutputPin::EndOfStream

IPin Interface

Informs the input pin that no additional data is expected until a new run command is issued.

Syntax

HRESULT EndOfStream(void);

Return Value

Returns E_UNEXPECTED.

Remarks

This member function implements the IPin::EndOfStream method but isn't expected to be called on an output pin.

CBaseOutputPin::GetDeliveryBuffer

CBaseOutputPin Class

Retrieves an IMediaSample buffer suitable for passing across the connection.

Syntax

virtual HRESULT GetDeliveryBuffer(
    IMediaSample **ppSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

Parameters

ppSample
Address of a pointer to the IMediaSample buffer to be provided.
pStartTime
Pointer to the start time of the media sample (optional and can be NULL).
pEndTime
Pointer to the stop time of the media sample (optional and can be NULL).
dwFlags

Flags indicating the capabilities of the buffer. The following flags are supported.

AM_GBF_NOTASYNCPOINT Dynamic format changes are not allowed on this buffer because it is not a key frame.
AM_GBF_PREVFRAMESKIPPED Buffer returned will not be filled with data contiguous with any previous data sent.

Return Value

Returns E_NOINTERFACE if an allocator is not found; otherwise, returns the value returned from calling the IMemAllocator::GetBuffer method.

Remarks

The pin object must lock itself before calling this member function; otherwise, the filter graph could disconnect this pin from the input pin midway through the process. If the filter has no worker threads, the lock is best applied on the IMemInputPin::Receive call; otherwise, it should be done when the worker thread is ready to deliver the sample.
This call can block; therefore, to avoid deadlocking with an IMediaFilter::Stop command, a two-tier locking scheme (such as that implemented in CTransformFilter) is required. Only the second-level lock is acquired here. The IBaseFilter base class implementation of IMediaFilter::Stop first gets the first-level lock and then calls IMemAllocator::Decommit on the allocator. This has the effect of making GetDeliveryBuffer return with a failure code. The Stop member function then gets the second-level lock and completes the command by calling Inactive for this pin.
No lock is needed when calling CBaseOutputPin::GetDeliveryBuffer when passing on samples using a worker thread. In this case, the CBaseFilter::Stop base class implementation acquires its filter-level lock and just calls IMemAllocator::Decommit on the allocator, at which point the worker thread is freed up to listen for a command to stop.
You must release the sample yourself after this function. If the connected input pin needs to hold on to the sample beyond the function, it will add the reference for the sample itself through IUnknown::AddRef. You must release this one and call CBaseOutputPin::GetDeliveryBuffer for the next. (You cannot reuse it directly.)

CBaseOutputPin::Inactive

CBaseOutputPin Class

Called by the CBaseFilter implementation when the state changes from either paused or running to stopped.

Syntax

HRESULT Inactive(void);

Return Value

Returns VFW_E_NO_ALLOCATOR if there is no allocator; otherwise, returns the value from calling the IMemAllocator::Decommit method.

Remarks

This member function calls IMemAllocator::Decommit to decommit memory before becoming inactive.

CBaseOutputPin::InitAllocator

CBaseOutputPin Class

Creates a default memory allocator. Override this to provide your own allocator or to provide no allocator.

Syntax

virtual HRESULT InitAllocator(
    IMemAllocator **ppAlloc
);

Parameters

ppAlloc
Address of a pointer to the returned memory allocator.

Return Value

Returns an HRESULT value.

Remarks

The allocator should be released after use. This is typically handled in the CBaseOutputPin::BreakConnect member function.

m_pAllocator	Pointer to the IMemAllocator interface for this pin.
m_pInputPin	Pointer to the input pin to which this pin is connected.

Active	Switches the pin to the active (running) mode.
BreakConnect	Releases the allocator and the IMemInputPin interface.
CheckConnect	Calls QueryInterface to retrieve an IMemInputPin interface.
CompleteConnect	Completes the connection.
DecideAllocator	Negotiates the allocator.
DecideBufferSize	Retrieves the number and size of buffers required for the transfer.
Deliver	Delivers an IMediaSample buffer to the connecting pin.
DeliverBeginFlush	Calls the IPin::BeginFlush method on the connected pin.
DeliverEndFlush	Calls IPin::EndFlush on the connected input pin to pass an end-flushing notification.
DeliverEndOfStream	Calls IPin::EndOfStream on the connected input pin to pass an end-of-stream notification.
DeliverNewSegment	Calls IPin::NewSegment on the connected input pin to pass a segment.
GetDeliveryBuffer	Returns an IMediaSample buffer suitable for passing across the connection.
Inactive	Switches the pin to the inactive (stopped) mode.
InitAllocator	Creates a default memory allocator. Override this to provide your own allocator or to provide no allocator.

BeginFlush	Informs the pin to begin a flush operation. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.
EndFlush	Informs the pin to end a flush operation. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.
EndOfStream	Informs the pin that no additional data is expected until a new run command is issued. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.

AM_GBF_NOTASYNCPOINT	Dynamic format changes are not allowed on this buffer because it is not a key frame.
AM_GBF_PREVFRAMESKIPPED	Buffer returned will not be filled with data contiguous with any previous data sent.