Microsoft DirectX 8.0

IFilterGraph Interface

This interface provides methods for building a filter graph. An application can use it to add filters to the graph, connect or disconnect filters, remove filters, and perform other basic operations. However, the IGraphBuilder interface inherits from this interface and provides additional methods that are more sophisticated. Therefore, applications should use IGraphBuilder rather than using IFilterGraph directly.

The filter graph manager implements this interface.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IFilterGraph methodsDescription
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 two pins directly (without intervening filters).
Reconnect Breaks the existing pin connection and reconnects it to the same pin.
Disconnect Disconnects a specified pin.
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. Possible values include the following.

S_OKSuccess.
VFW_S_DUPLICATE_NAMESuccessfully added a filter with a duplicate name.
E_FAILFailure.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNull pointer argument.
VFW_E_CERTIFICATION_FAILUREUse of this filter is restricted by a software key.
VFW_E_DUPLICATE_NAMEFailed to add a filter with a duplicate name.

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 one of the following values, or an error value returned by IPin::Connect.

S_OKSuccess.
E_POINTERNull pointer argument.
VFW_E_NOT_IN_GRAPHOne of the specified pins is not in the graph.
VFW_E_CIRCULAR_GRAPHThe input pin is upstream of the output pin, which would result in a circular graph.

IFilterGraph::Disconnect

IFilterGraph Interface

Disconnects this pin.

Syntax

HRESULT Disconnect(
    IPin *ppin
);

Parameters

ppin
[in] Pointer to the pin to disconnect.

Return Value

Returns one of the following values.

S_OKSuccess.
S_FALSEPin was not connected. No error.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_STOPPEDThe filter is not stopped, but does not support reconnection while in a running state.

Remarks

This method does not completely break the connection. To completely break the connection, both ends must be disconnected.

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 one of the following values.

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory to create the enumerator.
E_POINTERNull pointer argument.

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 one of the following values.

S_OKSuccess.
E_POINTERNull pointer argument.
VFW_E_NOT_FOUNDNo filter was found with the specified name.

Remarks

If no filter is found, the method returns a NULL pointer in the ppFilter parameter.

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 one of the following values.

S_OKSuccess.
E_FAILFailure.
E_POINTERNull pointer argument.
VFW_E_NOT_CONNECTEDPin is not connected.
VFW_E_WRONG_STATEFilter is not stopped.

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 one of the following values.

S_OKSuccess.
E_FAIL Failure.
E_POINTER Null pointer argument.

Remarks

The filter graph implementation informs the filter that it is being removed by calling the IBaseFilter::JoinFilterGraph method with a NULL argument. It is not necessary to disconnect the filter's pins before calling RemoveFilter, but the filter graph should be in the Stopped state. If the filters are not stopped, RemoveFilter may fail to disconnect the pins and then fail to remove the filter from the graph. IGraphConfig::RemoveFilterEx enables an application to remove a filter without disconnecting the pins automatically, which improves performance if you want to move groups of connected filters into a new graph.

IFilterGraph::SetDefaultSyncSource

IFilterGraph Interface

Sets the default source of synchronization.

Syntax

HRESULT SetDefaultSyncSource(void);

Return Value

Returns S_OK if successful. Otherwise, returns VFW_E_NOT_STOPPED (indicating that the graph is not in a stopped state) or another error value.

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.