A class that describes the configured region of interest in a media file. More...

#include <gstreamermm/segment.h>

Public Member Functions
	Segment ()

	Segment (GstSegment* gobject, bool make_a_copy=true)

	Segment (const Segment& other)

Segment&	operator= (const Segment& other)

	Segment (Segment&& other) noexcept

Segment&	operator= (Segment&& other) noexcept

	~Segment () noexcept

void	swap (Segment& other) noexcept

GstSegment*	gobj ()
	Provides access to the underlying C instance. More...

const GstSegment*	gobj () const
	Provides access to the underlying C instance. More...

GstSegment*	gobj_copy () const
	Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs. More...

bool	clip (Format format, guint64 start, guint64 stop, guint64& clip_start, guint64& clip_stop) const
	Clip the given start and stop values to the segment boundaries given in segment. More...

void	init (Format format)
	The start/position fields are set to 0 and the stop/duration fields are set to -1 (unknown). More...

void	set_seek (double rate, Format format, SeekFlags flags, SeekType start_type, gint64 start, SeekType stop_type, gint64 stop, bool& update)
	Update the segment structure with the field values of a seek event (see Gst::Event::new_seek()). More...

guint64	to_running_time (Format format, guint64 position) const
	Translate position to the total running time using the currently configured segment. More...

int	to_running_time (Format format, guint64 position, guint64& running_time) const
	Translate position to the total running time using the currently configured segment. More...

guint64	to_stream_time (Format format, guint64 position) const
	Translate position to stream time using the currently configured segment. More...

int	to_stream_time (Format format, guint64 position, guint64& stream_time) const
	Translate position to the total stream time using the currently configured segment. More...

guint64	to_position (Format format, guint64 running_time) const
	Convert running_time into a position in the segment so that to_running_time() with that position returns running_time. More...

