GstSegment

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

Types and Values

Object Hierarchy


Includes

#include <gst/gst.h>

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.

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 gst_segment_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 GstSegment to track the playback region, 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 the base 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 2012-03-29 (0.11.3)

Functions

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.

Parameters

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

Parameters

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 (const GstSegment *segment);

Create a copy of given segment .

Free-function: gst_segment_free

Parameters

segment

a GstSegment.

[transfer none]

Returns

a new GstSegment, free with gst_segment_free().

[transfer full]


gst_segment_free ()

void
gst_segment_free (GstSegment *segment);

Free the allocated segment segment .

Parameters

segment

a GstSegment.

[in][transfer full]

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.

Parameters

segment

a GstSegment structure.

 

rate

the rate of the segment.

 

format

the format of the segment.

 

flags

the segment 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 position was updated.

 

Returns

TRUE if the seek could be performed.


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.

Parameters

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

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.

Parameters

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

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 .

Parameters

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 .


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 .

Parameters

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 .


gst_segment_copy_into ()

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

Copy the contents of src into dest .

Parameters

src

a GstSegment.

[transfer none]

dest

a GstSegment.

[transfer none]

Types and Values

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.

Members

GstSegmentFlags flags;

flags for this segment

 

gdouble rate;

the rate of the segment

 

gdouble applied_rate;

the already applied rate to the segment

 

GstFormat format;

the format of the segment values

 

guint64 base;

the base of the segment

 

guint64 offset;

the offset to apply to start or stop

 

guint64 start;

the start of the segment

 

guint64 stop;

the stop of the segment

 

guint64 time;

the stream time of the segment

 

guint64 position;

the position in the segment

 

guint64 duration;

the duration of the segment

 

enum GstSegmentFlags

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

Members

GST_SEGMENT_FLAG_NONE

no flags

 

GST_SEGMENT_FLAG_RESET

reset the pipeline running_time to the segment running_time

 

GST_SEGMENT_FLAG_SKIP

perform skip playback

 

GST_SEGMENT_FLAG_SEGMENT

send SEGMENT_DONE instead of EOS

 

See Also

GstEvent