IMediaFilter Interface
Multimedia components that provide time-based data expose the IMediaFilter interface. This interface abstracts an object that processes time-based data streams and represents a multimedia device (possibly implemented in software). It controls the active or running state of the object and the synchronization of this state with other objects in the system.
This interface inherits the IPersist interface.
Methods on this interface should be implemented as part of any filter. This is typically done by using the base class CBaseFilter, which implements IBaseFilter and IMediaFilter.
Because the IMediaFilter interface is inherited by the IBaseFilter interface, which adds other necessary methods required to be exported by filters, this interface is not normally used directly by the filter graph manager or other filters. It can, however, be of use to plug-in distributors. For example, the filter graph manager internally exports IMediaFilter; its plug-in distributor exports IMediaControl and calls the IMediaFilter methods to implement its own methods.
Methods in Vtable Order
IUnknown methods Description QueryInterface Returns pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMediaFilter methods Description Stop Informs the filter to transition to the new (stopped) state. Pause Informs the filter to transition to the new (paused) state. Run Informs the filter to transition to the new (running) state. GetState Determines the state of the filter. SetSyncSource Identifies the reference clock to which the filter should synchronize activity. GetSyncSource Retrieves the current reference clock (or NULL if there is no clock). Passes a time value to synchronize independent streams.
IMediaFilter::GetState
Determines the filter's state.
Syntax
HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE *State
);
Parameters
- dwMilliSecsTimeout
- [in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.
- State
- [out] Pointer to the returned state of the filter. States include stopped, paused, running, or intermediate (in the process of changing).
Return Value
Returns S_OK if the state is running, paused, or inactive; otherwise, returns VFW_S_STATE_INTERMEDIATE if the transition is not complete (the time-out expired). The state returned in the latter case is the one being changed to.
Remarks
Usually, renderer filters will return VFW_S_STATE_INTERMEDIATE until they receive enough data to render at least one sample. In some circumstances, a filter will find that it can supply data on all of its output streams. This condition usually occurs because of unusual or bad data. An example of unusual data might be an MPEG slide show, where video frames occur infrequently in the data but audio is continuous. In this case, a video frame in the video stream might not be found until a certain spot in the audio stream. If the filter discovers that it cannot complete the state change (for this or any other reason), it can return VFW_S_CANT_CUE.
When an application calls the filter graph manager's IMediaControl::GetState method, the filter graph manager calls GetState on the filter and continues to poll. If the filter graph manager receives VFW_S_CANT_CUE back from the filter, it returns this value to the application from its IMediaControl::GetState method.
IMediaFilter::GetSyncSource
Retrieves the current reference clock in use by this filter.
Syntax
HRESULT GetSyncSource(
IReferenceClock **pClock
);
Parameters
- pClock
- [out] Address of a pointer to a reference clock; it will be set to the IReferenceClock interface.
Return Value
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
E_FAIL Failure. E_POINTER Null pointer argument. E_INVALIDARG Invalid argument. E_NOTIMPL Method isn't supported. S_OK or NOERROR Success.
Remarks
The returned interface (if it is non-NULL) will have a reference added by the IUnknown::AddRef method. The calling application should release the interface by calling the IUnknown::Release method when it has finished with the pointer.
IMediaFilter::Pause
Informs the filter to transition to the new state.
Syntax
HRESULT Pause(void);
Return Value
Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Error value Transition failed. S_FALSE Transition is not complete, but no error has occurred.
Remarks
The state transition might not be immediate (external mechanical activity might be involved, for example). The state method might return before the transition has completed.
IMediaFilter::Run
Informs the filter to transition to the new (running) state. Passes a time value to synchronize independent streams.
Syntax
HRESULT Run(
REFERENCE_TIME tStart
);
Parameters
- tStart
- Time value of the reference clock.
Return Value
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
E_FAIL Failure. E_POINTER Null pointer argument. E_INVALIDARG Invalid argument. E_NOTIMPL Method isn't supported. S_OK or NOERROR Success.
Remarks
The tStart parameter is the amount to be added to the IMediaSample time stamp to determine the time at which that sample should be rendered according to the reference clock. That is, it is the reference time at which a sample with a stream time of zero should be rendered.
For example, the time value for the beginning of the stream is the time at which the first sample should appear. If the application restarts from paused mode in midstream, tStart is the amount of time paused, plus the start time.
The filter graph provides this information to its filters. An application calling the filter graph may pass a start time of zero, in which case the filter graph calculates a time that will begin as soon as possible. Filter graphs accept zero to mean as soon as possible; most filters do not.
IMediaFilter::SetSyncSource
Identifies the reference clock to which the filter should synchronize activity.
Syntax
HRESULT SetSyncSource(
IReferenceClock *pClock
);
Parameters
- pClock
- [in] Pointer to the IReferenceClock interface.
Return Value
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
E_FAIL Failure. E_POINTER Null pointer argument. E_INVALIDARG Invalid argument. E_NOTIMPL Method isn't supported. S_OK or NOERROR Success.
Remarks
This method is of most importance to rendering filters and might not apply to other filters. The pClock parameter can be NULL, meaning that the filter should run as fast as possible at its current quality settings without any attempt to synchronize. For example, a filter graph that is doing compression probably runs in this mode. Each filter takes as long as it needs.
IMediaFilter::Stop
Informs the filter to transition to the new state.
Syntax
HRESULT Stop(void);
Return Value
Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Error value Transition failed. S_FALSE Transition is not complete, but no error has occurred.
Remarks
The state transition might not be immediate (external mechanical activity might be involved, for example). The state functions might return before the transition has completed.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.