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.

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.

---

ICutListGraphBuilder::AddCutList

ICutListGraphBuilder Interface

Adds a cutlist to the filter graph.

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 Values

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.

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.

HRESULT GetElementFlags(
  IAMCutListElement *pElement,
  LPDWORD lpdwFlags
  );

Parameters

pElement

[in] Pointer to the element's IAMCutListElement interface.

lpdwFlags

[out] Retrieved element flags. The flags are a logical combination of members of the CL_ELEM_FLAGS enumerated data type.

Return Values

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

ICutListGraphBuilder Interface

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

HRESULT GetFilterGraph(
  IGraphBuilder **ppFilterGraph
  );

Parameters

ppFilterGraph

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

Return Values

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.

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.

See Also

IGraphBuilder

---

ICutListGraphBuilder::RemoveCutList

ICutListGraphBuilder Interface

Removes a cutlist from a filter graph.

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 Values

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.

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.

HRESULT Render(void);

Return Values

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.

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.

See Also

ICutListGraphBuilder::AddCutList

---

ICutListGraphBuilder::SetFilterGraph

ICutListGraphBuilder Interface

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

HRESULT SetFilterGraph(
  IGraphBuilder *pFilterGraph
  );

Parameters

pFilterGraph

[in] Pointer to the desired filter graph.

Return Values

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.

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.

See Also

IGraphBuilder

---

ICutListGraphBuilder::SetOutputFileName

ICutListGraphBuilder Interface

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
  );

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 Values

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.

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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page