Microsoft DirectX 8.0 |
Implements a reference clock.
Declaration: Refclock.h.
This class implements a reference clock that supports the IReferenceClock interface. If a filter can provide a reference clock for the filter graphfor example, by accessing a hardware deviceit can use this class to implement the clock.
The CBaseReferenceClock object maintains two distinct time values:
It is valid for the internal clock to run backward over brief periods. For example, if the clock drifts forward, the filter can adjust it backwards. (See SetTimeDelta.) The GetTime method uses the time values reported by GetPrivateTime. However, the reference time is monotonically increasing; in other words, it never runs backward. Therefore, if the internal clock runs backward, GetTime continues to report the old time until the internal clock catches up.
For example, the two methods might return the following sequences:
GetPrivateTime: 105, 106, 103, 104, 105, 106, 107, 108 GetTime: 105, 106, 106, 106, 106, 106, 107, 108
On the third clock tick, the internal clock jumps backward to 103. The GetTime method continues to report 106 until the internal clock catches up.
By default, GetPrivateTime returns the system time, through a call to the timeGetTime function. A filter that is providing a reference clock from an external device can do one of the following:
This class uses a CAMSchedule object to handle scheduling of advise requests. For details, see the documentation for the CAMSchedule class.
Protected Member Variables | |
---|---|
m_pSchedule | CAMSchedule object that handles scheduling tasks for the clock. |
Protected Methods | |
~CBaseReferenceClock | Destructor method. |
Public Methods | |
CBaseReferenceClock | Constructor method. |
GetPrivateTime | Retrieves the real time from the clock. |
SetTimeDelta | Adjusts the internal clock time. |
GetSchedule | Retrieves a pointer to the clock's scheduling object. |
TriggerThread | Wakes up the worker thread that handles scheduling. |
IReferenceClock Methods | |
GetTime | Retrieves the current reference time. |
AdviseTime | Creates a one-shot advise request. |
AdvisePeriodic | Creates a periodic advise request. |
Unadvise | Removes a pending advise request. |
Helper Functions | |
ConvertToMilliseconds | Converts a reference time to milliseconds. |
CAMSchedule object that handles scheduling tasks for the clock.
Syntax
CAMSchedule * const m_pSchedule;
Creates a periodic advise request. Implements the IReferenceClock::AdvisePeriodic method.
Syntax
HRESULT AdvisePeriodic( REFERENCE_TIME StartTime, REFERENCE_TIME PeriodTime, HSEMAPHORE hSemaphore, DWORD *pdwAdviseToken );
Parameters
- StartTime
- Time of the first notification, in 100-nanosecond units. Must be greater than zero and less than MAX_TIME.
- PeriodTime
- Time between notifications, in 100-nanosecond units. Must be greater than zero.
- hSemaphore
- Handle to a semaphore, created by the caller.
- pdwAdviseToken
- Pointer to a variable that receives an identifier for the advise request.
Return Value
Returns one of the HRESULT values shown in the following table.
S_OK | Success |
E_INVALIDARG | Invalid time values |
E_OUTOFMEMORY | Failure |
E_POINTER | NULL pointer argument |
Remarks
At each notification time, the clock releases the semaphore specified in the hSemaphore parameter. When no further notifications are required, call the Unadvise method and pass the pdwAdviseToken value returned from this call.
Creates a one-shot advise request. Implements the IReferenceClock::AdviseTime method.
Syntax
HRESULT AdviseTime( REFERENCE_TIME baseTime, REFERENCE_TIME streamTime, HEVENT hEvent, DWORD *pdwAdviseToken );
Parameters
- baseTime
- Base reference time, in 100-nanosecond units.
- streamTime
- Stream offset time, in 100-nanosecond units.
- hEvent
- Handle to an event, created by the caller.
- pdwAdviseToken
- Pointer to a variable that receives an identifier for the advise request.
Return Value
Returns one of the HRESULT values shown in the following table.
S_OK Success E_INVALIDARG Invalid time values E_OUTOFMEMORY Failure E_POINTER NULL pointer argument
Remarks
This method creates a one-shot advise request for the reference time baseTime + streamTime. The sum must be greater than zero and less than MAX_TIME, or the method returns E_INVALIDARG. At the requested time, the clock signals the event specified in the hEvent parameter.
To cancel the notification before the time is reached, call the Unadvise method and pass the pdwAdviseToken value returned from this call. After the notification has occurred, the clock automatically clears it, so it is not necessary to call Unadvise. However, it is not an error to do so.
Constructor method.
Syntax
CBaseReferenceClock( TCHAR *pName, LPUNKNOWN pUnk, HRESULT *phr, CAMSchedule *pSched = NULL );
Parameters
- pName
- Pointer to a string containing the name of the object. For more information, see CBaseObject.
- pUnk
- Pointer to the IUnknown interface of the delegating object.
- phr
- 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.
- pSched
- Pointer to a CAMSchedule object. If NULL, this method creates a new CAMSchedule object.
Destructor method.
Syntax
CBaseReferenceClock(void);
Retrieves the real time from the clock.
Syntax
virtual REFERENCE_TIME GetPrivateTime(void);
Return Value
Returns the current clock time, in 100-nanosecond units.
Remarks
This method returns the real time reported by the clock. External callers use the GetTime method, which calls this method. Unlike the GetTime method, the internal clock is allowed to go backward. If that happens, the GetTime method continues to return the last time that it reported, until the GetPrivateTime method catches up.
Retrieves a pointer to the clock's scheduling object.
Syntax
CAMSchedule* GetSchedule(void);
Return Value
Returns the m_pSchedule member variable.
Retrieves the current reference time. Implements the IReferenceClock::GetTime method.
Syntax
HRESULT GetTime( REFERENCE_TIME *pTime );
Parameters
- pTime
- Pointer to a variable that receives the current time, in 100-nanosecond units.
Return Value
Returns one of the HRESULT values shown in the following table.
E_POINTER NULL pointer argument. S_FALSE Returned time is the same as the previous value. S_OK Success.
Remarks
This method calls the GetPrivateTime method to determine the real clock time. If the clock time is strictly greater than the previous value, GetTime uses the clock time and returns S_OK. Otherwise, GetTime uses the previous value and returns S_FALSE. Therefore, the internal clock can run backward for a short period, without causing the reference time to run backward. Instead, the reference time will "stall" at the same value until the internal clock catches up.
Adjusts the internal clock time.
Syntax
HRESULT SetTimeDelta( const REFERENCE_TIME& TimeDelta );
Parameters
- TimeDelta
- Amount to adjust the clock time, in 100-nanosecond units. A positive value moves the clock forward, and a negative value moves the clock backward.
Return Value
Returns S_OK.
Remarks
The derived class can use this method to adjust the internal clock, if it drifts from the device that is providing timing information.
The GetTime method never returns decreasing values. If you adjust the clock backwards, GetTime returns the previous value until the clock reaches that value again.
Wakes up the worker thread that handles scheduling.
Syntax
void TriggerThread(void);
Return Value
No return value.
Remarks
The clock uses a worker thread that calls the CAMSchedule::Advise method at appropriate times. The derived class can call TriggerThread to wake up the thread.
Removes a pending advise request. Implements the IReferenceClock::Unadvise method.
Syntax
HRESULT Unadvise( DWORD dwAdviseToken );
Parameters
- dwAdviseToken
- Identifier of the request to remove. Use the value returned by the AdviseTime or AdvisePeriodic methods in the pdwAdviseToken parameter.
Return Value
Returns one of the HRESULT values shown in the following table.
S_FALSE Not found. S_OK Success.
Converts a reference time to milliseconds.
Syntax
LONGLONG ConvertToMilliseconds( const REFERENCE_TIME& RT );
Parameters
- RT
- Reference time, in 100-nanosecond units.
Return Value
Returns the reference time converted to milliseconds.