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.

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.

---

IMediaFilter::GetState

IMediaFilter Interface

Determines the filter's state.

HRESULT GetState(
  DWORD dwMilliSecsTimeout,
  FILTER_STATE * State
  );

Parameters

dwMilliSecsTimeout

[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.

State

[out] Returned state of the filter. States include stopped, paused, running, or intermediate (in the process of changing).

Return Values

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

IMediaFilter Interface

Retrieves the current reference clock in use by this filter.

HRESULT GetSyncSource(
  IReferenceClock ** pClock
  );

Parameters

pClock

[out] Pointer to a reference clock; it will be set to the IReferenceClock interface.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
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

IMediaFilter Interface

Informs the filter to transition to the new state.

HRESULT Pause(void);

Return Values

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.

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

IMediaFilter Interface

Informs the filter to transition to the new (running) state. Passes a time value to synchronize independent streams.

HRESULT Run(
  REFERENCE_TIME tStart
  );

Parameters

tStart

Time value of the reference clock.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
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

IMediaFilter Interface

Identifies the reference clock to which the filter should synchronize activity.

HRESULT SetSyncSource(
  IReferenceClock * pClock
  );

Parameters

pClock

[in] Pointer to the IReferenceClock interface.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
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

IMediaFilter Interface

Informs the filter to transition to the new state.

HRESULT Stop(void);

Return Values

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.

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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page