bool	set_running_time (Format 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. More...

guint64	position_from_running_time (Gst::Format format, guint64 running_time) const
	Convert running_time into a position in the segment so that to_running_time() with that position returns running_time. More...

int	position_from_running_time (Gst::Format format, guint64 running_time, guint64& position) const
	Translate running_time to the segment position using the currently configured segment. More...

guint64	position_from_stream_time (Gst::Format format, guint64 stream_time) const
	Convert stream_time into a position in the segment so that to_stream_time() with that position returns stream_time. More...

int	position_from_stream_time (Gst::Format format, guint64 stream_time, guint64& position) const
	Translate stream_time to the segment position using the currently configured segment. More...

bool	offset_running_time (Gst::Format format, gint64 offset)
	Adjust the values in segment so that offset is applied to all future running-time calculations. More...

bool	is_equal (const Gst::Segment& s2) const
	Checks for two segments being equal. More...

Static Public Member Functions
static GType	get_type ()
	Get the GType for this class, for use with the underlying GObject type system. More...

Protected Attributes
GstSegment*	gobject_

Related Functions
(Note that these are not member functions.)
void	swap (Segment& lhs, Segment& rhs) noexcept

Gst::Segment	wrap (GstSegment* object, bool take_copy=false)
	A Glib::wrap() method for this object. More...

Detailed Description

A class that describes the configured region of interest in a media file.

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 current position in the segment should be set with the 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 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 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 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, 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 2016-07-12 (1.8.0)

Constructor & Destructor Documentation

◆ Segment() [1/4]

Gst::Segment::Segment ( )

◆ Segment() [2/4]

Gst::Segment::Segment	(	GstSegment *	gobject,
		bool	make_a_copy = `true`
	)

explicit

◆ Segment() [3/4]

Gst::Segment::Segment ( const Segment& other )

◆ Segment() [4/4]

Gst::Segment::Segment ( Segment&& other )

noexcept

◆ ~Segment()

Gst::Segment::~Segment ( )

noexcept

Member Function Documentation

◆ clip()

bool Gst::Segment::clip	(	Format	format,
		guint64	start,
		guint64	stop,
		guint64 &	clip_start,
		guint64 &	clip_stop
	)		const

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

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 or completely in segment, false if the values are completely outside of the segment.

◆ get_type()

static GType Gst::Segment::get_type ( )

static

Get the GType for this class, for use with the underlying GObject type system.

◆ gobj() [1/2]

GstSegment* Gst::Segment::gobj ( )

inline

Provides access to the underlying C instance.

◆ gobj() [2/2]

const GstSegment* Gst::Segment::gobj ( ) const

inline

Provides access to the underlying C instance.

◆ gobj_copy()

GstSegment* Gst::Segment::gobj_copy ( ) const

Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.

◆ init()

void Gst::Segment::init ( Format 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

format The format of the segment.

◆ is_equal()

bool Gst::Segment::is_equal ( const Gst::Segment& s2 ) const

Checks for two segments being equal.

Equality here is defined as perfect equality, including floating point values.

Parameters

s2	A Gst::Segment structure.

Returns: true if the segments are equal, false otherwise.

◆ offset_running_time()

bool Gst::Segment::offset_running_time	(	Gst::Format	format,
		gint64	offset
	)

Adjust the values in segment so that offset is applied to all future running-time calculations.

Parameters

format	The format of the segment.
offset	The offset to apply in the segment.

Returns: true if the segment could be updated successfully. If false is returned, offset is not in segment.

◆ operator=() [1/2]

Segment& Gst::Segment::operator= ( const Segment& other )

◆ operator=() [2/2]

Segment& Gst::Segment::operator= ( Segment&& other )

noexcept

◆ position_from_running_time() [1/2]

guint64 Gst::Segment::position_from_running_time	(	Gst::Format	format,
		guint64	running_time
	)		const

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

Parameters

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.

◆ position_from_running_time() [2/2]

int Gst::Segment::position_from_running_time	(	Gst::Format	format,
		guint64	running_time,
		guint64 &	position
	)		const

Translate running_time to the segment position using the currently configured segment.

Compared to position_from_running_time() this function can return negative segment position.

This function is typically used by elements that need to synchronize buffers against the clock or each other.

running_time can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, running_time resulted in a positive position returned in position.

When this function returns -1, the returned position should be negated to get the real negative segment position.

Parameters

format	The format of the segment.
running_time	The running-time.
position	The resulting position in the segment.

Returns: A 1 or -1 on success, 0 on failure.

◆ position_from_stream_time() [1/2]

guint64 Gst::Segment::position_from_stream_time	(	Gst::Format	format,
		guint64	stream_time
	)		const

Convert stream_time into a position in the segment so that to_stream_time() with that position returns stream_time.

Parameters

format	The format of the segment.
stream_time	The stream_time in the segment.

Returns: The position in the segment for stream_time. This function returns -1 when stream_time is -1 or when it is not inside segment.

◆ position_from_stream_time() [2/2]

int Gst::Segment::position_from_stream_time	(	Gst::Format	format,
		guint64	stream_time,
		guint64 &	position
	)		const

Translate stream_time to the segment position using the currently configured segment.

Compared to position_from_stream_time() this function can return negative segment position.

This function is typically used by elements that need to synchronize buffers against the clock or each other.

stream_time can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, stream_time resulted in a positive position returned in position.

When this function returns -1, the returned position should be negated to get the real negative segment position.

Parameters

format	The format of the segment.
stream_time	The stream-time.
position	The resulting position in the segment.

Returns: A 1 or -1 on success, 0 on failure.

◆ set_running_time()

bool Gst::Segment::set_running_time	(	Format	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

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.

◆ set_seek()

void Gst::Segment::set_seek	(	double	rate,
		Format	format,
		SeekFlags	flags,
		SeekType	start_type,
		gint64	start,
		SeekType	stop_type,
		gint64	stop,
		bool &	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

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.

◆ swap()

void Gst::Segment::swap ( Segment& other )

noexcept

◆ to_position()

guint64 Gst::Segment::to_position	(	Format	format,
		guint64	running_time
	)		const

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

Parameters

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.

Deprecated. Use position_from_running_time() instead.

◆ to_running_time() [1/2]

guint64 Gst::Segment::to_running_time	(	Format	format,
		guint64	position
	)		const

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 running time is a constantly increasing value starting from 0. When init() is called, this value will reset to 0.

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

Parameters

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.

◆ to_running_time() [2/2]

int Gst::Segment::to_running_time	(	Format	format,
		guint64	position,
		guint64 &	running_time
	)		const

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

Compared to to_running_time() this function can return negative running-time.

This function is typically used by elements that need to synchronize buffers against the clock or eachother.

position can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, position resulted in a positive running-time returned in running_time.

When this function returns -1, the returned running_time should be negated to get the real negative running time.

Parameters

format	The format of the segment.
position	The position in the segment.
running_time	Result running-time.

Returns: A 1 or -1 on success, 0 on failure.

◆ to_stream_time() [1/2]

guint64 Gst::Segment::to_stream_time	(	Format	format,
		guint64	position
	)		const

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

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.

◆ to_stream_time() [2/2]

int Gst::Segment::to_stream_time	(	Format	format,
		guint64	position,
		guint64 &	stream_time
	)		const

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

Compared to to_stream_time() this function can return negative stream-time.

This function is typically used by elements that need to synchronize buffers against the clock or eachother.

position can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, position resulted in a positive stream-time returned in stream_time.

When this function returns -1, the returned stream_time should be negated to get the real negative stream time.

Parameters

format	The format of the segment.
position	The position in the segment.
stream_time	Result stream-time.

Returns: A 1 or -1 on success, 0 on failure.

Friends And Related Function Documentation

◆ swap()

void swap	(	Segment&	lhs,
		Segment&	rhs
	)

lhs	The left-hand side
rhs	The right-hand side

◆ wrap()

Gst::Segment wrap	(	GstSegment *	object,
		bool	take_copy = `false`
	)

Parameters

object	The C instance.
take_copy	False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns: A C++ instance that wraps this C instance.

Member Data Documentation

◆ gobject_

GstSegment* Gst::Segment::gobject_

protected

Public Member Functions

Static Public Member Functions

Protected Attributes

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ Segment() [1/4]

◆ Segment() [2/4]

◆ Segment() [3/4]

◆ Segment() [4/4]

◆ ~Segment()

Member Function Documentation

◆ clip()

◆ get_type()

◆ gobj() [1/2]

◆ gobj() [2/2]

◆ gobj_copy()

◆ init()

◆ is_equal()

◆ offset_running_time()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ position_from_running_time() [1/2]

◆ position_from_running_time() [2/2]

◆ position_from_stream_time() [1/2]

◆ position_from_stream_time() [2/2]

◆ set_running_time()

◆ set_seek()

◆ swap()

◆ to_position()

◆ to_running_time() [1/2]

◆ to_running_time() [2/2]

◆ to_stream_time() [1/2]

◆ to_stream_time() [2/2]

Friends And Related Function Documentation

◆ swap()

◆ wrap()

Member Data Documentation

◆ gobject_