Segment

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

class Segment {

protected

GstSegment* gstSegment;

protected

bool ownedRef;

GstSegment* getSegmentStruct(bool transferOwnership);

void* getStruct();

this(GstSegment* gstSegment, bool ownedRef);

~this();

static GType getType();

this();

bool clip(GstFormat format, ulong start, ulong stop, ulong clipStart, ulong clipStop);

Segment copy();

void copyInto(Segment dest);

bool doSeek(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, ulong start, GstSeekType stopType, ulong stop, bool update);

void free();

void init(GstFormat format);

bool isEqual(Segment s1);

bool offsetRunningTime(GstFormat format, long offset);

ulong positionFromRunningTime(GstFormat format, ulong runningTime);

int positionFromRunningTimeFull(GstFormat format, ulong runningTime, ulong* position);

ulong positionFromStreamTime(GstFormat format, ulong streamTime);

int positionFromStreamTimeFull(GstFormat format, ulong streamTime, ulong* position);

bool setRunningTime(GstFormat format, ulong runningTime);

ulong toPosition(GstFormat format, ulong runningTime);

ulong toRunningTime(GstFormat format, ulong position);

int toRunningTimeFull(GstFormat format, ulong position, ulong* runningTime);

ulong toStreamTime(GstFormat format, ulong position);

int toStreamTimeFull(GstFormat format, ulong position, ulong* streamTime);

}

Constructors

this this(GstSegment* gstSegment, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(): Allocate a new #GstSegment structure and initialize it using gst_segment_init().

Destructor

~this ~this(): Undocumented in source.

Members

Functions

clip bool clip(GstFormat format, ulong start, ulong stop, ulong clipStart, ulong clipStop): 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.
copy Segment copy(): Create a copy of given @segment.
copyInto void copyInto(Segment dest): Copy the contents of @src into @dest.
doSeek bool doSeek(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, ulong start, GstSeekType stopType, ulong stop, bool update): Update the segment structure with the field values of a seek event (see gst_event_new_seek()).
free void free(): Free the allocated segment @segment.
getSegmentStruct GstSegment* getSegmentStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
init void init(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.
isEqual bool isEqual(Segment s1): Checks for two segments being equal. Equality here is defined as perfect equality, including floating point values.
offsetRunningTime bool offsetRunningTime(GstFormat format, long offset): Adjust the values in @segment so that @offset is applied to all future running-time calculations.
positionFromRunningTime ulong positionFromRunningTime(GstFormat format, ulong runningTime): Convert @running_time into a position in the segment so that gst_segment_to_running_time() with that position returns @running_time.
positionFromRunningTimeFull int positionFromRunningTimeFull(GstFormat format, ulong runningTime, ulong* position): Translate @running_time to the segment position using the currently configured segment. Compared to gst_segment_position_from_running_time() this function can return negative segment position.
positionFromStreamTime ulong positionFromStreamTime(GstFormat format, ulong streamTime): Convert @stream_time into a position in the segment so that gst_segment_to_stream_time() with that position returns @stream_time.
positionFromStreamTimeFull int positionFromStreamTimeFull(GstFormat format, ulong streamTime, ulong* position): Translate @stream_time to the segment position using the currently configured segment. Compared to gst_segment_position_from_stream_time() this function can return negative segment position.
setRunningTime bool setRunningTime(GstFormat format, ulong runningTime): Adjust the start/stop and base values of @segment such that the next valid buffer will be one with @running_time.
toPosition ulong toPosition(GstFormat format, ulong runningTime): Convert @running_time into a position in the segment so that gst_segment_to_running_time() with that position returns @running_time.
toRunningTime ulong toRunningTime(GstFormat format, ulong position): Translate @position to the total running time using the currently configured segment. Position is a value between @segment start and stop time.
toRunningTimeFull int toRunningTimeFull(GstFormat format, ulong position, ulong* 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.
toStreamTime ulong toStreamTime(GstFormat format, ulong position): Translate @position to stream time using the currently configured segment. The @position value must be between @segment start and stop value.
toStreamTimeFull int toStreamTimeFull(GstFormat format, ulong position, ulong* 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.

Static functions

getType GType getType()

Variables

gstSegment GstSegment* gstSegment;: the main Gtk struct
ownedRef bool ownedRef;: Undocumented in source.