Microsoft DirectX 8.0

IAMTimelineTrack Interface

Provides methods for manipulating track objects in Microsoft® DirectShow® Editing Services (DES).

A track contains a list of sources that are rendered in the final output. Sources within the same track may not overlap. Video tracks can have both effects and transitions. The render engine applies effects before it applies transitions. Audio tracks can have effects, but not transitions.

For more information, see The Timeline Model.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IAMTimelineTrack MethodsDescription
SrcAddAdds a source to the track.
GetNextSrcSearches the track for the next source that appears at the specified time or later.
GetNextSrc2Equivalent to GetNextSrc, but takes a REFTIME value.
MoveEverythingByMoves all objects that start at a specified time or later, moving them a specified distance along the timeline.
MoveEverythingBy2Equivalent to MoveEverythingBy, but takes REFTIME values.
GetSourcesCountRetrieves the number of sources in the track.
AreYouBlankDetermines whether the track is blank (contains no source objects).
GetSrcAtTimeRetrieves the source object nearest to the specified time, according to the specified boundary conditions.
GetSrcAtTime2Equivalent to GetSrcAtTime, but takes REFTIME values.
InsertSpaceSplits any objects that exist at the specified time and inserts space between them.
InsertSpace2Equivalent to InsertSpace, but takes REFTIME values.
ZeroBetweenRemoves everything from the track between the specified times.
ZeroBetween2Equivalent to ZeroBetween, but takes REFTIME values.
GetNextSrcExRetrieves the next source after the specified source.

IAMTimelineTrack::AreYouBlank

IAMTimelineTrack Interface

Determines whether the track is blank (contains no source objects).

Syntax

HRESULT AreYouBlank(
    long *pVal
);

Parameters

pVal
Pointer to a variable that receives a Boolean value specifying whether the track is blank. If the value is TRUE, the track is blank and contains no source objects. If FALSE, the track is not blank.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineTrack::GetNextSrc

IAMTimelineTrack Interface

Searches the track for the next source that appears at the specified time or later.

Syntax

HRESULT GetNextSrc(
    IAMTimelineObj **ppSrc,
    REFERENCE_TIME *pInOut
);

Parameters

ppSrc
[out] Address of a pointer that receives the source object's IAMTimelineObj interface.
pInOut
Pointer to a variable that contains the start time for the search, in 100-nanosecond units. If the method retrieves a source, it sets the value to the stop time of the source. If the method does not retrieve a source, the value becomes invalid and the application should not use it.

Return Value

Returns S_OK if the method retrieves a source, or S_FALSE otherwise.

Remarks

If the time specified by pInOut falls between the start and stop times of a source, the method retrieves that source.

If the method returns S_OK, the IAMTimelineObj interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.

IAMTimelineTrack::GetNextSrc2

IAMTimelineTrack Interface

Searches the track for the next source that appears at the specified time or later. This method is equivalent to GetNextSrc, but takes a REFTIME value.

Syntax

HRESULT GetNextSrc2(
    IAMTimelineObj **ppSrc,
    REFTIME *pInOut
);

Parameters

ppSrc
[out] Address of a pointer that receives the source object's IAMTimelineObj interface.
pInOut
Pointer to a variable that contains the start time for the search, in seconds. If the method retrieves a source, it sets the value to the stop time of the source. If the method does not retrieve a source, the value becomes invalid and the application should not use it.

Return Value

Returns S_OK if the method retrieves a source, or S_FALSE otherwise.

IAMTimelineTrack::GetNextSrcEx

IAMTimelineTrack Interface

Retrieves the next source after the specified source.

Syntax

HRESULT GetNextSrcEx(
    IAMTimelineObj *pLast, 
    IAMTimelineObj **ppNext
);

Parameters

pLast
Pointer to the previous source object, or NULL to retrieve the first source in the track.
ppNext
[out] Address of a pointer that receives the next source object's IAMTimelineObj interface.

Return Value

Returns S_OK if the method retrieves a source, or S_FALSE otherwise.

Remarks

If the method returns S_OK, the IAMTimelineObj interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.

IAMTimelineTrack::GetSourcesCount

IAMTimelineTrack Interface

Retrieves the number of sources in the track.

Syntax

HRESULT GetSourcesCount(
    long *pVal
);

Parameters

pVal
Pointer to a variable that receives the number of sources in the track.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineTrack::GetSrcAtTime

IAMTimelineTrack Interface

Retrieves the source object nearest to the specified time, according to the specified boundary conditions.

Syntax

HRESULT GetSrcAtTime(
    IAMTimelineObj **ppSrc,
    REFERENCE_TIME Time,
    long SearchDirection
);

Parameters

ppSrc
[out] Address of a pointer that receives the IAMTimelineObj interface of the source object.
Time
Start time for the search, in 100-nanosecond units.
SearchDirection
Member of the DEXTERF_TRACK_SEARCH_FLAGS enumerated type that specifies the boundary conditions for the search.

Return Value

Returns one of the following HRESULT values:

S_FALSEDid not locate a source object.
S_OKLocated a source object.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

Remarks

If the method returns S_OK, the IAMTimelineObj interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.

