Microsoft DirectX 8.0 |
This interface provides methods for starting, stopping, or removing chains of filters in a filter graph. The filter graph manager exposes this interface.
A filter chain is a sequence of filters, each with at most one connected input pin and one connected output pin, that forms an unbroken line of filters. A filter chain is defined by the filter at the start of the chain and the filter at the end of the chain. (These can be the same filter, making a chain of one filter.) By definition, there is a single stream path going from the start of the chain downstream to the end of the chain.
The methods on this interface are useful in situations where an entire stream of data can appear or disappear, such as a video conferencing application that receives multiple streams over a network. For more information, see Dynamic Graph Building. To control individual streams on a capture filter, use the IAMStreamControl interface instead.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IFilterChain methods Description StartChain Switches all the filters in a filter chain into a running state. StopChain Switches all the filters in a filter chain into a stopped state. RemoveChain Removes every filter in a filter chain from the filter graph. PauseChain Switches all the filters in a filter chain into a paused state.
Switches all the filters in a filter chain into a paused state.
Syntax
HRESULT PauseChain( IBaseFilter *pStartFilter, IBaseFilter *pEndFilter );
Parameters
- pStartFilter
- [in] Pointer to the filter at the start of the chain.
- pEndFilter
- [in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.
Return Value
Returns S_OK if successful. If the method fails, the return value may be VFW_E_NOT_PAUSED or another HRESULT value.
Remarks
If this method cannot switch a given filter into a paused state, it stops all of the filters in chain. The filter graph must be paused when you call this method.
Removes every filter in a filter chain from the filter graph.
Syntax
HRESULT RemoveChain( IBaseFilter *pStartFilter, IBaseFilter *pEndFilter );
Parameters
- pStartFilter
- [in] Pointer to the filter at the start of the chain.
- pEndFilter
- [in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the failure otherwise.
Remarks
You can call this method while the graph is running; the method stops the filters in the chain before removing them from the graph.
Switches all the filters in a filter chain into a running state.
Syntax
HRESULT StartChain( IBaseFilter *pStartFilter, IBaseFilter *pEndFilter );
Parameters
- pStartFilter
- [in] Pointer to the filter at the start of the chain.
- pEndFilter
- [in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.
Return Value
Returns S_OK if successful. If the method fails, the return value may be VFW_E_NOT_RUNNING or another HRESULT value.
Remarks
If this method cannot switch a given filter into a running state, it leaves all the filters in a stopped state. The filter graph must be running when you call this method.
Switches all the filters in a filter chain into a stopped state.
Syntax
HRESULT StopChain( IBaseFilter *pStartFilter, IBaseFilter *pEndFilter );
Parameters
- pStartFilter
- [in] Pointer to the filter at the start of the chain.
- pEndFilter
- [in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the failure otherwise.