IMediaSeeking::SetRate

The SetRate method 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.

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 IMediaSeeking::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 IMediaSeeking::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 Filter, 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.

See Also

• Error and Success Codes
• IMediaSeeking Interface