Microsoft DirectX 8.0 |
Handles seek commands for filters with one input pin that do not perform seeking on their own.
Declaration: Ctlutil.h
This helper class implements the IMediaPosition and IMediaSeeking interfaces for filters that pass seek commands upstream. When the filter graph manager receives a seek command from an application, it delivers the command to the renderer filters in the graph. The command is then passed upstream through each filter's output pin, until it reaches a filter that can execute the command (if any). Typically, seeking is implemented on source filters or parser filters.
The CPosPassThru class holds a pointer to the filter's input pin. It passes seek commands to the connected output pin on the upstream filter, as shown in the following diagram.
Use the CPosPassThru class for transform filters, and the derived CRendererPosPassThru class for renderer filters.
To use this class in your filter, create an instance of the class and specify the filter's input pin in the CPosPassThru constructor method. Then delegate all IMediaPosition and IMediaSeeking calls to the CPosPassThru object.
The simplest way to delegate seeking commands is to expose the CPosPassThru object's IMediaPosition and IMediaSeeking interfaces. When your filter or pin is queried for one of these interfaces, return a pointer to the CPosPassThru implementation of the interface. The following code shows how do this. It is adapted from the CTransformOutputPin class. The CreatePosPassThru function is a helper function that creates the CPosPassThru object:
// The following member variables are assumed: // CPosPassThru *m_pPos; // IPin *m_pPin; if (riid == IID_IMediaPosition || riid == IID_IMediaSeeking) { if (m_pPos == NULL) { HRESULT hr; hr = CreatePosPassThru(GetOwner(), FALSE, m_pPin, &m_pPos); if (FAILED(hr)) return hr; } return m_pPosition->QueryInterface(riid, ppv); } else { // Return pointers to the other interfaces on this pin. }
Except where noted, all IMediaPosition and IMediaSeeking methods in this class call the corresponding method on the connected pin and return the result.
Public Methods | |
---|---|
CPosPassThru | Constructor method. |
ForceRefresh | Obsolete. |
GetMediaTime | Retrieves the time stamps on the current sample. Virtual. |
IMediaPosition Methods | |
get_Duration | Retrieves the duration of the stream. |
put_CurrentPosition | Sets the current position, relative to the total duration of the stream. |
get_StopTime | Retrieves the time at which the playback will stop, relative to the duration of the stream. |
put_StopTime | Sets the time at which the playback will stop, relative to the duration of the stream. |
get_PrerollTime | Retrieves the amount of data that will be queued before the start position. |
put_PrerollTime | Sets the amount of data that will be queued before the start position. |
get_Rate | Retrieves the playback rate. |
put_Rate | Sets the playback rate. |
get_CurrentPosition | Retrieves the current position, relative to the total duration of the stream. |
CanSeekForward | Determines whether the stream can be seeked backward. |
CanSeekBackward | Determines whether the stream can be seeked forward. |
IMediaSeeking Methods | |
CheckCapabilities | Queries whether a stream has specified seeking capabilities. |
ConvertTimeFormat | Converts from one time format to another. |
GetAvailable | Retrieves the range of times in which seeking is efficient. |
GetCapabilities | Retrieves all the seeking capabilities of the stream. |
GetCurrentPosition | Retrieves the current position, relative to the total duration of the stream. |
GetDuration | Retrieves the duration of the stream. |
GetPositions | Retrieves the current position and the stop position, relative to the total duration of the stream. |
GetPreroll | Retrieves the amount of data that will be queued before the start position. |
GetRate | Retrieves the playback rate. |
GetStopPosition | Retrieves the time at which the playback will stop, relative to the duration of the stream. |
GetTimeFormat | Retrieves the current time format. |
IsFormatSupported | Determines whether a specified time format is supported. |
IsUsingTimeFormat | Determines whether a specified time format is the format currently in use. |
QueryPreferredFormat | Retrieves the preferred time format for the stream. |
SetPositions | Sets the current position and the stop position. |
SetRate | Sets the playback rate. |
SetTimeFormat | Sets the time format. |
Helper Functions | |
CreatePosPassThru | Creates a CPosPassThru or CRendererPosPassThru object. |
Determines whether the stream can be seeked backward. Implements the IMediaPosition::CanSeekBackward method.
Syntax
HRESULT CanSeekBackward( LONG *pCanSeekBackward );
Parameters
- pCanSeekBackward
- Pointer to a variable that receives the value OATRUE if the filter can seek backward, or OAFALSE otherwise.
Return Value
Returns the HRESULT value from the connected pin.
Determines whether the stream can be seeked forward. Implements the IMediaPosition::CanSeekForward method.
Syntax
HRESULT CanSeekForward( LONG *pCanSeekForward );
Parameters
- pCanSeekForward
- Pointer to a variable that receives the value OATRUE if the filter can seek forward, or OAFALSE otherwise.
Return Value
Returns the HRESULT value from the connected pin.
Queries whether a stream has specified seeking capabilities. Implements the IMediaSeeking::CheckCapabilities method.
Syntax
HRESULT CheckCapabilities( DWORD *pCapabilities );
Parameters
- pCapabilities
- Pointer to a bitwise combination of one or more AM_SEEKING_SEEKING_CAPABILITIES attributes. When the method returns, the value indicates which of those attributes are available.
Return Value
Returns the HRESULT value from the connected pin.
Converts from one time format to another. Implements the IMediaSeeking::ConvertTimeFormat method.
Syntax
HRESULT ConvertTimeFormat( LONGLONG *pTarget, const GUID *pTargetFormat, LONGLONG Source, const GUID *pSourceFormat );
Parameters
- pTarget
- Pointer to a variable that receives the converted time.
- pTargetFormat
- Pointer to the time format GUID of the target format. If NULL, the current format is used.
- Source
- Time value to be converted.
- pSourceFormat
- Pointer to the time format GUID of the format to convert. If NULL, the current format is used.
Return Value
Returns the HRESULT value from the connected pin.
Constructor method.
Syntax
CPosPassThru( const TCHAR *pName, LPUNKNOWN pUnk, HRESULT *phr, IPin *pPin );
Parameters
- pName
- Pointer to the name of the object, for debugging purposes. Allocate this parameter in static memory.
- pUnk
- Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
- phr
- Pointer to an HRESULT value. Ignored.
- pPin
- Pointer to the IPin interface of the filter's input pin.
Obsolete.
Syntax
HRESULT ForceRefresh(void);
Return Value
Returns S_OK.
Remarks
Originally this class was designed to cache pointers to the connected pin's IMediaPosition and IMediaSeeking interfaces. The ForceRefresh method released those interfaces.
As currently implemented, this class does not cache those interfaces. For compatibility, the ForceRefresh method is still included, but it returns S_OK without doing anything.
Retrieves the range of times in which seeking is efficient. Implements the IMediaSeeking::GetAvailable method.
Syntax
HRESULT GetAvailable( LONGLONG *pEarliest, LONGLONG *pLatest );
Parameters
- pEarliest
- Pointer to a variable that receives the earliest time for efficient seeking.
- pLatest
- Pointer to a variable that receives the latest time for efficient seeking.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves all the seeking capabilities of the stream. Implements the IMediaSeeking::GetCapabilities method.
Syntax
HRESULT GetCapabilities( DWORD *pCapabilities );
Parameters
- pCapabilities
- Pointer to a variable that receives a bitwise combination of AM_SEEKING_SEEKING_CAPABILITIES flags.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the current position, relative to the total duration of the stream. Implements the IMediaSeeking::GetCurrentPosition method.
Syntax
HRESULT GetCurrentPosition( LONGLONG *pCurrent );
Parameters
- pCurrent
- Pointer to a variable that receives the current position, in units of the current time format.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_NOTIMPL Method is not supported. E_POINTER NULL pointer argument.
Remarks
This method calls the CPosPassThru::GetMediaTime method to retrieve the most recent position. If GetMediaTime fails, the method calls IMediaSeeking::GetCurrentPosition on the connected pin.
The GetMediaTime method fails by default in the base class. If your filter caches the current position, override GetMediaTime to return the cached value.
Retrieves the current position, relative to the total duration of the stream. Implements the IMediaPosition::get_CurrentPosition method.
Syntax
HRESULT get_CurrentPosition( REFTIME *pllTime );
Parameters
- pllTime
- Pointer to a variable that receives the current position, in seconds.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the duration of the stream. Implements the IMediaSeeking::GetDuration method.
Syntax
HRESULT GetDuration( LONGLONG *pDuration );
Parameters
- pDuration
- Pointer to a variable that receives the duration, in units of the current time format.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the duration of the stream. Implements the IMediaPosition::get_Duration method.
Syntax
HRESULT get_Duration( REFTIME *plength );
Parameters
- plength
- Pointer to a variable that receives the total stream length, in seconds.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the time stamps on the current sample.
Syntax
virtual HRESULT GetMediaTime( LONGLONG *pStartTime, LONGLONG *pEndTime );
Parameters
- pStartTime
- Pointer to a variable that receives the start time, in units of the current time format.
- pEndTime
- Pointer to a variable that receives the end time, in units of the current time format.
Return Value
Returns E_FAIL.
Remarks
Override this method if your filter caches the time stamps on the samples it receives.
Retrieves the current position and the stop position, relative to the total duration of the stream. Implements the IMediaSeeking::GetPositions method.
Syntax
HRESULT GetPositions( LONGLONG *pCurrent, LONGLONG *pStop );
Parameters
- pCurrent
- Pointer to a variable that receives the current position, in units of the current time format.
- pStop
- Pointer to a variable that receives the stop position, in units of the current time format.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the amount of data that will be queued before the start position. Implements the IMediaSeeking::GetPreroll method.
Syntax
HRESULT GetPreroll( LONGLONG *pllPreroll );
Parameters
- pllPreroll
- Pointer to a variable that receives the preroll time, in units of the current time format.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the amount of data that will be queued before the start position. Implements the IMediaPosition::get_PrerollTime method.
Syntax
HRESULT get_PrerollTime( REFTIME *pllTime );
Parameters
- pllTime
- Pointer to a variable that receives the preroll time, in seconds.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the playback rate. Implements the IMediaSeeking::GetRate method.
Syntax
HRESULT GetRate( double *pdRate );
Parameters
- pdRate
- Pointer to a variable that receives the playback rate.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the playback rate. Implements the IMediaPosition::get_Rate method.
Syntax
HRESULT get_Rate( double *pdRate );
Parameters
- pdRate
- Pointer to a variable that receives the playback rate.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the time at which the playback will stop, relative to the duration of the stream. Implements the IMediaSeeking::GetStopPosition method.
Syntax
HRESULT GetStopPosition( LONGLONG *pStop );
Parameters
- pStop
- Pointer to a variable that receives the stop time, in units of the current time format.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the time at which the playback will stop, relative to the duration of the stream. Implements the IMediaPosition::get_StopTime method.
Syntax
HRESULT get_StopTime( REFTIME *pllTime );
Parameters
- pllTime
- Pointer to a variable that receives the stop time, in seconds.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the current time format. Implements the IMediaSeeking::GetTimeFormat method.
Syntax
HRESULT GetTimeFormat( const GUID *pFormat );
Parameters
- pFormat
- Pointer to a variable that receives a time format GUID.
Return Value
Returns the HRESULT value from the connected pin.
Determines whether a specified time format is supported. Implements the IMediaSeeking::IsFormatSupported method.
Syntax
HRESULT IsFormatSupported( const GUID *pFormat );
Parameters
- pFormat
- Pointer to a time format GUID.
Return Value
Returns the HRESULT value from the connected pin.
Determines whether a specified time format is the format currently in use. Implements the IMediaSeeking::IsUsingTimeFormat method.
Syntax
HRESULT IsUsingTimeFormat( const GUID *pFormat );
Parameters
- pFormat
- Pointer to a time format GUID.
Return Value
Returns the HRESULT value from the connected pin.
Sets the current position, relative to the total duration of the stream. Implements the IMediaPosition::put_CurrentPosition method.
Syntax
HRESULT put_CurrentPosition( REFTIME llTime );
Parameters
- llTime
- New position, in seconds.
Return Value
Returns the HRESULT value from the connected pin.
Sets the amount of data that will be queued before the start position. Implements the IMediaPosition::put_PrerollTime method.
Syntax
HRESULT put_PrerollTime( REFTIME llTime );
Parameters
- llTime
- Preroll time, in seconds.
Return Value
Returns the HRESULT value from the connected pin.
Remarks
Although this member function passes the call upstream, the IMediaPosition::put_PrerollTime method is not implemented on any DirectShow source filters.
Sets the playback rate. Implements the IMediaPosition::put_Rate method.
Syntax
HRESULT put_Rate( double dRate );
Parameters
- dRate
- Playback rate. Must not be zero.
Return Value
Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value from the connected pin.
Remarks
Negative rates indicate reverse play. Not all media will support reverse play.
Sets the time at which the playback will stop, relative to the duration of the stream. Implements the IMediaPosition::put_StopTime method.
Syntax
HRESULT put_StopTime( REFTIME llTime );
Parameters
- llTime
- Stop time as a double value, in seconds.
Return Value
Returns the HRESULT value from the connected pin.
Retrieves the preferred time format for the stream. Implements the IMediaSeeking::QueryPreferredFormat method.
Syntax
HRESULT QueryPreferredFormat( GUID *pFormat );
Parameters
- pFormat
- Pointer to a variable that receives a time format GUID.
Return Value
Returns the HRESULT value from the connected pin.
Sets the current position and the stop position. Implements the IMediaSeeking::SetPositions method.
Syntax
HRESULT SetPositions( LONGLONG *pCurrent, DWORD dwCurrentFlags, LONGLONG *pStop, DWORD dwStopFlags );
Parameters
- pCurrent
- Pointer to a variable that specifies the current position, in units of the current time format.
- dwCurrentFlags
- Bitwise combination of flags. See IMediaSeeking::SetPositions for more information.
- pStop
- Pointer to a variable that specifies the stop time, in units of the current time format.
- dwStopFlags
- Bitwise combination of flags. See IMediaSeeking::SetPositions for more information.
Return Value
Returns the HRESULT value from the connected pin.
Sets the playback rate. Implements the IMediaSeeking::SetRate method.
Syntax
HRESULT SetRate( double dRate );
Parameters
- dRate
- Playback rate. Must not be zero.
Return Value
Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value from the connected pin.
Sets the time format. Implements the IMediaSeeking::SetTimeFormat method.
Syntax
HRESULT SetTimeFormat( const GUID *pFormat );
Parameters
- pFormat
- Pointer to a time format GUID.
Return Value
Returns the HRESULT value from the connected pin.
Creates a CPosPassThru or CRendererPosPassThru object.
Syntax
STDAPI CreatePosPassThru( LPUNKNOWN pAgg, BOOL bRenderer, IPin *pPin, IUnknown **ppPassThru );
Parameters
- pAgg
- Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
- bRenderer
- Boolean value that specifies whether the filter is a renderer. Use the value TRUE if the filter is a renderer, or FALSE otherwise.
- pPin
- Pointer to the IPin interface on the filter's input pin.
- ppPassThru
- Address of a variable that receives a pointer to the object's IUnknown interface.
Return Value
Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.
Remarks
If the value of bSupportRendering is TRUE, this method creates an instance of the CRendererPosPassThru class. Otherwise, it creates an instance of the CPosPassThru class. For more information, see CSeekingPassThru.