Microsoft DirectX 8.0

IReferenceClock Interface

Provides the reference time for the filter graph.

Filters that can act as a reference clock can expose this interface. It is also exposed by the system reference clock. The filter graph manager uses this interface to synchronize the filter graph. Applications can use this interface to retrieve the current reference time, or to request notification of an elapsed time.

For more information, see Time and Clocks in DirectShow.

Filter developers: Implement this interface if you are writing a filter that generates reliable clock times. For example, the Audio Renderer filter implements this interface, because audio sound boards usually contain a reference clock. Use the CBaseReferenceClock class to implement this interface.

To increase the chances that a non-rendering filter will be selected by the Filter Graph Manager as the reference close, follow these steps:

  1. Implement IReferenceClock in the filter.
  2. Implement IAMFilterMiscFlags in the filter.
  3. Return AM_FILTER_MISC_FLAGS_IS_SOURCE from IAMFilterMiscFlags::GetMiscFlags.
  4. Implement IAMPushSource on all output pins.
  5. Return (* pFlags) = 0 from IAMPushSource::GetPushSourceFlags.
  6. You may return E_NOTIMPL from all other IAMPushSource methods.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IReferenceClock methodsDescription
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.

IReferenceClock::AdvisePeriodic

IReferenceClock Interface

Creates a periodic advise request.

Syntax

HRESULT AdvisePeriodic(
    REFERENCE_TIME rtStartTime,
    REFERENCE_TIME rtPeriodTime,
    HSEMAPHORE hSemaphore,
    DWORD *pdwAdviseCookie
);

Parameters

rtStartTime
[in] Time of the first notification, in 100-nanosecond units. Must be greater than zero and less than MAX_TIME.
rtPeriodTime
[in] Time between notifications, in 100-nanosecond units. Must be greater than zero.
hSemaphore
[in] Handle to a semaphore, created by the caller.
pdwAdviseCookie
[out] Pointer to a variable that receives an identifier for the advise request.

Return Value

Returns an HRESULT value. Possible values include the following.

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 Unadvise and pass the pdwAdviseToken value returned from this call.

The following code example creates an advise request that signals five seconds from the time it is created, and again every second thereafter.

IReferenceClock *pRefClock = NULL;
// Get an IReferenceClock pointer (not shown).

DWORD          dwAdviseToken;
HANDLE         hSemaphore = CreateSemaphore(NULL, 0, 0x7FFFFFFF, NULL);
REFERENCE_TIME rtPeriodTime = 10000000; // A one-second interval
REFERENCE_TIME rtNow;

pRefClock->GetTime(&rtNow);
pRefClock->AdvisePeriodic(rtNow + (5 * rtPeriodTime),
                          rtPeriodTime, 
                          hSemaphore, 
                          &dwAdviseToken);
...

pRefClock->Unadvise(dwAdviseToken);

IReferenceClock::AdviseTime

IReferenceClock Interface

Creates a one-shot advise request.

Syntax

HRESULT AdviseTime(
    REFERENCE_TIME rtBaseTime,
    REFERENCE_TIME rtStreamTime,
    HEVENT hEvent,
    DWORD *pdwAdviseCookie
);

Parameters

rtBaseTime
[in] Base reference time, in 100-nanosecond units. See Remarks.
rtStreamTime
[in] Stream offset time, in 100-nanosecond units. See Remarks.
hEvent
[in] Handle to an event, created by the caller.
pdwAdviseCookie
[out] Pointer to a variable that receives an identifier for the advise request.

Return Value

Returns an HRESULT value. Possible values include the following.

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.

IReferenceClock::GetTime

IReferenceClock Interface

Retrieves the current reference time.

Syntax

HRESULT GetTime(
    REFERENCE_TIME *pTime
);

Parameters

pTime
[out] Pointer to a variable that receives the current time, in 100-nanosecond units.

Return Value

Returns an HRESULT value. Possible values include the following.

E_POINTERNULL pointer argument.
S_FALSE Returned time is the same as the previous value.
S_OKSuccess.

IReferenceClock::Unadvise

IReferenceClock Interface

Removes a pending advise request.

Syntax

HRESULT Unadvise(
    DWORD dwAdviseCookie
);

Parameters

dwAdviseCookie
[in] Identifier of the request to remove. Use the value returned by AdviseTime or AdvisePeriodic in the pdwAdviseToken parameter.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSENot found.
S_OKSuccess.