The ICutListGraphBuilder interface enables you to easily implement one or more cutlist filter graphs. The simplest way to use this object is to add a cutlist by 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 the ICutListGraphBuilder::SetOutputFileName method to specify the media subtype (such as MEDIASUBTYPE_Avi) and the file name. ICutListGraphBuilder attempts to connect the filters needed to write to this file, so that when you call ICutListGraphBuilder::Render, the filter graph manager creates a filter graph that writes to a file.
See About Cutlists and Using Cutlists for more information.
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.
When compiling a cutlist application you must explicitly include the cutlist header file as follows:
#include <cutlist.h>
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 that the cutlist graph builder will use |
| GetFilterGraph | Retrieves the filter graph the cutlist graph builder is using to implement 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. |
Adds a cutlist to the filter graph.
HRESULT AddCutList(
IStandardCutList *pCutList,
IPin **ppPin
);
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. |
When you call the ICutListGraphBuilder::Render method, the ICutListGraphBuilder interface attempts to create a graph that plays back all the cutlists you have added to the graph. You must follow calls to AddCutList with a call to ICutListGraphBuilder::Render to render the new cutlist in the graph, or your cutlist will not be used. You can wait and call Render once after adding all of your cutlists to the graph.
You can't call IStandardCutList::AddElement on this cutlist after you have given the cutlist to the graph builder by calling this method. The AddElement call will be ignored. Make sure you have called AddElement as many times as you need to before calling ICutListGraphBuilder::AddCutList.
If you call AddCutList 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.
Retrieves the flags of a given element.
HRESULT GetElementFlags(
IAMCutListElement *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. |
Retrieves the filter graph that the cutlist graph builder is using to implement 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 is useful, for instance, to acquire the playback graph's IMediaControl and IMediaEvent interfaces.
This method increments the reference count on the filter graph interface pointed to by ppFilterGraph. Be sure to decrement the reference count on the filter graph object by calling its Release method when you're done.
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 the ICutListGraphBuilder::AddCutList method to add the cutlist to the filter graph, you must call this method before releasing the filter graph.
You should call this method only when the graph is stopped, otherwise resources will not be properly freed.
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 the previously specified cutlists and file writer filters.
If the graph contains a multiplexer (MUX) filter before you call this method, then this method connects all cutlist source filters to the MUX, and connects the MUX to a single renderer. Otherwise, each cutlist source filter renders through its own renderer. For example, rendering two separate video cutlists without a MUX would give you two video renderer windows for playback.
ICutListGraphBuilder::AddCutList
Sets the filter graph that 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 that the cutlist graph builder will try to use in constructing the graph before adding other filters.
If you've already called this method to give a cutlist to the cutlist graph builder, you can't call this method again.
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
);
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 to the screen and through the system speakers.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.