ICutListGraphBuilder Interface

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.

To add an element to an existing cutlist after the graph has been rendered, you must call ICutListGraphBuilder::RemoveCutList to remove the cutlist from the filter graph, then call IStandardCutList::AddElement to add the new cutlist element, then call ICutListGraphBuilder::AddCutList to add the cutlist to the filter graph. Then call ICutListGraphBuilder::Render to create the final cutlist filter graph.

See About Cutlists and Using Cutlists for more information.

Do not implement this interface. Microsoft® DirectShow® implements it for you.

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.

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.

ICutListGraphBuilder::AddCutList

ICutListGraphBuilder Interface

Adds a cutlist to the filter graph.

Syntax

HRESULT AddCutList(
  IStandardCutList *pCutList,
  IPin **ppPin
  );

Parameters

pCutList
[in] Pointer to the cutlist's IStandardCutList interface that the graph builder might query for more detailed information about the cutlist.
ppPin
[out] Address of a pointer to the output pin of the cutlist filter that this method added to the filter graph. Use this pin as a starting point to build custom cutlist filter graphs. Be sure to decrement the pin's reference count by calling the Release method on the pin before you call the ICutListGraphBuilder::RemoveCutList method. Specify NULL for ppPin if you don't need the pin.

Return Value

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.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

Remarks

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.

ICutListGraphBuilder::GetElementFlags

ICutListGraphBuilder Interface

Retrieves the flags of a given element.

Syntax

HRESULT GetElementFlags(
  IAMCutListElement *pElement,
  LPDWORD lpdwFlags
  );

Parameters

pElement
[in] Pointer to the element's IAMCutListElement interface.
lpdwFlags
[out] Pointer to retrieved element flags. The flags are a logical combination of members of the CL_ELEM_FLAGS enumerated data type.

Return Value

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.

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::GetFilterGraph

ICutListGraphBuilder Interface

Retrieves the filter graph that the cutlist graph builder is using to implement playback of the cutlist.

Syntax

HRESULT GetFilterGraph(
  IGraphBuilder **ppFilterGraph
  );

Parameters

ppFilterGraph
[out] Address of a pointer to the filter graph that the cutlist graph builder is using.

Return Value

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.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

Remarks

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.

ICutListGraphBuilder::RemoveCutList

ICutListGraphBuilder Interface

Removes a cutlist from a filter graph.

Syntax

HRESULT RemoveCutList(
  IStandardCutList *pCutList
  );

Parameters

pCutList
[in] Pointer to the cutlist's IStandardCutList interface that the graph builder might query for more detailed information about the cutlist.

Return Value

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.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

Remarks

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.

ICutListGraphBuilder::Render

ICutListGraphBuilder Interface

Creates the final cutlist filter graph.

Syntax

HRESULT Render(void);

Return Value

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.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

Remarks

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::SetFilterGraph

ICutListGraphBuilder Interface

Sets the filter graph that the cutlist graph builder will use.

Syntax

HRESULT SetFilterGraph(
  IGraphBuilder *pFilterGraph
  );

Parameters

pFilterGraph
[in] Pointer to the desired filter graph.

Return Value

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.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

Remarks

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.

ICutListGraphBuilder::SetOutputFileName

ICutListGraphBuilder Interface

Specifies the output file and media subtype to use when writing the movie to a file.

Syntax

HRESULT SetOutputFileName(
  const GUID *pType,
  LPCOLESTR lpwstrFile,
  IBaseFilter **ppf,
  IFileSinkFilter **pSink
  );

Parameters

pType
[in] Pointer to a GUID representing the media subtype. Must be &MEDIASUBTYPE_Avi because AVI is currently the only supported output format.
lpwstrFile
[in] Pointer to a Unicode™ string containing the output file name.
ppf
[in] Address of a pointer to an IBaseFilter interface representing the multiplexer filter. This method increments the reference count on the IBaseFilter interface, so you must decrement the reference count by using the Release method on this parameter when you're done using the filter.
pSink
[in] Address of a pointer to an IFileSinkFilter interface representing the file writer. This method increments the reference count on the IFileSinkFilter interface, so you must decrement the reference count by using Release when you're done using the filter.

Return Value

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.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

Remarks

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.

E_FAIL	Failure.
E_INVALIDARG	Argument is invalid.
E_NOTIMPL	Method is not supported.
E_OUTOFMEMORY	Could not allocate required memory.
S_OK	Success.