IFilterGraph Interface

The IFilterGraph interface is an abstraction representing a graph of filters. All filters in the graph share the same clock. They might or might not also be connected and stream data between them. This interface enables filters to be joined into a graph and operated as a unit. Unlike the IGraphBuilder interface, this interface does not use heuristics to connect and build the filter graph.

This interface is implemented on the filter graph manager and is not intended for implementation by developers.

Applications should not use this interface directly but instead should use the IGraphBuilder interface, which inherits this interface.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IFilterGraph methods Description
AddFilter Adds a filter to the graph and gives it a name.
RemoveFilter Removes a filter from the graph.
EnumFilters Provides an enumerator for all filters in the graph.
FindFilterByName Finds a filter that was added with a specified name.
ConnectDirect Connects the two IPin objects directly (without intervening filters).
Reconnect Breaks the existing pin connection and reconnects it to the same pin.
Disconnect Disconnects this pin, if connected.
SetDefaultSyncSource Sets the default synchronization source (a clock).

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IFilterGraph methods	Description
AddFilter	Adds a filter to the graph and gives it a name.
RemoveFilter	Removes a filter from the graph.
EnumFilters	Provides an enumerator for all filters in the graph.
FindFilterByName	Finds a filter that was added with a specified name.
ConnectDirect	Connects the two IPin objects directly (without intervening filters).
Reconnect	Breaks the existing pin connection and reconnects it to the same pin.
Disconnect	Disconnects this pin, if connected.
SetDefaultSyncSource	Sets the default synchronization source (a clock).

IFilterGraph::AddFilter

IFilterGraph Interface

Adds a filter to the graph and gives it a name.

Syntax

HRESULT AddFilter(
    IBaseFilter *pFilter,
    LPCWSTR pName
);

Parameters

pFilter
[in] Pointer to the filter to add to the graph.
pName
[in] Pointer to the name of the filter.

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 name of the filter can be NULL, in which case the filter graph manager will generate a name. If the name is not NULL and is not unique, this method will modify the name in an attempt to generate a new unique name. If this is successful, this method returns VFW_S_DUPLICATE_NAME. If it cannot generate a unique name, it returns VFW_E_DUPLICATE_NAME.
AddFilter calls the filter's IBaseFilter::JoinFilterGraph method to inform the filter that it has been added. AddFilter must be called before attempting to use the IGraphBuilder::Connect, IFilterGraph::ConnectDirect, or IGraphBuilder::Render method to connect or render pins belonging to the added filter.

IFilterGraph::ConnectDirect

IFilterGraph Interface

Connects the two pins directly (without intervening filters).

Syntax

HRESULT ConnectDirect(
    IPin *ppinOut,
    IPin *ppinIn,
    const AM_MEDIA_TYPE *pmt
);

Parameters

ppinOut
[in] Pointer to the output pin.
ppinIn
[in] Pointer to the input pin.
pmt
[in] Pointer to the media type to use for the connection (optional; that is, can be NULL).

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.

IFilterGraph::Disconnect

IFilterGraph Interface

Disconnects this pin.

Syntax

HRESULT Disconnect(
    IPin *ppin
);

Parameters

ppin
[in] Pointer to the pin to disconnect.

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 does not completely break the connection. To completely break the connection, both ends must be disconnected.
This method results in a successful no operation (no-op) if the pin is not connected.

IFilterGraph::EnumFilters

IFilterGraph Interface

Provides an enumerator for all filters in the graph.

Syntax

HRESULT EnumFilters(
    IEnumFilters **ppEnum
);

Parameters

ppEnum
[out] Address of a pointer to the enumerator.

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 interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.

IFilterGraph::FindFilterByName

IFilterGraph Interface

Finds a filter that was added to the filter graph with a specific name.

Syntax

HRESULT FindFilterByName(
    LPCWSTR pName,
    IBaseFilter **ppFilter
);

Parameters

pName
[in, string] Pointer to the name to search for.
ppFilter
[out] Address of a pointer to an IBaseFilter interface on the found filter.

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 function fails and sets pointers to the ppFilter parameter to NULL if the name is not in this graph.

IFilterGraph::Reconnect

IFilterGraph Interface

Disconnects this and the pin to which it connects and then reconnects it to the same pin. This enables the details of the connection, such as media type and allocator, to be renegotiated.

Syntax

HRESULT Reconnect(
    IPin *ppin
);

Parameters

ppin
[in] Pointer to the pin to disconnect and reconnect.

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 performs its operation on a separate thread that will not hold any relevant locks. It can be called by a pin or filter to enable renegotiation of the connection. When a transform filter has its input connected, it must agree upon some media type. When the output is connected, it might discover that, to please both its upstream and downstream connections, it would have been better to have chosen a different media type for the upstream connection. The solution is to reconnect the input pin. The caller of this method should ensure (for example, by calling IPin::QueryAccept) that the resulting renegotiation will succeed, because the reconnection process is performed asynchronously and there is no mechanism for reporting or correcting errors.

IFilterGraph::RemoveFilter

IFilterGraph Interface

Removes a filter from the graph.

Syntax

HRESULT RemoveFilter(
    IBaseFilter *pFilter
);

Parameters

pFilter
[in] Pointer to the filter to be removed from the graph.

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 filter graph implementation informs the filter that it is being removed by calling the IBaseFilter::JoinFilterGraph method with a NULL argument.

IFilterGraph::SetDefaultSyncSource

IFilterGraph Interface

Sets the default source of synchronization.

Syntax

HRESULT SetDefaultSyncSource(void);

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 used when no clock has been given to the filter graph, and the filter graph manager must find a clock to use as the synchronization source. The filter graph manager tries all connected filters, starting with renderers, and selects the first one that provides an IReferenceClock interface. If no connected filters are found, the filter graph manager will select an unconnected filter that exports a clock. Typically, this will be the audio rendering filter. If no unconnected filter exports a clock, the filter graph manager creates a system clock.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.