Microsoft DirectX 8.0 |
This interface provides methods that enable an application to build a filter graph. The filter graph manager implements this interface.
IGraphBuilder inherits from the IFilterGraph interface. IFilterGraph provides basic operations, such as adding a filter to the graph or connecting two pins. IGraphBuilder adds further methods that construct graphs from partial information. For example, the RenderFile method builds a graph for file playback, given the name of the file. The Render method renders data from an output pin by connecting new filters to the pin.
Using these methods, an application does not need to specify every filter and every pin connection in the graph. Instead, the filter graph manager selects filters that are registered on the user's system, introduces them into the graph, and connects them. Internally, it uses the filter mapper to look up filters in the registry. For more information, see IFilterMapper2.
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). IGraphBuilder methods Description Connect Connects two pins. If they will not connect directly, this method connects them with intervening transforms. Render Adds a chain of filters to a specified 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. SetLogFile Sets the file for logging actions taken when attempting to perform an operation. Abort Requests that the graph builder return as soon as possible from its current task. ShouldOperationContinue Queries whether the current operation should continue.
Requests that the graph builder return as soon as possible from its current task.
The current task may or may not fail to complete. It is possible that the fastest way for the graph builder to return from its current task is to complete it.
Syntax
HRESULT Abort(void);
Return Value
Returns S_OK.
Adds a source filter to the filter graph for a specific file. The IGraphBuilder::RenderFile method calls this to find the source filter.
Syntax
HRESULT AddSourceFilter( LPCWSTR lpwstrFileName, LPCWSTR lpwstrFilterName, IBaseFilter **ppFilter );
Parameters
- lpwstrFileName
- [in] Pointer to the file.
- lpwstrFilterName
- [in] Pointer to the name to give the source filter when it is added.
- ppFilter
- [out] Address of a pointer to an IBaseFilter interface on the filter that was added.
Return Value
Returns an HRESULT. Possible values include the following.
S_OK Success. E_NOINTERFACE Source filter does not support IFileSourceFilter interface. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument. VFW_E_CANNOT_LOAD_SOURCE_FILTER The source filter for this file could not be loaded. VFW_E_NOT_FOUND An object or name was not found. VFW_E_UNKNOWN_FILE_TYPE The media type of this file is not recognized.
Remarks
This method enables 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. 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.
The IGraphBuilder::RenderFile method adds the same source filter.
Connects the two pins, using intermediates if necessary.
Syntax
HRESULT Connect( IPin *ppinOut, IPin *ppinIn );
Parameters
- ppinOut
- [in] Pointer to the output pin.
- ppinIn
- [in] Pointer to the input pin.
Return Value
Returns an HRESULT. Possible values include the following.
S_OK Success. VFW_S_PARTIAL_RENDER Some of the streams in this movie are in an unsupported format. E_ABORT Operation aborted. E_POINTER NULL pointer argument. VFW_E_CANNOT_CONNECT No combination of intermediate filters could be found to make the connection. VFW_E_NOT_IN_GRAPH Cannot perform the requested function on an object that is not in the filter graph.
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.
During the connection process, the filter graph manager ignores pins on intermediate filters if the pin name begins with a tilde (~). For more information, see PIN_INFO.
Builds a filter graph that renders the data from this output pin.
Syntax
HRESULT Render( IPin *ppinOut );
Parameters
- ppinOut
- [in] Pointer to the output pin.
Return Value
Returns an HRESULT. Possible values include the following.
S_OK Success. VFW_S_AUDIO_NOT_RENDERED Cannot play back the audio stream: could not find a suitable renderer. VFW_S_DUPLICATE_NAME An attempt to add a filter with a duplicate name succeeded with a modified name. VFW_S_PARTIAL_RENDER Some of the streams in this movie are in an unsupported format. VFW_S_VIDEO_NOT_RENDERED Cannot play back the video stream: could not find a suitable renderer. E_ABORT Operation aborted. E_POINTER NULL pointer argument. VFW_E_CANNOT_CONNECT No combination of intermediate filters could be found to make the connection. VFW_E_CANNOT_RENDER No combination of filters could be found to render the stream. VFW_E_NO_ACCEPTABLE_TYPES There is no common media type between these pins. VFW_E_NOT_IN_GRAPH Cannot perform the requested function on an object that is not in the filter graph.
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.
During the connection process, the filter graph manager ignores pins on intermediate filters if the pin name begins with a tilde (~). For more information, see PIN_INFO.
Builds a filter graph that renders the specified file.
Syntax
HRESULT RenderFile( LPCWSTR lpwstrFile, LPCWSTR lpwstrPlayList );
Parameters
- lpwstrFile
- [in] Pointer to the name of the file, or the moniker of a capture device, containing the data to be rendered.
- lpwstrPlayList
- [in] Reserved. Must be NULL.
Return Value
Returns an HRESULT. Possible values include the following.
S_OK Success. VFW_S_AUDIO_NOT_RENDERED Cannot play back the audio stream: could not find a suitable renderer. VFW_S_DUPLICATE_NAME An attempt to add a filter with a duplicate name succeeded with a modified name. VFW_S_PARTIAL_RENDER Some of the streams in this movie are in an unsupported format. VFW_S_VIDEO_NOT_RENDERED Cannot play back the video stream: could not find a suitable renderer. E_ABORT Operation aborted. E_FAIL Failure. E_INVALIDARG Argument is invalid. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument. VFW_E_CANNOT_CONNECT No combination of intermediate filters could be found to make the connection. VFW_E_CANNOT_LOAD_SOURCE_FILTER The source filter for this file could not be loaded. VFW_E_CANNOT_RENDER No combination of filters could be found to render the stream. VFW_E_INVALID_FILE_FORMAT The file format is invalid. VFW_E_NOT_FOUND An object or name was not found. VFW_E_NOT_IN_GRAPH Cannot perform the requested function on an object that is not in the filter graph. VFW_E_UNKNOWN_FILE_TYPE The media type of this file is not recognized. VFW_E_UNSUPPORTED_STREAM Cannot play back the file: the format is not supported.
Remarks
This method adds a source filter that can handle the specified file. Then it renders the output pins on the source filter, adding intermediate filters if necessary. Filters are tried in the same order as for the IGraphBuilder::Connect method.
During the connection process, the filter graph manager ignores pins on intermediate filters if the pin name begins with a tilde (~). For more information, see PIN_INFO.
To determine the media type and compression scheme of the specified file, the Filter Graph Manager reads the first few bytes of the file, looking for file signatures as documented in the Registering a Custom File Type article.
The lpwstrFile parameter can specify a GraphEdit (.grf) file. The filter graph manager loads the graph from the .grf file.
The lpwstrFile parameter can also specify a device moniker for a capture device such as a USB camera or a DV camcorder. The filter graph manager creates a simple preview graph.
Sets the file for logging actions taken when attempting to perform an operation.
Syntax
HRESULT SetLogFile( HANDLE hFile );
Parameters
- hFile
- Handle to the log file.
Return Value
Returns S_OK.
Remarks
This method is for use in debugging; it is intended to help you determine the cause of any failure to automatically build a filter graph.
The hFile parameter must be an open file handle. Your application is responsible for opening the file and for closing it when you are done logging. Before closing the file handle, call SetLogFile with a NULL file handle. This will ensure that the component does not attempt to use the file handle after you have closed it.
Queries whether the current operation should continue. A filters that is performing some operation at the request of the graph can call this method to determine whether it should continue. Applications will not normally call this method.
Syntax
HRESULT ShouldOperationContinue(void);
Return Value
Returns an HRESULT. Possible values include the following.
S_OK The current operation should continue. S_FALSE The current operation should not continue. E_UNEXPECTED Unexpected error.