| 1 |
TIME |
| 2 |
In this document, the word "time" is not meant to represent a representation of |
| 3 |
time that is close to reality. Though that is the idea in most cases, it is not |
| 4 |
the focus. Time in this document is meant to represent time inside a stream that |
| 5 |
is played back by GStreamer. There might be reasons to represent time in non- |
| 6 |
realtime, for example when the processor is too slow to allow for video playback |
| 7 |
in realtime, the clock might not update fast enough. Or one might want to use |
| 8 |
a clock that purposefully increases/reduces the speed of time. |
| 9 |
Time in this document is not meant to be linear either. Whereas elements can set |
| 10 |
time freely by seeking, clocks should do their best to supply linear time. It is |
| 11 |
not a requirement however, there might for example be slight inconsistencies |
| 12 |
when audio clocks have buffer over/underruns. |
| 13 |
|
| 14 |
TIME IN A CLOCK |
| 15 |
The job of a clock is to report the time as exactly as possible that has elapsed |
| 16 |
in the stream since the stream was started. |
| 17 |
A Clock does never seek, so if someone seeks the stream back to the beginning, |
| 18 |
the clock will still represent the time since a start. |
| 19 |
The state of the clock is managed by all elements using its time as a state of a |
| 20 |
bin is changed according to its children. A clock will try to synchronize its |
| 21 |
state with its provider. (FIXME: or with all its children like a bin? FIXME: |
| 22 |
What to do in the case of a providerless clock like _a_ systemclock (we might |
| 23 |
use multiple systemclocks)? Attach to one element that uses it and reattach if |
| 24 |
element is removed? FIXME: What do we do when a provider is removed from a |
| 25 |
scheduler? Sounds like a good time to get a new clock to take over. FIXME: |
| 26 |
Write a test that does exactly this in Gst-Player when changing the GConf Key.) |
| 27 |
- NULL / READY |
| 28 |
Nobody cares about time reported by the clock. |
| 29 |
- PLAYING |
| 30 |
Clock is supposed to present the time elapsed since it was started. |
| 31 |
- PAUSED |
| 32 |
The clock has to remember the time it was stopped and resume with that time |
| 33 |
when it restarts playing. |
| 34 |
|
| 35 |
TIME IN AN ELEMENT |
| 36 |
An element only can request time information if it uses a clock. The element can |
| 37 |
query functions that give information about the elements time. Time information |
| 38 |
for the element is always in relation to the timestamps the element expects on |
| 39 |
its buffers. |
| 40 |
Example: XVideosink will output a new frame, when xvideosinks time matches the |
| 41 |
timestamps of the buffer. |
| 42 |
The elements time is in no relation to the time of its clock because of seeks. |
| 43 |
If an element seeks, it adjusts its time by the difference the seek has |
| 44 |
introduced. |
| 45 |
Example: Playback of a song with duration 1000 that is looping. Clock and |
| 46 |
element start at time offset 0, when the element is first set to |
| 47 |
PLAYING. After the first loop, the elements time is (by request of that |
| 48 |
element) reset to 0. The clock's time stays at 1000. |
| 49 |
Note: If an element goes into the PAUSED state the elements time will continue |
| 50 |
running. (FIXME: possibility to change that needed? Why would you want to |
| 51 |
pause an element that should be synced while the others continue running? |
| 52 |
FIXME: What happens if a clock provider and therefore the clock are |
| 53 |
already at EOS while other elements are still playing? I'd vote for make |
| 54 |
all other elements go as fast as possible. FIXME: Ask some video people if |
| 55 |
that sounds reasonable or if we gotta force the clock to go on, which |
| 56 |
would make it difficult to detect the difference between EOS and pause. |
| 57 |
|
| 58 |
PROVIDERS |
| 59 |
Providers are elements that can provide timing information and therefore provide |
| 60 |
a clock to other elements. These elements have to update the clock, when it is |
| 61 |
used. When a clock is used (state != NULL - FIXME: or other states?), the |
| 62 |
provider is guaranteed to use this clock. (FIXME: necessary?). The element is |
| 63 |
however required to synchronize to the clock it was assigned to, whether it is |
| 64 |
its own clock or not. |
| 65 |
|
| 66 |
SYNC POINTS |
| 67 |
FIXME: Is it necessary to have sync points? This would allow to supply a fixed |
| 68 |
time between sync point "SOURCE" and "SINK" so one could buffer the time |
| 69 |
inbetween. Or is there another solution for this problem? It's possibly easier |
| 70 |
to use an element that does TIMESTAMP = TIMESTAMP - x inside the pipeline and |
| 71 |
drops every buffer before. |
| 72 |
|
| 73 |
FUNCTIONS |
| 74 |
FIXME: Use GstTime(Diff) instead of GstClockTime(Diff) ? |
| 75 |
|
| 76 |
GstClockTime gst_clock_get_time (GstClock *clock); |
| 77 |
GstElementState gst_clock_get_state (GstClock *clock); /* setting works internally */ |
| 78 |
GstClockReturn gst_clock_wait (GstClock *clock, GstClockTime until, GstClockTimeDiff *jitter); |
| 79 |
|
| 80 |
GST_FLAG GST_ELEMENT_NEEDS_CLOCK; /* whether we want a clock or not */ |
| 81 |
GstClockTime gst_element_get_time (GstElement *element); |
| 82 |
void gst_element_(clock_)seek (GstElement *element, GstClockTimeDiff diff); |
| 83 |
GstClock * gst_element_get_clock (GstElement *element); |
| 84 |
GstClockReturn gst_element_(clock_)wait (GstElement *element, GstClockTime until, GstClockTimeDiff *jitter); |
| 85 |
|
| 86 |
possible extensions: |
| 87 |
GstClockTime gst_clock_get_resolution (GstClock *clock); /* sounds interesting */ |
| 88 |
void gst_clock_wait_async (GstClock *clock, GFunc callback, gpointer data); /* useless IMO */ |
| 89 |
void gst_clock_unlock (GstClock *clock); /* dunno what for */ |
| 90 |
void gst_clock_set_state (GstClock *clock, GstElementState state); /* might be needed, but screw up alot */ |
| 91 |
|
| 92 |
Hm, this looks to easy when you only need an API of 8 functions. But it's quite |
| 93 |
a bit of internal hacking because of the state changes. |