Microsoft DirectX 8.0 |
Provides methods for manipulating and setting properties on sources in Microsoft® DirectShow® Editing Services (DES). An AMTimelineSrc object represents a clip taken from one stream in 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 AMTimelineSrc 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, the pitch shifts).
Methods
FixMediaTimes Not supported for Visual Basic. FixMediaTimes2 Rounds the specified time values to the nearest frame boundary, as defined by the output frame rate. GetDefaultFPS Retrieves the source object's default frame rate. GetMediaLength Not supported for Visual Basic. GetMediaLength2 Retrieves the media length of this object. GetMediaName Retrieves the name of the source file represented by this object. GetMediaTimes Not supported for Visual Basic. GetMediaTimes2 Retrieves the media start and stop times. GetStreamNumber Retrieves the current stream number for the source object. GetStretchMode Retrieves the stretch mode. IsNormalRate Indicates whether the clip will play at the authored playback rate. ModifyStopTime Not supported for Visual Basic. ModifyStopTime2 Sets the stop time. SetDefaultFPS Sets the source object's default frame rate. SetMediaLength Not supported for Visual Basic. SetMediaLength2 Specifies the duration of the source file. SetMediaName Specifies the name of the source file. SetMediaTimes Not supported for Visual Basic. SetMediaTimes2 Sets the media stop and start times. SetStretchMode Sets the stretch mode. SetStreamNumber Specifies which stream to read from the source file. SpliceWithNext Joins the AMTimelineSrc object to another AMTimelineSrc object.
Not supported for Visual Basic.
Syntax
object.FixMediaTimes( pStart As <Unsupported variant type>, pStop As <Unsupported variant type> )
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
object.FixMediaTimes2( pStart As Double, pStop As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pStart
- Start time, in seconds. If the call succeeds, this variable is set to the rounded time.
- pStop
- Stop time, in seconds. If the call succeeds, this variable is set to the rounded time.
Error Codes
If the method fails, an error is raised.
Remarks
This method is similar to the AMTimelineObj.FixTimes2 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.
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
object.GetDefaultFPS( pFPS As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pFPS
- Variable that receives the default frame rate, in frames per second.
Error Codes
If the method fails, an error is raised.
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.
Not supported for Visual Basic.
Syntax
object.GetMediaLength( pLength As <Unsupported variant type> )
Retrieves the media length of this object.
Syntax
object.GetMediaLength2( pLength As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pLength
- Variable that receives the media length in seconds.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_NOTDETERMINED Media times are not set on this object.
See Also
Retrieves the name of the source file represented by this object.
Syntax
object.GetMediaName() As String
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
Return Value
Returns the name of the source file.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_OUTOFMEMORY Insufficient memory.
Not supported for Visual Basic.
Syntax
object.GetMediaTimes( pStart As <Unsupported variant type>, pStop As <Unsupported variant type> )
Retrieves the media start and stop times.
Syntax
object.GetMediaTimes2( pStart As Double, pStop As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pStart
- Variable that receives the media start time, in seconds.
- pStop
- Variable that receives the media stop time, in seconds.
Error Codes
If the method fails, an error is raised.
Remarks
The media times are relative to the original media file. For more information, see Time in DirectShow Editing Services.
Retrieves the current stream number for the source object.
Syntax
object.GetStreamNumber( pVal As Long )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pVal
- Variable that receives the stream number.
Error Codes
If the method fails, an error is raised.
Retrieves the stretch mode. The stretch mode determines how a video source is rendered if its size does not match the output dimensions.
Syntax
object.GetStretchMode( pnStretchMode As Long )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pnStretchMode
- Variable that receives one of the following values:
Error Codes
If the method fails, an error is raised.
Indicates whether the clip will play at the authored playback rate.
Syntax
object.IsNormalRate( pVal As Long )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pVal
- Variable that receives a value indicating how the clip will render. If non-zero, the clip will play at the normal rate. If zero, it will play faster or slower than normal.
Error Codes
If the method fails, an error is raised.
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.
Not supported for Visual Basic.
Syntax
object.ModifyStopTime( Stop As <Unsupported variant type> )
Sets the stop time.
Syntax
object.ModifyStopTime2( Stop As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- Stop
- New stop time, in seconds.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_INVALIDARG The specified time is invalid.
Sets the source object's default frame rate.
Syntax
object.SetDefaultFPS( FPS As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- FPS
- Default frame rate, in frames per second.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_INVALIDARG 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.
Not supported for Visual Basic.
Syntax
object.SetMediaLength( Length As <Unsupported variant type> )
Specifies the duration of the source file. This method is equivalent to the SetMediaLength method, but takes a REFTIME value.
Syntax
object.SetMediaLength2( Length As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- Length
- Media length, in seconds.
Error Codes
If the method fails, an error is raised.
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 retrieving the IMediaDet.StreamLength property.
Specifies the name of the source file.
Syntax
object.SetMediaName( newVal As String )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- newVal
- String that specifies the name of the media file.
Error Codes
If the method fails, an error is raised.
Not supported for Visual Basic.
Syntax
object.SetMediaTimes( Start As <Unsupported variant type>, Stop As <Unsupported variant type> )
Sets the media stop and start times.
Syntax
object.SetMediaTimes2( Start As Double, Stop As Double )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- Start
- Media start time, in seconds.
- Stop
- Media stop time, in seconds.
Error Codes
If the method fails, an error is raised.
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.
Specifies which stream to read from the source file.
Syntax
object.SetStreamNumber( Val As Long )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- Val
- The stream number, from the set of streams matching the media type of the parent group.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_INVALIDARG The Val parameter 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, suppose that a file contains two video streams and two audio streams. If the AMTimelineSrc 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
object.SetStretchMode( nStretchMode As Long )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- nStretchMode
- Flag indicating the current stretch mode. Must be one of the following values:
Error Codes
If the method fails, an error is raised.
Joins the AMTimelineSrc object to another AMTimelineSrc object.
Syntax
object.SpliceWithNext( pNext As AMTimelineObj )
Parts
- object
- Object expression that evaluates to an AMTimelineSrc object.
- pNext
- AMTimelineObj object to join to the current source.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to one of the following values:
E_INVALIDARG Invalid argument. E_NOINTERFACE Object specified by pNext parameter is not a source object.
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.