Microsoft DirectX 8.0

CBaseFilter Class

CBaseFilter class hierarchy

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_StateCurrent state of the filter.
m_pClockPointer to the filter's reference clock.
m_tStartReference time that corresponds to stream time 0.
m_clsidClass identifier (CLSID) of the filter.
m_pLockPointer to a critical section.
m_pNameFilter name.
m_pGraphPointer to the filter graph manager.
m_pSinkPointer to the IMediaEventSink interface on the filter graph manager.
m_PinVersionCurrent version of the set of pins on this filter.
Public Methods
CBaseFilterConstructor method.
~CBaseFilterDestructor method.
StreamTimeRetrieves the current stream time. Virtual.
IsActiveDetermines whether the filter is currently active (running or paused).
IsStoppedDetermines whether the filter is currently stopped.
NotifyEventSends an event notification to the filter graph manager.
GetFilterGraphRetrieves a pointer to the filter graph manager.
ReconnectPinBreaks an existing pin connection and reconnects it to the same pin, using a specified media type.
GetPinVersionRetrieves a version number for the set of pins on this filter. Virtual.
IncrementPinVersionIncrements the version number on the set of pins.
GetSetupDataRetrieves the registration data for the filter. Virtual.
Pure Virtual Methods
GetPinCountRetrieves the number of pins.
GetPinRetrieves a pin.
IPersist Methods
GetClassIDRetrieves the class identifier.
IMediaFilter Methods
GetStateRetrieves the filter's state (running, stopped, or paused).
SetSyncSourceSets a reference clock for the filter.
GetSyncSourceRetrieves the reference clock that the filter is using.
StopStops the filter.
PausePauses the filter.
RunRuns the filter.
IBaseFilter Methods
EnumPinsEnumerates the pins on this filter.
FindPinRetrieves the pin with the specified identifier.
QueryFilterInfoRetrieves information about the filter.
JoinFilterGraphNotifies the filter that it has joined or left a filter graph.
QueryVendorInfoRetrieves a string containing vendor information.
IAMovieSetup Merthods
RegisterAdds the filter to the registry.
UnregisterRemoves the filter from the registry.

CBaseFilter.m_State

CBaseFilter Class

Current state of the filter.

Syntax

FILTER_STATE m_State;

CBaseFilter.m_pClock

CBaseFilter Class

Pointer to the filter's reference clock.

Syntax

IReferenceClock *m_pClock;

CBaseFilter.m_tStart

CBaseFilter Class

Reference time that corresponds to stream time 0.

Syntax

CRefTime m_tStart;

CBaseFilter.m_clsid

CBaseFilter Class

Class identifier (CLSID) of the filter.

Syntax

CLSID m_clsid;

CBaseFilter.m_pLock

CBaseFilter Class

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.

CBaseFilter.m_pName

CBaseFilter Class

Filter name.

Syntax

WCHAR *m_pName;

CBaseFilter.m_pGraph

CBaseFilter Class

Pointer to the filter graph manager.

Syntax

IFilterGraph *m_pGraph;

CBaseFilter.m_pSink

CBaseFilter Class

Pointer to the IMediaEventSink interface on the filter graph manager.

Syntax

IMediaEventSink *m_pSink;

CBaseFilter.m_PinVersion

CBaseFilter Class

Current version of the set of pins on this filter. For more information, see GetPinVersion.

Syntax

LONG m_PinVersion;

CBaseFilter::CBaseFilter

CBaseFilter Class

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:

CBaseFilter::~CBaseFilter

CBaseFilter Class

Destructor method.

Syntax

CBaseFilter(void);

Remarks

Always stop the filter before destroying it.

CBaseFilter::EnumPins

CBaseFilter Class

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_OKSuccess
E_OUTOFMEMORYInsufficient memory
E_POINTERNULL 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.

CBaseFilter::FindPin

CBaseFilter Class

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_OKSuccess.
E_POINTERNULL pointer argument.
VFW_E_NOT_FOUNDCould 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.

CBaseFilter::GetClassID

CBaseFilter Class

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.

CBaseFilter::GetFilterGraph

CBaseFilter Class

Retrieves a pointer to the filter graph manager.

Syntax

IFilterGraph *GetFilterGraph(void);

Return Value

Returns the value of m_pGraph.

CBaseFilter::GetPin

CBaseFilter Class

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.

CBaseFilter::GetPinCount

CBaseFilter Class

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.

CBaseFilter::GetPinVersion

CBaseFilter Class

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.

CBaseFilter::GetSetupData

CBaseFilter Class

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.

CBaseFilter::GetState

CBaseFilter Class

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.

CBaseFilter::GetSyncSource

CBaseFilter Class

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.

CBaseFilter::IncrementPinVersion

CBaseFilter Class

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.

CBaseFilter::IsActive

CBaseFilter Class

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.

CBaseFilter::IsStopped

CBaseFilter Class

Determines whether the filter is currently stopped.

Syntax

BOOL IsStopped(void);

Return Value

Returns TRUE if the filter is stopped, or FALSE otherwise.

CBaseFilter::JoinFilterGraph

CBaseFilter Class

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.

CBaseFilter::NotifyEvent

CBaseFilter Class

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_FALSEThe filter graph manager is not accepting event notifications.
S_OKSuccess.
E_NOTIMPLFilter 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.

CBaseFilter::Pause

CBaseFilter Class

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.

CBaseFilter::QueryFilterInfo

CBaseFilter Class

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.

CBaseFilter::QueryVendorInfo

CBaseFilter Class

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.

CBaseFilter::ReconnectPin

CBaseFilter Class

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_OKSuccess.
E_NOINTERFACEm_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.

CBaseFilter::Register

CBaseFilter Class

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_OKSuccess.
S_FALSENo registration information is available.

Remarks

This method calls the AMovieSetupRegisterFilter function to register the filter.

CBaseFilter::Run

CBaseFilter Class

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.

CBaseFilter::SetSyncSource

CBaseFilter Class

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.

CBaseFilter::Stop

CBaseFilter Class

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.

CBaseFilter::StreamTime

CBaseFilter Class

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_OKSuccess.
VFW_E_NO_CLOCKNo 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.

CBaseFilter::Unregister

CBaseFilter Class

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.