Microsoft DirectX 8.0

IAMTimelineSrc Interface

Provides methods for manipulating and setting properties on source objects in Microsoft® DirectShow® Editing Services (DES). A source object represents one stream from a media source.

You can use a portion of the data within a source file by setting the media start and media stop times. These values specify the beginning and end of the source object, relative to the original media source. The media times can differ from the object's start and stop times on the timeline, allowing for fast- or slow-motion playback. (With audio sources, pitch shifting occurs.)

For more information, see Constructing a Timeline and Working with Sources.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IAMTimelineSrc MethodsDescription
GetMediaTimesRetrieves the media start and stop times.
GetMediaTimes2Equivalent to GetMediaTimes, but takes REFTIME values.
ModifyStopTimeSets the stop time, relative to the timeline.
ModifyStopTime2Equivalent to ModifyStopTime, but takes REFTIME values.
FixMediaTimesRounds the specified time values to the nearest frame boundary, as defined by the output frame rate.
FixMediaTimes2Equivalent to FixMediaTimes, but takes REFTIME values.
SetMediaTimesSets the media stop and start times.
SetMediaTimes2Equivalent to SetMediaTimes, but takes REFTIME values.
SetMediaLengthSpecifies the duration of the source file.
SetMediaLength2Equivalent to SetMediaLength, but takes REFTIME values.
GetMediaLengthRetrieves the media length of this source object.
GetMediaLength2Equivalent to GetMediaLength, but takes REFTIME values.
GetMediaNameRetrieves the name of the source file represented by this source object.
SetMediaNameSpecifies the name of the source file represented by this source object.
SpliceWithNextJoins this source object to another source object.
GetStreamNumberRetrieves the current stream number for the source object.
SetStreamNumberSpecifies which stream to read from the source file associated with this source object.
IsNormalRateIndicates whether the clip will play at the normal playback rate.
GetDefaultFPSRetrieves the source object's default frame rate.
SetDefaultFPSSets the source object's default frame rate.
GetStretchModeRetrieves the stretch mode of a video source.
SetStretchModeSets the stretch mode of a video source.

IAMTimelineSrc::FixMediaTimes

IAMTimelineSrc Interface

Rounds the specified time values to the nearest frame boundary, as defined by the output frame rate. In general, applications do not need to call this method.

Syntax

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

Parameters

pStart
Pointer to a variable that contains the start time, in 100-nanosecond units. If the call succeeds, this variable is set to the rounded time.
pStop
Pointer to a variable that contains the stop time, in 100-nanosecond units. If the call succeeds, this variable is set to the rounded time.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

This method is similar to the IAMTimelineObj::FixTimes method, but it preserves the original ratio of media times and timeline times. Just rounding the times to the nearest frame boundary could distort this ratio.

IAMTimelineSrc::FixMediaTimes2

IAMTimelineSrc Interface

Rounds the specified time values to the nearest frame boundary, as defined by the output frame rate. This method is equivalent to FixMediaTimes, but takes REFTIME values.

Syntax

HRESULT FixMediaTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

Parameters

pStart
Pointer to a variable that contains the start time, in seconds. If the call succeeds, this variable is set to the rounded time.
pStop
Pointer to a variable that contains the stop time, in seconds. If the call succeeds, this variable is set to the rounded time.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineSrc::GetDefaultFPS

IAMTimelineSrc Interface

Retrieves the source object's default frame rate. The render engine uses this value if it cannot determine the frame rate from the original source.

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.

Remarks

The default frame rate is not required if the file format specifies the frame rate. This is the case for audio and video formats.

If the source is a bitmap or JPEG image, the render engine uses it as the first image in a device-independent bitmap (DIB) sequence, with a frame rate equal to the default frame rate. To render a static image, rather than a DIB sequence, set the default frame rate to 0.

If the source is a GIF, do not set the frame rate. For animated GIFs, the GIF file specifies the delay between each image.

IAMTimelineSrc::GetMediaLength

IAMTimelineSrc Interface

Retrieves the media length of this source object.

Syntax

HRESULT GetMediaLength(
    REFERENCE_TIME *pLength
);

Parameters

pLength
Pointer to a variable that receives the media length in 100-nanosecond units.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_NOTDETERMINEDMedia times are not set on this object.
E_POINTERNULL pointer argument.

See Also

SetMediaLength

IAMTimelineSrc::GetMediaLength2

