CBaseOutputPin Class

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.

---

CBaseOutputPin::Active

CBaseOutputPin Class

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

HRESULT Active(void);

Return Values

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.

HRESULT BeginFlush(void);

Return Values

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.

HRESULT BreakConnect(void);

Return Values

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.

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

Parameters

pObjectName

Name of the object used in the CBaseOutputPin constructor for debugging purposes.

pFilter

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

Pin name.

Return Values

No return value.

---

CBaseOutputPin::CheckConnect

CBaseOutputPin Class

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

HRESULT CheckConnect(
  IPin *pPin
  );

Parameters

pPin

Pointer to the IPin interface on the connecting pin.

Return Values

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

---

CBaseOutputPin::CompleteConnect

CBaseOutputPin Class

Completes a connection to another filter.

virtual HRESULT CompleteConnect(
  IPin *pReceivePin
  );

Parameters

pReceivePin

Pointer to the connected (receiving) pin.

Return Values

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.

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

Parameters

pPin

Pointer to the IPin interface of the connecting pin.

pAlloc

Pointer to the negotiated IMemAllocator interface.

Return Values

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.

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

Parameters

pAlloc

Allocator assigned to the transfer.

ppropInputRequest

Requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.

Return Values

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.

virtual HRESULT Deliver(
  IMediaSample *pSample
  );

Parameters

pSample

Buffer to deliver.

Return Values

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.

virtual HRESULT DeliverBeginFlush(void);

Return Values

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.

virtual HRESULT DeliverEndFlush(void);

Return Values

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.

virtual HRESULT DeliverEndOfStream(void);

Return Values

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.

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 Values

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.

HRESULT EndFlush(void);

Return Values

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.

HRESULT EndOfStream(void);

Return Values

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.

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

Parameters

ppSample

IMediaSample buffer to be provided.

pStartTime

Start time of the media sample (optional and can be NULL).

pEndTime

Stop time of the media sample (optional and can be NULL).

dwFlags

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 Values

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.

HRESULT Inactive(void);

Return Values

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.

virtual HRESULT InitAllocator(
  IMemAllocator **ppAlloc
  );

Parameters

ppAlloc

Returned memory allocator.

Return Values

Returns an HRESULT value.

Remarks

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

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page