[Bug 690564] Design documentation is out of date WRT GstSegment

[GStreamer (bugzilla.gnome.org)]

https://bugzilla.gnome.org/show_bug.cgi?id=690564
  GStreamer | documentation | 1.0.0

--- Comment #1 from Will Manley <gnome at williammanley.net> 2012-12-20 16:57:03 UTC ---
Posting notes inline for easier access:

Field overview
==============

s.base is total elapsed clock time spent in previous segments (base == 0 means
it is the first segment).  e.g. the running time at which the segment started. 
running time (and thus s.base) is reset every time there is a flushing seek.

s.start is the stream time of the start of the segment (e.g. the lower bound of
the stream that should actually be displayed as part of this segment in stream
time)

s.stop is the stream time of the end of the segment (e.g. the upper bound of
the stream that should actually be displayed as part of this segment in stream
time)

s.offset is non-zero when a seek that didn't involve updating the play position
has occurred (e.g. a play speed adjustment).  In which case it's the amount of
the segment (in stream time) that has already been played at the time the
segment was updated.



If we are doing a seek which involves adjusting the play position (e.g. not
just adjusting the playback rate) s.position is set to the start of the segment
in stream time (or end in the case of reverse playback), so s.position is the
stream time that the position query would return at the beginning of the
segment (segment time == 0).

!!! Is position the stream time at which we want one of these transformations
to occur???  In which case it would only be interesting when we are making one
of these GstSegment transformations rather than in any other situation.  This
would also make sense for duration. !!!

???s.duration is the duration of the stream (e.g. is what would be returned by
gst_element_query_duration???

???s.time is the stream time at which position and duration were sampled???

s.time - After a seek s.time = s.start - seems to have something to do with
applied_rates as against rate.

Relationships between segment fields and different clocks
=========================================================
If the above is true then the transformations between the different clocks are:

running time -> stream time

    f(s, x) = (x - s.base) * rate + s.start

stream time -> running time

    f(s, x) = (x - s.start) / rate + s.base

stream time -> clock time ?

    f(s, x) = (x - s.start) / rate + s.base + element.base_time

These transformations do not include s.time or s.offset so must be incomplete
in some way.

Methods
=======

gst_segment_to_running_time
---------------------------

input: Stream Time
output: Running time

Forward play (rate > 0):

    f(s, x) = (p - s.start - s.offset)/s.rate + base

Backward play (rate <= 0):

    f(s, x) = (p - s.stop  + s.offset)/s.rate + base

gst_segment_to_position
-----------------------

Nominally the inverse of gst_segment_to_running_time but doesn't involve
s.offset for some reason?

input: Running time
output: Stream time

Forward (s.rate > 0)

    f(s, x) = start + (x - s.base) * s.rate

Backward (s.rate <= 0)

    f(s, x) = stop  + (x - s.base) * s.rate

gst_segment_to_stream_time
--------------------------

Seems to have something to do with timestamp transformations when a rate
transformation has already been applied to embedded video data PTS? or buffer
timestamps?

input: Not sure (same time as in buffer timestamps)
output: stream time

Forward (s.applied_rate > 0)

    f(s, x) = s.time + (x-s.start) * s.applied_rate

Backward (s.applied_rate <= 0)

    f(s, x) = s.time - (x-s.start) * s.applied_rate

-- 
Configure bugmail: https://bugzilla.gnome.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.