IAMTimelineSrc Interface

Retrieves the media length of this source object. This method is equivalent to GetMediaLength, but takes REFTIME values.

Syntax

HRESULT GetMediaLength2(
    REFTIME *pLength
);

Parameters

pLength
Pointer to a variable that receives the media length in seconds.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_NOTDETERMINEDMedia times are not set on this object.
E_POINTERNULL pointer argument.

IAMTimelineSrc::GetMediaName

IAMTimelineSrc Interface

Retrieves the name of the source file represented by this source object.

Syntax

HRESULT GetMediaName(
    BSTR *pVal
);

Parameters

pVal
[out, retval] Pointer to a string that receives the name of the file.

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.

IAMTimelineSrc::GetMediaTimes

IAMTimelineSrc Interface

Retrieves the media start and stop times.

Syntax

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

Parameters

pStart
Pointer to a variable that receives the media start time, in 100-nanosecond units.
pStop
Pointer to a variable that receives the media stop time, in 100-nanosecond units.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

The media times are relative to the original media file. For more information, see Time in DirectShow Editing Services.

IAMTimelineSrc::GetMediaTimes2

IAMTimelineSrc Interface

Retrieves the media start and stop times. This method is equivalent to GetMediaTimes, but takes REFTIME values.

Syntax

HRESULT GetMediaTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

Parameters

pStart
Pointer to a variable that receives the media start time, in seconds.
pStop
Pointer to a variable that receives the media stop time, in seconds.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineSrc::GetStreamNumber

IAMTimelineSrc Interface

Retrieves the current stream number for the source object.

Syntax

HRESULT GetStreamNumber(
    long *pVal
);

Parameters

pVal
Pointer to a variable that receives the stream number.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineSrc::GetStretchMode

IAMTimelineSrc Interface

Retrieves the stretch mode. The stretch mode determines how a video source is rendered if its size does not match the output dimensions.

Syntax

HRESULT GetStretchMode(
    int *pnStretchMode
);

Parameters

pnStretchMode
Pointer to a variable that receives a flag indicating the current stretch mode. Possible values include the following:

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineSrc::IsNormalRate

IAMTimelineSrc Interface

Indicates whether the clip will play at the normal playback rate; that is, the playback rate of the original file.

Syntax

HRESULT IsNormalRate(
    BOOL *pVal
);

Parameters

pVal
Pointer to a variable that receives a Boolean value indicating how the clip will render. If the value is TRUE, the clip will play at the normal rate. Otherwise, it will play faster or slower than normal.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

A clip's playback rate is determined by its media start and stop times, relative to its timeline times:

Playback rate = (Media Stop — Media Start) / (Timeline Stop — Timeline Start)

If this ratio is equal to 1, the clip plays at the authored speed. Otherwise, it plays faster or slower. For more information, see Time in DirectShow Editing Services.

IAMTimelineSrc::ModifyStopTime

IAMTimelineSrc Interface

Sets the stop time, relative to the timeline.

Syntax

HRESULT ModifyStopTime(
    REFERENCE_TIME Stop
);

Parameters

Stop
New stop time, in 100-nanosecond units.

Return Value

Returns S_OK, or E_INVALIDARG if the specified time is not valid.

Remarks

This method is equivalent to calling IAMTimelineObj::SetStartStop with the original start time and a new stop time.

IAMTimelineSrc::ModifyStopTime2

IAMTimelineSrc Interface

Sets the stop time. This method is equivalent to ModifyStopTime, but takes a REFTIME value.

Syntax

HRESULT ModifyStopTime2(
    REFTIME Stop
);

Parameters

Stop
New stop time, in seconds.

Return Value

Returns S_OK if successful, or E_INVALIDARG if the specified time is not valid.

IAMTimelineSrc::SetDefaultFPS

IAMTimelineSrc Interface

Sets the source object's default frame rate.

Syntax

HRESULT SetDefaultFPS(
    double FPS
);

Parameters

FPS
Default frame rate, in frames per second.

Return Value

Returns S_OK if successful, or E_INVALIDARG if the specified frame rate is less than zero.

Remarks

The render engine uses this value if it cannot determine the frame rate from the original source file.

Call this method only for source files without a predefined frame rate. For bitmap and JPEG files, the default frame rate is zero, which causes the source to be rendered as a still image. To use the image as the first frame in a DIB sequence, set the frame rate to a value greater than zero. For more information, see Working with Sources.

