Microsoft DirectX 8.0

IMediaSeeking Interface

Contains methods for seeking to a position within a stream, and for setting the playback rate.

The filter graph manager exposes this interface, as do individual filters. Applications should obtain this interface from the filter graph manager, not from a filter. The filter graph manager distributes method calls to all of the renderer filters. The renderer filters send the calls upstream to the source filters. This sequence of events ensures that all streams remain synchronized.

If any of the distributed calls returns an error, the filter graph manager returns the first error value it received, even if some of the distributed calls succeed. An exception is E_NOTIMPL: the filter graph manager does not return E_NOTIMPL unless it was returned by all of the distributed calls.

An application can seek the graph while the graph is in any state (running, paused or stopped). If the graph is running, the filter graph manager pauses the graph before it issues the seek command. Then it runs the graph again. All seeking operations are independent of the current playback rate. Seeking operations cause any pending media data to be flushed from the graph.

This interface improves on the IMediaPosition interface. The IMediaPosition methods require time parameters in fractions of seconds, whereas the IMediaSeeking methods can accept arbitrary formats, such as frames, bytes, or 100-nanosecond units. Also, IMediaSeeking uses 64-bit integers (LONGLONG), providing for greater accuracy. On the other hand, IMediaSeeking is not compatible with Automation, so applications written in Microsoft® Visual Basic® must use IMediaPosition.

For all IMediaSeeking parameters that specify time, the unit of time depends on the current time format. To set the time format, call the IMediaSeeking::SetTimeFormat method. Time formats are globally unique identifiers (GUIDs) defined in uuids.h. For more information, see Time Format GUIDs.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IMediaSeeking methodsDescription
GetCapabilitiesRetrieves all the seeking capabilities of the stream.
CheckCapabilitiesQueries whether a stream has specified seeking capabilities.
IsFormatSupportedDetermines whether a specified time format is supported.
QueryPreferredFormatRetrieves the preferred time format for the stream.
GetTimeFormatRetrieves the current time format.
IsUsingTimeFormatDetermines whether a specified time format is the format currently in use.
SetTimeFormatSets the time format.
GetDurationRetrieves the duration of the stream.
GetStopPositionRetrieves the time at which the playback will stop, relative to the duration of the stream.
GetCurrentPositionRetrieves the current position, relative to the total duration of the stream.
ConvertTimeFormatConverts from one time format to another.
SetPositionsSets the current position and the stop position.
GetPositionsRetrieves the current position and the stop position, relative to the total duration of the stream.
GetAvailableRetrieves the range of times in which seeking is efficient.
SetRateSets the playback rate.
GetRateRetrieves the playback rate.
GetPrerollRetrieves the amount of data that will be queued before the start position.

IMediaSeeking::CheckCapabilities

IMediaSeeking Interface

Queries whether a stream has specified seeking capabilities.

Syntax

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
[in, out] Pointer to a bitwise combination of one or more AM_SEEKING_SEEKING_CAPABILITIES attributes. When the method returns, the value indicates which of those attributes are available.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSENot all of the capabilities in pCapabilities are present.
S_OKAll capabilities in pCapabilities are present.
E_FAILNo capabilities in pCapabilities are present.
E_POINTERNULL pointer argument.

Remarks

If you are only interested in a few specific capabilities, calling this method is more efficient than calling GetCapabilities, which checks all the stream's seeking capabilities.

Declare a DWORD value equal to the bitwise-OR combination of the AM_SEEKING_SEEKING_CAPABILITIES attributes that you want to test. Pass a pointer to this value in the pCapabilities parameter. When the method returns, pCapabilities contains a subset of the original bits, indicating which capabilities are present. The return value indicates whether some, none, or all of the requested capabilities are present.

The following code example shows how to find out whether the stream supports forward seeking, backward seeking, and absolute seeking.

// Set flags for the capabilities you want to check.
DWORD dwCaps = AM_SEEKING_CanSeekAbsolute | 
             AM_SEEKING_CanSeekForwards |
             AM_SEEKING_CanSeekBackwards;

