The IGraphBuilder interface allows applications to call upon the filter graph manager to attempt to build a complete filter graph, or parts of a filter graph given only partial information, such as the name of a file or the interfaces of two separate pins. The filter mapper looks up filters in the registry to configure the filter graph in a meaningful way.
IGraphBuilder inherits from the IFilterGraph interface and exposes all its methods. For this reason, IFilterGraph should normally not be used directly.
When to Implement
This interface is implemented on the filter graph manager and is not intended for implementation by developers.
When to Use
Applications use this interface to create a filter graph, add filters to or remove filters from a filter graph, enumerate all the filters in a filter graph, and force connections when adding a filter. Filters typically use the interface to reconnect pins during the connection and negotiation process of building a filter graph.
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).
IGraphBuilder methods Description
Connect Connects two IPin objects. If they will not connect directly, this method connects them with intervening transforms.
Render Adds a chain of filters to this output pin to render it.
RenderFile Builds a filter graph that renders the specified file.
AddSourceFilter Adds a source filter to the filter graph for a specific file. The IGraphBuilder::RenderFile method calls this to find the source filter.
SetLogFile Sets the Log File into which actions taken in attempting to perform an operation are logged.
--------------------------------------------------------------------------------
IGraphBuilder::AddSourceFilter
IGraphBuilder Interface
Adds a source filter to the filter graph for a specific file.
HRESULT AddSourceFilter(
LPCWSTR lpwstrFileName,
LPCWSTR lpwstrFilterName,
IBaseFilter* * ppFilter
);
Parameters
lpwstrFileName
Pointer to the file.
lpwstrFilterName
Name to give the source filter when it is added.
ppFilter
[out] Pointer to an IBaseFilter interface on the filter that was added.
Return Values
Returns an HRESULT value.
Remarks
This method allows you to obtain and retain more control over building the rest of the graph. For example, you can use the IFilterGraph::AddFilter method to add a renderer of your choice, and then use the IGraphBuilder::Connect method to connect the two filters. The IBaseFilter interface exposed by the source filter is returned in the ppFilter parameter, and the reference is already added by the IUnknown::AddRef method. The lpwstrFilterName parameter is used to allow the filter to be Identified by this name in this filter graph. For more information, see FindFilterByName.
It is the application's responsibility to find the output pin of the added source filter in order to build the rest of the filter graph, which can be done by calling IGraphBuilder::Render on the output pin, to build the entire filter graph automatically, or by adding and connecting filters individually. Note that, when adding filters individually, the asynchronous file reader source filter and the URL moniker source filter do not parse the data, so the output pins of these source filters can be connected only to a parser filter, such as the MPEG splitter filter.
Note that the IGraphBuilder::RenderFile method adds the same source filter.
--------------------------------------------------------------------------------
IGraphBuilder::Connect
IGraphBuilder Interface
Connects the two pins, using intermediates if necessary.
HRESULT Connect(
IPin * ppinOut,
IPin * ppinIn
);
Parameters
ppinOut
Output pin.
ppinIn
Input pin.
Return Values
Returns an HRESULT value.
Remarks
This method connects these two pins directly or indirectly, using transform filters if necessary. The method either succeeds or leaves the filter graph unchanged. The filter graph manager attempts a direct connection. If that fails, it attempts to use any available transforms provided by filters that are already in the filter graph. (It enumerates these in an arbitrary order.) If that fails, it attempts to find filters from the registry to provide a transform. These will be tried in order of merit.
--------------------------------------------------------------------------------
IGraphBuilder::Render
IGraphBuilder Interface
Builds a filter graph that renders the data from this output pin.
HRESULT Render(
IPin * ppinOut
);
Parameters
ppinOut
Output pin.
Return Values
Returns an HRESULT value, which can include one of the following: VFW_S_AUDIO_NOT_RENDERED
VFW_S_DUPLICATE_NAME
VFW_S_PARTIAL_RENDER
VFW_S_RPZA
VFW_S_VIDEO_NOT_RENDERED
Remarks
This method connects this output pin directly or indirectly to a filter or filters that will render it, using transform filters as intermediary filters if necessary. Filters are tried in the same order as for the IGraphBuilder::Connect method.
--------------------------------------------------------------------------------
IGraphBuilder::RenderFile
IGraphBuilder Interface
Builds a filter graph that renders the specified file.
HRESULT RenderFile(
LPCWSTR lpwstrFile,
LPCWSTR lpwstrPlayList
);
Parameters
lpwstrFile
Name of the file containing the data to be rendered.
lpwstrPlayList
Playlist name. Reserved; must be NULL. (This parameter is currently unimplemented.)
Return Values
Returns an HRESULT value, which can include one of the following: VFW_S_AUDIO_NOT_RENDERED
VFW_S_DUPLICATE_NAME
VFW_S_PARTIAL_RENDER
VFW_S_RPZA
VFW_S_VIDEO_NOT_RENDERED
Remarks
If the lpwstrPlayList parameter is NULL, this method would use the default playlist, which typically renders the entire file.
--------------------------------------------------------------------------------
IGraphBuilder::SetLogFile
IGraphBuilder Interface
Sets the file into which actions taken in attempting to perform an operation are logged.
HRESULT SetLogFile(
HANDLE hFile
);
Parameters
hFile
Handle to the log file.
Return Values
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed: Value Meaning
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 hFile parameter must be an open file handle. After calling this method with a valid file handle, actions taken by IGraphBuilder methods when attempting to build a filter graph are logged to this file. This is intended to help you determine the cause of any failure to automatically build a filter graph.
