The CPosPassThru class is a utility class that handles the IMediaPosition and IMediaSeeking interfaces for single-input pin renderers and transform filters.
IMediaPosition is the interface originally used for seeking in time-based media streams. IMediaSeeking is an interface intended to replace IMediaPosition in filter graphs that require seeking to units other than time, such as samples or fields, or that require more precise time-based seeking.
Renderers will use this class to implement IMediaPosition and IMediaSeeking from the filter; transform filters will use it to implement these two interfaces from the output pin. In both cases, the methods will be implemented by calls to the IMediaPosition or IMediaSeeking interface provided by the output pin of the connected upstream filter, effectively passing the position information through to the next filter.
Create a class derived from CPosPassThru, giving it the IPin pointer to your input pin, and delegate all IMediaPosition and IMediaSeeking methods to it. The class will find the output pin connected to the input pin, query this output pin for the IMediaPosition or IMediaSeeking interface, and respond appropriately.
Protected Data Members
| Name | Description |
| m_Pin | Pointer to the input pin of the filter. |
Member Functions
| Name | Description |
| CPosPassThru | Constructs a CPosPassThru object. |
| ForceRefresh | Releases any cached interfaces held on the upstream pin. |
Overridable Member Functions
| Name | Description |
| GetMediaTime | Retrieves the starting and ending media times. |
Implemented IMediaPosition Methods
| Name | Description |
| CanSeekBackward | Determines if the current position can be moved backward in the media stream. |
| CanSeekForward | Determines if the current position can be moved forward in the media stream. |
| get_CurrentPosition | Retrieves the current position in terms of the total length of the media stream. |
| get_Duration | Retrieves the total duration of the media stream. |
| get_PrerollTime | Retrieves the time before the start position that the filter graph will start any nonrandom access device rolling. |
| get_Rate | Retrieves the playback rate, relative to normal playback of the media. |
| get_StopTime | Retrieves the position within the media at which playback should stop. |
| put_CurrentPosition | Sets the position within the media at which playback should start. |
| put_PrerollTime | Sets the time before the start position that the filter graph will start any nonrandom access device rolling. |
| put_Rate | Sets the playback rate, relative to normal playback of the media. |
| put_StopTime | Sets the position within the media at which playback should stop. |
Implemented IMediaSeeking Methods
| Name | Description |
| CheckCapabilities | Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value. |
| ConvertTimeFormat | Converts a time from one time format to another. |
| GetAvailable | Returns the range of times in which seeking is efficient. |
| GetCapabilities | Retrieves the seeking capabilities of the media stream. |
| GetCurrentPosition | Retrieves the current position within the media stream. |
| GetDuration | Retrieves the length of time that the media stream will play. |
| GetPositions | Retrieves the current and stop position settings. |
| GetPreroll | Retrieves the preroll settings. |
| GetRate | Retrieves the current rate. |
| GetStopPosition | Retrieves the position at which the media stream stops. |
| GetTimeFormat | Retrieves the current media time format. |
| IsFormatSupported | Determines if a specified time format is supported. |
| IsUsingTimeFormat | Determines if the time format being used in the call is the same as the one the interface currently uses. |
| QueryPreferredFormat | Retrieves the preferred time format the interface will use. |
| SetPositions | Sets current and stop positions and applies flags to both. |
| SetRate | Sets a new playback rate. |
| SetTimeFormat | Sets the time format, which determines the format of units used during seeking. |
Implemented INonDelegatingUnknown Methods
| Name | Description |
| NonDelegatingQueryInterface | Returns a specified reference-counted interface. |
Determines if the current position can be moved backward in the media stream.
HRESULT CanSeekBackward(
LONG *pCanSeekBackward
);
Returns the HRESULT value returned from calling IMediaPosition::CanSeekBackward on the connected pin.
This member function calls IMediaPosition::CanSeekBackward on the connected pin and returns the result.
Determines if the current position can be moved forward in the media stream.
HRESULT CanSeekForward(
LONG *pCanSeekForward
);
Returns the HRESULT value returned from calling IMediaPosition::CanSeekForward on the connected pin.
This member function calls IMediaPosition::CanSeekForward on the upstream output pin connected to the peer input pin and returns the result.
Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value.
HRESULT CheckCapabilities(
DWORD * pCapabilities
);
| AM_SEEKING_CanGetCurrentPos |
| AM_SEEKING_CanGetDuration |
| AM_SEEKING_CanGetStopPos |
| AM_SEEKING_CanPlayBackwards |
| AM_SEEKING_CanSeekAbsolute |
| AM_SEEKING_CanSeekBackwards |
| AM_SEEKING_CanSeekForwards |
Returns S_OK if all capabilities in pCapabilities are present, S_FALSE if some are present, or E_FAIL if none are present.
This member function implements IMediaSeeking::CheckCapabilities, by calling the IMediaSeeking::CheckCapabilities method on the upstream output pin connected to the peer input pin. The pin that performs the seek operation will return whether the flags presented in the pCapabilities parameter are present. This returned value will then, in turn, propagate to calls made from CPosPassThru::CheckCapabilities member functions in intervening filters.
Converts a time from one format to another.
HRESULT ConvertTimeFormat(
LONGLONG * pTarget,
const GUID * pTargetFormat,
LONGLONG Source,
const GUID * pSourceFormat
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::ConvertTimeFormat method by calling this same method on the upstream filter's output pin.
Constructs a CPosPassThru object.
CPosPassThru(
const TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT * phr,
IPin * pPin
);
No return value.
Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.
Releases any cached interfaces on the upstream pin.
HRESULT ForceRefresh( );
Returns S_OK.
For efficiency, the CPosPassThru class can cache the IMediaPosition interface of the connected upstream output pin. This method releases any cached interface pointers and forces them to be obtained again via QueryInterface if needed.
Presently, this class does not cache the upstream IMediaPosition so this member function is not necessary. It is left in for future flexibility.
Retrieves the current position in terms of the total length of the media stream.
HRESULT get_CurrentPosition(
REFTIME* pllTime
);
Returns an HRESULT value.
The start position is applied before the rate and therefore is the position at typical playback speed.
Retrieves the total duration of the media stream.
HRESULT get_Duration(
REFTIME * plength
);
Returns an HRESULT value.
The duration assumes normal playback speed, and it is therefore unaffected by the rate.
Retrieves the time prior to the start position that devices should start rolling.
HRESULT get_PrerollTime(
REFTIME* pllTime
);
Returns an HRESULT value.
Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.
Retrieves the rate of playback relative to normal playback speed.
HRESULT get_Rate(
double * pdRate
);
Returns an HRESULT value.
A rate of 1.0 indicates normal playback speed. A rate of 0.5 indicates half speed. A rate of –1.0 indicates normal speed in reverse.
Retrieves the time at which the media stream stops.
HRESULT get_StopTime(
REFTIME* pllTime
);
Returns an HRESULT value.
The stop time is a position between zero and the duration of the media at which playback should stop.
The stop position is applied before the rate and therefore is the position at typical playback speed.
Returns the range of times in which seeking is efficient.
HRESULT GetAvailable(
LONGLONG * pEarliest,
LONGLONG * pLatest
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetAvailable method by calling this same method on the upstream filter's output pin.
Returns the seeking capabilities of the media stream.
HRESULT GetCapabilities(
DWORD * pCapabilities
);
| AM_SEEKING_CanGetCurrentPos |
| AM_SEEKING_CanGetDuration |
| AM_SEEKING_CanGetStopPos |
| AM_SEEKING_CanPlayBackwards |
| AM_SEEKING_CanSeekAbsolute |
| AM_SEEKING_CanSeekBackwards |
| AM_SEEKING_CanSeekForwards |
Returns an HRESULT value.
This member function implements IMediaSeeking::GetCapabilities by calling the IMediaSeeking::GetCapabilities method on the upstream output pin connected to the peer input pin. The pin that performs the seek operation will return the capabilities present in the pCapabilities parameter. These returned capabilities will then, in turn, propagate to calls made from CPosPassThru::GetCapabilities member functions in intervening filters.
Retrieves the current position in terms of the media stream's total length.
HRESULT GetCurrentPosition(
LONGLONG* pCurrent
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetCurrentPosition interface. It calls the CPosPassThru::GetMediaTime virtual member function, which you should override and implement in your derived class to return the current position. If this fails (which it does by default), the IMediaSeeking::GetCurrentPosition on the upstream filter's output pin is called.
Retrieves the length of time that the media stream will play.
HRESULT GetDuration(
LONGLONG* pDuration
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetDuration method by calling this same method on the upstream filter's output pin.
Retrieves the starting and ending media times.
virtual HRESULT GetMediaTime(
LONGLONG* pStartTime,
LONGLONG* pEndTime
);
Returns an HRESULT value (E_FAIL by default).
Override this virtual member function to return the current samples' media time. This represents the current position in terms of media time (for example, frame 20 of a total 130 frames).
Returns the current and stop position settings.
HRESULT GetPositions(
LONGLONG * pCurrent,
LONGLONG * pStop
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetPositions method by calling this same method on the upstream filter's output pin. It allows the retrieval of several values with only one call.
Retrieves the preroll settings.
HRESULT GetPreroll(
LONGLONG * pllPreroll
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetPreroll method by calling this same method on the upstream filter's output pin.
Retrieves the current rate.
HRESULT GetRate(
double * dRate
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetRate method by calling this same method on the upstream filter's output pin.
Retrieves the position at which the media stream stops.
HRESULT GetStopPosition(
LONGLONG* pStop
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetStopPosition method by calling this same method on the upstream filter's output pin. The stop position is a time between zero and the duration of the media at which playback should stop.
The stop position is applied before the rate and therefore is the position at typical playback speed.
Retrieves the current time format, which determines the format of units used during seeking.
HRESULT GetTimeFormat(
const GUID * pFormat
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::GetTimeFormat method by calling this same method on the upstream filter's output pin.
See the IMediaSeeking::IsFormatSupported method for a list of time formats.
Determines if a specified time format is supported.
HRESULT IsFormatSupported(
const GUID * pFormat
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::IsFormatSupported method. See that method for a list of valid time formats.
Determines if the time format being used in the call is the same as the one currently in use by the interface.
HRESULT IsUsingTimeFormat(
const GUID * pFormat
);
Returns S_OK if pFormat is the current time format; otherwise returns S_FALSE.
This member function implements the IMediaSeeking::IsUsingTimeFormat method by calling this same method on the upstream filter's output pin. This can be used in place of IMediaSeeking::GetTimeFormat to save copying the GUID.
Returns a specified reference-counted interface.
HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);
Returns pointers to the IMediaPosition, IMediaSeeking, and IUnknown interfaces by default.
Override this method to publish any additional interfaces implemented by the derived class.
This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.
Sets the time that the media stream begins.
HRESULT put_CurrentPosition(
REFTIME llTime
);
Returns an HRESULT value.
The start time is a position between zero and the duration of the media at which playback should begin when the next run command is issued. Do not call this method when the filter graph is running, only when it is paused or stopped.
Setting the start position when paused causes playback to resume from the new start position when the run command is issued.
The start position is applied before the rate and therefore is the position at typical playback speed.
Sets the time prior to the start position that devices should start rolling.
HRESULT put_PrerollTime(
REFTIME llTime
);
Returns an HRESULT value.
Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.
Note that while this member function passes the call upstream, the IMediaPosition::put_PrerollTime method is not implemented on any Microsoft source filter.
Sets the rate of playback relative to normal speed.
HRESULT put_Rate(
double dRate
);
Returns an HRESULT value.
This property allows an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop frames.
Negative rates indicate reverse play. Not all media will support reverse play.
Sets the time at which the media stream will stop.
HRESULT put_StopTime(
REFTIME llTime
);
Returns an HRESULT value.
The stop time is a position between zero and the duration of the media at which playback should stop.
The stop position is applied before the rate and therefore is the position at typical playback speed.
Retrieves the preferred time format to be used by the interface.
HRESULT QueryPreferredFormat(
GUID *pFormat
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::QueryPreferredFormat method by calling this same method on the upstream filter's output pin.
See the description for IMediaSeeking::IsFormatSupported for a list of available time formats. If the time format returned is not satisfactory, use the IMediaSeeking::IsFormatSupported method to query for supported time formats that you can use.
Sets current and stop positions and applies flags to both.
HRESULT SetPositions(
LONGLONG * pCurrent,
DWORD dwCurrentFlags,
LONGLONG * pStop,
DWORD dwStopFlags
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::SetPositions method by calling this same method on the upstream filter's output pin. It allows the retrieval of several values with only one call.
Sets a new playback rate.
HRESULT SetRate(
double dRate
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::SetRate method by calling this same method on the upstream filter's output pin. It is an error to set the rate to 0.
Sets the time format, which determines the format of units used during seeking.
HRESULT SetTimeFormat(
const GUID * pFormat
);
Returns an HRESULT value.
This member function implements the IMediaSeeking::SetTimeFormat method by calling this same method on the upstream filter's output pin. See the IMediaSeeking::IsFormatSupported method for a list of time formats.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.