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
| Name | Description |
| 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
| Name | Description |
| CBaseOutputPin | Constructs a CBaseOutputPin object. |
Overridable Member Functions
| Name | Description |
| 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
| Name | Description |
| 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. |
Called by the CBaseFilter implementation when the state changes from stopped to either paused or running.
HRESULT Active(void);
Returns VFW_E_NO_ALLOCATOR if there is no allocator.
This member function calls CMemAllocator::Commit to commit memory required before becoming active.
Informs the pin to begin a flush operation.
HRESULT BeginFlush(void);
Returns E_UNEXPECTED.
This member function implements the IPin::BeginFlush method. It returns E_UNEXPECTED because this should be called only on input pins.
Releases IMemAllocator and IMemInputPin objects acquired by the pin.
HRESULT BreakConnect(void);
Returns NOERROR by the default base class implementation.
This member function releases the IMemAllocator and IPin interfaces used during the connection.
Constructs a CBaseOutputPin object.
CBaseOutputPin(
TCHAR *pObjectName,
CBaseFilter *pFilter,
CCritSec *pLock,
HRESULT * phr,
LPCWSTR pName
);
No return value.
Calls QueryInterface on the connected pin to retrieve an IMemInputPin interface.
HRESULT CheckConnect(
IPin *pPin
);
Returns NOERROR if successful; otherwise, returns an HRESULT error value.
Completes a connection to another filter.
virtual HRESULT CompleteConnect(
IPin *pReceivePin
);
Returns an HRESULT value. The default implementation returns NOERROR.
This member function overrides the CBasePin::CompleteConnect member function and calls the CBaseOutputPin::DecideAllocator member function to finish completing the connection.
Negotiates the allocator to use.
virtual HRESULT DecideAllocator(
IMemInputPin * pPin,
IMemAllocator ** pAlloc
);
Returns NOERROR if successful; otherwise, returns an HRESULT value.
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.
Retrieves the number and size of buffers required for the transfer.
virtual HRESULT DecideBufferSize(
IMemAllocator * pAlloc,
ALLOCATOR_PROPERTIES * ppropInputRequest
) PURE;
Returns an HRESULT value.
The CBaseOutputPin::DecideAllocator member function calls this member function. You must override this member function in your derived class and call IMemAllocator::SetProperties.
Delivers the IMediaSample buffer to the connected pin.
virtual HRESULT Deliver(
IMediaSample *pSample
);
Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns an HRESULT value.
This member function delivers this buffer to the connected input pin by calling its IMemInputPin::Receive method.
Calls the IPin::BeginFlush method on the connected input pin.
virtual HRESULT DeliverBeginFlush(void);
Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value that is returned by the IPin::BeginFlush method.
This member function delivers the BeginFlush notification downstream.
Calls the IPin::EndFlush method on the connected input pin.
virtual HRESULT DeliverEndFlush(void);
Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value that is returned by IPin::EndFlush.
This member function delivers the EndFlush notification downstream.
Calls the IPin::EndOfStream method on the connected input pin.
virtual HRESULT DeliverEndOfStream(void);
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.
This member function delivers the end-of-stream notification downstream by calling the IPin::EndOfStream method on the connected pin.
Calls the IPin::NewSegment method on the connected input pin.
virtual HRESULT DeliverNewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);
Returns an HRESULT value.
You will need to override this member function in your derived output pin class if your filter queues any data in the output pin.
Informs the pin to end a flush operation.
HRESULT EndFlush(void);
Returns E_UNEXPECTED.
This member function implements the IPin::EndFlush method. It returns E_UNEXPECTED because this should be called only on input pins.
Informs the input pin that no additional data is expected until a new run command is issued.
HRESULT EndOfStream(void);
Returns E_UNEXPECTED.
This member function implements the IPin::EndOfStream method but isn't expected to be called on an output pin.
Retrieves an IMediaSample buffer suitable for passing across the connection.
virtual HRESULT GetDeliveryBuffer(
IMediaSample ** ppSample,
REFERENCE_TIME * pStartTime,
REFERENCE_TIME * pEndTime,
DWORD dwFlags
);
| 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. |
Returns E_NOINTERFACE if an allocator is not found; otherwise, returns the value returned from calling the IMemAllocator::GetBuffer method.
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.)
Called by the CBaseFilter implementation when the state changes from either paused or running to stopped.
HRESULT Inactive(void);
Returns VFW_E_NO_ALLOCATOR if there is no allocator; otherwise, returns the value from calling the IMemAllocator::Decommit method.
This member function calls IMemAllocator::Decommit to decommit memory before becoming inactive.
Creates a default memory allocator. Override this to provide your own allocator or to provide no allocator.
virtual HRESULT InitAllocator(
IMemAllocator **ppAlloc
);
Returns an HRESULT value.
The allocator should be released after use. This is typically handled in the CBaseOutputPin::BreakConnect member function.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.