Microsoft DirectX 8.0

IGraphConfig Interface

The Filter Graph Manager exposes IGraphConfig to support dynamic graph building. This interface enables applications and filters to reconfigure the filter graph while the graph is in a running state, and without losing data from the stream.

The most straightforward way to rebuild the graph dynamically is to call the Reconnect method. This method handles most of the details of dynamically rebuilding the graph. If a situation ever arises where you want to implement your own technique, IGraphConfig also provides the Reconfigure method. This method obtains a lock on the filter graph and then calls a callback function in your application, which reconfigures the graph. With this method, most of the work is shifted to your application. For more information, see Dynamic Graph Building.

To optimize the process of adding and removing filters, the filter graph maintains a cache of filters. During a call to the Reconnect method, you can specify that any filters removed from the graph get added to the cache. You can also add a filter to the cache directly, if you know it is likely to be needed, by calling AddFilterToCache. The IGraphBuilder::Render, IGraphBuilder::RenderFile, and IGraphBuilder::Connect methods automatically try to use filters in the cache before using other filters. Also, in the Reconnect method you can specify that only cached filters will be used for the reconnection. Note that filters held in the cache are not actually part of the graph. They are disconnected from any pins and are kept in a stopped state.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IGraphConfig methodsDescription
ReconnectPerforms a dynamic reconnection between two pins.
ReconfigureLocks the filter graph and calls a callback function in the application or filter to perform a dynamic reconfiguration.
AddFilterToCacheAdds a filter to the filter cache.
RemoveFilterFromCacheRemoves a filter from the filter cache.
EnumCacheFilterEnumerates the filters in the filter cache.
GetStartTimeRetrieves the reference time used when the filter graph was last put into a running state.
PushThroughDataPushes data through the filter graph to the specified pin.
SetFilterFlagsSets a filter's configuration information.
GetFilterFlagsRetrieves a filter's configuration information.
RemoveFilterExRemoves a filter from the filter graph.

IGraphConfig::AddFilterToCache

IGraphConfig Interface

Adds a filter to the filter cache.

Syntax

HRESULT AddFilterToCache(
    IBaseFilter *pFilter
);

Parameters

pFilter
[in] Pointer to the IBaseFilter interface of the filter.

Return Value

Returns one of the following HRESULT values.

E_FAILFailure.
E_POINTERNull pointer argument.
S_FALSEFilter is already in the cache.
S_OKFilter was added to the cache.

Remarks

You must disconnect all of the filter's pins before calling this method, or the method will fail. If the filter is in the filter graph, this method will remove it. This method will also put the filter into a stopped state, if it is not already.

IGraphConfig::EnumCacheFilter

IGraphConfig Interface

Enumerates the filters in the filter cache.

Syntax

HRESULT EnumCacheFilter(
    IEnumFilters **pEnum
);

Parameters

pEnum
[out] Address of a pointer to the IEnumFilters interface on the filter enumerator.

Return Value

Returns one of the following HRESULT values.

E_OUTOFMEMORYFailed to allocate necessary memory.
E_POINTERNull pointer argument.
S_OKSuccess.

IGraphConfig::GetFilterFlags

IGraphConfig Interface

Retrieves a filter's configuration information.

Syntax

HRESULT GetFilterFlags(
    IBaseFilter *pFilter, 
    DWORD *pdwFlags
);

Parameters

pFilter
[in] Pointer to a filter in the filter graph.
pdwFlags
[out] Pointer to a variable of type DWORD that receives the current configuration flags.

Return Value

Returns one of the following HRESULT values.

E_POINTERNull pointer argument.
S_OKSuccess.
VFW_E_NOT_IN_GRAPHThe filter is not in the graph.

See Also

SetFilterFlags

IGraphConfig::GetStartTime

IGraphConfig Interface

Retrieves the reference time that was used when the filter graph was last put into a running state.

Syntax

HRESULT GetStartTime(
    REFERENCE_TIME *prtStart
);

Parameters

prtStart
[out] Pointer to a variable that receives the start time.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
VFW_E_WRONG_STATEFilter graph is not in a running state.

Remarks

The filter graph must currently be in a running state or this method will fail.

IGraphConfig::PushThroughData

IGraphConfig Interface

Pushes data through the filter graph to the specified pin.

Syntax

HRESULT PushThroughData(
    IPin *pOutputPin,
    IPinConnection *pConnection,
    HANDLE hEventAbort
);

Parameters

