GstSegment

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

## Synopsis

    #include <gst/gst.h>

    struct              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);
    GstSegment *        gst_segment_copy                    (GstSegment *segment);
    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_newsegment_full     (GstSegment *segment,
                                                             gboolean update,
                                                             gdouble rate,
                                                             gdouble applied_rate,
                                                             GstFormat format,
                                                             gint64 start,
                                                             gint64 stop,
                                                             gint64 time);
    void                gst_segment_set_seek                (GstSegment *segment,
                                                             gdouble rate,
                                                             GstFormat format,
                                                             GstSeekFlags flags,
                                                             GstSeekType start_type,
                                                             gint64 start,
                                                             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);
    gint64              gst_segment_to_position             (GstSegment *segment,
                                                             GstFormat format,
                                                             gint64 running_time);
    gboolean            gst_segment_set_running_time        (GstSegment *segment,
                                                             GstFormat format,
                                                             gint64 running_time);

## 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 and applied_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. 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 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_stop field will contain the new playback position. If the cur_type was different from GST_SEEK_TYPE_NONE, playback continues from the last_stop position, possibly with updated flags or rate.

For elements that want to use 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 as well as any rate or applied_rate conversions.

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 2007-05-17 (0.10.13)

## Details

### struct GstSegment

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

      gint64         last_stop;
      gint64         duration;

      /* API added 0.10.6 */
      gdouble        applied_rate;
    };

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 `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
gdouble `applied_rate`; | the already applied rate to the 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`. `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.

`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. [out][allow-none]
`clip_stop` : | the clipped stop position in the segment. [out][allow-none]
Returns : | TRUE if the given `start` and `stop` times fall partially or completely 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()`.

Free-function: gst_segment_free

Returns : | a new GstSegment, free with `gst_segment_free()`. [transfer full]

### gst_segment_copy ()

    GstSegment *        gst_segment_copy                    (GstSegment *segment);

Create a copy of given `segment`.

Free-function: gst_segment_free

`segment` : | a GstSegment. [transfer none]
Returns : | a new GstSegment, free with `gst_segment_free()`. [transfer full]

Since 0.10.20

### gst_segment_free ()

    void                gst_segment_free                    (GstSegment *segment);

Free the allocated segment `segment`.

`segment` : | a GstSegment. [in][transfer full]

### 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 requests relative to the duration.

`segment` : | a GstSegment structure.
`format` : | the format of the segment.
`duration` : | the duration of the segment info or -1 if unknown.

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

This field should be set to allow seeking requests relative to the current playing 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 and with a default applied_rate of 1.0.

`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

Since 0.10.6

### gst_segment_set_newsegment_full ()

    void                gst_segment_set_newsegment_full     (GstSegment *segment,
                                                             gboolean update,
                                                             gdouble rate,
                                                             gdouble applied_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.
`applied_rate` : | the applied 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 start_type,
                                                             gint64 start,
                                                             GstSeekType stop_type,
                                                             gint64 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 last_stop 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` last_stop 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` last_stop 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 last_stop field. This field can be FALSE if, for example, only the `rate` has been changed but not the playback position.

`segment` : | a GstSegment structure.
`rate` : | the rate of the segment.
`format` : | the format of the segment.
`flags` : | the seek flags for the segment
`start_type` : | the seek method
`start` : | the seek start value
`stop_type` : | the seek method
`stop` : | the seek stop value
`update` : | boolean holding whether last_stop was updated.

### 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 and previously accumulated segments. 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.

`segment` : | a GstSegment structure.
`format` : | the format of the segment.
`position` : | the position in the segment
Returns : | the position as the total running time or -1 when an invalid position was given.

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

`segment` : | a GstSegment structure.
`format` : | the format of the segment.
`position` : | the position in the segment
Returns : | the position in stream_time or -1 when an invalid position was given.

### gst_segment_to_position ()

    gint64              gst_segment_to_position             (GstSegment *segment,
                                                             GstFormat format,
                                                             gint64 running_time);

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

`segment` : | a GstSegment structure.
`format` : | the format of the segment.
`running_time` : | the running_time in the segment
Returns : | the position in the segment for `running_time`. This function returns -1 when `running_time` is -1 or when it is not inside `segment`.

Since 0.10.24

### gst_segment_set_running_time ()

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

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

`segment` : | a GstSegment structure.
`format` : | the format of the segment.
`running_time` : | the running_time in the segment
Returns : | `TRUE` if the segment could be updated successfully. If `FALSE` is returned, `running_time` is -1 or not in `segment`.

Since 0.10.24

## See Also

GstEvent