HRESULT hr = pMediaSeeking->CheckCapabilities(&dwCaps);
if(FAILED(hr)) 
{
    // The stream cannot seek.
}
else if (hr == S_OK) 
{   
    // The stream can seek forward, backward, and to an absolute position.
}
else if (hr == S_FALSE) // The stream might have some of the capabilities.
{
    if (dwCaps & AM_SEEKING_CanSeekAbsolute)
        // The stream can seek to an absolute position.
    if dwCaps & AM_SEEKING_CanSeekAbsolute)
        // The stream can seek forward.
    if (dwCaps & AM_SEEKING_CanSeekBackwards)
        // The stream can seek backward.
}

IMediaSeeking::ConvertTimeFormat

IMediaSeeking Interface

Converts from one time format to another.

Syntax

HRESULT ConvertTimeFormat(
    LONGLONG *pTarget,
    const GUID *pTargetFormat,
    LONGLONG Source,
    const GUID *pSourceFormat
);

Parameters

pTarget
[out] Pointer to a variable that receives the converted time.
pTargetFormat
[in] Pointer to the time format GUID of the target format. If NULL, the current format is used.
Source
[in] Time value to be converted.
pSourceFormat
[in] Pointer to the time format GUID of the format to convert. If NULL, the current format is used.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_INVALIDARGConversion between these types is not supported.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

IMediaSeeking::GetAvailable

IMediaSeeking Interface

Retrieves the range of times in which seeking is efficient.

Syntax

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

Parameters

pEarliest
[out] Pointer to a variable that receives the earliest time for efficient seeking.
pLatest
[out] Pointer to a variable that receives the latest time for efficient seeking.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

This method is intended primarily for seeking in media streams that might have excessive latency, such as streams being sent over a network. The returned values indicate cached data that has already arrived, which can be easily seeked. It is assumed that seeking to values beyond these returned parameters will cause a delay while the application waits for the data to arrive.

IMediaSeeking::GetCapabilities

IMediaSeeking Interface

Retrieves all the seeking capabilities of the stream.

Syntax

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
[out] Pointer to a variable that receives a bitwise combination of AM_SEEKING_SEEKING_CAPABILITIES flags.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTERNULL pointer argument.

Remarks

This method returns information on all the seeking capabilities of the stream. Examine pCapabilities by performing a separate bitwise-AND operation on each AM_SEEKING_SEEKING_CAPABILITIES value you are interested in.

DWORD dwCaps = 0;
pMediaSeeking->GetCapabilities(&dwCaps);

if (dwCaps & AM_SEEKING_CanGetCurrentPos) 
{
    // The stream can seek to the current position.
}
if (dwCaps & AM_SEEKING_CanPlayBackwards) 
{
    // The stream can play backward.
}

IMediaSeeking::GetCurrentPosition

IMediaSeeking Interface

Retrieves the current position, relative to the total duration of the stream.

Syntax

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

Parameters

pCurrent
[out] Pointer to a variable that receives the current position, in units of the current time format.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

This method returns the current position that playback has reached. The value ignores the playback rate and start time. For example, if you set the rate to 2.0 and the start time to five seconds, running the graph for four seconds yields a current position of nine seconds (5 + 4 × 2.0). The returned value is expressed in units of the current time format. To determine the current time format, call the GetTimeFormat method.

If the graph is paused or stopped, the current position is the point at which playback will resume.

The filter graph manager calculates the position from the current stream time; it does not query the filters in the graph. For file playback, this yields an accurate result, because playback is synchronized to the stream time. For file writing, the results are not accurate. To get the current position in a file-writing graph, query the multiplexer filter. (Position is not relevant for live capture, however.)

IMediaSeeking::GetDuration

IMediaSeeking Interface

Retrieves the duration of the stream.

Syntax

HRESULT GetDuration(
    LONGLONG *pDuration
);

Parameters

pDuration
[out] Pointer to a variable that receives the duration, in units of the current time format.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

This method retrieves the duration of the stream at normal playback speed. Changing the playback rate does not affect the duration. The returned value is expressed in units of the current time format. To determine the current time format, call the GetTimeFormat method.

IMediaSeeking::GetPositions

IMediaSeeking Interface

Retrieves the current position and the stop position, relative to the total duration of the stream.

Syntax

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

Parameters

pCurrent
[out] Pointer to a variable that receives the current position, in units of the current time format.
pStop
[out] Pointer to a variable that receives the stop position, in units of the current time format.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

The current position and the stop position are both relative to the original stream, and are independent of the playback rate.

The returned values are expressed in units of the current time format. To determine the current time format, call the GetTimeFormat method.

IMediaSeeking::GetPreroll

IMediaSeeking Interface

Retrieves the amount of data that will be queued before the start position.

Syntax

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

Parameters

pllPreroll
[out] Pointer to a variable that receives the preroll time, in units of the current time format.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

The preroll is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

IMediaSeeking::GetRate

IMediaSeeking Interface

Retrieves the playback rate.

Syntax

HRESULT GetRate(
    double *dRate
);

Parameters

dRate
[out] Pointer to a variable that receives the playback rate.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

The playback rate is expressed as a ratio of the normal speed. Thus, 1.0 is normal playback speed, 0.5 is half speed, and 2.0 is twice speed.

IMediaSeeking::GetStopPosition

IMediaSeeking Interface

Retrieves the time at which the playback will stop, relative to the duration of the stream.

Syntax

HRESULT GetStopPosition(
    LONGLONG *pStop
);

Parameters

pStop
[out] Pointer to a variable that receives the stop time, in units of the current time format.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

The playback rate does not affect the value returned by this method. The returned values are expressed in units of the current time format. To determine the current time format, call the GetTimeFormat method.

IMediaSeeking::GetTimeFormat

IMediaSeeking Interface

Retrieves the current time format.

Syntax

HRESULT GetTimeFormat(
    GUID *pFormat
);

Parameters

pFormat
[out] Pointer to a variable that receives a time format GUID.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTERNULL pointer argument.

IMediaSeeking::IsFormatSupported

IMediaSeeking Interface

Determines whether a specified time format is supported.

Syntax

HRESULT IsFormatSupported(
    const GUID *pFormat
);

Parameters

pFormat
[in] Pointer to a time format GUID.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSEThe format is not supported.
S_OKThe format is supported.
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.

IMediaSeeking::IsUsingTimeFormat

IMediaSeeking Interface

Determines whether a specified time format is the format currently in use.

Syntax

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
[in] Pointer to a time format GUID.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSEThe specified format is not the current format.
S_OKThe specified format is the current format.
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.

Remarks

This method is more efficient than the IMediaSeeking::GetTimeFormat method, because it does not require copying the GUID.

IMediaSeeking::QueryPreferredFormat

IMediaSeeking Interface

Retrieves the preferred time format for the stream.

Syntax

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

Parameters

pFormat
[out] Pointer to a variable that receives a time format GUID.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.

Remarks

If the returned format is not satisfactory, call the IsFormatSupported method to query for other supported time formats.

IMediaSeeking::SetPositions

IMediaSeeking Interface

Sets the current position and the stop position.

Syntax

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD dwCurrentFlags,
    LONGLONG *pStop,
    DWORD dwStopFlags
);

Parameters

pCurrent
[in,out] Pointer to a variable that specifies the current position, in units of the current time format.
dwCurrentFlags
[in] Bitwise combination of flags. See Remarks.
pStop
[in,out] Pointer to a variable that specifies the stop time, in units of the current time format.
dwStopFlags
[in] Bitwise combination of flags. See Remarks.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSENo position change. (Both flags specify no seeking.)
S_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

The dwCurrentFlags and dwStopFlags parameters define the type of seek. The following flags are defined:

