IMediaPosition Interface
Although the IMediaPosition interface provides applications a simple seeking interface on a filter graph, it has a number of limitations. The IMediaPosition interface allows seeking only by using REFTIME time-based units; however, many filter graphs need to seek on units of samples, video frames, or fields in a compressed stream. Also, the IMediaPosition interface uses separate methods to set and retrieve position properties, which can cause unnecessary filter flushing. For these reasons, you should use the IMediaSeeking interface, which improves on IMediaPosition.
Applications communicating with the filter graph can call methods on the IMediaPosition interface to set or retrieve properties such as the duration of the stream, the start and stop times, the preroll time, the rate, and the current position. The filter graph uses these properties on seekable filters to control the playback of streams within the graph; where there are multiple streams, the filter graph sets them all to play in parallel, beginning at the same position, and will report the duration as being the duration of the longest stream. The REFTIME parameters used in this interface are double value, representing a fractional number of seconds. Internally, filters will store time to an accuracy of 100 nanoseconds.
The filter graph manager exposes the IMediaPosition interface if any of the filters within the graph are seekable (can seek to an arbitrary position in the stream). This usually means a seekable file source filter. Filters, such as a file source filter, will expose IMediaPosition if they can seek their data or if their output pin represents a seekable stream. The renderer filter should also expose this interface. Output pins of transform filters expose this interface to pass the positioning information upstream from the renderer through each intermediate filter to the seekable filter.
Use the CMediaPosition class to help implement this interface on a filter. Use the CPosPassThru base class to implement this interface on output pins of transform filters used to pass media positioning information upstream. This is enabled by default in the pin base classes.
Applications can use this interface to set or retrieve media positioning properties. Most commonly, an application will use the methods on this interface to play a media stream for some duration starting at some set position in the stream (for example, 10 seconds from the start).
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IDispatch methods Description GetTypeInfoCount Determines whether there is type information available for this dispinterface. GetTypeInfo Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully. GetIDsOfNames Converts text names of properties and methods (including arguments) to their corresponding DISPIDs. Invoke Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters. IMediaPosition methods Description get_Duration Retrieves the total duration of the media stream. put_CurrentPosition Sets the time that the media stream begins. get_CurrentPosition Retrieves the current position in terms of the total length of the media stream. get_StopTime Retrieves the position within the media stream at which playback should stop. put_StopTime Sets the position within the media stream at which playback should stop. get_PrerollTime Retrieves the time prior to the start position that the filter graph begins any nonrandom access device rolling. put_PrerollTime Sets the time prior to the start position that the filter graph begins any nonrandom access device rolling. put_Rate Sets the playback rate, relative to normal playback of the media stream. get_Rate Retrieves the playback rate, relative to normal playback of the media stream. CanSeekForward Determines if the current position can be moved forward in the media stream. CanSeekBackward Determines if the current position can be moved backward in the media stream.
IMediaPosition::CanSeekBackward
Determines if the current position can be moved backward in the media stream.
Syntax
HRESULT CanSeekBackward(
LONG *pCanSeekBackward
);
Parameters
- pCanSeekBackward
- [out] Pointer to a value indicating whether the current position can be moved backward. OATRUE indicates able to seek backward; OAFALSE otherwise.
Return Value
Returns an HRESULT value.
IMediaPosition::CanSeekForward
Determines if the current position can be moved forward in the media stream.
Syntax
HRESULT CanSeekForward(
LONG *pCanSeekForward
);
Parameters
- pCanSeekForward
- [out] Pointer to a value indicating whether the current position can be moved forward. OATRUE indicates able to seek forward; OAFALSE otherwise.
Return Value
Returns an HRESULT value.
IMediaPosition::get_CurrentPosition
Retrieves the current position in terms of the total length of the media stream.
Syntax
HRESULT get_CurrentPosition(
REFTIME *pllTime
);
Parameters
- pllTime
- [out] Pointer to the reference time of the current position.
Return Value
Returns an HRESULT value.
Remarks
This is the position that playback has reached. It is a value between zero and the total duration of the media (that is, it does not take into account the rate and start time). If the filter graph is paused, this is the position at which it will restart.
When the filter graph is stopped or paused, this method returns the position at which playback will recommence. When the filter graph is running, the filter graph manager returns the position according to the reference clock. If an individual filter implements this, it should return the stream time of the sample it is processing (that is, the offset time from the beginning) when paused or running. If you implement this using stream time or the reference clock, remember to adjust the value you return for start position and playback rate so that the value returned is in terms of the media's total duration.
After stopping or pausing, a run command causes playback to begin at the current position. This will be where playback stopped or paused, unless there has been an IMediaPosition::put_CurrentPosition call in the meantime.
IMediaPosition::get_Duration
Retrieves the total duration of the media stream.
Syntax
HRESULT get_Duration(
REFTIME *plength
);
Parameters
- plength
- [out] Pointer to the returned length of the media stream.
Return Value
Returns an HRESULT value.
Remarks
The duration assumes normal playback speed, and it is therefore unaffected by the rate.
IMediaPosition::get_PrerollTime
Retrieves the time prior to the start position that any nonrandom access device should start rolling.
Syntax
HRESULT get_PrerollTime(
REFTIME *pllTime
);
Parameters
- pllTime
- [out] Pointer to the returned preroll time as a double pointer value.
Return Value
Returns an HRESULT value.
Remarks
Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.
IMediaPosition::get_Rate
Retrieves the rate of playback relative to normal playback speed.
Syntax
HRESULT get_Rate(
double *pdRate
);
Parameters
- pdRate
- [out] Pointer to the returned rate.
Return Value
Returns an HRESULT value.
Remarks
A rate of 1.0 indicates normal playback speed. A rate of 0.5 indicates half speed. A rate of –1.0 indicates normal speed in reverse.
IMediaPosition::get_StopTime
Retrieves the time at which the media stream stops.
Syntax
HRESULT get_StopTime(
REFTIME *pllTime
);
Parameters
- pllTime
- [out] Pointer to the returned stop time as a double pointer value.
Return Value
Returns an HRESULT value.
Remarks
The stop time is a position between zero and the duration of the media at which playback should stop.
The stop position is applied before the rate and therefore is the position at typical playback speed.
IMediaPosition::put_CurrentPosition
Sets the time that the media stream begins.
Syntax
HRESULT put_CurrentPosition(
REFTIME llTime
);
Parameters
- llTime
- [in] Start time expressed as a double value.
Return Value
Returns an HRESULT value.
Remarks
The start time is a position between zero and the duration of the media at which playback should begin when the next run command is issued.
If this method is called when the filter graph manager is running, the filter graph manager will pause the graph, run the method, and then issue a new run command.
If called when the filter graph is paused, this method must flush existing data by using IPin::BeginFlush and IPin::EndFlush before pushing the new data (at the new current position).
Setting the current position when paused or stopped causes playback to resume from the new start position when the run command is issued.
The current position is applied before the rate and therefore is the position at typical playback speed.
IMediaPosition::put_PrerollTime
Sets the time prior to the start position that any nonrandom access device should start rolling.
Syntax
HRESULT put_PrerollTime(
REFTIME llTime
);
Parameters
- llTime
- [in] Preroll time to be set.
Return Value
Returns an HRESULT value.
Remarks
Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.
IMediaPosition::put_Rate
Sets the rate of playback relative to normal speed.
Syntax
HRESULT put_Rate(
double dRate
);
Parameters
- dRate
- [in] Rate to set.
Return Value
Returns an HRESULT value.
Remarks
This method allows an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop samples.
IMediaPosition::put_StopTime
Sets the time at which the media stream will stop.
Syntax
HRESULT put_StopTime(
REFTIME llTime
);
Parameters
- llTime
- [in] Stop time as a double value.
Return Value
Returns an HRESULT value.
Remarks
The stop time is a position between zero and the duration of the media at which playback should stop.
The stop position is applied before the rate and therefore is the position at typical playback speed.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.