[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

Wim Taymans <wim.taymans> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |wim.taymans at gmail.com

--- Comment #3 from Wim Taymans <wim.taymans at gmail.com> 2012-12-21 09:04:05 UTC ---
(In reply to comment #1)
> Posting notes inline for easier access:
> 
> 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.start and s.stop are _not_ stream-time but the first and last valid buffer
timestamp for the segment.

> 
> 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).

There are two use cases for the GstSegment structure. One is to track the
current progress in a media file, like what a demuxer or source might do. And
the other is to send as an event in-band to notify downstream elements of the
running-time of buffers.

Position and duration are only used when tracking the current progress in a
media file.

> 
> !!! 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. !!!

No, it is purely to track current progress for a demuxer.

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

It is used by a demuxer to track current progress and the demuxer would also
use it to answer the duration query.

> 
> ???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.

s.time is the stream-time associated with the timestamp s.start.

> 
> 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.

These transformations are wrong, stream-time != timestamp.

> 
> Methods
> =======
> 
> gst_segment_to_running_time
> ---------------------------
> 
> input: Stream Time

No, these methods take a buffer timestamp as input, not a stream-time

> output: Running time
> 
> Forward play (rate > 0):
> 
>     f(s, x) = (p - s.start - s.offset)/s.rate + base
> 
> Backward play (rate <= 0):

Rate == 0 is not allowed, it must be done by pausing the pipeline.

> 
>     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?

This could be a bug.

> 
> input: Running time
> output: Stream time

No, output is a timestamp in the segment, not a 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?

gives the position in the stream, a value between 0 and the duration of the
stream.

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

Input is a buffer timestamp.

> output: stream time
> 
> Forward (s.applied_rate > 0)
> 
>     f(s, x) = s.time + (x-s.start) * s.applied_rate
> 
> Backward (s.applied_rate <= 0)

applied rate can't be 0

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

I'll try to update and clarify the docs a little.

-- 
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.