IAMTimelineSrc::SetMediaLength

IAMTimelineSrc Interface

Specifies the duration of the source file.

Syntax

HRESULT SetMediaLength(
    REFERENCE_TIME Length
);

Parameters

Length
Media length, in 100-nanosecond units.

Return Value

Returns S_OK.

Remarks

You can avoid potential rendering errors by setting the media length before you set the media stop time. When you set the media stop time, DES checks it against the media length.

This method does not validate the Length parameter, but the value must equal the actual duration of the source file. Obtain the source file duration by calling IMediaDet::get_StreamLength.

IAMTimelineSrc::SetMediaLength2

IAMTimelineSrc Interface

Specifies the duration of the source file. This method is equivalent to SetMediaLength, but takes a REFTIME value.

Syntax

HRESULT SetMediaLength2(
    REFTIME Length
);

Parameters

Length
Media length, in seconds.

Return Value

Returns S_OK.

IAMTimelineSrc::SetMediaName

IAMTimelineSrc Interface

Specifies the name of the source file represented by this source object.

Syntax

HRESULT SetMediaName(
    BSTR newVal
);

Parameters

newVal
String that specifies the name of the media file.

Return Value

Returns S_OK.

IAMTimelineSrc::SetMediaTimes

IAMTimelineSrc Interface

Sets the media stop and start times.

Syntax

HRESULT SetMediaTimes(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

Parameters

Start
Media start time, in 100-nanosecond units.
Stop
Media stop time, in 100-nanosecond units.

Return Value

Returns S_OK.

Remarks

The media times are the stop and start times relative to the original media file. Always set the media times when you add a video or audio source to the timeline. Otherwise, rendering problems might occur. The stop time must be greater than the start time.

To use a still frame from a video source, set the stop time to a fractional amount more than the start time, such as 100 nanoseconds. Setting them to the same value causes a rendering error.

If the timeline duration does not match the media duration, the source stretches or shrinks accordingly. This causes the clip to play slower or faster than the authored rate. (Pitch shifting will occur in an audio source.) For more information, see Time in DirectShow Editing Services.

You can specify the duration of the source file by calling the SetMediaLength method. If you set a media stop time that exceeds the duration, DES truncates the stop time.

IAMTimelineSrc::SetMediaTimes2

IAMTimelineSrc Interface

Sets the media stop and start times. This method is equivalent to SetMediaTimes, but takes REFTIME values.

Syntax

HRESULT SetMediaTimes2(
    REFTIME Start,
    REFTIME Stop
);

Parameters

Start
Media start time, in seconds.
Stop
Media stop time, in seconds.

Return Value

Returns S_OK.

IAMTimelineSrc::SetStreamNumber

IAMTimelineSrc Interface

Specifies which stream to read from the source file associated with this source object.

Syntax

HRESULT SetStreamNumber(
    long Val
);

Parameters

Val
The stream number, from the set of streams matching the media type of the parent group.

Return Value

Returns S_OK if successful, or E_INVALIDARG if Val is less than zero.

Remarks

The Val parameter specifies a stream number from the set of streams that matches the parent group's media type, not from the entire set of streams in the source file. For example, For example, suppose that a file contains two video streams and two audio streams. If the source object is inside a video group, setting Val to 0 selects the first video stream. The caller is responsible for specifying a valid stream number.

The stream number defaults to zero.

IAMTimelineSrc::SetStretchMode

IAMTimelineSrc Interface

Sets the stretch mode. The stretch mode determines how a video source is rendered if its size does not match the output dimensions.

Syntax

HRESULT SetStretchMode(
    int nStretchMode
);

Parameters

nStretchMode
Flag indicating the current stretch mode. Possible values include the following:

Return Value

Returns S_OK.

IAMTimelineSrc::SpliceWithNext

IAMTimelineSrc Interface

Joins the source object to another source object.

Syntax

HRESULT SpliceWithNext(
    IAMTimelineObj *pNext
);

Parameters

pNext
Pointer to the IAMTimelineObj interface of the source object to join to the current source.

Return Value

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

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOINTERFACEObject specified by pNext parameter is not a source object.
E_POINTERNULL pointer argument.

Remarks

As currently implemented, this method discards any effects on pNext.

For this method to succeed, pNext must be a match frame of the current source object: