Microsoft DirectX 8.0

CBaseOutputPin Class

CBaseOutputPin class hierarchy

Abstract base class that implements an output pin.

Declaration: Amfilter.h

This class derives from CBasePin. It differs from CBasePin in the following respects:

When the pin connects, it requests a memory allocator from the input pin. Failing that, it creates a new allocator object. The output pin is responsible for setting the allocator properties. It does this through the pure virtual method DecideBufferSize. Override this method in your derived class. If the input pin has any buffer requirements, they are passed to the DecideBufferSize method.

Call the GetDeliveryBuffer method to obtain an empty media sample. Call the Deliver method to deliver samples downstream.

Protected Member Variables
m_pAllocatorPointer to the memory allocator.
m_pInputPinPointer to the input pin connected to this pin.
Public Methods
CBaseOutputPinConstructor method.
CompleteConnectCompletes a connection to an input pin. Virtual.
DecideAllocatorSelects a memory allocator. Virtual.
GetDeliveryBufferRetrieves a media sample that contains an empty buffer. Virtual.
DeliverDelivers a media sample to the connected input pin. Virtual.
InitAllocatorCreates a memory allocator. Virtual.
CheckConnectDetermines whether a pin connection is suitable.
BreakConnectReleases the pin from a connection.
ActiveNotifies the pin that the filter is now active.
InactiveNotifies the pin that the filter is no longer active.
DeliverEndOfStreamDelivers an end-of-stream notification to the connected input pin. Virtual.
DeliverBeginFlushRequests the connected input pin to begin a flush operation. Virtual.
DeliverEndFlushRequests the connected input pin to end a flush operation. Virtual.
DeliverNewSegmentDelivers a new-segment notification to the connected input pin. Virtual.
Pure Virtual Methods
DecideBufferSizeSets the buffer requirements.
IPin Methods
BeginFlushBegins a flush operation.
EndFlushEnds a flush operation.
EndOfStreamINotifies the pin that no additional data is expected.

CBaseOutputPin.m_pAllocator

CBaseOutputPin Class

Pointer to the memory allocator.

Syntax

IMemAllocator *m_pAllocator;

CBaseOutputPin.m_pInputPin

CBaseOutputPin Class

Pointer to the input pin connected to this pin.

Syntax

IMemInputPin *m_pInputPin;

CBaseOutputPin::Active

CBaseOutputPin Class

Notifies the pin that the filter is now active.

Syntax

HRESULT Active(void);

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
VFW_E_NO_ALLOCATORNo memory allocator is available.

Remarks

This method overrides the CBasePin::Active method. It calls the IMemAllocator::Commit method on the allocator, to allocate memory for buffers.

If you override this method, call the base-class method from your overriding method.

CBaseOutputPin::BeginFlush

CBaseOutputPin Class

Begins a flush operation. Implements the IPin::BeginFlush method.

Syntax

HRESULT BeginFlush(void);

Return Value

Returns E_UNEXPECTED.

Remarks

This method should only be called on input pins, so the CBaseOutputPin implementation returns E_UNEXPECTED.

CBaseOutputPin::BreakConnect

CBaseOutputPin Class

Releases the pin from a connection.

Syntax

HRESULT BreakConnect(void);

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

This method overrides the CBasePin::BreakConnect method. It decommits the allocator and releases the IMemAllocator and IPin interfaces.

If you override this method, call the base-class method from your overriding method. Otherwise, you might cause memory leaks.

CBaseOutputPin::CBaseOutputPin

CBaseOutputPin Class

Constructor method.

Syntax

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

Parameters

pObjectName
String containing the debug name of the object. For more information, see CbaseObject.
pFilter
Pointer to the filter that created this pin.
pLock
Pointer to a CCritSec lock, used to serialize state changes. This can be the same critical section as the filter lock, CBaseFilter.m_pLock.
phr
Pointer to a variable that receives an HRESULT value indicating the success or failure of the method.
pName
Unicode™ string containing the pin name (also used as the pin identifier).

Remarks

All of the parameters are passed directly to the CBasePin constructor.

CBaseOutputPin::CheckConnect

CBaseOutputPin Class

Determines whether a pin connection is suitable.

Syntax

HRESULT CheckConnect(
    IPin *pPin
);

Parameters

pPin
Pointer to the input pin's IPin interface.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_NOINTERFACEInput pin does not support IMemInputPin.
VFW_E_INVALID_DIRECTIONPin directions are not compatible.

Remarks

This method calls the base-class CBasePin::CheckConnect method, and then queries the input pin for its IMemInputPin interface.

CBaseOutputPin::CompleteConnect

CBaseOutputPin Class

Completes a connection to an input pin.

Syntax

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

Parameters

pReceivePin
Pointer to the input pin.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

This method overrides the CBasePin::CompleteConnect method. It calls the DecideAllocator method, which selects the memory allocator to use for this connection.

CBaseOutputPin::DecideAllocator

CBaseOutputPin Class

Selects a memory allocator.

Syntax

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

Parameters

pPin
Pointer to the input pin's IMemInputPin interface.
pAlloc
Address of a variable that receives a pointer to the allocator's IMemAllocator interface.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