IAMTimelineTrack::GetSrcAtTime2

IAMTimelineTrack Interface

Retrieves the source object nearest to the specified time, according to the specified boundary conditions. This method is equivalent to GetSrcAtTime, but takes a REFTIME value.

Syntax

HRESULT GetSrcAtTime2(
    IAMTimelineObj **ppSrc,
    REFTIME Time,
    long SearchDirection
);

Parameters

ppSrc
[out] Address of a pointer that receives the IAMTimelineObj interface of the source object.
Time
Start time for the search, in seconds.
SearchDirection
Member of the DEXTERF_TRACK_SEARCH_FLAGS enumerated type that specifies the boundary conditions for the search.

Return Value

Returns one of the following HRESULT values:

S_FALSEDid not locate a source object.
S_OKLocated a source object.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

IAMTimelineTrack::InsertSpace

IAMTimelineTrack Interface

Splits any objects that exist at the specified time and inserts space between them.

Syntax

HRESULT InsertSpace(
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtEnd
);

Parameters

rtStart
Time at which to create the split, and the starting point of the inserted space, in 100-nanosecond units.
rtEnd
End point of the inserted space, in 100-nanosecond units.

Return Value

Returns an HRESULT value. Possible return values include the following:

S_FALSEThere are no objects at the specified time.
S_OKSuccess.
E_INVALIDARGInvalid argument.
E_OUTOFMEMORYInsufficient memory.

IAMTimelineTrack::InsertSpace2

IAMTimelineTrack Interface

Splits any objects that exist at the specified time and inserts space between them. This method is equivalent to InsertSpace, but takes REFTIME values.

Syntax

HRESULT InsertSpace2(
    REFTIME rtStart,
    REFTIME rtEnd
);

Parameters

rtStart
Time at which to create the split, and the starting point of the inserted space, in seconds.
rtEnd
End point of the inserted space, in seconds.

Return Value

Returns an HRESULT value. Possible return values include the following:

S_FALSEThere are no objects at the specified time.
S_OKSuccess.
E_INVALIDARGInvalid argument.
E_OUTOFMEMORYInsufficient memory.

IAMTimelineTrack::MoveEverythingBy

IAMTimelineTrack Interface

Moves all objects that start at a specified time or later, moving them a specified distance along the timeline.

Syntax

HRESULT MoveEverythingBy(
    REFERENCE_TIME Start,
    REFERENCE_TIME MoveBy
);

Parameters

Start
Starting time of the move, in 100-nanosecond units. Only objects that begin at this time or later are moved.
MoveBy
Amount of time along the timeline to move the objects, in 100-nanosecond units.

Return Value

Returns S_OK if any objects were moved, or S_FALSE if no objects were moved.

IAMTimelineTrack::MoveEverythingBy2

IAMTimelineTrack Interface

Moves all objects that start at a specified time or later, moving them a specified distance along the timeline. This method is equivalent to MoveEverythingBy, but takes REFTIME values.

Syntax

HRESULT MoveEverythingBy2(
    REFTIME Start,
    REFTIME MoveBy
);

Parameters

Start
Starting time of the move, in seconds. Only objects that begin at this time or later are moved.
MoveBy
Amount of time along the timeline to move the objects, in seconds.

Return Value

Returns S_OK if any objects were moved, or S_FALSE if no objects were moved.

IAMTimelineTrack::SrcAdd

IAMTimelineTrack Interface

Adds a source to the track.

Syntax

HRESULT SrcAdd(
    IAMTimelineObj *pSrc
);

Parameters

pSrc
Pointer to the source object's IAMTimelineObj interface.

Return Value

Returns S_OK if successful. Returns E_NOINTERFACE if the object is not a source object. Otherwise, returns an HRESULT value indicating the cause of the error.

Remarks

Set the source's start and stop times before calling this method. (Call IAMTimelineObj::SetStartStop.)

Currently, DES cannot simultaneously render more than 75 sources that were compressed with Video Compression Manager (VCM) codecs. Also, if the project as a whole contains more than 75 such sources, you must use dynamic reconnection or DES cannot preview the project. For more information, see IRenderEngine::SetDynamicReconnectLevel.

IAMTimelineTrack::ZeroBetween

IAMTimelineTrack Interface

Removes everything from the track between the specified times. This method splits any objects that span the specified time range and removes the pieces that fall within the range.

Syntax

HRESULT ZeroBetween(
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtEnd
);

Parameters

rtStart
Beginning of the range to clear, in 100-nanosecond units.
rtEnd
End of the range to clear, in 100-nanosecond units.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSEThe time range falls beyond everything in the track.
S_OKSuccess.

IAMTimelineTrack::ZeroBetween2

IAMTimelineTrack Interface

Removes everything from the track between the specified times. This method is equivalent to ZeroBetween, but takes REFTIME values.

Syntax

HRESULT ZeroBetween2(
    REFTIME rtStart,
    REFTIME rtEnd
);

Parameters

rtStart
Beginning of the range to clear, in seconds.
rtEnd
End of the range to clear, in seconds.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSEThe time range falls beyond everything in the track.
S_OKSuccess.