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.
When to Implement
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.
When to Use
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. |
Determines the filter's state.
HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);
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.
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.
Retrieves the current reference clock in use by this filter.
HRESULT GetSyncSource(
IReferenceClock ** pClock
);
Returns an HRESULT value.
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.
Informs the filter to transition to the new state.
HRESULT Pause(void);
Returns S_OK if the transition is complete; otherwise, returns one of the following values.
| Value | Meaning |
| Error value | Transition failed. |
| S_FALSE | Transition is not complete, but no error has occurred. |
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.
Informs the filter to transition to the new (running) state. Passes a time value to synchronize independent streams.
HRESULT Run(
REFERENCE_TIME tStart
);
Returns an HRESULT value.
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.
Identifies the reference clock to which the filter should synchronize activity.
HRESULT SetSyncSource(
IReferenceClock * pClock
);
Returns an HRESULT value.
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.
Informs the filter to transition to the new state.
HRESULT Stop(void);
Returns S_OK if the transition is complete; otherwise, returns one of the following values.
| Value | Meaning |
| Error value | Transition failed. |
| S_FALSE | Transition is not complete, but no error has occurred. |
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.