DirectShow Animated Header -- CSourcePosition Class DirectShow Animated Header -- CSourcePosition Class* Microsoft DirectShow SDK
*Index  *Topic Contents
*Previous Topic: CSource Class
*Next Topic: CSourceSeeking Class

CSourcePosition Class


CSourcePosition class hierarchy

CSourcePosition is an abstract class that assists source filters with the implementation of IMediaPosition methods.

Derive from this class and set the duration and default stop positions. This class supports IMediaPosition, and calls the pure virtual member functions CSourcePosition::ChangeStart, CSourcePosition::ChangeStop, and CSourcePosition::ChangeRate when CSourcePosition::put_CurrentPosition, CSourcePosition::put_StopTime, or CSourcePosition::put_Rate is called, to allow a source filter to handle these commands and start sending new data.

Override the CSourcePosition::ChangeStart, CSourcePosition::ChangeStop, and CSourcePosition::ChangeRate member functions to do something when the properties change.

Protected Data Members
Name Description
m_Duration Duration of the stream.
m_pLock Pointer to a CCritSec object for locking.
m_Rate Sample rate.
m_Start Start time.
m_Stop Stop time.

Member Functions
Name Description
CSourcePosition Constructs a CSourcePosition object.

Overridable Member Functions
Name Description
ChangeRate Override this pure virtual to handle notification that the rate property has changed.
ChangeStart Override this pure virtual to handle notification that the start position property has changed.
ChangeStop Override this pure virtual to handle notification that the stop position property has changed.

Implemented IMediaPosition Methods
Name Description
get_CurrentPosition Not currently implemented.
get_Duration Retrieves the total duration of the media.
get_PrerollTime Not currently implemented.
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 Not currently implemented.
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.


CSourcePosition::ChangeRate

CSourcePosition Class

Override this member function to handle notification of a change of sample rate.

virtual HRESULT ChangeRate( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value Meaning
E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function is called when a change to the rate has been made by a call to IMediaPosition::put_Rate. Override this and change the rate of data sent; typically, this will be by a call to CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then sending samples marked with new time stamps.


CSourcePosition::ChangeStart

CSourcePosition Class

Override this member function to handle notification of a change of start time.

virtual HRESULT ChangeStart( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value Meaning
E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function is called when a new start position has been requested by a call to IMediaPosition::put_CurrentPosition. Override this and change the data sent; typically, this will be by a call to CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then sending samples marked with new time stamps.


CSourcePosition::ChangeStop

CSourcePosition Class

Override this member function to handle notification of a change in stop time.

virtual HRESULT ChangeStop( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value Meaning
E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function is called when a change to the stop position has been made by a call to IMediaPosition::put_StopTime. Override this and ensure that the correct stop time is being observed; typically, this will be a call to CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then resending data.


CSourcePosition::CSourcePosition

CSourcePosition Class

Constructs a CSourcePosition object.

CSourcePosition(
  const TCHAR * pName,
  LPUNKNOWN pUnk,
  HRESULT * phr,
  CCritSec * pLock
  );

Parameters
pName
Name of the object used in the CSourcePosition constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
phr
Pointer to an HRESULT value for resulting information.
pLock
Pointer to a CCritSec object used for locking.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.


CSourcePosition::get_CurrentPosition

CSourcePosition Class

Currently not implemented.

HRESULT get_CurrentPosition(
  REFTIME* pllTime
  );

Parameters
pllTime
Returned start time as a double value in seconds.
Return Values

Returns E_NOTIMPL.

Remarks

Override this method if you can return the data you are actually working on. The start position is applied before the rate and therefore is the position at typical playback speed.


CSourcePosition::get_Duration

CSourcePosition Class

Retrieves the total duration of the media stream.

HRESULT get_Duration(
  REFTIME* plength
  );

Parameters
plength
Returned length of the media stream.
Return Values

Returns E_POINTER if pLength is invalid. Otherwise, returns S_OK.

Remarks

The duration assumes normal playback speed; it is therefore unaffected by the rate.


CSourcePosition::get_PrerollTime

CSourcePosition Class

Validates the pointer, but the preroll retrieval is not currently implemented.

HRESULT get_PrerollTime(
  REFTIME* pllTime
  );

Parameters
pllTime
Returned preroll time as a double value in seconds.
Return Values

Returns E_POINTER if pllTime is invalid. Otherwise, returns E_NOTIMPL.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.


CSourcePosition::get_Rate

CSourcePosition Class

Retrieves the rate of playback relative to normal playback speed.

HRESULT get_Rate(
  double * pdRate
  );

Parameters
pdRate
Returned rate.
Return Values

Returns E_POINTER if pdRate is invalid. Otherwise, returns S_OK.

Remarks

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.


CSourcePosition::get_StopTime

CSourcePosition Class

Retrieves the time at which the media stream stops.

HRESULT get_StopTime(
  REFTIME* pllTime
  );

Parameters
pllTime
Returned stop time as a double value in seconds.
Return Values

Returns E_POINTER if pllTime is invalid. Otherwise, returns S_OK.

Remarks

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.


CSourcePosition::put_CurrentPosition

CSourcePosition Class

Sets the time within the media stream that playback should begin.

HRESULT put_CurrentPosition(
  REFTIME llTime
  );

Parameters
llTime
Start time expressed as a double value in seconds.
Return Values

Returns an HRESULT value from the call to CSourcePosition::ChangeStart.

Remarks

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.

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.


CSourcePosition::put_PrerollTime

CSourcePosition Class

Not currently implemented.

HRESULT put_PrerollTime(
  REFTIME llTime
  );

Parameters
llTime
Preroll time to be set.
Return Values

Returns E_NOTIMPL.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.


CSourcePosition::put_Rate

CSourcePosition Class

Sets the rate of playback relative to normal speed.

HRESULT put_Rate(
  double dRate
  );

Parameters
dRate
Rate to set.
Return Values

Returns an HRESULT value from the call to CSourcePosition::ChangeRate.

Remarks

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.


CSourcePosition::put_StopTime

CSourcePosition Class

Sets the time at which the media stream will stop.

HRESULT put_StopTime(
  REFTIME llTime
  );

Parameters
llTime
Stop time as a double value in seconds.
Return Values

Returns an HRESULT value from the call to CSourcePosition::ChangeStop.

Remarks

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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

*Top of Page