Package org.freedesktop.gstreamer.gst

Class Segment

java.lang.Object

org.javagi.base.ProxyInstance

org.freedesktop.gstreamer.gst.Segment

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Segment
extends ProxyInstance

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

Constructor Summary

Constructors

Constructor	Description
Segment()	Allocate a new GstSegment structure and initialize it using gst_segment_init().
Segment(MemorySegment address)	Create a Segment proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
boolean	clip(Format format, long start, long stop, @Nullable Out<Long> clipStart, @Nullable Out<Long> clipStop)	Clip the given start and stop values to the segment boundaries given in segment. start and stop are compared and clipped to this Segment start and stop values.
Segment	copy()	Create a copy of given segment.
void	copyInto(Segment dest)	Copy the contents of this Segment into dest.
boolean	doSeek(double rate, Format format, Set<SeekFlags> flags, SeekType startType, long start, SeekType stopType, long stop, @Nullable Out<Boolean> update)	Update the segment structure with the field values of a seek event (see gst_event_new_seek()).
boolean	doSeek(double rate, Format format, SeekFlags flags, SeekType startType, long start, SeekType stopType, long stop, @Nullable Out<Boolean> update)	Update the segment structure with the field values of a seek event (see gst_event_new_seek()).
void	free()	Free the allocated segment segment.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static @Nullable Type	getType()	Get the GType of the Segment class
void	init(Format format)	The start/position fields are set to 0 and the stop/duration fields are set to -1 (unknown).
boolean	isEqual(Segment s1)	Checks for two segments being equal.
boolean	offsetRunningTime(Format format, long offset)	Adjust the values in this Segment so that offset is applied to all future running-time calculations.
long	positionFromRunningTime(Format format, long runningTime)	Convert runningTime into a position in the segment so that gst_segment_to_running_time() with that position returns runningTime.
int	positionFromRunningTimeFull(Format format, long runningTime, Out<Long> position)	Translate runningTime to the segment position using the currently configured segment.
long	positionFromStreamTime(Format format, long streamTime)	Convert streamTime into a position in the segment so that gst_segment_to_stream_time() with that position returns streamTime.
int	positionFromStreamTimeFull(Format format, long streamTime, Out<Long> position)	Translate streamTime to the segment position using the currently configured segment.
double	readAppliedRate()	Read the value of the field applied_rate.
long	readBase()	Read the value of the field base.
long	readDuration()	Read the value of the field duration.
Set<SegmentFlags>	readFlags()	Read the value of the field flags.
Format	readFormat()	Read the value of the field format.
long	readOffset()	Read the value of the field offset.
long	readPosition()	Read the value of the field position.
double	readRate()	Read the value of the field rate.
long	readStart()	Read the value of the field start.
long	readStop()	Read the value of the field stop.
long	readTime()	Read the value of the field time.
boolean	setRunningTime(Format format, long runningTime)	Adjust the start/stop and base values of this Segment such that the next valid buffer will be one with runningTime.
long	toPosition(Format format, long runningTime)	Deprecated. Use gst_segment_position_from_running_time() instead.
long	toRunningTime(Format format, long position)	Translate position to the total running time using the currently configured segment.
int	toRunningTimeFull(Format format, long position, @Nullable Out<Long> runningTime)	Translate position to the total running time using the currently configured segment.
long	toStreamTime(Format format, long position)	Translate position to stream time using the currently configured segment.
int	toStreamTimeFull(Format format, long position, Out<Long> streamTime)	Translate position to the total stream time using the currently configured segment.
void	writeAppliedRate(double appliedRate)	Write a value in the field applied_rate.
void	writeBase(long base)	Write a value in the field base.
void	writeDuration(long duration)	Write a value in the field duration.
void	writeFlags(Set<SegmentFlags> flags)	Write a value in the field flags.
void	writeFormat(Format format)	Write a value in the field format.
void	writeOffset(long offset)	Write a value in the field offset.
void	writePosition(long position)	Write a value in the field position.
void	writeRate(double rate)	Write a value in the field rate.
void	writeStart(long start)	Write a value in the field start.
void	writeStop(long stop)	Write a value in the field stop.
void	writeTime(long time)	Write a value in the field time.

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Segment