pOutputPin
[in] Pointer to an output pin in the filter graph.
pConnection
[in] Pointer to an input pin in the filter graph, or NULL.
hEventAbort
[in] Handle to an event. If the caller is a filter calling on one of its data processing threads, this parameter should be a handle to an event that will be signaled when the filter is put into a stopped state. Otherwise, this parameter can be NULL. For more information, see Remarks.

Return Value

Returns S_OK if successful. Otherwise, returns an error code that may be one of the following values, or others not listed.

E_OUTOFMEMORYFailed to allocate necessary memory.
VFW_E_NOT_FOUNDCould not find a candidate input pin.
VFW_E_STATE_CHANGEDFilter state changed during the operation.

Remarks

This method pushes through any pending data, from a specified output pin down to a specified input pin. Optionally, you can leave the input pin unspecified and let the method search the filter graph for the best candidate. Do not call this method from the thread that is pushing data.

If a filter calls this method on one of its own data processing threads, it creates the potential for a deadlock. The method obtains a lock on the filter graph, which can block the filter from stopping on receiving a call to IMediaFilter::Stop. To prevent this situation, the method takes a handle to an event object provided by the filter. The filter should signal the event if it receives a call to its Stop method.

IGraphConfig::Reconfigure

IGraphConfig Interface

Locks the filter graph and calls a callback function in the application or filter to perform a dynamic reconfiguration.

Syntax

HRESULT Reconfigure(
    IGraphConfigCallback *pCallback,
    PVOID pvContext,
    DWORD dwFlags,
    HANDLE hAbortEvent
);

Parameters

pCallback
[in] Pointer to the IGraphConfigCallback callback interface on the application or filter.
pvContext
[in] Pointer to a variable of type PVOID that is passed to the callback routine.
dwFlags
[in] Application-defined flags that are passed to the callback routine.
hAbortEvent
[in] Handle to an event. If the caller is a filter calling on one of its data processing threads, this parameter should be a handle to an event that will be signaled when the filter is put into a stopped state. Otherwise, this parameter can be NULL. For more information, see Remarks.

Return Value

Returns S_OK if successful, or an error code otherwise. Possible errors include VFW_E_WRONG_STATE, if the method could not obtain a lock on the filter graph; whatever HRESULT was returned by the callback routine; or an error code indicating that the graph could not put the filters into a running state.

Remarks

This method is provided so that an application or filter can implement specialized dynamic graph building. In most cases, however, the IGraphConfig::Reconnect method is adequate, and should be preferred because it handles most of the implementation details.

Before calling this method, block any streams as needed and push the data through the graph (see IPinFlowControl::Block and IGraphConfig::PushThroughData). If the callback method succeeds, IGraphConfig::Reconfigure attempts to put all the filters into a running state. (The caller must then unblock the data flow.) Otherwise, it returns whatever error code the callback method returned.

If a filter calls this method on one of its own data processing threads, it creates the potential for a deadlock. The method obtains a lock on the filter graph, which can block the filter from stopping on receiving a call to IMediaFilter::Stop. To prevent this situation, the method takes a handle to an event object provided by filter. The filter should signal the event if it receives a call to its Stop method.

IGraphConfig::Reconnect

IGraphConfig Interface

Performs a dynamic reconnection between two pins.

Syntax

HRESULT Reconnect(
    IPin *pOutputPin, 
    IPin *pInputPin,
    const AM_MEDIA_TYPE *pmtFirstConnection,
    IBaseFilter *pUsingFilter,
    HANDLE hAbortEvent,
    DWORD dwFlags
);

Parameters

pOutputPin
[in] Pointer to an output pin. Can be NULL, in which case pInputPin must not be NULL.
pInputPin
[in] Pointer to an input pin. Can be NULL, in which case pOutputPin must not be NULL.
pmtFirstConnection
[in] Pointer to an AM_MEDIA_TYPE structure that specifies the media type for the first pin connection made during the reconnection. If this parameter is NULL, the first connection can have any media type.
pUsingFilter
[in] Pointer to an optional filter to use in the reconnection. The filter must already be in the graph. Can be NULL.
hAbortEvent
[in] Handle to an event. If the caller is a filter calling on one of its data processing threads, this parameter should be a handle to an event that will be signaled when the filter is put into a stopped state. Otherwise, this parameter can be NULL. For more information, see Remarks.
dwFlags
[in] Combination of flags from the AM_GRAPH_CONFIG_RECONNECT_FLAGS enumeration, specifying how to perform the reconnection.

Return Value

Returns S_OK if successful. Otherwise, returns an error code that may be one of the following values, or others not listed.

