Microsoft DirectX 8.0 |
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:
Methods in Vtable Order
IUnknown methods Description QueryInterface Returns pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IReferenceClock methods Description 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.
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_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 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);
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_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.
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_POINTER NULL pointer argument. S_FALSE Returned time is the same as the previous value. S_OK Success.
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_FALSE Not found. S_OK Success.