Microsoft DirectX 8.0

CBaseReferenceClock Class

CBaseReferenceClock class hierarchy

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 graph—for example, by accessing a hardware device—it 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_pScheduleCAMSchedule object that handles scheduling tasks for the clock.
Protected Methods
~CBaseReferenceClockDestructor method.
Public Methods
CBaseReferenceClockConstructor method.
GetPrivateTimeRetrieves the real time from the clock.
SetTimeDeltaAdjusts the internal clock time.
GetScheduleRetrieves a pointer to the clock's scheduling object.
TriggerThreadWakes up the worker thread that handles scheduling.
IReferenceClock Methods
GetTimeRetrieves the current reference time.
AdviseTimeCreates a one-shot advise request.
AdvisePeriodicCreates a periodic advise request.
UnadviseRemoves a pending advise request.
Helper Functions
ConvertToMillisecondsConverts a reference time to milliseconds.

CBaseReferenceClock.m_pSchedule

CBaseReferenceClock Class

CAMSchedule object that handles scheduling tasks for the clock.

Syntax

CAMSchedule * const m_pSchedule;

CBaseReferenceClock::AdvisePeriodic

CBaseReferenceClock Class

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_OKSuccess
E_INVALIDARGInvalid time values
E_OUTOFMEMORYFailure
E_POINTERNULL 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.

CBaseReferenceClock::AdviseTime

CBaseReferenceClock Class

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_OKSuccess
E_INVALIDARGInvalid time values
E_OUTOFMEMORYFailure
E_POINTERNULL 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.

CBaseReferenceClock::CBaseReferenceClock

CBaseReferenceClock Class

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.

CBaseReferenceClock::~CBaseReferenceClock

CBaseReferenceClock Class

Destructor method.

Syntax

CBaseReferenceClock(void);

CBaseReferenceClock::GetPrivateTime

CBaseReferenceClock Class

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.

CBaseReferenceClock::GetSchedule

CBaseReferenceClock Class

Retrieves a pointer to the clock's scheduling object.

Syntax

CAMSchedule* GetSchedule(void);

Return Value

Returns the m_pSchedule member variable.

CBaseReferenceClock::GetTime

CBaseReferenceClock Class

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_POINTERNULL pointer argument.
S_FALSE Returned time is the same as the previous value.
S_OKSuccess.

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.

CBaseReferenceClock::SetTimeDelta

CBaseReferenceClock Class

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.

CBaseReferenceClock::TriggerThread

CBaseReferenceClock Class

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.

CBaseReferenceClock::Unadvise

CBaseReferenceClock Class

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_FALSENot found.
S_OKSuccess.

ConvertToMilliseconds Function

CBaseReferenceClock Class

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.