IStandardCutList Interface


IStandardCutList provides a simple way for an application to feed a cutlist into a cutlist provider (filter).

IStandardCutList::AddElement provides the primary functionality of this interface by taking a pointer to a cutlist element and adding it to the list.

The DirectShow cutlist interfaces define two types of objects: cutlist elements and cutlists. Cutlist elements contain information related to the media from which they are extracted, while cutlists describe the relative time and duration of each element. A cutlist as a collection of cutlist elements. Each cutlist element can in turn expose multiple interfaces - one for each type of attribute.

Applications use the following interfaces to create and manipulate cutlists and their playback.
IStandardCutList
IFileClip
ICutListGraphBuilder

These interfaces generalize cutlist functionality, allowing application writers to construct filter graphs without having to worry about the specifics of each cutlist or effects filter. In addition, a single cutlist filter calls these interfaces -- the application must be aware of the different cutlist filters that are installed and generate the proper filter graph.

If you need functionality not provided by the interfaces above, see the following interfaces:
ICutListElement
IFileCutListElement
IVideoCutListElement
IAudioCutListElement

When to Implement

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

When to Use

Use this interface in your application to create a whole cutlist out of individual cuts (elements).

Methods in Vtable Order
IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IStandardCutList methods Description
AddElement Accepts a cutlist element from the application and adds it to the cutlist to be played.
RemoveElement Removes an element from a cutlist. (Not currently implemented.)
GetNextElement Retrieves the cutlist element that follows the one passed in.
GetMediaType Retrieves the clip's media type structure.

IStandardCutList::AddElement

IStandardCutList Interface

Accepts a cutlist element from the application and adds it to the cutlist to be played.

HRESULT AddElement(
  ICutListElement *pElement,
  REFERENCE_TIME mtStart,
  REFERENCE_TIME mtDuration
  );

Parameters
pElement
[in] Pointer to the cutlist element to be added to the cutlist.
mtStart
[in] Relative position of the cut in the cutlist. Must be CL_DEFAULT_TIME (indicating the relative position is the end of the current cutlist).
mtDuration
[in] Length of the cut. Must be CL_DEFAULT_TIME (indicating the duration is defined by the element).
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 the element descriptor.
S_OK Success.

Remarks

This method adds a clip to the end of the clip list. The cutlist will play in the order you add the clips.

Note: Removing clips from the cutlist is not supported.

IStandardCutList::RemoveElement

IStandardCutList Interface

Removes an element from a cutlist. (Not currently implemented.)

HRESULT RemoveElement(
  ICutListElement *pElement
  );

Parameters
pElement
[in] Pointer to the element to be removed.

IStandardCutList::GetNextElement

IStandardCutList Interface

Retrieves the cutlist element that follows the one passed in.

HRESULT GetNextElement(
  ICutListElement **ppElement
  );

Parameters
ppElement
[in, out] Address of a pointer to a cutlist element. Specify a NULL ICutListElement pointer to retrieve the first element of 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.

IStandardCutList::GetMediaType

IStandardCutList Interface

Retrieves the clip's media type structure.

HRESULT GetMediaType(
  AM_MEDIA_TYPE *pmt
  );

Parameters
pmt
[in] Pointer to the AM_MEDIA_TYPE structure describing the clip.
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 retrieves the media type of all cuts in the cutlist.

Note: The first cut added to a cutlist determines the media type. All other cuts must be of the same media type.

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