This helper structure holds the relevant values for tracking the region of interest in a media file, called a segment.
The structure can be used for two purposes:
* performing seeks (handling seek events) * tracking playback regions (handling newsegment events)
The segment is usually configured by the application with a seek event which is propagated upstream and eventually handled by an element
that performs the seek.
The configured segment is then propagated back downstream with a newsegment event. This information is then used to clip media to the
segment boundaries.
A segment structure is initialized with init, which takes a
Format that will be used as the format of the segment values. The segment will be configured
with a start value of 0 and a stop/duration of -1, which is undefined. The default rate and applied_rate is 1.0.
The public duration field contains the duration of the segment. When using the segment for seeking, the start and time members should
normally be left to their default 0 value. The stop position is left to -1 unless explicitly configured to a different value after a seek
event.
The current position in the segment should be set by changing the position member in the structure.
For elements that perform seeks, the current segment should be updated with the do_seek
and the values from the seek event. This method will update all the segment fields. The position field will contain the new playback
position. If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from the position position, possibly with updated
flags or rate.
For elements that want to use Segment to track the playback region, update the segment fields with the
information from the newsegment event. The clip method can be used to check and clip
the media data to the segment boundaries.
For elements that want to synchronize to the pipeline clock, to_running_time
can be used to convert a timestamp to a value that can be used to synchronize to the clock. This function takes into account the base
as well as any rate or applied_rate conversions.
For elements that need to perform operations on media data in stream_time,
to_stream_time can be used to convert a timestamp and the segment info to stream time (which is always between 0 and the duration of
the stream).
- public bool clip (Format format, uint64 start, uint64 stop, out uint64 clip_start, out uint64 clip_stop)
Clip the given start and stop values to the
segment boundaries given in this.
- public Segment copy ()
Create a copy of given this.
- public void copy_into (Segment dest)
Copy the contents of this into
dest.
- public bool do_seek (double rate, Format format, SeekFlags flags, SeekType start_type, uint64 start, SeekType stop_type, uint64 stop, out bool update)
Update the segment structure with the field values of a seek event
(see Event.seek).
- public void free ()
Free the allocated segment this.
- public void init (Format format)
The start/position fields are set to 0 and the stop/duration fields
are set to -1 (unknown).
- public bool is_equal (Segment s1)
Checks for two segments being equal.
- public bool offset_running_time (Format format, int64 offset)
Adjust the values in this so that
offset is applied to all future running-time calculations.
- public uint64 position_from_running_time (Format format, uint64 running_time)
Convert running_time into a position in the segment so
that to_running_time with that position returns running_time
.
- public int position_from_running_time_full (Format format, uint64 running_time, out uint64 position)
Translate running_time to the segment position using the
currently configured segment.
- public uint64 position_from_stream_time (Format format, uint64 stream_time)
Convert stream_time into a position in the segment so
that to_stream_time with that position returns stream_time.
- public int position_from_stream_time_full (Format format, uint64 stream_time, out uint64 position)
Translate stream_time to the segment position using the
currently configured segment.
- public bool set_running_time (Format format, uint64 running_time)
Adjust the start/stop and base values of
this such that the next valid buffer will be one with running_time.
- public uint64 to_position (Format format, uint64 running_time)
Convert running_time into a position in the segment so
that to_running_time with that position returns running_time
.
- public uint64 to_running_time (Format format, uint64 position)
Translate position to the total running time using the
currently configured segment.
- public int to_running_time_full (Format format, uint64 position, out uint64 running_time)
Translate position to the total running time using the
currently configured segment.
- public uint64 to_stream_time (Format format, uint64 position)
Translate position to stream time using the currently
configured segment.
- public int to_stream_time_full (Format format, uint64 position, out uint64 stream_time)
Translate position to the total stream time using the
currently configured segment.