public Segment(MemorySegment address)

Create a Segment proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Segment

public Segment()

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

Free-function: gst_segment_free

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Segment class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readFlags

public Set<SegmentFlags> readFlags()

Read the value of the field flags.

Returns:

The value of the field flags

writeFlags

public void writeFlags(Set<SegmentFlags> flags)

Write a value in the field flags.

Parameters:

flags - The new value for the field flags

readRate

public double readRate()

Read the value of the field rate.

Returns:

The value of the field rate

writeRate

public void writeRate(double rate)

Write a value in the field rate.

Parameters:

rate - The new value for the field rate

readAppliedRate

public double readAppliedRate()

Read the value of the field applied_rate.

Returns:

The value of the field applied_rate

writeAppliedRate

public void writeAppliedRate(double appliedRate)

Write a value in the field applied_rate.

Parameters:

appliedRate - The new value for the field applied_rate

readFormat

public Format readFormat()

Read the value of the field format.

Returns:

The value of the field format

writeFormat

public void writeFormat(Format format)

Write a value in the field format.

Parameters:

format - The new value for the field format

readBase

public long readBase()

Read the value of the field base.

Returns:

The value of the field base

writeBase

public void writeBase(long base)

Write a value in the field base.

Parameters:

base - The new value for the field base

readOffset

public long readOffset()

Read the value of the field offset.

Returns:

The value of the field offset

writeOffset

public void writeOffset(long offset)

Write a value in the field offset.

Parameters:

offset - The new value for the field offset

readStart

public long readStart()

Read the value of the field start.

Returns:

The value of the field start

writeStart

public void writeStart(long start)

Write a value in the field start.

Parameters:

start - The new value for the field start

readStop

public long readStop()

Read the value of the field stop.

Returns:

The value of the field stop

writeStop

public void writeStop(long stop)

Write a value in the field stop.

Parameters:

stop - The new value for the field stop

readTime

public long readTime()

Read the value of the field time.

Returns:

The value of the field time

writeTime

public void writeTime(long time)

Write a value in the field time.

Parameters:

time - The new value for the field time

readPosition

public long readPosition()

Read the value of the field position.

Returns:

The value of the field position

writePosition

public void writePosition(long position)

Write a value in the field position.

Parameters:

position - The new value for the field position

readDuration

public long readDuration()

Read the value of the field duration.

Returns:

The value of the field duration

writeDuration

public void writeDuration(long duration)

Write a value in the field duration.

Parameters:

duration - The new value for the field duration

clip

public boolean clip(Format format,
 long start,
 long stop,
 @Nullable Out<Long> clipStart,
 @Nullable Out<Long> clipStop)

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

If the function returns false, start and stop are known to fall outside of this Segment and clipStart and clipStop are not updated.

When the function returns true, clipStart and clipStop will be updated. If clipStart or clipStop are different from start or stop respectively, the region fell partially in the segment.

Note that when stop is -1, clipStop 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

clipStart - the clipped start position in the segment

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

copy

public Segment copy()

Create a copy of given segment.

Free-function: gst_segment_free

Returns:

a new GstSegment, free with gst_segment_free().

copyInto

public void copyInto(Segment dest)

Copy the contents of this Segment into dest.

Parameters:

dest - a GstSegment

doSeek

