docs/random/company/clocks

TIME
In this document, the word "time" is not meant to represent a representation of
time that is close to reality. Though that is the idea in most cases, it is not
the focus. Time in this document is meant to represent time inside a stream that
is played back by GStreamer. There might be reasons to represent time in non-
realtime, for example when the processor is too slow to allow for video playback
in realtime, the clock might not update fast enough. Or one might want to use
a clock that purposefully increases/reduces the speed of time.
Time in this document is not meant to be linear either. Whereas elements can set
time freely by seeking, clocks should do their best to supply linear time. It is
not a requirement however, there might for example be slight inconsistencies 
when audio clocks have buffer over/underruns.

TIME IN A CLOCK
The job of a clock is to report the time as exactly as possible that has elapsed
in the stream since the stream was started.
A Clock does never seek, so if someone seeks the stream back to the beginning, 
the clock will still represent the time since a start.
The state of the clock is managed by all elements using its time as a state of a
bin is changed according to its children. A clock will try to synchronize its 
state with its provider. (FIXME: or with all its children like a bin? FIXME: 
What to do in the case of a providerless clock like _a_ systemclock (we might 
use multiple systemclocks)? Attach to one element that uses it and reattach if 
element is removed? FIXME: What do we do when a provider is removed from a 
scheduler? Sounds like a good time to get a new clock to take over. FIXME: 
Write a test that does exactly this in Gst-Player when changing the GConf Key.)
- NULL / READY
  Nobody cares about time reported by the clock.
- PLAYING
  Clock is supposed to present the time elapsed since it was started.
- PAUSED
  The clock has to remember the time it was stopped and resume with that time
  when it restarts playing.

TIME IN AN ELEMENT
An element only can request time information if it uses a clock. The element can
query functions that give information about the elements time. Time information
for the element is always in relation to the timestamps the element expects on 
its buffers.
Example: XVideosink will output a new frame, when xvideosinks time matches the 
         timestamps of the buffer.
The elements time is in no relation to the time of its clock because of seeks.
If an element seeks, it adjusts its time by the difference the seek has
introduced.
Example: Playback of a song with duration 1000 that is looping. Clock and 
         element start at time offset 0, when the element is first set to 
         PLAYING. After the first loop, the elements time is (by request of that
         element) reset to 0. The clock's time stays at 1000.
Note: If an element goes into the PAUSED state the elements time will continue
      running. (FIXME: possibility to change that needed? Why would you want to
      pause an element that should be synced while the others continue running?
      FIXME: What happens if a clock provider and therefore the clock are 
      already at EOS while other elements are still playing? I'd vote for make
      all other elements go as fast as possible. FIXME: Ask some video people if
      that sounds reasonable or if we gotta force the clock to go on, which
      would make it difficult to detect the difference between EOS and pause.
      
PROVIDERS
Providers are elements that can provide timing information and therefore provide
a clock to other elements. These elements have to update the clock, when it is
used. When a clock is used (state != NULL - FIXME: or other states?), the 
provider is guaranteed to use this clock. (FIXME: necessary?). The element is
however required to synchronize to the clock it was assigned to, wether it is
its own clock or not.

SYNC POINTS
FIXME: Is it necessary to have sync points? This would allow to supply a fixed
time between sync point "SOURCE" and "SINK" so one could buffer the time
inbetween. Or is there another solution for this problem? It's possibly easier
to use an element that does TIMESTAMP = TIMESTAMP - x inside the pipeline and 
drops every buffer before.

FUNCTIONS
FIXME: Use GstTime(Diff) instead of GstClockTime(Diff) ?

GstClockTime	gst_clock_get_time	(GstClock *clock);
GstElementState	gst_clock_get_state 	(GstClock *clock); /* setting works internally */
GstClockReturn	gst_clock_wait		(GstClock *clock, GstClockTime until, GstClockTimeDiff *jitter);

GST_FLAG	GST_ELEMENT_NEEDS_CLOCK; /* wether we want a clock or not */
GstClockTime	gst_element_get_time	(GstElement *element);
void		gst_element_(clock_)seek (GstElement *element, GstClockTimeDiff diff);
GstClock *	gst_element_get_clock	(GstElement *element);
GstClockReturn	gst_element_(clock_)wait (GstElement *element, GstClockTime until, GstClockTimeDiff *jitter);

possible extensions:
GstClockTime	gst_clock_get_resolution (GstClock *clock); /* sounds interesting */
void		gst_clock_wait_async	(GstClock *clock, GFunc callback, gpointer data); /* useless IMO */
void		gst_clock_unlock	(GstClock *clock); /* dunno what for */
void		gst_clock_set_state	(GstClock *clock, GstElementState state); /* might be needed, but screw up alot */

Hm, this looks to easy when you only need an API of 8 functions. But it's quite
a bit of internal hacking because of the state changes.