IAMPushSource interface (strmif.h)

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The IAMPushSource interface synchronizes a filter graph that renders a live source. A live source is a source that streams data in real time, such as a capture device or a network broadcast.

Source filters that stream live data should expose this interface on their output pins. Generally, applications should not call the methods on this interface; instead, use the IAMGraphStreams interface.

Inheritance

The IAMPushSource interface inherits from IAMLatency. IAMPushSource also has these types of members:

Methods

The IAMPushSource interface has these methods.

IAMPushSource::GetMaxStreamOffset The GetMaxStreamOffset method retrieves the maximum stream offset the filter can support.
IAMPushSource::GetPushSourceFlags The GetPushSourceFlags method retrieves a combination of flags describing the behavior of the filter.
IAMPushSource::GetStreamOffset The GetStreamOffset method retrieves the offset that the filter uses when generating time stamps.
IAMPushSource::SetMaxStreamOffset The SetMaxStreamOffset method specifies the stream offset that will be allowed in the filter graph.
IAMPushSource::SetPushSourceFlags The SetPushSourceFlags method sets flags that specify the behavior of the filter. Currently, applications should not call this method, because request flags are not supported and an application should not override the flags set by the filter.
IAMPushSource::SetStreamOffset The SetStreamOffset method sets the offset for time stamps generated by this filter.

Remarks

The Filter Graph Manager uses the methods on this interface to address two problems that commonly occur when rendering live sources:

• Latency: When a filter graph includes more than one live source, the sources often have different latencies, which can cause them to be out of sync. For example, if audio capture has a longer latency time than video capture, the audio will lag behind the video unless the graph compensates for the difference.
• Rate Matching: When a renderer filter is connected to a live source, it must adjust its data consumption rate to match the source filter's production rate. Otherwise, there might be gaps in the data (if the renderer runs faster than the source) or data might get dropped (if the source runs faster).

To correct for latency, the filter graph calls IAMLatency::GetLatency on each output pin that exposes the IAMPushSource interface, and determines the maximum latency in the graph. It then calls IAMPushSource::SetStreamOffset on any filters with less than the maximum latency, so that they will adjust the time stamps they generate by the correct offset.

To perform rate matching, the filter graph needs to determine whether the renderer filter can match clock rates with the source filter. The IAMPushSource::GetPushSourceFlags method returns a set of flags indicating whether it is safe for the renderer to match rates with the source.

These issues do not affect capturing to a file. The File Writer filter relies on time stamps on the incoming samples to write the file correctly; the streams are then synchronized during playback. As for rate matching, the data is always written to the file as fast as possible.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	strmif.h (include Dshow.h)

See also

IAMLatency