Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IAMTimelineSrc Methods Description GetMediaTimes Retrieves the media start and stop times. GetMediaTimes2 Equivalent to GetMediaTimes, but takes REFTIME values. ModifyStopTime Sets the stop time, relative to the timeline. ModifyStopTime2 Equivalent to ModifyStopTime, but takes REFTIME values. FixMediaTimes Rounds the specified time values to the nearest frame boundary, as defined by the output frame rate. FixMediaTimes2 Equivalent to FixMediaTimes, but takes REFTIME values. SetMediaTimes Sets the media stop and start times. SetMediaTimes2 Equivalent to SetMediaTimes, but takes REFTIME values. SetMediaLength Specifies the duration of the source file. SetMediaLength2 Equivalent to SetMediaLength, but takes REFTIME values. GetMediaLength Retrieves the media length of this source object. GetMediaLength2 Equivalent to GetMediaLength, but takes REFTIME values. GetMediaName Retrieves the name of the source file represented by this source object. SetMediaName Specifies the name of the source file represented by this source object. SpliceWithNext Joins this source object to another source object. GetStreamNumber Retrieves the current stream number for the source object. SetStreamNumber Specifies which stream to read from the source file associated with this source object. IsNormalRate Indicates whether the clip will play at the normal playback rate. GetDefaultFPS Retrieves the source object's default frame rate. SetDefaultFPS Sets the source object's default frame rate. GetStretchMode Retrieves the stretch mode of a video source. SetStretchMode Sets the stretch mode of a video source.
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.
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.
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.
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_OK Success. E_NOTDETERMINED Media times are not set on this object. E_POINTER NULL pointer argument.
See Also
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_OK Success. E_NOTDETERMINED Media times are not set on this object. E_POINTER NULL pointer argument.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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_OK Success. E_INVALIDARG Invalid argument. E_NOINTERFACE Object specified by pNext parameter is not a source object. E_POINTER NULL 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:
- It must share the same source file.
- The media start time must equal the media stop time of the current source.
- The playback rate must be the same. Playback rate is media duration divided by timeline duration.