public boolean doSeek(double rate,
 Format format,
 Set<SeekFlags> flags,
 SeekType startType,
 long start,
 SeekType stopType,
 long stop,
 @Nullable Out<Boolean> 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 startType and stopType.

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

For negative rate, the new position in the segment is the new this Segment stop field when it was updated with a stopType 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 this Segment stop position (GST_SEEK_TYPE_NONE), stop is ignored and this 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 this 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

startType - the seek method

start - the seek start value

stopType - the seek method

stop - the seek stop value

update - boolean holding whether position was updated.

Returns:

true if the seek could be performed.

doSeek

public boolean doSeek(double rate,
 Format format,
 SeekFlags flags,
 SeekType startType,
 long start,
 SeekType stopType,
 long stop,
 @Nullable Out<Boolean> 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 startType and stopType.

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

For negative rate, the new position in the segment is the new this Segment stop field when it was updated with a stopType 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 this Segment stop position (GST_SEEK_TYPE_NONE), stop is ignored and this 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 this 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

startType - the seek method

start - the seek start value

stopType - the seek method

stop - the seek stop value

update - boolean holding whether position was updated.

Returns:

true if the seek could be performed.

free

public void free()

Free the allocated segment segment.

init

public void 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 this Segment to its default values.

Parameters:

format - the format of the segment.

isEqual

public boolean isEqual(Segment s1)

Checks for two segments being equal. Equality here is defined as perfect equality, including floating point values.

Parameters:

s1 - a GstSegment structure.

Returns:

true if the segments are equal, false otherwise.

Since:

1.6

offsetRunningTime

public boolean offsetRunningTime(Format format,
 long offset)

Adjust the values in this 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.

Since:

1.2.3

positionFromRunningTime

public long positionFromRunningTime(Format format,
 long runningTime)

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

Parameters:

format - the format of the segment.

runningTime - the running_time in the segment

Returns:

the position in the segment for runningTime. This function returns -1 when runningTime is -1 or when it is not inside segment.

Since:

1.8

positionFromRunningTimeFull

public int positionFromRunningTimeFull(Format format,
 long runningTime,
 Out<Long> position)

Translate runningTime to the segment position using the currently configured segment. Compared to gst_segment_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.

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

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

When this function returns -1, the returned position was < 0, and the value in the position variable should be negated to get the real negative segment position.

Parameters:

format - the format of the segment.

runningTime - the running-time

position - the resulting position in the segment

Returns:

a 1 or -1 on success, 0 on failure.

Since:

1.8

positionFromStreamTime

public long positionFromStreamTime(Format format,
 long streamTime)

Convert streamTime into a position in the segment so that gst_segment_to_stream_time() with that position returns streamTime.

Parameters:

format - the format of the segment.

streamTime - the stream_time in the segment

Returns:

the position in the segment for streamTime. This function returns -1 when streamTime is -1 or when it is not inside segment.

Since:

1.8

positionFromStreamTimeFull

public int positionFromStreamTimeFull(Format format,
 long streamTime,
 Out<Long> position)

Translate streamTime to the segment position using the currently configured segment. Compared to gst_segment_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.

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

When 1 is returned, streamTime 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.

streamTime - the stream-time

position - the resulting position in the segment

Returns:

a 1 or -1 on success, 0 on failure.

Since:

1.8

setRunningTime

public boolean setRunningTime(Format format,
 long runningTime)

Adjust the start/stop and base values of this Segment such that the next valid buffer will be one with runningTime.

Parameters:

format - the format of the segment.

runningTime - the running_time in the segment

Returns:

true if the segment could be updated successfully. If false is returned, runningTime is -1 or not in segment.

toPosition

@Deprecated
public long toPosition(Format format,
 long runningTime)

Deprecated.

Use gst_segment_position_from_running_time() instead.

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

Parameters:

format - the format of the segment.

runningTime - the running_time in the segment

Returns:

the position in the segment for runningTime. This function returns -1 when runningTime is -1 or when it is not inside segment.

toRunningTime

public long toRunningTime(Format format,
 long position)

Translate position to the total running time using the currently configured segment. Position is a value between this 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 gst_segment_init() is called, this value will reset to 0.

This function returns -1 if the position is outside of this 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.

toRunningTimeFull

public int toRunningTimeFull(Format format,
 long position,
 @Nullable Out<Long> runningTime)

Translate position to the total running time using the currently configured segment. Compared to gst_segment_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 each other.

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

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

Parameters:

format - the format of the segment.

position - the position in the segment

runningTime - result running-time

Returns:

a 1 or -1 on success, 0 on failure.

Since:

1.6

toStreamTime

public long toStreamTime(Format format,
 long position)

Translate position to stream time using the currently configured segment. The position value must be between this 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.

Since:

1.8

toStreamTimeFull

public int toStreamTimeFull(Format format,
 long position,
 Out<Long> streamTime)

Translate position to the total stream time using the currently configured segment. Compared to gst_segment_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 each other.

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

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

Parameters:

format - the format of the segment.

position - the position in the segment

streamTime - result stream-time

Returns:

a 1 or -1 on success, 0 on failure.

Since:

1.8