ICutListGraphBuilder allows you to easily implement one or more cutlist filter graphs. The simplest way to use this object is to add a cutlist using the ICutListGraphBuilder::AddCutList method and then use the ICutListGraphBuilder::Render method to create and connect the graph.
You can also use this interface to save your movie to a file. Use ICutListGraphBuilder::SetOutputFileName to specify the media subtype (such as MEDIASUBTYPE_Avi) and the filename. ICutListGraphBuilder attempts to connect the filters needed to write to this file, so that when you call the ICutListGraphBuilder::Render method, the filter graph manager creates a filter graph which writes to a file.
See IStandardCutList for more information about other cutlist interfaces typically used by applications.
When to Implement
Do not implement this interface. DirectShow implements it for you.
When to Use
Use this interface in your application when you want to provide cutlist functionality to the user.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Retrieves pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| ICutListGraphBuilder methods | Description |
| SetFilterGraph | Sets the filter graph which the cutlist graph builder will use |
| GetFilterGraph | Retrieves the filter graph the cutlist graph builder is using to implement the playback of the cutlist. |
| AddCutList | Adds a cutlist to the filter graph. |
| RemoveCutList | Removes a cutlist from a filter graph. |
| SetOutputFileName | Specifies the output file and media subtype to use when writing the movie to a file. |
| Render | Creates the final cutlist filter graph. |
| GetElementFlags | Retrieves the flags of a given element. |
Sets the filter graph which the cutlist graph builder will use.
HRESULT SetFilterGraph(
IGraphBuilder *pFilterGraph
);
Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Could not allocate required memory. |
| S_OK | Success. |
The filter graph can contain filters which will be used preferentially by the cutlist graph builder.
Retrieves the filter graph the cutlist graph builder is using to implement the playback of the cutlist
HRESULT GetFilterGraph(
IGraphBuilder **ppFilterGraph
);
Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Could not allocate required memory. |
| S_OK | Success. |
This method can be called before you have added any filters or cutlists to the filter graph. This is useful, for instance, to acquire the IMediaControl and IMediaEvent interface of the playback graph.
This method increments the reference count on ppFilterGraph. Be sure to decrement the reference count on the filter graph object by calling its Release method when you're done.
Adds a cutlist to the filter graph.
HRESULT AddCutList(
IStandardCutList *pCutList
);
Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Could not allocate required memory. |
| S_OK | Success. |
ICutListGraphBuilder attempts to create a graph that plays back all of the cutlists you have added to the graph.
If you call this method to add the cutlist to the filter graph, you must later call ICutListGraphBuilder::RemoveCutList to remove the cutlist from the filter graph. You must do so before releasing the filter graph.
Removes a cutlist from a filter graph.
HRESULT RemoveCutList(
IStandardCutList *pCutList
);
Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Could not allocate required memory. |
| S_OK | Success. |
If you called ICutListGraphBuilder::AddCutList to add the cutlist to the filter graph, you must call this method before releasing the filter graph.
This method should only be called when the graph is stopped, otherwise resources will not be properly freed.
Specifies the output file and media subtype to use when writing the movie to a file.
HRESULT SetOutputFileName(
const GUID *pType,
LPCOLESTR lpwstrFile,
IBaseFilter **ppf,
IFileSinkFilter **pSink
);
&MEDIASUBTYPE_Avi
because AVI is currently the only supported output format.
Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Could not allocate required memory. |
| S_OK | Success. |
This method specifies to the cutlist graph builder that the output of this filter graph should be a file of media subtype pType. If you do not call this method then the cutlist graph builder will attempt to render a graph to play the cutlist live.
Creates the final cutlist filter graph.
HRESULT Render(void);
Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Could not allocate required memory. |
| S_OK | Success. |
Call this method to create the final filter graph containing all of the previously specified cutlists and file writers.
Retrieves the flags of a given element.
HRESULT GetElementFlags(
ICutListElement *pElement,
LPDWORD lpdwFlags
);
Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Could not allocate required memory. |
| S_OK | Success. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.