GstSegment

GstSegment — Structure describing the configured region of interest in a media file.

Synopsis


#include <gst/gst.h>


            GstSegment;
gboolean    gst_segment_clip                (GstSegment *segment,
                                             GstFormat format,
                                             gint64 start,
                                             gint64 stop,
                                             gint64 *clip_start,
                                             gint64 *clip_stop);
void        gst_segment_init                (GstSegment *segment,
                                             GstFormat format);
GstSegment* gst_segment_new                 (void);
void        gst_segment_free                (GstSegment *segment);
void        gst_segment_set_duration        (GstSegment *segment,
                                             GstFormat format,
                                             gint64 duration);
void        gst_segment_set_last_stop       (GstSegment *segment,
                                             GstFormat format,
                                             gint64 position);
void        gst_segment_set_newsegment      (GstSegment *segment,
                                             gboolean update,
                                             gdouble rate,
                                             GstFormat format,
                                             gint64 start,
                                             gint64 stop,
                                             gint64 time);
void        gst_segment_set_seek            (GstSegment *segment,
                                             gdouble rate,
                                             GstFormat format,
                                             GstSeekFlags flags,
                                             GstSeekType cur_type,
                                             gint64 cur,
                                             GstSeekType stop_type,
                                             gint64 stop,
                                             gboolean *update);
gint64      gst_segment_to_running_time     (GstSegment *segment,
                                             GstFormat format,
                                             gint64 position);
gint64      gst_segment_to_stream_time      (GstSegment *segment,
                                             GstFormat format,
                                             gint64 position);


Description

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 gst_segment_init(), which takes a GstFormat 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 is 1.0.

If the segment is used for managing seeks, the segment duration should be set with gst_segment_set_duration(). The public duration field contains the duration of the segment.

The current position in the segment should be set with the gst_segment_set_last_stop(). The public last_stop field contains the last set stop position in the segment.

For elements that perform seeks, the current segment should be updated with the gst_segment_set_seek() and the values from the seek event. This method will update all the segment fields. The last_pos field will contain the new playback position. If the cur_type was different from GST_SEEK_TYPE_NONE, playback continues from the last_pos position, possibly with updated flags or rate.

For elements that want to us GstSegment to track the playback region, use gst_segment_set_newsegment() to update the segment fields with the information from the newsegment event. The gst_segment_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, gst_segment_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 all accumulated segments.

For elements that need to perform operations on media data in stream_time, gst_segment_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).

Last reviewed on 2005-12-12 (0.10.0)

Details

GstSegment

typedef struct {
  gdouble        rate;
  gdouble        abs_rate;
  GstFormat      format;
  GstSeekFlags   flags;
  gint64         start;
  gint64         stop;
  gint64         time;
  gint64         accum;

  gint64         last_stop;
  gint64         duration;
} GstSegment;

A helper structure that holds the configured region of interest in a media file.

gdouble rate; the rate of the segment
gdouble abs_rate; absolute value of the rate
GstFormat format; the format of the segment values
GstSeekFlags flags; flags for this segment
gint64 start; the start of the segment
gint64 stop; the stop of the segment
gint64 time; the stream time of the segment
gint64 accum; accumulated segment
gint64 last_stop; last known stop time
gint64 duration; total duration of segment

gst_segment_clip ()

gboolean    gst_segment_clip                (GstSegment *segment,
                                             GstFormat format,
                                             gint64 start,
                                             gint64 stop,
                                             gint64 *clip_start,
                                             gint64 *clip_stop);

Clip the given start and stop values to the segment boundaries given in segment.

segment : a GstSegment structure.
format : the format of the segment.
start : the start position in the segment
stop : the stop position in the segment
clip_start : the clipped start position in the segment
clip_stop : the clipped stop position in the segment
Returns : TRUE if the given start and stop times fall partially in segment, FALSE if the values are completely outside of the segment.

gst_segment_init ()

void        gst_segment_init                (GstSegment *segment,
                                             GstFormat format);

The start/last_stop positions are set to 0 and the stop/duration fields are set to -1 (unknown). The default rate of 1.0 and no flags are set.

Initialize segment to its default values.

segment : a GstSegment structure.
format : the format of the segment.

gst_segment_new ()

GstSegment* gst_segment_new                 (void);

Allocate a new GstSegment structure and initialize it using gst_segment_init().

Returns : a new GstSegment, free with gst_segment_free().

gst_segment_free ()

void        gst_segment_free                (GstSegment *segment);

Free the allocated segment segment.

segment : a GstSegment

gst_segment_set_duration ()

void        gst_segment_set_duration        (GstSegment *segment,
                                             GstFormat format,
                                             gint64 duration);

Set the duration of the segment to duration. This function is mainly used by elements that perform seeking and know the total duration of the segment.

This field should be set to allow seeking request relative to the duration.

segment : a GstSegment structure.
format : the format of the segment.
duration : the duration of the segment info.

gst_segment_set_last_stop ()

void        gst_segment_set_last_stop       (GstSegment *segment,
                                             GstFormat format,
                                             gint64 position);

Set the last observed stop position in the segment to position.

segment : a GstSegment structure.
format : the format of the segment.
position : the position

gst_segment_set_newsegment ()

void        gst_segment_set_newsegment      (GstSegment *segment,
                                             gboolean update,
                                             gdouble rate,
                                             GstFormat format,
                                             gint64 start,
                                             gint64 stop,
                                             gint64 time);

Update the segment structure with the field values of a new segment event.

segment : a GstSegment structure.
update : flag indicating a new segment is started or updated
rate : the rate of the segment.
format : the format of the segment.
start : the new start value
stop : the new stop value
time : the new stream time

gst_segment_set_seek ()

void        gst_segment_set_seek            (GstSegment *segment,
                                             gdouble rate,
                                             GstFormat format,
                                             GstSeekFlags flags,
                                             GstSeekType cur_type,
                                             gint64 cur,
                                             GstSeekType stop_type,
                                             gint64 stop,
                                             gboolean *update);

Update the segment structure with the field values of a seek event.

After calling this method, the segment field last_stop will contain the requested new position in the segment. If the cur_type is different from GST_SEEK_TYPE_NONE, the current position is not updated and streaming should continue from the last position, possibly with updated rate, flags or stop position.

segment : a GstSegment structure.
rate : the rate of the segment.
format : the format of the segment.
flags : the seek flags for the segment
cur_type : the seek method
cur : the seek start value
stop_type : the seek method
stop : the seek stop value
update : boolean holding whether an update the current segment is needed.

gst_segment_to_running_time ()

gint64      gst_segment_to_running_time     (GstSegment *segment,
                                             GstFormat format,
                                             gint64 position);

Translate position to the total running time using the currently configured segment.

This function is typically used by elements that need to synchronize to the global clock in a pipeline. The runnning time is a constantly increasing value starting from 0.

segment : a GstSegment structure.
format : the format of the segment.
position : the position in the segment
Returns : the position as the total running time.

gst_segment_to_stream_time ()

gint64      gst_segment_to_stream_time      (GstSegment *segment,
                                             GstFormat format,
                                             gint64 position);

Translate position to stream time using the currently configured segment.

This function is typically used by elements that need to operate on the stream time of the buffers it receives, such as effect plugins. The stream time is always between 0 and the total duration of the media stream.

segment : a GstSegment structure.
format : the format of the segment.
position : the position in the segment
Returns : the position in stream_time.

See Also

GstEvent