This method is called at the end of the pin connection process. It performs the following steps:

  1. Calls the IMemInputPin::GetAllocatorRequirements method to retrieve the input pin's buffer requirements, if any.
  2. Calls the IMemInputPin::GetAllocator method to request an allocator from the input pin. If the input pin does not provide an allocator, the output pin creates one by calling the InitAllocator class method.
  3. Calls the DecideBufferSize class method, which sets the allocator properties. This is a pure virtual method; the derived class must implement it.
  4. Calls the IMemInputPin::NotifyAllocator method, which notifies the input pin of the allocator being used.

CBaseOutputPin::DecideBufferSize

CBaseOutputPin Class

Sets the buffer requirements.

Syntax

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

Parameters

pAlloc
Pointer to the allocator's IMemAllocator interface.
ppropInputRequest
Pointer to an ALLOCATOR_PROPERTIES structure that contains the input pin's buffer requirements. If the input pin did not specify any requirements, the caller should zero out the members of this structure.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

Override this method in your derived class. Call the IMemAllocator::SetProperties method to specify your buffer requirements. Typically, the derived class will honor the input pin's buffer requirements, but it is not required to.

CBaseOutputPin::Deliver

CBaseOutputPin Class

Delivers a media sample to the connected input pin.

Syntax

virtual HRESULT Deliver(
    IMediaSample *pSample
);

Parameters

pSample
Pointer to the sample's IMediaSample interface.

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

This method calls the IMemInputPin::Receive method on the input pin. Receive can block if the IMemInputPin::ReceiveCanBlock method returns S_OK.

Release the sample after calling this method. The input pin might hold a reference count on the sample, so do not reuse the sample. Always call the GetDeliveryBuffer method to obtain a new sample.

Hold the filter's critical section before calling this method. Otherwise, the pin might get disconnected during the method call. If the filter uses a worker thread to deliver samples, hold the critical section when the filter is ready to deliver a sample. Otherwise, you can hold the critical section in the filter's IMemInputPin::Receive method, where the filter processes samples.

Worker threads can create a potential deadlock. When the thread holds the critical section, it might wait on a state change in the filter. At the same time, the state change might be waiting for the thread to complete. To prevent this, the state-change code should signal an event that terminates the thread, and then wait for the thread to signal completion.

CBaseOutputPin::DeliverBeginFlush

CBaseOutputPin Class

Requests the connected input pin to begin a flush operation.

Syntax

virtual HRESULT DeliverBeginFlush(void);

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

This method calls the IPin::BeginFlush method on the input pin.

CBaseOutputPin::DeliverEndFlush

CBaseOutputPin Class

Requests the connected input pin to end a flush operation.

Syntax

virtual HRESULT DeliverEndFlush(void);

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

This method calls the IPin::EndFlush method on the input pin.

CBaseOutputPin::DeliverEndOfStream

CBaseOutputPin Class

Delivers an end-of-stream notification to the connected input pin.

Syntax

virtual HRESULT DeliverEndOfStream(void);

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

This method calls the IPin::EndOfStream method on the input pin.

CBaseOutputPin::DeliverNewSegment

CBaseOutputPin Class

Delivers a new-segment notification to the connected input pin.

Syntax

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

Parameters

tStart
Starting media position of the segment, in 100-nanosecond units.
tStop
End media position of the segment, in 100-nanosecond units.
dRate
Rate at which this segment should be processed, as a percentage of the original rate.

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

This method calls the IPin::NewSegment method on the input pin.

CBaseOutputPin::EndFlush

IPin Interface

Ends a flush operation. Implements the IPin::EndFlush method.

Syntax

HRESULT EndFlush(void);

Return Value

Returns E_UNEXPECTED.

Remarks

This method should only be called on input pins, so the CBaseOutputPin implementation returns E_UNEXPECTED.

CBaseOutputPin::EndOfStream

IPin Interface

Notifies the pin that no additional data is expected. Implements the IPin::EndOfStream method.

Syntax

HRESULT EndOfStream(void);

Return Value

Returns E_UNEXPECTED.

Remarks

This method should only be called on input pins, so the CBaseOutputPin implementation returns E_UNEXPECTED.

CBaseOutputPin::GetDeliveryBuffer

CBaseOutputPin Class

Retrieves a media sample that contains an empty buffer.

Syntax

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

Parameters

ppSample
Address of a variable that receives a pointer to the buffer's IMediaSample interface.
pStartTime
Pointer to the start time of the sample, or NULL.
pEndTime
Pointer to the ending time of the sample, or NULL.
dwFlags
Bitwise combination of flags supported by the IMemAllocator::GetBuffer interface.

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
E_NOINTERFACENo allocator available.

Remarks

This method calls the IMemAllocator::GetBuffer method on the allocator, and passes the parameters to that method.

CBaseOutputPin::Inactive

CBaseOutputPin Class

Notifies the pin that the filter is no longer active.

Syntax

HRESULT Inactive(void);

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_OKSuccess.
VFW_E_NO_ALLOCATORNo memory allocator is available.

Remarks

This method overrides the CBasePin::Inactive method. It calls the IMemAllocator::Decommit method to decommit the memory allocator.

If you override this method, call the base-class method from your overriding method.

CBaseOutputPin::InitAllocator

CBaseOutputPin Class

Creates a memory allocator.

Syntax

virtual HRESULT InitAllocator(
    IMemAllocator **ppAlloc
);

Parameters

ppAlloc
Address of a variable that receives a pointer to the allocator's IMemAllocator interface.

Return Value

Returns S_OK if successful, or an error code from the CoCreateInstance function.

Remarks

If the input pin does not provide a memory allocator, the DecideAllocator method calls this method to create an allocator.