Time and Clocks in DirectShow (Windows Embedded CE 6.0)

1/6/2010

This topic gives an overview of time and clocks in the DirectShow architecture. It contains the following sections:

• Reference Clocks
• Clock Times
• Time Stamps and Media Times

Reference Clocks

One function of the filter graph manager is to synchronize the filters in the graph. To accomplish this, the filter graph manager and the filters all rely on a single clock, called the reference clock. Any object that supports the IReferenceClock interface can serve as a reference clock. A filter with access to a hardware timer can provide a clock (an example is the audio renderer), or the filter graph manager can create one that uses the system time.

At run time, the filter graph manager selects a reference clock and calls IMediaFilter::SetSyncSource on all the filters to inform them of the choice. An application can override the filter graph manager's choice by calling SetSyncSource on the filter graph manager. Only do this if you have a particular reason to prefer another clock.

The filter graph manager uses the following heuristic to select the reference clock:

• If any filter in the graph can provide a reference clock, use that filter. Exception: If the graph contains live sources, choose only a source filter clock.
• If no filter provides a suitable clock, use the system time.

Reference clocks measure time in 100-nanosecond intervals. To retrieve a clock's current time, call the IReferenceClock::GetTime method. A clock's baseline — the time from which it starts counting — depends on the clock's implementation, so the particular time value it returns is not inherently meaningful. What matters is that it returns monotonically increasing values at a rate of one per 100 nanoseconds.

Clock Times

DirectShow defines two related clock times: reference time and stream time.

• Reference time is the absolute time returned by the reference clock.
• Stream time is defined relative to when the graph last started running.
  • While the graph is running, stream time equals reference time minus start time.
  • While the graph is paused, stream time remains at the stream time when it was paused.
  • While the graph is stopped, stream time is zero.

When an application calls IMediaControl::Run to run the filter graph, the filter graph manager calls IMediaFilter::Run on each filter. To compensate for the slight amount of time it takes for the filters to start running, the filter graph manager specifies a start time slightly in the future.

Time Stamps and Media Times

A media sample has two time-based properties: a time stamp, and a media time.

Time Stamps

The time stamp defines the sample's start and finish times, measured in stream time. The time stamp is sometimes called the presentation time.

When a renderer filter receives a sample, it schedules rendering based on the time stamp. If the sample arrives late, or has no time stamp, the filter renders the sample immediately. Otherwise, the filter waits until the sample's start time before it renders the sample. (It waits for the start time by calling the IReferenceClock::AdviseTime method.)

Source filters and parser filters are responsible for setting the correct time stamps on the samples they process. The first sample is time stamped with a start time of zero. Subsequent time stamps are determined by the sample length and the playback rate.

To set the time stamp on a sample, call the IMediaSample::SetTime method.

Media Time

Media time specifies the sample's original position within a seekable medium, such as a file on disk. For video, media time represents the frame number. For audio, media time represents the sample number in the packet. For example, if each packet contains one second of 44.1 kilohertz (kHz) audio, the first packet has a media start time of zero and a media stop time of 44100. Renderer filters can determine whether frames or samples have been dropped by checking for gaps in the media times.

Whereas the time stamp depends on factors outside the source, such as seeking and playback rate, the media time is always calculated relative to the original source.

To set the media time on a sample, call the IMediaSample::SetMediaTime method.

See Also

Concepts

DirectShow Architecture for Filter Developers