Microsoft DirectX 8.0 |
Provides methods for manipulating the timeline, the central object in Microsoft® DirectShow® Editing Services (DES). A timeline is a collection of time-ordered elements, such as video clips, audio clips, effects, and transitions between clips. The render engine uses the timeline to create a filter graph, from which the application can generate the rendered output.
IAMTimeline performs three basic services. It
Requirements
Requires Qedit.h.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IAMTimeline Methods Description CreateEmptyNode Creates a new timeline object. AddGroup Adds a group to the timeline. RemGroupFromList Not supported. GetGroup Retrieves a specified group. GetGroupCount Retrieves the number of groups that are contained in the timeline. ClearAllGroups Removes all groups from the timeline, along with all objects contained in those groups. GetInsertMode Not supported. SetInsertMode Not implemented. EnableTransitions Enables or disables all transitions in the timeline. TransitionsEnabled Determines whether transitions are enabled. EnableEffects Enables or disables all effects in the timeline. EffectsEnabled Determines whether effects are enabled. SetInterestRange Not implemented. GetDuration Retrieves the duration of the timeline. GetDuration2 Equivalent to GetDuration, but takes a parameter of type double. SetDefaultFPS Sets the default output frame rate, in frames per second. GetDefaultFPS Retrieves the default output frame rate, in frames per second. IsDirty Not supported. GetDirtyRange Not supported. GetCountOfType Retrieves the number of objects of the specified type that are contained in a specified group and all of its children. ValidateSourceNames Validates source names in the timeline. SetDefaultTransition Sets the default transition. GetDefaultTransition Retrieves the default transition. SetDefaultEffect Sets the default effect. GetDefaultEffect Retrieves the default effect. SetDefaultTransitionB Equivalent to SetDefaultTransition, but takes a BSTR value. GetDefaultTransitionB Equivalent to GetDefaultTransition, but receives a BSTR value. SetDefaultEffectB Equivalent to SetDefaultEffect, but takes a BSTR value. GetDefaultEffectB Equivalent to GetDefaultEffect, but receives a BSTR value.
Adds a group to the timeline.
Syntax
HRESULT AddGroup( IAMTimelineObj *pGroup );
Parameters
- pGroup
- Pointer to the IAMTimelineObj interface of the group.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_INVALIDARG Maximum number of groups exceeded. E_NOINTERFACE The object is not a group.
Remarks
Currently, timelines support a maximum of 32 groups.
Removes all groups from the timeline, along with all objects contained in those groups.
Syntax
HRESULT ClearAllGroups( void );
Return Value
Returns S_OK.
Creates a new timeline object.
Use this method to create timeline objects, rather than the CoCreateInstance function, because this method performs important initialization routines. Every object created by this method supports at least the IAMTimelineObj interface, along with other interfaces specific to that type of object.
Syntax
HRESULT CreateEmptyNode( IAMTimelineObj **ppObj, TIMELINE_MAJOR_TYPE Type );
Parameters
- ppObj
- [out] Address of a pointer that receives the new object's IAMTimelineObj interface.
- Type
- Member of the TIMELINE_MAJOR_TYPE enumerated type, specifying the type of object to create.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_INVALIDARG Object type is not valid. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument.
Remarks
Do not add the new object to another timeline instance. Every object in a timeline must be created by that timeline.
If the method succeeds, the IAMTimelineObj interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.
Determines whether effects are enabled. If effects are disabled, they remain in the timeline but are not rendered.
Syntax
HRESULT EffectsEnabled( BOOL *pfEnabled );
Parameters
- pfEnabled
- Pointer to a variable that receives a Boolean value indicating whether effects are enabled. If TRUE, effects are enabled. If FALSE, effects are disabled.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Enables or disables all effects in the timeline. If effects are disabled, they remain in the timeline but are not rendered.
Syntax
HRESULT EnableEffects( BOOL fEnabled );
Parameters
- fEnabled
- Boolean value that specifies whether to enable or disable effects. If TRUE, effects are enabled. If FALSE, effects are disabled.
Return Value
Returns S_OK.
Enables or disables all transitions in the timeline. If transitions are disabled, the render engines treats them as cuts; that is, the rendered output jumps instantly from one track to the next. The default cut point is halfway through the duration of the transition. You can change the cut point by calling the IAMTimelineTrans::SetCutPoint method on the transition. Disabled transitions are not removed from the timeline.
Syntax
HRESULT EnableTransitions( BOOL fEnabled );
Parameters
- fEnabled
- Boolean value that specifies whether to enable or disable transitions. If TRUE, transitions are enabled. If FALSE, transitions are disabled.
Return Value
Returns S_OK.
Retrieves the number of objects of the specified type that are contained in a specified group and all of its children.
Syntax
HRESULT GetCountOfType( long Group, long *pVal, long *pValWithComps, TIMELINE_MAJOR_TYPE MajorType );
Parameters
- Group
- Index number of the group for which to retrieve the count.
- pVal
- Pointer to a variable that receives the number of objects of the specified type contained in the group and all of its virtual tracks, recursively.
- pValWithComps
- Pointer to a variable that receives the count returned in pVal plus the number of compositions searched, including this one.
- MajorType
- Member of the TIMELINE_MAJOR_TYPE enumerated type, specifying the type of object to count.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_INVALIDARG Invalid group number. E_POINTER NULL pointer argument.
Remarks
Calling this method is equivalent to calling IAMTimelineComp::GetCountOfType on the specified group. See the Remarks section of that method for more information.
Typically, an application will not call this method. It is called internally by the render engine.
Retrieves the default effect. If the render engine cannot render an effect, it substitutes the default effect.
Syntax
HRESULT GetDefaultEffect( GUID *pGuid );
Parameters
- pGuid
- Pointer to a variable that receives the globally unique identifier (GUID) of the default effect.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Retrieves the default effect. This method is equivalent to GetDefaultEffect, but receives a BSTR value rather than a GUID.
Syntax
HRESULT GetDefaultEffectB( BSTR *pGuid );
Parameters
- pGuid
- [out, retval] Pointer to a variable that receives a BSTR value representing the GUID of the default effect.
Return Value
Returns S_OK if successful. Otherwise, returns E_OUTOFMEMORY or another HRESULT value indicating the cause of the error.
Remarks
The method allocates memory for the string. The application must call SysFreeString to free the memory.
Retrieves the default output frame rate, in frames per second (FPS). Groups use this value as their default frame rate. To set a group's frame rate, call the IAMTimelineGroup::SetOutputFPS method on the group.
Syntax
HRESULT GetDefaultFPS( double *pFPS );
Parameters
- pFPS
- Pointer to a variable that receives the default frame rate, in frames per second.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Retrieves the default transition. If the render engine cannot render a transition, it substitutes the default transition.
Syntax
HRESULT GetDefaultTransition( GUID *pGuid );
Parameters
- pGuid
- Pointer to a variable that receives the GUID of the default transition.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Retrieves the default transition. This method is equivalent to GetDefaultTransition, but receives a BSTR value, rather than a GUID.
Syntax
HRESULT GetDefaultTransitionB( BSTR *pGuid );
Parameters
- pGuid
- [out, retval] Pointer to a variable that receives a BSTR value representing the GUID of the default transition.
Return Value
Returns S_OK if successful. Otherwise, returns E_OUTOFMEMORY or another HRESULT value indicating the cause of the error.
Remarks
The method allocates memory for the string. The application must call SysFreeString to free the memory.
Not supported.
Syntax
HRESULT GetDirtyRange( REFERENCE_TIME *pStart, REFERENCE_TIME *pStop );
Retrieves the duration of the timeline.
Syntax
HRESULT GetDuration( REFERENCE_TIME *pDuration );
Parameters
- pDuration
- Pointer to a variable that receives the duration of the timeline, in 100-nanosecond units.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Retrieves the duration of the timeline. This method is equivalent to GetDuration, but takes a parameter of type double.
Syntax
HRESULT GetDuration2( double *pDuration );
Parameters
- pDuration
- Pointer to a variable that receives the duration of the timeline, in fractional seconds.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Retrieves a specified group.
Syntax
HRESULT GetGroup( IAMTimelineObj **ppGroup, long WhichGroup );
Parameters
- ppGroup
- [out] Address of a pointer that receives the group's IAMTimelineObj interface.
- WhichGroup
- Index of the group to retrieve, based on the order in which the groups were added to the timeline. The first group added to the timeline has an index of 0.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_INVALIDARG Invalid argument. E_POINTER NULL pointer argument.
Remarks
If the method succeeds, the IAMTimelineObj interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.
Retrieves the number of groups that are contained in the timeline.
Syntax
HRESULT GetGroupCount( long *pCount );
Parameters
- pCount
- Pointer to a variable that receives the number of groups in the timeline.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Not supported.
Syntax
HRESULT GetInsertMode( long *pMode );
Not supported.
Syntax
HRESULT IsDirty( BOOL *pDirty );
Not supported.
Syntax
HRESULT RemGroupFromList( IAMTimelineObj *pGroup );
Sets the default effect. If the render engine cannot render an effect, it substitutes the default effect.
Syntax
HRESULT SetDefaultEffect( GUID *pGuid );
Parameters
- pGuid
- Pointer to a variable that contains the GUID of the default effect.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Remarks
If you do not set a default effect, or if the effect that you specify as a default causes an error, DES uses its own default effect.
Sets the default effect. This method is equivalent to SetDefaultEffect, but takes a BSTR value, rather than a pointer to a GUID.
Syntax
HRESULT SetDefaultEffectB( BSTR pGuid );
Parameters
- pGuid
- BSTR value representing the GUID of the default effect.
Return Value
Returns S_OK if successful. Otherwise, returns E_OUTOFMEMORY or another HRESULT value indicating the cause of the error.
Sets the default output frame rate, in frames per second. Groups use this value as their default frame rate. To set a group's frame rate, call the IAMTimelineGroup::SetOutputFPS method on the group.
Syntax
HRESULT SetDefaultFPS( double FPS );
Parameters
- FPS
- Default frame rate, in frames per second.
Return Value
Returns S_OK.
Sets the default transition. If the render engine cannot render a transition, it substitutes the default transition.
Syntax
HRESULT SetDefaultTransition( GUID *pGuid );
Parameters
- pGuid
- Pointer to a variable that contains the GUID of the default transition.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
Remarks
If you do not set a default transition, or if the transition that you specify as a default causes an error, DES uses its own default transition.
Sets the default transition. This method is equivalent to SetDefaultTransition, but takes a BSTR value, rather than a pointer to a GUID.
Syntax
HRESULT SetDefaultTransitionB( BSTR pGuid );
Parameters
- pGuid
- BSTR value representing the GUID of the default transition.
Return Value
Returns S_OK if successful. Otherwise, returns E_OUTOFMEMORY or another HRESULT value indicating the cause of the error.
Not implemented.
Syntax
HRESULT SetInsertMode( long Mode );
Not implemented.
Syntax
HRESULT SetInterestRange( REFERENCE_TIME Start, REFERENCE_TIME Stop );
Determines whether transitions are enabled.
Syntax
HRESULT TransitionsEnabled( BOOL *pfEnabled );
Parameters
- pfEnabled
- Pointer to a variable that receives a Boolean value. If TRUE, transitions are enabled. Otherwise, transitions are disabled.
Return Value
Returns S_OK if successful, or E_POINTER otherwise.
See Also
Validates source names in the timeline, using the media locator. Optionally, this method also updates any source object for which it locates a file.
Syntax
HRESULT ValidateSourceNames( long ValidateFlags, IMediaLocator *pOverride, long NotifyEventHandle );
Parameters
- ValidateFlags
- Bitwise combination of flags specifying the behavior of the media locator. The SFN_VALIDATEF_REPLACE and SFN_VALIDATEF_CHECK flags must be present, or the method returns E_INVALIDARG.
- pOverride
- Optional pointer to the IMediaLocator interface of a media locator to use in place of the default. To use the default media locator, set the value of this parameter to NULL. See Remarks for more information.
- NotifyEventHandle
- Handle to an event. The method signals the event after it has completed the validation.
Return Value
Returns S_OK if successful. Otherwise, returns E_INVALIDARG or another error code.
Remarks
Using the pOverride parameter, you can supply your own custom implementation of the IMediaLocator interface. For example, the default media locator will not notify your application about the files that it finds (or cannot find). To get around this limitation, you could implement a custom media locator, making it a wrapper for the default version. In your custom version, pass FindMediaFile calls directly to the default version, and examine the return value.