Microsoft DirectX 8.0

IMediaFilter Interface

Controls the streaming state of a filter.

All Microsoft® DirectShow® filters implement this interface. It provides methods for switching the filter between states (stopped, paused, and running); for retrieving the filter's current state; and for setting a reference clock. The filter graph manager also exposes this interface. It distributes the method calls to the filters in the filter graph.

This interface provides low-level control of the graph. Applications should use the IMediaControl interface instead, because it provides control of the graph at a higher level.

IMediaFilter inherits the IPersist interface. The IBaseFilter interface inherits from IMediaFilter.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IMediaFilter methodsDescription
Stop Stops the filter.
Pause Pauses the filter.
Run Runs the filter.
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.

IMediaFilter::GetState

IMediaFilter Interface

Retrieves the filters's state (running, stopped, or paused).

Syntax

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

Parameters

dwMilliSecsTimeout
[in] Time-out interval, in milliseconds. To block indefinitely, use the value INFINITE.
State
[out] Pointer to a variable that receives a member of the FILTER_STATE enumerated type, indicating the filter's state.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_POINTERNULL pointer argument.
VFW_S_STATE_INTERMEDIATEIntermediate state.
VFW_S_CANT_CUEThe filter is active, but cannot deliver data.

Remarks

State transitions can be asynchronous. If the filter is transitioning to a new state, and the method times out before the transition completes, the method returns VFW_S_STATE_INTERMEDIATE.

If a filter cannot deliver data for some reason, it returns VFW_S_CANT_CUE. Live capture filters return this value while paused, because they do not deliver data in the paused state.

For more information, see Data Flow in the Filter Graph.

IMediaFilter::GetSyncSource

IMediaFilter Interface

Retrieves the reference clock that the filter is using.

Syntax

HRESULT GetSyncSource(

  IReferenceClock **pClock
  );

Parameters

pClock
[out] Address of a variable that receives a pointer to the clock's IReferenceClock interface.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess
E_POINTERNULL pointer argument

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.

IMediaFilter::Pause

IMediaFilter Interface

Pauses the filter.

Syntax

HRESULT Pause(void);

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_FALSETransition is not complete.
S_OKSuccess. Transition is complete.

Remarks

When a filter is paused, it can receive, process, and deliver samples. However, a renderer filter will only accept one sample while paused. Therefore, when the filter graph is paused, samples move through the graph until the first sample reaches the renderer. At that point, streaming is paused until the Run method is called. Video renderers display the first sample as a still frame.

Live capture filters do not deliver any samples while paused, only while running.

The state transition might be asynchronous. If the method returns before the transition completes, the return value is S_FALSE. Renderer filters do not complete the state transition until they receive one sample.

IMediaFilter::Run

IMediaFilter Interface

Runs the filter.

Syntax

HRESULT Run(
    REFERENCE_TIME tStart
);

Parameters

tStart
Reference time corresponding to stream time 0.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_FALSETransition is not complete.
S_OKSuccess. Transition is complete.

Remarks

When a filter is running, it can receive, process, and deliver samples. Source filters generate new samples, and renderer filters render them.

The state transition might be asynchronous. If the method returns before the transition completes, the return value is S_FALSE.

Stream time is calculated as the current reference time minus tStart. To calculate when a media sample should be rendered, the renderer compares the time stamp with the current stream time. Thus, a media sample with a time stamp of zero should be rendered at time tStart. For more information, see Time and Clocks in DirectShow.

When an application calls the IMediaControl::Run method, the filter graph manager calls IMediaFilter::Run on each filter. It sets the value of tStart slightly in the future, to account for graph latency.

IMediaFilter::SetSyncSource

IMediaFilter Interface

Sets a reference clock for the filter.

Syntax

HRESULT SetSyncSource(
    IReferenceClock *pClock
);

Parameters

pClock
[in] Pointer to the clock's IReferenceClock interface, or NULL.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

If the pClock parameter is NULL, the filter does not use a reference clock. Renderer filters use the reference clock to schedule when samples get rendered. If there is no reference clock, a renderer filter renders every sample as soon as it arrives.

All the filters in the filter graph should share the same reference clock, in order to stay synchronized. Normally the filter graph manager selects the reference clock. An application can override the default clock by calling the IMediaFilter::SetSyncSource method on the filter graph manager. Only do this if you have a particular reason to prefer another clock.

IMediaFilter::Stop

IMediaFilter Interface

Stops the filter.

Syntax

HRESULT Stop(void);

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_FALSETransition is not complete.
S_OKSuccess. Transition is complete.

Remarks

When a filter is stopped, it does not process or deliver any samples, and it rejects samples from upstream filters.

The state transition might be asynchronous. If the method returns before the transition completes, the return value is S_FALSE.