Microsoft DirectX 8.0 |
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 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 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).
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_OK Success. VFW_S_DUPLICATE_NAME Successfully added a filter with a duplicate name. E_FAIL Failure. E_OUTOFMEMORY Insufficient memory. E_POINTER Null pointer argument. VFW_E_CERTIFICATION_FAILURE Use of this filter is restricted by a software key. VFW_E_DUPLICATE_NAME Failed 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.
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_OK Success. E_POINTER Null pointer argument. VFW_E_NOT_IN_GRAPH One of the specified pins is not in the graph. VFW_E_CIRCULAR_GRAPH The input pin is upstream of the output pin, which would result in a circular graph.
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_OK Success. S_FALSE Pin was not connected. No error. E_FAIL Failure. E_POINTER Null pointer argument. VFW_E_NOT_STOPPED The 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.
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_OK Success. E_OUTOFMEMORY Insufficient memory to create the enumerator. E_POINTER Null 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.
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_OK Success. E_POINTER Null pointer argument. VFW_E_NOT_FOUND No filter was found with the specified name.
Remarks
If no filter is found, the method returns a NULL pointer in the ppFilter parameter.
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_OK Success. E_FAIL Failure. E_POINTER Null pointer argument. VFW_E_NOT_CONNECTED Pin is not connected. VFW_E_WRONG_STATE Filter 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.
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_OK Success. 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.
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.