Class Segment

java.lang.Object
org.javagi.base.ProxyInstance
org.freedesktop.gstreamer.gst.Segment
All Implemented Interfaces:
Proxy
@Generated("org.javagi.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 ProxyInstance

    equals, handle, hashCode

    Methods inherited from class 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