struct GstSegment

struct GstSegment {
  GstSegmentFlags flags;

  gdouble         rate;
  gdouble         applied_rate;

  GstFormat       format;
  guint64         base;
  guint64         offset;
  guint64         start;
  guint64         stop;
  guint64         time;

  guint64         position;
  guint64         duration;
};

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

enum GstSegmentFlags

typedef enum {
 /*< flags >*/
  GST_SEGMENT_FLAG_NONE            = GST_SEEK_FLAG_NONE,
  GST_SEGMENT_FLAG_RESET           = GST_SEEK_FLAG_FLUSH,
  GST_SEGMENT_FLAG_SKIP            = GST_SEEK_FLAG_SKIP,
  GST_SEGMENT_FLAG_SEGMENT         = GST_SEEK_FLAG_SEGMENT
} GstSegmentFlags;

Flags for the GstSegment structure. Currently mapped to the corresponding values of the seek flags.

gst_segment_clip ()

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

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

If the function returns FALSE, start and stop are known to fall outside of segment and clip_start and clip_stop are not updated.

When the function returns TRUE, clip_start and clip_stop will be updated. If clip_start or clip_stop are different from start or stop respectively, the region fell partially in the segment.

Note that when stop is -1, clip_stop will be set to the end of the segment. Depending on the use case, this may or may not be what you want.

gst_segment_init ()

void                gst_segment_init                    (GstSegment *segment,
                                                         GstFormat format);

The start/position fields 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.

gst_segment_new ()

GstSegment *        gst_segment_new                     (void);

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

Free-function: gst_segment_free

gst_segment_copy ()

GstSegment *        gst_segment_copy                    (const GstSegment *segment);

Create a copy of given segment.

Free-function: gst_segment_free

gst_segment_free ()

void                gst_segment_free                    (GstSegment *segment);

Free the allocated segment segment.

gst_segment_do_seek ()

gboolean            gst_segment_do_seek                 (GstSegment *segment,
                                                         gdouble rate,
                                                         GstFormat format,
                                                         GstSeekFlags flags,
                                                         GstSeekType start_type,
                                                         guint64 start,
                                                         GstSeekType stop_type,
                                                         guint64 stop,
                                                         gboolean *update);

Update the segment structure with the field values of a seek event (see gst_event_new_seek()).

After calling this method, the segment field position and time will contain the requested new position in the segment. The new requested position in the segment depends on rate and start_type and stop_type.

For positive rate, the new position in the segment is the new segment start field when it was updated with a start_type different from GST_SEEK_TYPE_NONE. If no update was performed on segment start position (GST_SEEK_TYPE_NONE), start is ignored and segment position is unmodified.

For negative rate, the new position in the segment is the new segment stop field when it was updated with a stop_type different from GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the duration of the segment will be used to update the stop position. If no update was performed on segment stop position (GST_SEEK_TYPE_NONE), stop is ignored and segment position is unmodified.

The applied rate of the segment will be set to 1.0 by default. If the caller can apply a rate change, it should update segment rate and applied_rate after calling this function.

update will be set to TRUE if a seek should be performed to the segment position field. This field can be FALSE if, for example, only the rate has been changed but not the playback position.

gst_segment_to_running_time ()

guint64             gst_segment_to_running_time         (const GstSegment *segment,
                                                         GstFormat format,
                                                         guint64 position);

Translate position to the total running time using the currently configured segment. Position is a value between segment start and stop time.

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. When gst_segment_init() is called, this value will reset to 0.

This function returns -1 if the position is outside of segment start and stop.

gst_segment_to_stream_time ()

guint64             gst_segment_to_stream_time          (const GstSegment *segment,
                                                         GstFormat format,
                                                         guint64 position);

Translate position to stream time using the currently configured segment. The position value must be between segment start and stop value.

This function is typically used by elements that need to operate on the stream time of the buffers it receives, such as effect plugins. In those use cases, position is typically the buffer timestamp or clock time that one wants to convert to the stream time. The stream time is always between 0 and the total duration of the media stream.

gst_segment_to_position ()

guint64             gst_segment_to_position             (const GstSegment *segment,
                                                         GstFormat format,
                                                         guint64 running_time);

Convert running_time into a position in the segment so that gst_segment_to_running_time() with that position returns running_time.

gst_segment_set_running_time ()

gboolean            gst_segment_set_running_time        (GstSegment *segment,
                                                         GstFormat format,
                                                         guint64 running_time);

Adjust the start/stop and base values of segment such that the next valid buffer will be one with running_time.

gst_segment_copy_into ()

void                gst_segment_copy_into               (const GstSegment *src,
                                                         GstSegment *dest);

Copy the contents of src into dest.