Microsoft DirectX 8.0

IAMPushSource Interface

This interface provides methods for synchronizing a filter graph that renders a live source (that is, a source that streams data in real time, such as a capture device or a network broadcast). It inherits from the IAMLatency interface.

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. The filter graph manager uses the methods on this interface to address two problems that commonly occur when rendering live sources:

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.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IAMLatency methodsDescription
GetLatencyRetrieves the expected latency associated with this filter.
IAMPushSource methodsDescription
GetPushSourceFlagsRetrieves a combination of flags describing the behavior of the filter.
SetPushSourceFlagsSets flags that specify the behavior of the filter.
SetStreamOffsetSets the offset for time stamps generated by this filter.
GetStreamOffsetRetrieves the offset that the filter uses when generating time stamps.
GetMaxStreamOffsetRetrieves the maximum stream offset the filter can support.
SetMaxStreamOffsetReference time specifying the maximum stream offset.

IAMPushSource::GetMaxStreamOffset

IAMPushSource Interface

Retrieves the maximum stream offset the filter can support.

Syntax

HRESULT GetMaxStreamOffset(
    REFERENCE_TIME *prtMaxOffset
);

Parameters

prtMaxOffset
[out] Pointer to a variable that receives a reference time indicating the maximum offset the filter can support.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The Microsoft® DirectShow® implementation returns E_POINTER or S_OK.

Remarks

If the stream offset is set to a value larger than the maximum supported offset, the filter is not guaranteed to have a buffer large enough to hold data for the entire amount of the offset. Unless there is another buffer downstream, data might be lost.

IAMPushSource::GetPushSourceFlags

IAMPushSource Interface

Retrieves a combination of flags describing the behavior of the filter.

Syntax

HRESULT GetPushSourceFlags(
    ULONG *pFlags
);

Parameters

pFlags
[out] Pointer to a variable that receives a combination of flags from the AM_PUSHSOURCE_FLAGS enumerated type.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Call this method to determine whether a renderer filter can safely match clock rates with this source filter.

IAMPushSource::GetStreamOffset

IAMPushSource Interface

Retrieves the offset that the filter uses when generating time stamps.

Syntax

HRESULT GetStreamOffset(
    REFERENCE_TIME  *prtOffset
);

Parameters

prtOffset
[out] Pointer to a variable that receives a reference time indicating the current stream offset.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMPushSource::SetMaxStreamOffset

IAMPushSource Interface

Specifies the stream offset that will be allowed in the filter graph.

Syntax

HRESULT SetMaxStreamOffset(
    REFERENCE_TIME rtMaxOffset
);

Parameters

rtMaxOffset
[in] Reference time specifying the maximum stream offset.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

If this method is called prior to connecting the filter, the filter can allocate an appropriately sized buffer.

IAMPushSource::SetPushSourceFlags

IAMPushSource Interface

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.

Syntax

HRESULT SetPushSourceFlags(
    ULONG Flags
);

Parameters

Flags
[in] Combination of flags from the AM_PUSHSOURCE_FLAGS enumerated type.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMPushSource::SetStreamOffset

IAMPushSource Interface

Sets the offset for time stamps generated by this filter.

Syntax

HRESULT SetStreamOffset(
    REFERENCE_TIME rtOffset
);

Parameters

rtOffset
[in] New stream offset for the filter.

Return Value

Returns S_FALSE if the specified offset is larger than the filter's maximum preferred offset. Otherwise, returns S_OK if successful or an HRESULT value indicating the cause of the error.

Remarks

The filter graph calls this method to adjust a filter's stream offset, in order to synchronize streams with different latency values.

If the return value is S_FALSE, the filter might not support a buffer large enough for the requested offset. Unless there is another buffer downstream, data might be lost. To retrieve the filter's maximum preferred offset, call the GetMaxStreamOffset method.