IStandardCutList Interface
The IStandardCutList interface provides a simple way for an application to feed a cutlist into a cutlist provider (filter).
The IStandardCutList::AddElement method provides the primary functionality of this interface, by taking a pointer to a cutlist element and adding it to the list. The first clip added to a cutlist determines the media type. All other clips must be of the same media type. Removing clips from the cutlist is not supported.
The filter graph must be stopped when you call many of the methods on this interface.
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.
For more information, see About Cutlists and Using Cutlists.
Do not implement this interface. Microsoft® DirectShow® implements it for you.
Use this interface in your application when you need to create a whole cutlist out of individual cuts (elements).
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. IStandardCutList methods Description AddElement Accepts a cutlist element from the application and adds it to the cutlist. RemoveElement Removes an element from a cutlist. (Not currently implemented.) GetFirstElement Retrieves the first element you added to cutlist. GetLastElement Retrieves the last element you added to cutlist. GetNextElement Retrieves the next element in the cutlist. GetPreviousElement Retrieves the previous element in the cutlist. GetMediaType Retrieves the clip's media type structure. SetMediaType Sets the media type for all clips in the cutlist.
IStandardCutList::AddElement
IStandardCutList Interface
Accepts a cutlist element from the application and adds it to the cutlist.
Syntax
HRESULT AddElement(
IAMCutListElement *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 that 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 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 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.
You can't call AddElement on this cutlist after you have given the cutlist to the graph builder by calling ICutListGraphBuilder::AddCutList. The AddElement call will be ignored. Make sure you have called AddElement as many times as you need to before calling ICutListGraphBuilder::AddCutList.
Removing clips from the cutlist is not supported.
The first clip added to a cutlist determines the media type. All other clips must be of the same media type.
See Also
IStandardCutList::GetFirstElement
IStandardCutList Interface
Retrieves the first element you added to the cutlist.
Syntax
HRESULT GetFirstElement(
IAMCutListElement **ppElement
);
Parameters
- ppElement
- [out] Address of a pointer to the first element in 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
You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.
This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.
*ppElement->Release();
See Also
IStandardCutList::GetLastElement
IStandardCutList Interface
Retrieves the last element you added to the cutlist.
Syntax
HRESULT GetLastElement(
IAMCutListElement **ppElement
);
Parameters
- ppElement
- [out] Address of a pointer to the last element you added to 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
You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.
This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.
*ppElement->Release();
See Also
IStandardCutList::GetMediaType
IStandardCutList Interface
Retrieves the clip's media type structure.
Syntax
HRESULT GetMediaType(
AM_MEDIA_TYPE *pmt
);
Parameters
- pmt
- [in] Pointer to the AM_MEDIA_TYPE structure describing the clip.
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 retrieves the media type of all clips in the cutlist.
The first clip added to a cutlist determines the media type. All other clips must be of the same media type.
IStandardCutList::GetNextElement
IStandardCutList Interface
Retrieves the next element in the cutlist.
Syntax
HRESULT GetNextElement(
IAMCutListElement **ppElement
);
Parameters
- ppElement
- [out] Address of a pointer to the next cutlist element.
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. You must call GetFirstElement or GetLastElement. E_INVALIDARG Argument is invalid. E_NOTIMPL Method is not supported. E_OUTOFMEMORY Could not allocate required memory. S_FALSE There is no next element. S_OK Success.
Remarks
You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.
You must call GetFirstElement or GetLastElement before this method will succeed.
This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.
*ppElement->Release();
See Also
IStandardCutList::GetPreviousElement
IStandardCutList Interface
Retrieves the previous element in the cutlist.
Syntax
HRESULT GetPreviousElement(
IAMCutListElement **ppElement
);
Parameters
- ppElement
- [out] Address of a pointer to the previous cutlist element.
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. You must call GetFirstElement or GetLastElement. E_INVALIDARG Argument is invalid. E_NOTIMPL Method is not supported. E_OUTOFMEMORY Could not allocate required memory. S_FALSE There is no previous element. S_OK Success.
Remarks
You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.
You must call GetFirstElement or GetLastElement before this method will succeed.
This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.
*ppElement->Release();
See Also
IStandardCutList::RemoveElement
IStandardCutList Interface
Removes an element from a cutlist.
This method is not currently implemented and returns E_NOTIMPL.
Syntax
HRESULT RemoveElement( IAMCutListElement *pElement );
Parameters
- pElement
- [in] Pointer to the element to be removed.
Return Value
Returns E_NOTIMPL.
IStandardCutList::SetMediaType
IStandardCutList Interface
Sets the media type for all clips in the cutlist.
Syntax
HRESULT SetMediaType(
AM_MEDIA_TYPE *pmt
);
Parameters
- pmt
- [in] Pointer to the AM_MEDIA_TYPE structure describing the clip.
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_UNEXPECTED Too late to set the media type. S_OK Success.
Remarks
This method tells a cutlist what media type all of the elements in the cutlist must have. If you do not call this method, the first non-NULL element given to the cutlist through IStandardCutList::AddElement will determine the media type of the cutlist. All subsequent calls to AddElement must be of the same media type.
If you call this method, you must do so before ever calling AddElement. This method limits the elements that can be added to elements of the specified media type.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.