Microsoft DirectX 8.0 |
Abstract base class that implements an input pin.
Declaration: Amfilter.h
This class adds support for the IMemInputPin interface, in addition to the IPin interface support provided by CBasePin.
To use this class, derive a new class and override at least the following methods:
Protected Member Variables | |
---|---|
m_pAllocator | Pointer to the memory allocator. |
m_bReadOnly | Flag that indicates whether the allocator produces read-only media samples. |
m_bFlushing | Flag that indicates whether the pin is currently flushing. |
m_SampleProps | Properties of the most recent sample. |
Public Methods | |
CBaseInputPin | Constructor method. |
~CBaseInputPin | Destructor method. |
BreakConnect | Releases the pin from a connection. |
IsReadOnly | Queries whether the allocator uses read-only media samples. |
IsFlushing | Queries whether the filter is currently flushing. |
CheckStreaming | Determines whether the pin can accept samples. Virtual. |
PassNotify | Passes a quality-control message to the appropriate object. |
Inactive | Notifies the pin that the filter is no longer active. Virtual. |
SampleProps | Retrieves the properties of the most recent sample. |
IPin Methods | |
BeginFlush | Begins a flush operation. |
EndFlush | Ends a flush operation. |
IMemInputPin Methods | |
GetAllocator | Retrieves the memory allocator proposed by this pin. |
NotifyAllocator | Specifies an allocator for the connection. |
GetAllocatorRequirements | Retrieves the allocator properties requested by the input pin. |
Receive | Receives the next media sample in the stream. |
ReceiveMultiple | Receives multiple samples in the stream. |
ReceiveCanBlock | Determines whether calls to the Receive method might block. |
IQualityControl Methods | |
Notify | Receives a quality-control message. |
Pointer to the memory allocator.
Syntax
IMemAllocator *m_pAllocator;
Flag that indicates whether the allocator produces read-only media samples. If TRUE, the allocator produces read-only samples.
Syntax
BYTE m_bReadOnly;
Flag that indicates whether the pin is currently flushing. If TRUE, the pin is flushing.
Syntax
BYTE m_bFlushing;
Properties of the most recent sample.
Syntax
AM_SAMPLE2_PROPERTIES m_SampleProps;
Begins a flush operation. Implements the IPin::BeginFlush method.
Syntax
HRESULT BeginFlush(void);
Return Value
Returns S_OK.
Remarks
This method sets the m_bFlushing flag to TRUE, which causes the Receive method to reject any more samples.
The derived class must override this method and perform the following steps:
- Call the IPin::BeginFlush method on downstream input pins. If the pin has not yet delivered any media samples downstream, you can skip this step. If your output pins derive from the CBaseOutputPin class, you can call the CBaseOutputPin::DeliverBeginFlush method.
- Call the base class method.
- Begin discarding queued data.
- Return from any blocked calls to the Receive method.
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 interface.
If you override this method, call the base-class method from your overriding method. Otherwise, you might cause memory leaks.
Constructor method.
Syntax
CBaseInputPin( TCHAR *pObjectName, CBaseFilter *pFilter, CCritSec *pLock, HRESULT *phr, LPCWSTR pPinName );
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.
- pPinName
- Unicode string containing the pin name (also used as the pin identifier).
Remarks
All of the parameters are passed directly to the CBasePin constructor.
Destructor method.
Syntax
~CBaseInputPin(void);
Determines whether the pin can accept samples.
Syntax
virtual HRESULT CheckStreaming(void);
Return Value
Returns one of the HRESULT values listed in the following table.
S_OK Success. S_FALSE Pin is currently flushing. VFW_E_RUNTIME_ERROR A run-time error occurred. VFW_E_WRONG_STATE The pin is stopped.
Remarks
The derived class can override this method to perform further checks. In the overriding method, also call the base class implementation.
The CBasePin::Receive method calls this method. You should override the CBasePin::EndOfStream method to call this method as well.
Ends a flush operation. Implements the IPin::EndFlush method.
Syntax
HRESULT EndFlush(void);
Return Value
Returns S_OK.
Remarks
This method sets the m_bFlushing flag to TRUE, which enables the Receive method to accept samples.
The derived class must override this method and perform the following steps:
- Free any buffered data and wait for all queued samples to be discarded.
- Clear any pending EC_COMPLETE notifications.
- Call the base class method.
- Call IPin::EndFlush on downstream input pins. If the pin has not yet delivered any media samples downstream, you can skip this step. If your output pins derive from the CBaseOutputPin class, you can call the CBaseOutputPin::DeliverEndFlush method.
Retrieves the memory allocator proposed by this pin. Implements the IMemInputPin::GetAllocator method.
Syntax
HRESULT GetAllocator( IMemAllocator **ppAllocator );
Parameters
- ppAllocator
- 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
This method creates a CMemAllocator object. Override this method if your filter uses an allocator from a downstream pin, or a custom allocator.
If the method succeeds, the IMemAllocator interface has an outstanding reference count. Be sure to release it when you are done.
Retrieves the allocator properties requested by the input pin.
Syntax
HRESULT GetAllocatorRequirements( ALLOCATOR_PROPERTIES *pProps );
Parameters
- pProps
- Pointer to an ALLOCATOR_PROPERTIES structure, which is filled in with the requirements.
Return Value
Returns E_NOTIMPL.
Remarks
When an output pin initializes a memory allocator, it can call this method to determine whether the input pin has any buffer requirements. For more information, see CBaseOutputPin::DecideAllocator.
Implementing this method is optional. If the filter has specific alignment or prefix requirements, override this 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.
Queries whether the filter is currently flushing.
Syntax
BOOL IsFlushing(void);
Return Value
Returns the m_bFlushing member variable.
Queries whether the allocator uses read-only media samples.
Syntax
BOOL IsReadOnly(void);
Return Value
Returns the m_bReadOnly member variable.
Notifies the pin that a quality change is requested. Implements the IQualityControl::Notify method.
Syntax
HRESULT Notify( IBaseFilter *pSelf, Quality q );
Parameters
- pSelf
- Pointer to the filter that is sending the quality-control message.
- q
- Quality structure that contains the quality-control message.
Return Value
Returns S_OK.
Remarks
Filters usually pass quality-control messages to an upstream output pin, not to an input pin. Therefore, this method returns S_OK without doing anything.
For more information, see Quality-Control Management.
Specifies an allocator for the connection. Implements the IMemInputPin::NotifyAllocator method.
Syntax
HRESULT NotifyAllocator( IMemAllocator *pAllocator, BOOL bReadOnly );
Parameters
- pAllocator
- Pointer to the allocator's IMemAllocator interface.
- bReadOnly
- Flag that specifies whether samples from this allocator are read-only. If TRUE, samples are read-only.
Return Value
Returns S_OK.
Remarks
During the pin connection, the output pin chooses an allocator and calls this method to notify the input pin. The output pin can use the allocator that the input pin proposed in the IMemInputPin::GetAllocator method, or it can provide its own allocator.
Passes a quality-control message to the appropriate object.
Syntax
HRESULT PassNotify( Quality q );
Parameters
- q
- Quality structure that contains the quality-control message.
Return Value
Returns an HRESULT value. Possible values include those listed in the following table.
S_OK Success. VFW_E_NOT_FOUND Could not find an object to accept the message.
Remarks
Call this method if the filter does not handle quality-control messages. This method passes the message to one of the following objects, in order of preference:
- An external quality-control manager, if the IQualityControl::SetSink method was called.
- The upstream output pin.
For more information, see Quality-Control Management.
Receives the next media sample in the stream. Implements the IMemInputPin::Receive method.
Syntax
HRESULT Receive( 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. S_FALSE Pin is currently flushing; sample was rejected. E_POINTER NULL pointer argument. VFW_E_INVALIDMEDIATYPE Invalid media type. VFW_E_RUNTIME_ERROR A run-time error occurred. VFW_E_WRONG_STATE The pin is stopped.
Remarks
The upstream output pin calls this method to deliver a sample to the input pin. The input pin must do one of the following:
- Process the sample before returning.
- Return, and process the sample in a worker thread.
- Reject the sample.
If the pin uses a worker thread to process the sample, add a reference count to the sample inside this method. After the method returns, the upstream pin releases the sample. When the sample's reference count reaches zero, the sample returns to the allocator for re-use.
This method is synchronous and can block. If the method might block, the pin's ReceiveCanBlock method should return S_OK.
In the base class, this method performs the following steps:
- Calls the CheckStreaming method to verify that the pin can process samples now. If it cannotfor example, if the pin is stoppedthe method fails.
- Retrieves the sample properties and checks whether the format has changed (see below).
- If the format has changed, the method calls the CBasePin::CheckMediaType method to determine whether the new format is acceptable.
- If the new format is not acceptable, the method calls the CBasePin::EndOfStream method, posts an EC_ERRORABORT event, and returns an error code.
- Assuming there were no errors, the method returns S_OK.
Test for a format change as follows:
- If the sample supports the IMediaSample2 interface, check the dwSampleFlags member of the AM_SAMPLE2_PROPERTIES structure. If the AM_SAMPLE_TYPECHANGED flag is present, the format has changed.
- Otherwise, if the sample does not support IMediaSample2, call the IMediaSample::GetMediaType method. If the method returns a non-NULL value, the format has changed.
In the base class, this method does not process the sample. The derived class must override this method to perform the processing. (What this entails depends entirely on the filter.) The derived class should call the base-class method, to check for the errors described previously.
Determines whether calls to the IMemInputPin::Receive method might block. Implements the IMemInputPin::ReceiveCanBlock method.
Syntax
HRESULT ReceiveCanBlock(void);
Return Value
Returns an HRESULT value. Possible value include those listed in the following table.
S_FALSE The pin will not block on a call to Receive. S_OK The pin might block on a call to Receive.
Remarks
Return S_FALSE if calls to the Receive method are guaranteed not to block. Otherwise, return S_OK or an error code. If the Receive method calls Receive on a downstream pin, the downstream pin might block; ReceiveCanBlock must take that factor into account.
An upstream filter can use this method to determine its threading strategy. If the Receive method might block, the upstream filter might decide to use a worker thread that buffers data. See the COutputQueue class for an implementation of this strategy.
In the base class, this method returns S_OK when any of the following are true:
- The filter has no output pins.
- An input pin connected to this filter signals that it might block.
- An input pin connected to this filter does not support the IMemInputPin interface.
Receives multiple samples in the stream. Implements the IMemInputPin::ReceiveMultiple method.
Syntax
HRESULT ReceiveMultiple( IMediaSample **pSamples, long nSamples, long *nSamplesProcessed );
Parameters
- pSamples
- Address of an array of IMediaSample pointers, of size nSamples.
- nSamples
- Number of samples to process.
- nSamplesProcessed
- Pointer to a variable that receives the number of samples that were processed.
Return Value
Returns an HRESULT value. Possible values include those listed in the following table.
S_OK Success. S_FALSE Pin is currently flushing; sample was rejected. E_POINTER NULL pointer argument. VFW_E_INVALIDMEDIATYPE Invalid media type. VFW_E_RUNTIME_ERROR A run-time error occurred. VFW_E_WRONG_STATE The pin is stopped.
Remarks
This method behaves like the Receive method, but receives an array of samples. In the base class, the method loops through the array and calls Receive with each sample. Override this function if your filter can process batches of samples more efficiently than processing them one at a time.
Retrieves the properties of the most recent sample, as an AM_SAMPLE2_PROPERTIES structure.
Syntax
AM_SAMPLE2_PROPERTIES *SampleProps(void);
Return Value
Returns the address of the m_SampleProps member variable.