Positioning Flags
AM_SEEKING_NoPositioningNo change in position. (The time parameter can be NULL.)
AM_SEEKING_AbsolutePositioningThe specified position is absolute.
AM_SEEKING_RelativePositioning The specified position is relative to the previous value.
AM_SEEKING_IncrementalPositioning The stop position (pStop) is relative to the current position (pCurrent).
Modifier Flags
AM_SEEKING_SeekToKeyFrame Seek to the nearest key frame. This might be faster, but less accurate.
AM_SEEKING_ReturnTime Return the equivalent reference times.
AM_SEEKING_Segment Use segment seeking.
AM_SEEKING_NoFlush Do not flush.

For each parameter, use one positioning flag. Optionally, include one or more modifier flags.

If the AM_SEEKING_ReturnTime flag is specified, the method converts the position value to a reference time and returns it in the pCurrent or pStop variable. This flag is useful if you are using another time format, such as frames.

The AM_SEEKING_Segment and AM_SEEKING_NoFlush flags support seamless looping:

To perform looping, the graph must report AM_SEEKING_CanDoSegments in the GetCapabilities method. Currently, only the WAVE Parser filter supports this feature.

IMediaSeeking::SetRate

IMediaSeeking Interface

Sets the playback rate.

Syntax

HRESULT SetRate(
    double dRate
);

Parameters

dRate
[in] Playback rate. Must not be zero.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_INVALIDARGThe specified rate was zero or a negative value. (See Remarks.)
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.
VFW_E_UNSUPPORTED_AUDIOAudio device or filter does not support this rate.

Remarks

The playback rate is expressed as a ratio of the normal speed. Thus, 1.0 is normal playback speed, 0.5 is half speed, and 2.0 is twice speed. For audio streams, changing the rate also changes the pitch.

Negative values indicate reverse playback. Most filters do not support negative playback, but instead return an error code if the dRate parameter is negative.

When an application calls this method on the filter graph manager, the filter graph manager does the following:

  1. Calls the GetCurrentPosition method. This call returns the current position as calculated by the filter graph manager.
  2. Stops the filter graph (if the graph is paused or running).
  3. Calls the SetPositions method on the filters, with the current position as the start time. This has the effect of resetting the stream time to zero.
  4. Calls the SetRate method on the filters, with the new rate.
  5. Resumes the filter graph, if it was paused or running.

If an error occurs in step 4, the filter graph manager tries to restore the previous rate.

Filters should repond to rate changes as follows:

Parser and source filters: The filter that originates the time stamps responds to the SetRate call. This is usually a parser filter, such as the AVI Splitter, but it might be a source filter. After any seek or rate change, the filter should call the IPin::NewSegment method with the new settings. After a rate change, it should adjust its time stamps accordingly. Because a rate change is preceded by a seek, time stamps restart from zero, so the filter can simply divide by the rate to calculate the new time stamps.

Decoder filters: Decoders should not act on SetRate calls other than to pass them upstream. Instead, they should respond to the NewSegment call that the upstream parser issues. When a decoder filter receives new segment information, it should store the values and pass the NewSegment call downstream. Some decoders need to generate extra time stamps by interpolating their input; they should take rate changes into account when doing so.

Renderers: Video renderers can typically ignore rate changes, because the incoming frames already have the correct time stamp. Audio renderers must modify their playback rate, because audio decoders typically do not make rate-change conversions.

IMediaSeeking::SetTimeFormat

IMediaSeeking Interface

Sets the time format.

Syntax

HRESULT SetTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
[in] Pointer to a time format GUID.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.
VFW_E_WRONG_STATEFilter graph is not stopped.

Remarks

This method specifies the time units used by other IMediaSeeking methods, such as GetPositions and SetPositions. To determine what formats are supported, call the IsFormatSupported method. To retrieve the current time format, call the GetTimeFormat method. To determine the preferred time format, call the QueryPreferredFormat method.

Only one time format can be set on the filter graph at any one time.