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 allows 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.
When to Implement
This interface is implemented on the filter graph manager and is not intended for implementation by developers.
When to Use
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 | Returns 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). |
Adds a filter to the graph and names it by using the pName parameter.
HRESULT AddFilter(
IBaseFilter * pFilter,
LPCWSTR pName
);
Returns an HRESULT value.
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.
Connects the two pins directly (without intervening filters).
HRESULT ConnectDirect(
IPin * ppinOut,
IPin * ppinIn,
const AM_MEDIA_TYPE * pmt
);
Returns an HRESULT value.
Disconnects this pin.
HRESULT Disconnect(
IPin * ppin
);
Returns an HRESULT value.
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.
Provides an enumerator for all filters in the graph.
HRESULT EnumFilters(
IEnumFilters ** ppEnum
);
Returns an HRESULT value.
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.
Finds a filter that was added to the filter graph with a specific name.
HRESULT FindFilterByName(
LPCWSTR pName,
IBaseFilter ** ppFilter
);
Returns an HRESULT value.
This function fails and sets pointers to the ppFilter parameter to NULL if the name is not in this graph.
Disconnects this and the pin to which it connects and then reconnects it to the same pin. This allows the details of the connection, such as media type and allocator, to be renegotiated.
HRESULT Reconnect(
IPin * ppin
);
Returns an HRESULT value.
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 allow 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.
Removes a filter from the graph.
HRESULT RemoveFilter(
IBaseFilter * pFilter
);
Returns an HRESULT value.
The filter graph implementation informs the filter that it is being removed by calling the IBaseFilter::JoinFilterGraph method with a NULL argument.
Sets the default source of synchronization.
HRESULT SetDefaultSyncSource(void);
Returns an HRESULT value.
This method is used when no clock has been given to the filter graph, and the filter graph manager consequently must find a clock to use as the synchronization source. The filter graph manager first tries all filters, starting with renderers, to see if any filter exports a clock (by providing an IReferenceClock interface). The filter graph manager will choose the first filter that it finds, providing that filter is connected to an upstream source. If no connected filters are found, the first filter if IReferenceClock is used. Typically, this will be the audio rendering filter. If no filter exports a clock, the filter graph manager uses a system clock.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.