Microsoft DirectX 8.0 |
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_pAllocator | Pointer to the memory allocator. |
m_pInputPin | Pointer to the input pin connected to this pin. |
Public Methods | |
CBaseOutputPin | Constructor method. |
CompleteConnect | Completes a connection to an input pin. Virtual. |
DecideAllocator | Selects a memory allocator. Virtual. |
GetDeliveryBuffer | Retrieves a media sample that contains an empty buffer. Virtual. |
Deliver | Delivers a media sample to the connected input pin. Virtual. |
InitAllocator | Creates a memory allocator. Virtual. |
CheckConnect | Determines whether a pin connection is suitable. |
BreakConnect | Releases the pin from a connection. |
Active | Notifies the pin that the filter is now active. |
Inactive | Notifies the pin that the filter is no longer active. |
DeliverEndOfStream | Delivers an end-of-stream notification to the connected input pin. Virtual. |
DeliverBeginFlush | Requests the connected input pin to begin a flush operation. Virtual. |
DeliverEndFlush | Requests the connected input pin to end a flush operation. Virtual. |
DeliverNewSegment | Delivers a new-segment notification to the connected input pin. Virtual. |
Pure Virtual Methods | |
DecideBufferSize | Sets the buffer requirements. |
IPin Methods | |
BeginFlush | Begins a flush operation. |
EndFlush | Ends a flush operation. |
EndOfStream | INotifies the pin that no additional data is expected. |
Pointer to the memory allocator.
Syntax
IMemAllocator *m_pAllocator;
Pointer to the input pin connected to this pin.
Syntax
IMemInputPin *m_pInputPin;
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_OK Success. VFW_E_NO_ALLOCATOR No 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.
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.
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.
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.
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_OK Success. E_NOINTERFACE Input pin does not support IMemInputPin. VFW_E_INVALID_DIRECTION Pin directions are not compatible.
Remarks
This method calls the base-class CBasePin::CheckConnect method, and then queries the input pin for its IMemInputPin interface.
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.
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:
- Calls the IMemInputPin::GetAllocatorRequirements method to retrieve the input pin's buffer requirements, if any.
- 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.
- Calls the DecideBufferSize class method, which sets the allocator properties. This is a pure virtual method; the derived class must implement it.
- Calls the IMemInputPin::NotifyAllocator method, which notifies the input pin of the allocator being used.
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.
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_OK Success. VFW_E_NOT_CONNECTED Pin 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.
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_OK Success. VFW_E_NOT_CONNECTED Pin is not connected.
Remarks
This method calls the IPin::BeginFlush method on the input pin.
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_OK Success. VFW_E_NOT_CONNECTED Pin is not connected.
Remarks
This method calls the IPin::EndFlush method on the input pin.
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_OK Success. VFW_E_NOT_CONNECTED Pin is not connected.
Remarks
This method calls the IPin::EndOfStream method on the input pin.
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_OK Success. VFW_E_NOT_CONNECTED Pin is not connected.
Remarks
This method calls the IPin::NewSegment method on the input pin.
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.
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.
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_OK Success. E_NOINTERFACE No allocator available.
Remarks
This method calls the IMemAllocator::GetBuffer method on the allocator, and passes the parameters to that method.
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_OK Success. VFW_E_NO_ALLOCATOR No 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.
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.