E_INVALIDARGInvalid argument. (For example, both pInputPin and pOutputPin are NULL.)
E_NOINTERFACEInput pin does not support IPinConnection.
VFW_E_CANNOT_CONNECTUnable to connect filter.
VFW_E_STATE_CHANGEDThe state of the filter changed. Unable to complete the operation.

Remarks

If you specify only one pin, the method will search for the other pin. By default, however, the search fails if it reaches a filter that was added to the graph by means of the IFilterGraph::AddFilter method. To override this behavior, call IGraphConfig::SetFilterFlags and set the AM_FILTER_FLAGS_REMOVABLE flag on the filter.

The reconnection process involves several steps, most of them handled inside this method:

  1. First, before calling the method, make sure to block the flow of data along the path that is being reconfigured. Applications should call the IPinFlowControl::Block method to do this. If the caller is a filter, rather than an application, possibly the filter can control the data flow internally.
  2. The specified output and input pins define the starting and ending points for the reconnection. The input pin must support the IPinConnection interface. If you leave one of these pins unspecified (by passing a NULL parameter), the method searches the filter graph to find a candidate pin for reconnection. (To find an input pin, it searches downstream from the output pin; to find an output pin, it searches upstream from the input pin.)
  3. The method pushes any pending data through the filter graph (through an internal call to PushThroughData).
  4. If you have specified a filter to insert into the graph, the method connects the starting output pin to the filter's input pin, and connects the filter's output pin to the final input pin. If you do not specify a filter, the method simply connects the output pin to the input pin. In either case, the method inserts any transform filters required to complete the connections. (However, you can override this behavior by setting the appropriate flag; for more information see the description of the dwFlags parameter.)
  5. Finally, the method places the new filters into a running state. It is up to the caller to restart the data flow. Applications can do this by calling IPinFlowControl::Block with no flags.

If a filter calls this method on one of its own data processing threads, it creates the potential for a deadlock. The method obtains a lock on the filter graph, which can block the filter from stopping on receiving a call to IMediaFilter::Stop. To prevent this situation, the method takes a handle to an event object provided by filter. The filter should signal the event if it receives a call to its Stop method.

IGraphConfig::RemoveFilterEx

IGraphConfig Interface

Removes a filter from the filter graph.

Syntax

HRESULT RemoveFilterEx( 
    IBaseFilter *pFilter, 
    DWORD Flags 
);

Parameters

pFilter
[in] Pointer to the filter to remove from the graph.
Flags
[in] Combination of flags from the REM_FILTER_FLAGS enumerated type.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the failure.

Remarks

This method extends the IFilterGraph::RemoveFilter method by accepting a flag that specifies the behavior of the method. This flag enables an application to remove a filter without disconnecting the pins automatically, which improves performance when moving groups of connected filters into a new graph.

By default, this method disconnects the filter before removing it from the graph. Use the REMFILTERF_LEAVECONNECTED flag to leave the filter connected.

RemoveFilterEx

IGraphConfig::RemoveFilterFromCache

IGraphConfig Interface

Removes a filter from the filter cache.

Syntax

HRESULT RemoveFilterFromCache(
    IBaseFilter *pFilter
);

Parameters

pFilter
[in] Pointer to the filter to remove from the cache.

Return Value

Returns one of the following HRESULT values.

E_POINTERNull pointer argument.
S_FALSEFilter was not in the cache.
S_OKFilter was successfully removed from the cache.

IGraphConfig::SetFilterFlags

IGraphConfig Interface

Sets a filter's configuration information.

Syntax

HRESULT SetFilterFlags(
    IBaseFilter *pFilter, 
    DWORD dwFlags
);

Parameters

pFilter
[in] Pointer to a filter in the filter graph.
dwFlags
[in] Value specifying the new configuration flags. Must be one of the following values.
ZeroNo flags set.
AM_FILTER_FLAGS_REMOVABLEThe filter is removable during a dynamic reconnection. For more information, see Remarks.

Return Value

Returns one of the following HRESULT values.

E_POINTERNull pointer argument.
E_INVALIDARGInvalid argument.
S_OKSuccess.
VFW_E_NOT_IN_GRAPHThe filter is not in the graph.

Remarks

The AM_FILTER_FLAGS_REMOVABLE flag changes the behavior of the IGraphConfig::Reconnect method. The Reconnect method performs a dynamic reconnection between two pins. If the caller specifies one pin, but leaves the other pin unspecified, Reconnect searches upstream or downstream from the specified pin to find a suitable match. By default, however, the search fails if it reaches a filter that was added to the graph by means of the IFilterGraph::AddFilter method. To override this behavior, call SetFilterFlags and set the AM_FILTER_FLAGS_REMOVABLE flag on the filter.