Microsoft DirectX 8.0 |
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.
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IAMLatency methods Description GetLatency Retrieves the expected latency associated with this filter. IAMPushSource methods Description GetPushSourceFlags Retrieves a combination of flags describing the behavior of the filter. SetPushSourceFlags Sets flags that specify the behavior of the filter. SetStreamOffset Sets the offset for time stamps generated by this filter. GetStreamOffset Retrieves the offset that the filter uses when generating time stamps. GetMaxStreamOffset Retrieves the maximum stream offset the filter can support. SetMaxStreamOffset Reference time specifying the maximum stream offset.
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.
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.
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.
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.
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.
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.