Microsoft DirectX 8.0

IGraphBuilder Interface

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 methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IFilterGraph methodsDescription
AddFilterAdds a filter to the graph and gives it a name.
RemoveFilterRemoves a filter from the graph.
EnumFiltersProvides an enumerator for all filters in the graph.
FindFilterByNameFinds a filter that was added with a specified name.
ConnectDirectConnects two pins directly (without intervening filters).
ReconnectBreaks the existing pin connection and reconnects it to the same pin.
DisconnectDisconnects a specified pin.
SetDefaultSyncSourceSets the default synchronization source (a clock).
IGraphBuilder methodsDescription
ConnectConnects two pins. If they will not connect directly, this method connects them with intervening transforms.
RenderAdds a chain of filters to a specified output pin to render it.
RenderFileBuilds a filter graph that renders the specified file.
AddSourceFilterAdds a source filter to the filter graph for a specific file.
SetLogFileSets the file for logging actions taken when attempting to perform an operation.
AbortRequests that the graph builder return as soon as possible from its current task.
ShouldOperationContinueQueries whether the current operation should continue.

IGraphBuilder::Abort

IGraphBuilder Interface

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.

IGraphBuilder::AddSourceFilter

IGraphBuilder Interface

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_OKSuccess.
E_NOINTERFACESource filter does not support IFileSourceFilter interface.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.
VFW_E_CANNOT_LOAD_SOURCE_FILTERThe source filter for this file could not be loaded.
VFW_E_NOT_FOUNDAn object or name was not found.
VFW_E_UNKNOWN_FILE_TYPEThe 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.

IGraphBuilder::Connect

IGraphBuilder Interface

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_OKSuccess.
VFW_S_PARTIAL_RENDERSome of the streams in this movie are in an unsupported format.
E_ABORT Operation aborted.
E_POINTERNULL pointer argument.
VFW_E_CANNOT_CONNECTNo combination of intermediate filters could be found to make the connection.
VFW_E_NOT_IN_GRAPHCannot 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.

IGraphBuilder::Render

IGraphBuilder Interface

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_OKSuccess.
VFW_S_AUDIO_NOT_RENDEREDCannot play back the audio stream: could not find a suitable renderer.
VFW_S_DUPLICATE_NAMEAn attempt to add a filter with a duplicate name succeeded with a modified name.
VFW_S_PARTIAL_RENDERSome of the streams in this movie are in an unsupported format.
VFW_S_VIDEO_NOT_RENDEREDCannot play back the video stream: could not find a suitable renderer.
E_ABORT Operation aborted.
E_POINTERNULL pointer argument.
VFW_E_CANNOT_CONNECTNo combination of intermediate filters could be found to make the connection.
VFW_E_CANNOT_RENDERNo combination of filters could be found to render the stream.
VFW_E_NO_ACCEPTABLE_TYPESThere is no common media type between these pins.
VFW_E_NOT_IN_GRAPHCannot 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.

IGraphBuilder::RenderFile

IGraphBuilder Interface

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_OKSuccess.
VFW_S_AUDIO_NOT_RENDEREDCannot play back the audio stream: could not find a suitable renderer.
VFW_S_DUPLICATE_NAMEAn attempt to add a filter with a duplicate name succeeded with a modified name.
VFW_S_PARTIAL_RENDERSome of the streams in this movie are in an unsupported format.
VFW_S_VIDEO_NOT_RENDEREDCannot play back the video stream: could not find a suitable renderer.
E_ABORT Operation aborted.
E_FAILFailure.
E_INVALIDARGArgument is invalid.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.
VFW_E_CANNOT_CONNECTNo combination of intermediate filters could be found to make the connection.
VFW_E_CANNOT_LOAD_SOURCE_FILTERThe source filter for this file could not be loaded.
VFW_E_CANNOT_RENDERNo combination of filters could be found to render the stream.
VFW_E_INVALID_FILE_FORMATThe file format is invalid.
VFW_E_NOT_FOUNDAn object or name was not found.
VFW_E_NOT_IN_GRAPHCannot perform the requested function on an object that is not in the filter graph.
VFW_E_UNKNOWN_FILE_TYPEThe media type of this file is not recognized.
VFW_E_UNSUPPORTED_STREAMCannot 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.

IGraphBuilder::SetLogFile

IGraphBuilder Interface

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.

IGraphBuilder::ShouldOperationContinue

IGraphBuilder Interface

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_OKThe current operation should continue.
S_FALSE The current operation should not continue.
E_UNEXPECTED Unexpected error.