/**
* SECTION:gstsegment
+ * @title: GstSegment
* @short_description: Structure describing the configured region of interest
* in a media file.
* @see_also: #GstEvent
* interest in a media file, called a segment.
*
* The structure can be used for two purposes:
- * <itemizedlist>
- * <listitem><para>performing seeks (handling seek events)</para></listitem>
- * <listitem><para>tracking playback regions (handling newsegment events)</para></listitem>
- * </itemizedlist>
+ *
+ * * 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.
* info to stream time (which is always between 0 and the duration of the stream).
*/
+/* FIXME 2.0: remove unused format parameter.
+ * Most of the methods in gstsegment.c take and extra GstFormat format, just to
+ * verify segment->format == format.
+ * See https://bugzilla.gnome.org/show_bug.cgi?id=788979
+ */
+
/**
* gst_segment_copy:
* @segment: (transfer none): a #GstSegment
* @start: the seek start value
* @stop_type: the seek method
* @stop: the seek stop value
- * @update: boolean holding whether position was updated.
+ * @update: (out) (allow-none): boolean holding whether position was updated.
*
* Update the segment structure with the field values of a seek event (see
* gst_event_new_seek()).
* @segment: a #GstSegment structure.
* @format: the format of the segment.
* @position: the position in the segment
- * @stream_time: result stream-time
+ * @stream_time: (out): result stream-time
*
* 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 eachother.
+ * 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.
* @segment: a #GstSegment structure.
* @format: the format of the segment.
* @stream_time: the stream-time
- * @position: the resulting position in the segment
+ * @position: (out): the resulting position in the segment
*
* Translate @stream_time to the segment position using the currently configured
* segment. Compared to gst_segment_position_from_stream_time() this function can
* @segment: a #GstSegment structure.
* @format: the format of the segment.
* @position: the position in the segment
- * @running_time: result running-time
+ * @running_time: (out) (allow-none): result running-time
*
* 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 eachother.
+ * 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.
} else {
stop = segment->stop;
+ if (stop == -1 && segment->duration != -1)
+ stop = segment->start + segment->duration;
+
/* cannot continue if no stop position set or invalid offset */
g_return_val_if_fail (stop != -1, 0);
g_return_val_if_fail (stop >= offset, 0);
g_return_val_if_fail (segment->format == format, FALSE);
/* if we have a stop position and a valid start and start is bigger,
- * we're outside of the segment */
- if (G_UNLIKELY (segment->stop != -1 && start != -1 && start >= segment->stop))
+ * we're outside of the segment. (Special case) segment start and
+ * segment stop can be identical. In this case, if start is also identical,
+ * it's inside of segment */
+ if (G_UNLIKELY (segment->stop != -1 && start != -1 && (start > segment->stop
+ || (segment->start != segment->stop && start == segment->stop))))
return FALSE;
/* if a stop position is given and is before the segment start,
* @segment: a #GstSegment structure.
* @format: the format of the segment.
* @running_time: the running-time
- * @position: the resulting position in the segment
+ * @position: (out): the resulting position in the segment
*
* Translate @running_time to the segment position using the currently configured
* segment. Compared to gst_segment_position_from_running_time() this function can
* 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.
+ * 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.
*
* Returns: a 1 or -1 on success, 0 on failure.
*
*position = base - running_time;
if (G_UNLIKELY (abs_rate != 1.0))
*position = ceil (*position * abs_rate);
- if (start + segment->offset > *position) {
- *position -= start + segment->offset;
- res = -1;
- } else {
+ if (start + segment->offset >= *position) {
+ /* The TS is before the segment, but the result is >= 0 */
*position = start + segment->offset - *position;
res = 1;
+ } else {
+ /* The TS is before the segment, and the result is < 0
+ * so negate the return result */
+ *position = *position - (start + segment->offset);
+ res = -1;
}
}
} else {
res = 1;
}
} else {
+ /* This case is tricky. Requested running time precedes the
+ * segment base, so in a reversed segment where rate < 0, that
+ * means it's before the alignment point of (stop - offset).
+ * Before = always bigger than (stop-offset), which is usually +ve,
+ * but could be -ve is offset is big enough. -ve position implies
+ * that the offset has clipped away the entire segment anyway */
*position = base - running_time;
if (G_UNLIKELY (abs_rate != 1.0))
*position = ceil (*position * abs_rate);
- if (G_UNLIKELY (stop < segment->offset - *position)) {
- *position -= segment->offset - stop;
- res = -1;
- } else {
+
+ if (G_LIKELY (stop + *position >= segment->offset)) {
*position = stop + *position - segment->offset;
res = 1;
+ } else {
+ /* Requested position is still negative because offset is big,
+ * so negate the result */
+ *position = segment->offset - *position - stop;
+ res = -1;
}
}
}
* 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 gst_segment_position_from_running_time() instead.
+ * Deprecated: Use gst_segment_position_from_running_time() instead.
*/
#ifndef GST_REMOVE_DEPRECATED
-#ifdef GST_DISABLE_DEPRECATED
-guint64 gst_segment_to_position (const GstSegment * segment, GstFormat format,
- guint64 running_time);
-#endif
guint64
gst_segment_to_position (const GstSegment * segment, GstFormat format,
guint64 running_time)