IMediaSeeking::SetRate
| Microsoft DirectShow 9.0 |
IMediaSeeking::SetRate
The SetRate method sets the playback rate.
Syntax
HRESULT SetRate( double dRate );
Parameters
dRate
[in] Playback rate. Must not be zero.
Return Values
Returns an HRESULT value. Possible values include the following.
| Return code | Description |
| S_OK | Success. |
| E_INVALIDARG | The specified rate was zero or a negative value. (See Remarks.) |
| E_NOTIMPL | Not implemented. |
| E_POINTER | NULL pointer argument. |
| VFW_E_UNSUPPORTED_AUDIO | Audio 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:
- Calls the IMediaSeeking::GetCurrentPosition method. This call returns the current position as calculated by the Filter Graph Manager.
- Stops the filter graph (if the graph is paused or running).
- 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.
- Calls the SetRate method on the filters, with the new rate.
- 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.
Requirements
Header: Declared in Strmif.h; include Dshow.h.
Library: Use Strmiids.lib.
See Also