2 * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
4 * gstsegment.c: GstSegment subsystem
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
22 #include "gst_private.h"
27 #include "gstsegment.h"
31 * @short_description: Structure describing the configured region of interest
33 * @see_also: #GstEvent
35 * This helper structure holds the relevant values for tracking the region of
36 * interest in a media file, called a segment.
38 * The structure can be used for two purposes:
40 * <listitem><para>performing seeks (handling seek events)</para></listitem>
41 * <listitem><para>tracking playback regions (handling newsegment events)</para></listitem>
44 * The segment is usually configured by the application with a seek event which
45 * is propagated upstream and eventually handled by an element that performs the seek.
47 * The configured segment is then propagated back downstream with a newsegment event.
48 * This information is then used to clip media to the segment boundaries.
50 * A segment structure is initialized with gst_segment_init(), which takes a #GstFormat
51 * that will be used as the format of the segment values. The segment will be configured
52 * with a start value of 0 and a stop/duration of -1, which is undefined. The default
53 * rate and applied_rate is 1.0.
55 * If the segment is used for managing seeks, the segment duration should be set with
56 * gst_segment_set_duration(). The public duration field contains the duration of the
57 * segment. When using the segment for seeking, the start and time members should
58 * normally be left to their default 0 value. The stop position is left to -1 unless
59 * explicitly configured to a different value after a seek event.
61 * The current position in the segment should be set with the gst_segment_set_last_stop().
62 * The public last_stop field contains the last set stop position in the segment.
64 * For elements that perform seeks, the current segment should be updated with the
65 * gst_segment_set_seek() and the values from the seek event. This method will update
66 * all the segment fields. The last_stop field will contain the new playback position.
67 * If the cur_type was different from GST_SEEK_TYPE_NONE, playback continues from
68 * the last_stop position, possibly with updated flags or rate.
70 * For elements that want to use #GstSegment to track the playback region, use
71 * gst_segment_set_newsegment() to update the segment fields with the information from
72 * the newsegment event. The gst_segment_clip() method can be used to check and clip
73 * the media data to the segment boundaries.
75 * For elements that want to synchronize to the pipeline clock, gst_segment_to_running_time()
76 * can be used to convert a timestamp to a value that can be used to synchronize
77 * to the clock. This function takes into account all accumulated segments as well as
78 * any rate or applied_rate conversions.
80 * For elements that need to perform operations on media data in stream_time,
81 * gst_segment_to_stream_time() can be used to convert a timestamp and the segment
82 * info to stream time (which is always between 0 and the duration of the stream).
84 * Last reviewed on 2007-05-17 (0.10.13)
89 * @segment: a #GstSegment
91 * Create a copy of given @segment.
93 * Returns: a new #GstSegment, free with gst_segment_free().
98 gst_segment_copy (GstSegment * segment)
100 GstSegment *result = NULL;
103 result = (GstSegment *) g_slice_copy (sizeof (GstSegment), segment);
109 gst_segment_get_type (void)
111 static GType gst_segment_type = 0;
113 if (G_UNLIKELY (gst_segment_type == 0)) {
114 gst_segment_type = g_boxed_type_register_static ("GstSegment",
115 (GBoxedCopyFunc) gst_segment_copy, (GBoxedFreeFunc) gst_segment_free);
118 return gst_segment_type;
124 * Allocate a new #GstSegment structure and initialize it using
125 * gst_segment_init().
127 * Returns: a new #GstSegment, free with gst_segment_free().
130 gst_segment_new (void)
134 result = g_slice_new0 (GstSegment);
135 gst_segment_init (result, GST_FORMAT_UNDEFINED);
142 * @segment: a #GstSegment
144 * Free the allocated segment @segment.
147 gst_segment_free (GstSegment * segment)
149 g_slice_free (GstSegment, segment);
154 * @segment: a #GstSegment structure.
155 * @format: the format of the segment.
157 * The start/last_stop positions are set to 0 and the stop/duration
158 * fields are set to -1 (unknown). The default rate of 1.0 and no
161 * Initialize @segment to its default values.
164 gst_segment_init (GstSegment * segment, GstFormat format)
166 g_return_if_fail (segment != NULL);
169 segment->abs_rate = 1.0;
170 segment->applied_rate = 1.0;
171 segment->format = format;
177 segment->last_stop = 0;
178 segment->duration = -1;
182 * gst_segment_set_duration:
183 * @segment: a #GstSegment structure.
184 * @format: the format of the segment.
185 * @duration: the duration of the segment info or -1 if unknown.
187 * Set the duration of the segment to @duration. This function is mainly
188 * used by elements that perform seeking and know the total duration of the
191 * This field should be set to allow seeking requests relative to the
195 gst_segment_set_duration (GstSegment * segment, GstFormat format,
198 g_return_if_fail (segment != NULL);
200 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
201 segment->format = format;
203 g_return_if_fail (segment->format == format);
205 segment->duration = duration;
209 * gst_segment_set_last_stop:
210 * @segment: a #GstSegment structure.
211 * @format: the format of the segment.
212 * @position: the position
214 * Set the last observed stop position in the segment to @position.
216 * This field should be set to allow seeking requests relative to the
217 * current playing position.
220 gst_segment_set_last_stop (GstSegment * segment, GstFormat format,
223 g_return_if_fail (segment != NULL);
225 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
226 segment->format = format;
228 g_return_if_fail (segment->format == format);
230 segment->last_stop = MAX (segment->start, position);
234 * gst_segment_set_seek:
235 * @segment: a #GstSegment structure.
236 * @rate: the rate of the segment.
237 * @format: the format of the segment.
238 * @flags: the seek flags for the segment
239 * @start_type: the seek method
240 * @start: the seek start value
241 * @stop_type: the seek method
242 * @stop: the seek stop value
243 * @update: boolean holding whether last_stop was updated.
245 * Update the segment structure with the field values of a seek event (see
246 * gst_event_new_seek()).
248 * After calling this method, the segment field last_stop and time will
249 * contain the requested new position in the segment. The new requested
250 * position in the segment depends on @rate and @start_type and @stop_type.
252 * For positive @rate, the new position in the segment is the new @segment
253 * start field when it was updated with a @start_type different from
254 * #GST_SEEK_TYPE_NONE. If no update was performed on @segment start position
255 * (#GST_SEEK_TYPE_NONE), @start is ignored and @segment last_stop is
258 * For negative @rate, the new position in the segment is the new @segment
259 * stop field when it was updated with a @stop_type different from
260 * #GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the
261 * duration of the segment will be used to update the stop position.
262 * If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE),
263 * @stop is ignored and @segment last_stop is unmodified.
265 * The applied rate of the segment will be set to 1.0 by default.
266 * If the caller can apply a rate change, it should update @segment
267 * rate and applied_rate after calling this function.
269 * @update will be set to TRUE if a seek should be performed to the segment
270 * last_stop field. This field can be FALSE if, for example, only the @rate
271 * has been changed but not the playback position.
274 gst_segment_set_seek (GstSegment * segment, gdouble rate,
275 GstFormat format, GstSeekFlags flags,
276 GstSeekType start_type, gint64 start,
277 GstSeekType stop_type, gint64 stop, gboolean * update)
279 gboolean update_stop, update_start;
282 g_return_if_fail (rate != 0.0);
283 g_return_if_fail (segment != NULL);
285 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
286 segment->format = format;
288 update_start = update_stop = TRUE;
290 /* segment->start is never invalid */
291 switch (start_type) {
292 case GST_SEEK_TYPE_NONE:
293 /* no update to segment, take previous start */
294 start = segment->start;
295 update_start = FALSE;
297 case GST_SEEK_TYPE_SET:
298 /* start holds desired position, map -1 to the start */
301 /* start must be 0 or the formats must match */
302 g_return_if_fail (start == 0 || segment->format == format);
304 case GST_SEEK_TYPE_CUR:
305 g_return_if_fail (start == 0 || segment->format == format);
306 /* add start to currently configured segment */
307 start = segment->start + start;
309 case GST_SEEK_TYPE_END:
310 if (segment->duration != -1) {
311 g_return_if_fail (start == 0 || segment->format == format);
312 /* add start to total length */
313 start = segment->duration + start;
315 /* no update if duration unknown */
316 start = segment->start;
317 update_start = FALSE;
321 /* bring in sane range */
322 if (segment->duration != -1)
323 start = CLAMP (start, 0, segment->duration);
325 start = MAX (start, 0);
327 /* stop can be -1 if we have not configured a stop. */
329 case GST_SEEK_TYPE_NONE:
330 stop = segment->stop;
333 case GST_SEEK_TYPE_SET:
334 /* stop holds required value, if it's not -1, it must be of the same
335 * format as the segment. */
336 g_return_if_fail (stop == -1 || segment->format == format);
338 case GST_SEEK_TYPE_CUR:
339 if (segment->stop != -1) {
340 /* only add compatible formats or 0 */
341 g_return_if_fail (stop == 0 || segment->format == format);
342 stop = segment->stop + stop;
346 case GST_SEEK_TYPE_END:
347 if (segment->duration != -1) {
348 /* only add compatible formats or 0 */
349 g_return_if_fail (stop == 0 || segment->format == format);
350 stop = segment->duration + stop;
352 stop = segment->stop;
358 /* if we have a valid stop time, make sure it is clipped */
360 if (segment->duration != -1)
361 stop = CLAMP (stop, 0, segment->duration);
363 stop = MAX (stop, 0);
366 /* we can't have stop before start */
368 g_return_if_fail (start <= stop);
370 segment->rate = rate;
371 segment->abs_rate = ABS (rate);
372 segment->applied_rate = 1.0;
373 segment->flags = flags;
374 segment->start = start;
375 segment->stop = stop;
376 segment->time = start;
378 last_stop = segment->last_stop;
379 if (update_start && rate > 0.0) {
382 if (update_stop && rate < 0.0) {
386 if (segment->duration != -1)
387 last_stop = segment->duration;
392 /* set update arg to reflect update of last_stop */
394 *update = last_stop != segment->last_stop;
396 /* update new position */
397 segment->last_stop = last_stop;
401 * gst_segment_set_newsegment:
402 * @segment: a #GstSegment structure.
403 * @update: flag indicating a new segment is started or updated
404 * @rate: the rate of the segment.
405 * @format: the format of the segment.
406 * @start: the new start value
407 * @stop: the new stop value
408 * @time: the new stream time
410 * Update the segment structure with the field values of a new segment event and
411 * with a default applied_rate of 1.0.
416 gst_segment_set_newsegment (GstSegment * segment, gboolean update, gdouble rate,
417 GstFormat format, gint64 start, gint64 stop, gint64 time)
419 gst_segment_set_newsegment_full (segment, update, rate, 1.0, format, start,
424 * gst_segment_set_newsegment_full:
425 * @segment: a #GstSegment structure.
426 * @update: flag indicating a new segment is started or updated
427 * @rate: the rate of the segment.
428 * @applied_rate: the applied rate of the segment.
429 * @format: the format of the segment.
430 * @start: the new start value
431 * @stop: the new stop value
432 * @time: the new stream time
434 * Update the segment structure with the field values of a new segment event.
437 gst_segment_set_newsegment_full (GstSegment * segment, gboolean update,
438 gdouble rate, gdouble applied_rate, GstFormat format, gint64 start,
439 gint64 stop, gint64 time)
441 gint64 duration, last_stop;
443 g_return_if_fail (rate != 0.0);
444 g_return_if_fail (applied_rate != 0.0);
445 g_return_if_fail (segment != NULL);
447 GST_DEBUG ("configuring segment update %d, rate %lf, format %s, "
448 "start %" G_GINT64_FORMAT ", stop %" G_GINT64_FORMAT ", position %"
449 G_GINT64_FORMAT, update, rate, gst_format_get_name (format), start,
451 GST_DEBUG ("old segment was: %" GST_SEGMENT_FORMAT, segment);
453 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
454 segment->format = format;
456 /* any other format with 0 also gives time 0, the other values are
457 * invalid in the format though. */
458 if (format != segment->format && start == 0) {
459 format = segment->format;
466 g_return_if_fail (segment->format == format);
469 if (G_LIKELY (segment->rate > 0.0)) {
470 /* an update to the current segment is done, elapsed time is
471 * difference between the old start and new start. */
472 if (start > segment->start)
473 duration = start - segment->start;
477 /* for negative rates, the elapsed duration is the diff between the stop
479 if (stop != -1 && stop < segment->stop)
480 duration = segment->stop - stop;
484 /* update last_stop to be a valid value in the updated segment */
485 if (start > segment->last_stop)
487 else if (stop != -1 && stop < segment->last_stop)
490 last_stop = segment->last_stop;
492 /* the new segment has to be aligned with the old segment.
493 * We first update the accumulated time of the previous
494 * segment. the accumulated time is used when syncing to the
496 if (segment->stop != -1) {
497 duration = segment->stop - segment->start;
498 } else if (segment->last_stop != -1) {
499 /* else use last seen timestamp as segment stop */
500 duration = segment->last_stop - segment->start;
502 /* else we don't know and throw a warning.. really, this should
503 * be fixed in the element. */
504 g_warning ("closing segment of unknown duration, assuming duration of 0");
507 /* position the last_stop to the next expected position in the new segment,
508 * which is the start or the stop of the segment */
514 /* use previous rate to calculate duration */
515 if (G_LIKELY (segment->abs_rate != 1.0))
516 duration /= segment->abs_rate;
518 /* accumulate duration */
519 segment->accum += duration;
521 /* then update the current segment */
522 segment->rate = rate;
523 segment->abs_rate = ABS (rate);
524 segment->applied_rate = applied_rate;
525 segment->start = start;
526 segment->last_stop = last_stop;
527 segment->stop = stop;
528 segment->time = time;
532 * gst_segment_to_stream_time:
533 * @segment: a #GstSegment structure.
534 * @format: the format of the segment.
535 * @position: the position in the segment
537 * Translate @position to stream time using the currently configured
538 * segment. The @position value must be between @segment start and
541 * This function is typically used by elements that need to operate on
542 * the stream time of the buffers it receives, such as effect plugins.
543 * In those use cases, @position is typically the buffer timestamp or
544 * clock time that one wants to convert to the stream time.
545 * The stream time is always between 0 and the total duration of the
548 * Returns: the position in stream_time or -1 when an invalid position
552 gst_segment_to_stream_time (GstSegment * segment, GstFormat format,
555 gint64 result, start, stop, time;
556 gdouble abs_applied_rate;
558 g_return_val_if_fail (segment != NULL, -1);
560 /* format does not matter for -1 */
561 if (G_UNLIKELY (position == -1))
564 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
565 segment->format = format;
567 /* if we have the position for the same format as the segment, we can compare
568 * the start and stop values, otherwise we assume 0 and -1 */
569 if (G_LIKELY (segment->format == format)) {
570 start = segment->start;
571 stop = segment->stop;
572 time = segment->time;
579 /* outside of the segment boundary stop */
580 if (G_UNLIKELY (stop != -1 && position > stop))
583 /* before the segment boundary */
584 if (G_UNLIKELY (position < start))
587 /* time must be known */
588 if (G_UNLIKELY (time == -1))
591 /* bring to uncorrected position in segment */
592 result = position - start;
594 abs_applied_rate = ABS (segment->applied_rate);
596 /* correct for applied rate if needed */
597 if (G_UNLIKELY (abs_applied_rate != 1.0))
598 result *= abs_applied_rate;
600 /* add or subtract from segment time based on applied rate */
601 if (G_LIKELY (segment->applied_rate > 0.0)) {
602 /* correct for segment time */
605 /* correct for segment time, clamp at 0. Streams with a negative
606 * applied_rate have timestamps between start and stop, as usual, but have
607 * the time member starting high and going backwards. */
608 if (G_LIKELY (time > result))
609 result = time - result;
618 * gst_segment_to_running_time:
619 * @segment: a #GstSegment structure.
620 * @format: the format of the segment.
621 * @position: the position in the segment
623 * Translate @position to the total running time using the currently configured
624 * and previously accumulated segments. Position is a value between @segment
625 * start and stop time.
627 * This function is typically used by elements that need to synchronize to the
628 * global clock in a pipeline. The runnning time is a constantly increasing value
629 * starting from 0. When gst_segment_init() is called, this value will reset to
632 * This function returns -1 if the position is outside of @segment start and stop.
634 * Returns: the position as the total running time or -1 when an invalid position
638 gst_segment_to_running_time (GstSegment * segment, GstFormat format,
642 gint64 start, stop, accum;
644 g_return_val_if_fail (segment != NULL, -1);
646 if (G_UNLIKELY (position == -1))
649 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
650 segment->format = format;
652 /* if we have the position for the same format as the segment, we can compare
653 * the start and stop values, otherwise we assume 0 and -1 */
654 if (G_LIKELY (segment->format == format)) {
655 start = segment->start;
656 stop = segment->stop;
657 accum = segment->accum;
664 /* before the segment boundary */
665 if (G_UNLIKELY (position < start))
668 if (G_LIKELY (segment->rate > 0.0)) {
669 /* outside of the segment boundary stop */
670 if (G_UNLIKELY (stop != -1 && position > stop))
673 /* bring to uncorrected position in segment */
674 result = position - start;
676 /* cannot continue if no stop position set or outside of
678 if (G_UNLIKELY (stop == -1 || position > stop))
681 /* bring to uncorrected position in segment */
682 result = stop - position;
685 /* scale based on the rate, avoid division by and conversion to
686 * float when not needed */
687 if (G_UNLIKELY (segment->abs_rate != 1.0))
688 result /= segment->abs_rate;
690 /* correct for accumulated segments */
698 * @segment: a #GstSegment structure.
699 * @format: the format of the segment.
700 * @start: the start position in the segment
701 * @stop: the stop position in the segment
702 * @clip_start: the clipped start position in the segment
703 * @clip_stop: the clipped stop position in the segment
705 * Clip the given @start and @stop values to the segment boundaries given
706 * in @segment. @start and @stop are compared and clipped to @segment
707 * start and stop values.
709 * If the function returns FALSE, @start and @stop are known to fall
710 * outside of @segment and @clip_start and @clip_stop are not updated.
712 * When the function returns TRUE, @clip_start and @clip_stop will be
713 * updated. If @clip_start or @clip_stop are different from @start or @stop
714 * respectively, the region fell partially in the segment.
716 * Note that when @stop is -1, @clip_stop will be set to the end of the
717 * segment. Depending on the use case, this may or may not be what you want.
719 * Returns: TRUE if the given @start and @stop times fall partially or
720 * completely in @segment, FALSE if the values are completely outside
724 gst_segment_clip (GstSegment * segment, GstFormat format, gint64 start,
725 gint64 stop, gint64 * clip_start, gint64 * clip_stop)
727 g_return_val_if_fail (segment != NULL, FALSE);
729 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
730 segment->format = format;
732 g_return_val_if_fail (segment->format == format, FALSE);
734 /* if we have a stop position and a valid start and start is bigger,
735 * we're outside of the segment */
736 if (G_UNLIKELY (segment->stop != -1 && start != -1 && start >= segment->stop))
739 /* if a stop position is given and is before the segment start,
740 * we're outside of the segment. Special case is were start
741 * and stop are equal to the segment start. In that case we
742 * are inside the segment. */
743 if (G_UNLIKELY (stop != -1 && (stop < segment->start || (start != stop
744 && stop == segment->start))))
751 *clip_start = MAX (start, segment->start);
756 *clip_stop = segment->stop;
757 else if (segment->stop == -1)
758 *clip_stop = MAX (-1, stop);
760 *clip_stop = MIN (stop, segment->stop);
762 if (segment->duration != -1)
763 *clip_stop = MIN (*clip_stop, segment->duration);
770 * gst_segment_to_position:
771 * @segment: a #GstSegment structure.
772 * @format: the format of the segment.
773 * @running_time: the running_time in the segment
775 * Convert @running_time into a position in the segment so that
776 * gst_segment_to_running_time() with that position returns @running_time.
778 * Returns: the position in the segment for @running_time. This function returns
779 * -1 when @running_time is -1 or when it is not inside @segment.
784 gst_segment_to_position (GstSegment * segment, GstFormat format,
788 gint64 start, stop, accum;
790 g_return_val_if_fail (segment != NULL, -1);
792 if (G_UNLIKELY (running_time == -1))
795 if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
796 segment->format = format;
798 /* if we have the position for the same format as the segment, we can compare
799 * the start and stop values, otherwise we assume 0 and -1 */
800 if (G_LIKELY (segment->format == format)) {
801 start = segment->start;
802 stop = segment->stop;
803 accum = segment->accum;
810 /* this running_time was for a previous segment */
811 if (running_time < accum)
814 /* start by subtracting the accumulated time */
815 result = running_time - accum;
817 /* move into the segment at the right rate */
818 if (G_UNLIKELY (segment->abs_rate != 1.0))
819 result = ceil (result * segment->abs_rate);
821 if (G_LIKELY (segment->rate > 0.0)) {
822 /* bring to corrected position in segment */
825 /* outside of the segment boundary stop */
826 if (G_UNLIKELY (stop != -1 && result > stop))
829 /* cannot continue if no stop position set or outside of
831 if (G_UNLIKELY (stop == -1 || result + start > stop))
834 /* bring to corrected position in segment */
835 result = stop - result;
842 * gst_segment_set_running_time:
843 * @segment: a #GstSegment structure.
844 * @format: the format of the segment.
845 * @running_time: the running_time in the segment
847 * Adjust the start/stop and accum values of @segment such that the next valid
848 * buffer will be one with @running_time.
850 * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
851 * returned, @running_time is -1 or not in @segment.
856 gst_segment_set_running_time (GstSegment * segment, GstFormat format,
860 gint64 start, stop, last_stop;
862 /* start by bringing the running_time into the segment position */
863 position = gst_segment_to_position (segment, format, running_time);
865 /* we must have a valid position now */
866 if (G_UNLIKELY (position == -1))
869 start = segment->start;
870 stop = segment->stop;
871 last_stop = segment->last_stop;
873 if (G_LIKELY (segment->rate > 0.0)) {
874 /* update the start/last_stop and time values */
876 if (last_stop < start)
879 /* reverse, update stop */
881 /* if we were past the position, go back */
882 if (last_stop > stop)
885 /* and accumulated time is exactly the running time */
886 segment->time = gst_segment_to_stream_time (segment, format, start);
887 segment->start = start;
888 segment->stop = stop;
889 segment->last_stop = last_stop;
890 segment->accum = running_time;