Microsoft DirectX 8.0

IAMTimeline Interface

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 methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IAMTimeline MethodsDescription
CreateEmptyNodeCreates a new timeline object.
AddGroupAdds a group to the timeline.
RemGroupFromListNot supported.
GetGroupRetrieves a specified group.
GetGroupCountRetrieves the number of groups that are contained in the timeline.
ClearAllGroupsRemoves all groups from the timeline, along with all objects contained in those groups.
GetInsertModeNot supported.
SetInsertModeNot implemented.
EnableTransitionsEnables or disables all transitions in the timeline.
TransitionsEnabledDetermines whether transitions are enabled.
EnableEffectsEnables or disables all effects in the timeline.
EffectsEnabledDetermines whether effects are enabled.
SetInterestRangeNot implemented.
GetDurationRetrieves the duration of the timeline.
GetDuration2Equivalent to GetDuration, but takes a parameter of type double.
SetDefaultFPSSets the default output frame rate, in frames per second.
GetDefaultFPSRetrieves the default output frame rate, in frames per second.
IsDirtyNot supported.
GetDirtyRangeNot supported.
GetCountOfTypeRetrieves the number of objects of the specified type that are contained in a specified group and all of its children.
ValidateSourceNamesValidates source names in the timeline.
SetDefaultTransitionSets the default transition.
GetDefaultTransitionRetrieves the default transition.
SetDefaultEffectSets the default effect.
GetDefaultEffectRetrieves the default effect.
SetDefaultTransitionBEquivalent to SetDefaultTransition, but takes a BSTR value.
GetDefaultTransitionBEquivalent to GetDefaultTransition, but receives a BSTR value.
SetDefaultEffectBEquivalent to SetDefaultEffect, but takes a BSTR value.
GetDefaultEffectBEquivalent to GetDefaultEffect, but receives a BSTR value.

IAMTimeline::AddGroup

IAMTimeline Interface

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_OKSuccess.
E_INVALIDARGMaximum number of groups exceeded.
E_NOINTERFACEThe object is not a group.

Remarks

Currently, timelines support a maximum of 32 groups.

IAMTimeline::ClearAllGroups

IAMTimeline Interface

Removes all groups from the timeline, along with all objects contained in those groups.

Syntax

HRESULT ClearAllGroups( void );

Return Value

Returns S_OK.

IAMTimeline::CreateEmptyNode

IAMTimeline Interface

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_OKSuccess.
E_INVALIDARGObject type is not valid.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL 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.

IAMTimeline::EffectsEnabled

IAMTimeline Interface

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.

IAMTimeline::EnableEffects

IAMTimeline Interface

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.

IAMTimeline::EnableTransitions

IAMTimeline Interface

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.

IAMTimeline::GetCountOfType

IAMTimeline Interface

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_OKSuccess.
E_INVALIDARGInvalid group number.
E_POINTERNULL 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.

IAMTimeline::GetDefaultEffect

IAMTimeline Interface

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.

IAMTimeline::GetDefaultEffectB

IAMTimeline Interface

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.

IAMTimeline::GetDefaultFPS

IAMTimeline Interface

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.

IAMTimeline::GetDefaultTransition

IAMTimeline Interface

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.

IAMTimeline::GetDefaultTransitionB

IAMTimeline Interface

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.

IAMTimeline::GetDirtyRange

IAMTimeline Interface

Not supported.

Syntax

HRESULT GetDirtyRange(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

IAMTimeline::GetDuration

IAMTimeline Interface

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.

IAMTimeline::GetDuration2

IAMTimeline Interface

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.

IAMTimeline::GetGroup

IAMTimeline Interface

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_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERNULL 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.

IAMTimeline::GetGroupCount

IAMTimeline Interface

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.

IAMTimeline::GetInsertMode

IAMTimeline Interface

Not supported.

Syntax

HRESULT GetInsertMode(
    long *pMode
);

IAMTimeline::IsDirty

IAMTimeline Interface

Not supported.

Syntax

HRESULT IsDirty(
    BOOL *pDirty
);

IAMTimeline::RemGroupFromList

IAMTimeline Interface

Not supported.

Syntax

HRESULT RemGroupFromList(
    IAMTimelineObj *pGroup
);

IAMTimeline::SetDefaultEffect

IAMTimeline Interface

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.

IAMTimeline::SetDefaultEffectB

IAMTimeline Interface

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.

IAMTimeline::SetDefaultFPS

IAMTimeline Interface

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.

IAMTimeline::SetDefaultTransition

IAMTimeline Interface

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.

IAMTimeline::SetDefaultTransitionB

IAMTimeline Interface

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.

IAMTimeline::SetInsertMode

IAMTimeline Interface

Not implemented.

Syntax

HRESULT SetInsertMode(
    long Mode
);

IAMTimeline::SetInterestRange

IAMTimeline Interface

Not implemented.

Syntax

HRESULT SetInterestRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IAMTimeline::TransitionsEnabled

IAMTimeline Interface

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

EnableTransitions

IAMTimeline::ValidateSourceNames

IAMTimeline Interface

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.