Microsoft DirectX 8.0 |
Abstract class for implementing filters.
Declaration: Amfilter.h
To implement a filter using CBaseFilter, you must perform at least the following steps:
Several base classes derive from CBaseFilter, including CSource, CBaseRenderer, and CTransformFilter. It is usually easier to implement a filter with one of these specialized classes, rather than use CBaseFilter directly.
Protected Member Variables | |
---|---|
m_State | Current state of the filter. |
m_pClock | Pointer to the filter's reference clock. |
m_tStart | Reference time that corresponds to stream time 0. |
m_clsid | Class identifier (CLSID) of the filter. |
m_pLock | Pointer to a critical section. |
m_pName | Filter name. |
m_pGraph | Pointer to the filter graph manager. |
m_pSink | Pointer to the IMediaEventSink interface on the filter graph manager. |
m_PinVersion | Current version of the set of pins on this filter. |
Public Methods | |
CBaseFilter | Constructor method. |
~CBaseFilter | Destructor method. |
StreamTime | Retrieves the current stream time. Virtual. |
IsActive | Determines whether the filter is currently active (running or paused). |
IsStopped | Determines whether the filter is currently stopped. |
NotifyEvent | Sends an event notification to the filter graph manager. |
GetFilterGraph | Retrieves a pointer to the filter graph manager. |
ReconnectPin | Breaks an existing pin connection and reconnects it to the same pin, using a specified media type. |
GetPinVersion | Retrieves a version number for the set of pins on this filter. Virtual. |
IncrementPinVersion | Increments the version number on the set of pins. |
GetSetupData | Retrieves the registration data for the filter. Virtual. |
Pure Virtual Methods | |
GetPinCount | Retrieves the number of pins. |
GetPin | Retrieves a pin. |
IPersist Methods | |
GetClassID | Retrieves the class identifier. |
IMediaFilter Methods | |
GetState | Retrieves the filter's state (running, stopped, or paused). |
SetSyncSource | Sets a reference clock for the filter. |
GetSyncSource | Retrieves the reference clock that the filter is using. |
Stop | Stops the filter. |
Pause | Pauses the filter. |
Run | Runs the filter. |
IBaseFilter Methods | |
EnumPins | Enumerates the pins on this filter. |
FindPin | Retrieves the pin with the specified identifier. |
QueryFilterInfo | Retrieves information about the filter. |
JoinFilterGraph | Notifies the filter that it has joined or left a filter graph. |
QueryVendorInfo | Retrieves a string containing vendor information. |
IAMovieSetup Merthods | |
Register | Adds the filter to the registry. |
Unregister | Removes the filter from the registry. |
Current state of the filter.
Syntax
FILTER_STATE m_State;
Pointer to the filter's reference clock.
Syntax
IReferenceClock *m_pClock;
Reference time that corresponds to stream time 0.
Syntax
CRefTime m_tStart;
Class identifier (CLSID) of the filter.
Syntax
CLSID m_clsid;
Pointer to a critical section.
Syntax
CCritSec *m_pLock;
Remarks
Hold this critical section during state transitions, or when a method accesses the state over several operations. The base class holds the critical section in the following methods:
Do not hold this critical section during streaming operations (that is, when delivering samples to a downstream filter). Serialize streaming operations using a different critical section. Otherwise, it can cause deadlock.
Filter name.
Syntax
WCHAR *m_pName;
Pointer to the filter graph manager.
Syntax
IFilterGraph *m_pGraph;
Pointer to the IMediaEventSink interface on the filter graph manager.
Syntax
IMediaEventSink *m_pSink;
Current version of the set of pins on this filter. For more information, see GetPinVersion.
Syntax
LONG m_PinVersion;
Constructor method.
Syntax
CBaseFilter( const TCHAR *pName, LPUNKNOWN pUnk, CCritSec *pLock, REFCLSID clsid );
Parameters
- pName
- Pointer to a string containing the name of the filter, for debugging purposes.
- pUnk
- Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
- pLock
- Pointer to a CCritSec lock, used to serialize state changes.
- clsid
- Class identifier of the object.
Remarks
For the critical section object, you would typically do one of the following:
- Derive a class that inherits both CBaseFilter and CCritSec. For pLock, pass the this pointer.
- Derive a class that inherits CBaseFilter and contains a CCritSec member variable. For pLock, pass the address of that variable.
Destructor method.
Syntax
CBaseFilter(void);
Remarks
Always stop the filter before destroying it.
Enumerates the pins on this filter. Implements the IBaseFilter::EnumPins method.
Syntax
HRESULT EnumPins( IEnumPins **ppEnum );
Parameters
- ppEnum
- Address of a variable that receives a pointer to the IEnumPins interface.
Return Value
Returns one of the following HRESULT values.
S_OK Success E_OUTOFMEMORY Insufficient memory E_POINTER NULL pointer argument
Remarks
This method creates an instance of the CEnumPins base class, and returns a pointer to that object, of type IEnumPins. If the method succeeds, the IEnumPins interface has an outstanding reference count. Be sure to release it when you are done.
Retrieves the pin with the specified identifier. Implements the IBaseFilter::FindPin method.
Syntax
HRESULT FindPin( LPCWSTR Id, IPin **ppPin );
Parameters
- Id
- Pointer to a constant, null-terminated Unicode string that identifies the pin.
- ppPin
- Address of a variable that receives a pointer to the pin's IPin interface.
Return Value
Returns one of the following HRESULT values.
S_OK Success. E_POINTER NULL pointer argument. VFW_E_NOT_FOUND Could not find a matching pin.
Remarks
This method calls the CBasePin::Name method to compare each pin's name against the string specified by the Id parameter.
If the method succeeds, the IPin interface has an outstanding reference count. Be sure to release it when you are done.
Retrieves the class identifier. Implements the IPersist::GetClassID method.
Syntax
HRESULT GetClassID( CLSID *pClsID );
Parameters
- pClsID
- Pointer to a variable that receives the class identifier.
Return Value
Returns S_OK or E_POINTER.
Retrieves a pointer to the filter graph manager.
Syntax
IFilterGraph *GetFilterGraph(void);
Return Value
Returns the value of m_pGraph.
Retrieves a pin.
Syntax
virtual CBasePin *GetPin( int n ) PURE;
Parameters
- n
- Number of the specified pin.
Return Value
Returns a pointer to the CBasePin object that implements the pin.
Remarks
The derived class must implement this pure virtual method. Return a pointer to the nth pin on this filter, indexed from zero.
Retrieves the number of pins.
Syntax
virtual int GetPinCount(void) PURE;
Return Value
Returns the number of pins.
Remarks
The derived class must implement this pure virtual method. Return the number of pins that are currently available on this filter. Filters can dynamically create or destroy pins.
Retrieves a version number for the set of pins on this filter.
Syntax
virtual long GetPinVersion(void);
Return Value
Returns the m_PinVersion member variable.
Remarks
The CBaseFilter constructor initializes the pin version to 1. In the base class, this number never changes. If the filter dynamically creates or destroys pins, it should increment the pin version whenever the pins change. To increment the version number, call the IncrementPinVersion method.
The pin enumerator object, which is implemented by the CEnumPins class, uses the pin version to keep itself synchronized with the filter.
Retrieves the registration data for the filter.
Note This method is obsolete. It is called by the Register and Unregister methods.
Syntax
virtual LPAMOVIESETUP_FILTER GetSetupData(void);
Return Value
Returns a pointer to an AMOVIESETUP_FILTER structure containing registration information for the filter.
Remarks
The base class returns NULL.
Retrieves the filters's state (running, stopped, or paused). Implements the IMediaFilter::GetState method.
Syntax
HRESULT GetState( DWORD dwMilliSecsTimeout, FILTER_STATE *State );
Parameters
- dwMilliSecsTimeout
- Time-out interval, in milliseconds.
- State
- Pointer to a variable that receives a member of the FILTER_STATE enumerated type, indicating the filter's state.
Return Value
Returns S_OK or E_POINTER.
Remarks
In the base class, all state transitions are synchronous and the dwMilliSecsTimeout parameter is ignored. If a derived class performs asynchronous state transitions, it should override this method to wait during state transitions, with a time-out of dwMilliSecsTimeout milliseconds.
Retrieves the reference clock that the filter is using. Implements the IMediaFilter::GetSyncSource method.
Syntax
HRESULT GetSyncSource( IReferenceClock **pClock );
Parameters
- pClock
- Address of a variable that receives a pointer to the clock's IReferenceClock interface.
Return Value
Returns S_OK or E_POINTER.
Remarks
If the filter is not using a reference clock, *pClock is set to NULL. When the method returns, if *pClock is non-NULL, the IReferenceClock interface has an outstanding reference count. Be sure to release it when you are done.
Increments the version number on the set of pins.
Syntax
void IncrementPinVersion(void);
Remarks
This method increments the m_PinVersion member variable. If the filter dynamically creates or destroys pins, call this method whenever the pins change. For more information, see GetPinVersion.
Determines whether the filter is currently active (running or paused).
Syntax
BOOL IsActive(void);
Return Value
Returns TRUE if the filter is paused or running, or FALSE if it is stopped.
Determines whether the filter is currently stopped.
Syntax
BOOL IsStopped(void);
Return Value
Returns TRUE if the filter is stopped, or FALSE otherwise.
Notifies the filter that it has joined or left a filter graph. Implements the IBaseFilter::JoinFilterGraph method.
Syntax
HRESULT JoinFilterGraph( IFilterGraph *pGraph, LPCWSTR pName );
Parameters
- pGraph
- Pointer to the filter graph manager's IFilterGraph interface, or NULL if the filter is leaving the graph.
- pName
- [in, string] Pointer to a Unicode string containing a name for the filter.
Return Value
Returns S_OK.
Remarks
This method sets the m_pGraph member variable equal to the pGraph parameter. It also queries for an IMediaEventSink interface pointer and stores it in the m_pSink member variable. However, the filter does not keep a reference count on either of these interfaces. Doing so would create a circular reference count, because the filter graph manager keeps a reference count on the filter.
The method copies the string specified by pName into the m_pName member variable.
Sends an event notification to the filter graph manager.
Syntax
HRESULT NotifyEvent( long EventCode, LONG_PTR EventParam1, LONG_PTR EventParam2 );
Parameters
- EventCode
- Event notification code.
- EventParam1
- First parameter of the event.
- EventParam2
- Second parameter of the event.
Return Value
Returns an HRESULT value. Possible values include those in the following table.
S_FALSE The filter graph manager is not accepting event notifications. S_OK Success. E_NOTIMPL Filter does not have a pointer to the IMediaEventSink interface.
Remarks
For a list of notification codes and parameter values, see Event Notification Codes.
In the base class, if the event code is EC_COMPLETE, the method sets the EventParam2 parameter to a pointer to the filter's IBaseFilter interface.
Pauses the filter. Implements the IMediaFilter::Pause method.
Syntax
HRESULT Pause(void);
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
This method calls the CBasePin::Active method on each of the filter's connected pins.
Retrieves information about the filter. Implements the IBaseFilter::QueryFilterInfo method.
Syntax
HRESULT QueryFilterInfo( FILTER_INFO *pInfo );
Parameters
- pInfo
- Pointer to a FILTER_INFO structure.
Return Value
Returns S_OK or E_POINTER.
Remarks
This method copies the filter's name from the m_pName member variable into the achName member of the FILTER_INFO structure. If m_pName is NULL, the method sets achName to L'\0'.
The method sets the pGraph member of the FILTER_INFO structure equal to the m_pGraph member variable, and increments the reference count. The caller must release the interface.
Retrieves a string containing vendor information.
Syntax
HRESULT QueryVendorInfo( LPWSTR *pVendorInfo );
Parameters
- pVendorInfo
- Address of a variable that receives a pointer to a wide-character string containing the vendor information.
Return Value
Returns E_NOTIMPL.
Remarks
To provide vendor information for a filter, override this method. If you implement this method, use the CoTaskMemAlloc function to allocate memory for the string. The caller is responsible for calling the CoTaskMemFree function.
Breaks an existing pin connection and reconnects it to the same pin, using a specified media type.
Syntax
HRESULT ReconnectPin( IPin *pPin, AM_MEDIA_TYPE const *pmt );
Parameters
- pPin
- Pointer to the pin's IPin interface.
- pmt
- Pointer to an AM_MEDIA_TYPE structure that specifies the media type, or NULL.
Return Value
Returns an HRESULT value. Possible values include those listed in the following table.
S_OK Success. E_NOINTERFACE m_pGraph member variable is NULL.
Remarks
This method calls the IFilterGraph2::ReconnectEx method on the filter graph manager. If the IFilterGraph2 interface is not available, the method calls IFilterGraph::Reconnect.
Adds the filter to the registry. Implements the IAMovieSetup::Register method.
Note The IAMovieSetup interface is obsolete. New filters should be registered using the AMovieDllRegisterServer2 function, which does not require IAMovieSetup. For more information, see How to Register DirectShow Filters.
Syntax
HRESULT Register(void);
Return Value
Returns one of the HRESULT values listed in the following table.
S_OK Success. S_FALSE No registration information is available.
Remarks
This method calls the AMovieSetupRegisterFilter function to register the filter.
Runs the filter. Implements the IMediaFilter::Run method.
Syntax
HRESULT Run( REFERENCE_TIME tStart );
Parameters
- tStart
- Reference time corresponding to stream time 0.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
If the filter is stopped, this method pauses the filter by calling the CBaseFilter::Pause method. It then calls the CBasePin::Run method on each of the filter's connected pins. Finally, it sets the m_State member variable to State_Running.
Stream time is calculated as the current reference time minus tStart. A media sample with a time stamp of zero should be rendered at time tStart.
Sets a reference clock for the filter. Implements the IMediaFilter::SetSyncSource method.
Syntax
HRESULT SetSyncSource( IReferenceClock *pClock );
Parameters
- pClock
- Pointer to the clock's IReferenceClock interface, or NULL.
Return Value
Returns S_OK.
Stops the filter. Implements the IMediaFilter::Stop method.
Syntax
HRESULT Stop(void);
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
This method calls the CBasePin::Inactive method on each of the filter's connected pins.
Retrieves the current stream time.
Syntax
virtual HRESULT StreamTime( CRefTime& rtStream );
Parameters
- rtStream
- Reference to a CRefTime object that receives the current stream time.
Return Value
Returns an HRESULT value. Possible values include those listed in the following table.
S_OK Success. VFW_E_NO_CLOCK No reference clock is available.
Remarks
Stream time is defined as the current reference time (as given by the reference clock) minus the start time (specified by m_tStart). A media sample's time stamp specifies the stream time when it should be rendered. If a sample with a time stamp less than the current stream time has not yet been rendered, it is late.
Removes the filter from the registry. Implements the IAMovieSetup::Unregister method.
Note The IAMovieSetup interface is obsolete. New filters should be unregistered using the AMovieDllRegisterServer2 function, which does not require IAMovieSetup. For more information, see How to Register DirectShow Filters.
Syntax
HRESULT Unregister(void);
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
This method calls the AMovieSetupRegisterFilter function to unregister the filter.